> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes Operator Helm Configuration

> Reference documentation for Helm configuration values when installing and configuring the ngrok Kubernetes Operator.

The following YAML block contains the default `values.yaml` used when installing the ngrok Kubernetes Operator. You can reference these values and change them individually with `--set` flags while installing/upgrading the ngrok Kubernetes Operator.

You can also see these values in [the ngrok Operator repo](https://github.com/ngrok/ngrok-operator/blob/main/helm/ngrok-operator/values.yaml).

## Helm values

```yaml title="helm values" wrap theme={null}
##
## @section Common parameters
##
## @param nameOverride String to partially override generated resource names
## @param fullnameOverride String to fully override generated resource names
## @param description ngrok-operator description that will appear in the ngrok dashboard
## @param commonLabels Labels to add to all deployed objects
## @param commonAnnotations Annotations to add to all deployed objects
## @param oneClickDemoMode If true, then the operator will startup without required fields or API registration, become Ready, but not actually be running
nameOverride: ""
fullnameOverride: ""
description: "The official ngrok Kubernetes Operator."
commonLabels: {}
commonAnnotations: {}
oneClickDemoMode: false

## @param podAnnotations Custom pod annotations to apply to all pods.
## @param podLabels Custom pod labels to apply to all pods.
podAnnotations: {}
podLabels: {}

##
## @section Image configuration
##
## @param image.registry The ngrok operator image registry.
## @param image.repository The ngrok operator image repository.
## @param image.tag The ngrok operator image tag. Defaults to the chart's appVersion if not specified
## @param image.pullPolicy The ngrok operator image pull policy.
## @param image.pullSecrets An array of imagePullSecrets to be used when pulling the image.
##
image:
  registry: docker.io
  repository: ngrok/ngrok-operator
  tag: ""
  pullPolicy: IfNotPresent
  ## Example
  ## pullSecrets:
  ## - name: my-imagepull-secret
  ##
  pullSecrets: []

##
## @section ngrok configuration
##
## @param region ngrok region to create tunnels in. Defaults to connect to the closest geographical region.
##
region: "" # empty means global or all regions

## @param rootCAs Set to "trusted" for the ngrok agent CA or "host" to trust the host's CA. Defaults to "trusted".
##
rootCAs: ""

## @param serverAddr  This is the address of the ngrok server to connect to. You should set this if you are using a custom ingress address.
##
serverAddr: ""

## @param apiURL  This is the URL of the ngrok API. You should set this if you are using a custom API URL.
##
apiURL: "" # default to ngrok-api-go SDK's default

## @extra metaData DEPRECATED: Use ngrokMetadata instead
## @param ngrokMetadata This is a map of key=value,key=value pairs that will be added as metadata to all ngrok api resources created
##
ngrokMetadata: {}

## @param clusterDomain Configure the default cluster base domain for your kubernetes cluster DNS resolution
##
clusterDomain: svc.cluster.local

##
## @section Operator Manager parameters
##

## @param replicaCount The number of controllers to run.
## A minimum of 2 is recommended in production for HA.
##
replicaCount: 1

## @param affinity Affinity for the controller pod assignment
## ref: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity
## Note: podAffinityPreset, podAntiAffinityPreset, and  nodeAffinityPreset will be ignored when it's set
##
affinity: {}
## @param podAffinityPreset Pod affinity preset. Ignored if `affinity` is set. Allowed values: `soft` or `hard`
## ref: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity
##
podAffinityPreset: ""
## @param podAntiAffinityPreset Pod anti-affinity preset. Ignored if `affinity` is set. Allowed values: `soft` or `hard`
## Ref: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity
##
podAntiAffinityPreset: soft
## Node affinity preset
## Ref: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity
##
nodeAffinityPreset:
  ## @param nodeAffinityPreset.type Node affinity preset type. Ignored if `affinity` is set. Allowed values: `soft` or `hard`
  ##
  type: ""
  ## @param nodeAffinityPreset.key Node label key to match. Ignored if `affinity` is set.
  ## E.g.
  ## key: "kubernetes.io/e2e-az-name"
  ##
  key: ""
  ## @param nodeAffinityPreset.values Node label values to match. Ignored if `affinity` is set.
  ## E.g.
  ## values:
  ##   - e2e-az1
  ##   - e2e-az2
  ##
  values: []

## @param nodeSelector Node labels for manager pod(s)
## @param tolerations Tolerations for manager pod(s)
## @param topologySpreadConstraints Topology Spread Constraints for manager pod(s)
nodeSelector: {}
tolerations: []
topologySpreadConstraints: []

## @param priorityClassName Priority class for pod scheduling
## ref: https://kubernetes.io/docs/concepts/configuration/pod-priority-preemption/#priorityclass
##
priorityClassName: ""

## @param terminationGracePeriodSeconds The amount of time to wait for the pod to gracefully terminate
## ref: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination
## Increase this value to give the operator more time to clean up finalizers during shutdown
##
terminationGracePeriodSeconds: 30

## @param lifecycle an object containing lifecycle configuration
## ref: https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/
##
lifecycle: {}

## Pod Disruption Budget configuration
## ref: https://kubernetes.io/docs/tasks/run-application/configure-pdb/
## @param podDisruptionBudget.create Enable a Pod Disruption Budget creation
## @param podDisruptionBudget.maxUnavailable [string] Maximum number/percentage of pods that may be made unavailable
## @param podDisruptionBudget.minAvailable [string] Minimum number/percentage of pods that should remain scheduled
##
podDisruptionBudget:
  create: false
  maxUnavailable: "1"
  # minAvailable:

## Controller container resource requests and limits
## ref: https://kubernetes.io/docs/user-guide/compute-resources/
## We usually recommend not to specify default resources and to leave this as a conscious
## choice for the user. This also increases chances charts run on environments with little
## resources, such as Minikube. If you do want to specify resources, uncomment the following
## lines, adjust them as necessary, and remove the curly braces after 'resources:'.
## @param resources.limits The resources limits for the container
## @param resources.requests The requested resources for the container
##
resources:
  ## Example:
  ## limits:
  ##    cpu: 100m
  ##    memory: 128Mi
  ##
  limits: {}
  ## Examples:
  ## requests:
  ##    cpu: 100m
  ##    memory: 128Mi
  ##
  requests: {}

## @param extraVolumes An array of extra volumes to add to the controller.
##
extraVolumes: []
## @param extraVolumeMounts An array of extra volume mounts to add to the controller.
##
extraVolumeMounts: []
##
## Example:
##
## extraVolumes:
## - name: test-volume
##   emptyDir: {}
## extraVolumeMounts:
## - name: test-volume
##   mountPath: /test-volume

## @param extraEnv an object of extra environment variables to add to the controller.
##
extraEnv: {}
## Example:
##   MY_VAR: test
##   MY_SECRET_VAR:
##     secretKeyRef:
##       key: test-key
##       value: test-value
##   NGROK_OPERATOR_RESTART_ON_CERT_CHANGE: "false"

## Controller Service Account Settings
## @param serviceAccount.create Specifies whether a ServiceAccount should be created
## @param serviceAccount.name The name of the ServiceAccount to use.
## If not set and create is true, a name is generated using the fullname template
## @param serviceAccount.annotations Additional annotations to add to the ServiceAccount
##
serviceAccount:
  create: true
  name: ""
  annotations: {}

## CRD Access Role Settings
## @param crdAccessRoles.create Whether to create editor/viewer ClusterRoles for CRDs
## @param crdAccessRoles.annotations Annotations for CRD access ClusterRoles (e.g., RBAC aggregation)
## Commonly used for RBAC role aggregation (e.g., aggregate into the built-in admin/edit roles).
##
crdAccessRoles:
  create: true
  annotations: {}

## @param defaultDomainReclaimPolicy The default domain reclaim policy to use for domains created by the operator. Valid values are "Delete" and "Retain". The default is "Delete".
defaultDomainReclaimPolicy: "Delete"

##
## @section Logging configuration
##
## @param log.level The level to log at. One of 'debug', 'info', or 'error'.
## @param log.stacktraceLevel The level to report stacktrace logs one of 'info' or 'error'.
## @param log.format The log format to use. One of console, json.
##
log:
  format: json
  level: info
  stacktraceLevel: error

##
## @section Credentials configuration
##
## @param credentials.secret.name The name of the secret the credentials are in. If not provided, one will be generated using the helm release name.
## @param credentials.apiKey Your ngrok API key. If provided, it will be written to the secret and the authtoken must be provided as well.
## @param credentials.authtoken Your ngrok authtoken. If provided, it will be written to the secret and the apiKey must be provided as well.
##
credentials:
  secret:
    name: ""
  apiKey: ""
  authtoken: ""

##
## @section Kubernetes Ingress feature configuration
##
## @extra ingressClass.name DEPRECATED: Use ingress.ingressClass.name instead
## @extra ingressClass.create DEPRECATED: Use ingress.ingressClass.create instead
## @extra ingressClass.default DEPRECATED: Use ingress.ingressClass.default instead
## @extra watchNamespace DEPRECATED: Use ingress.watchNamespace instead
## @extra controllerName DEPRECATED: Use ingress.controllerName instead
## @param ingress.enabled When true, enable the Ingress controller features
## @param ingress.ingressClass.name The name of the ingress class to use.
## @param ingress.ingressClass.create Whether to create the ingress class.
## @param ingress.ingressClass.default Whether to set the ingress class as default.
## @param ingress.watchNamespace The namespace to watch for ingress resources (default all)
## @param ingress.controllerName The name of the controller to look for matching ingress classes
##
ingress:
  enabled: true # enabled by default
  controllerName: "k8s.ngrok.com/ingress-controller"
  watchNamespace: "" # default all
  ingressClass:
    name: ngrok
    create: true
    default: false

##
## @section Agent configuration
##
## @param agent.podAnnotations Custom pod annotations to apply to agent pods. If not set, falls back to podAnnotations.
## @param agent.priorityClassName Priority class for pod scheduling.
## @param agent.replicaCount The number of agents to run.
## @param agent.serviceAccount.create Specifies whether a ServiceAccount should be created for the agent.
## @param agent.serviceAccount.name The name of the ServiceAccount to use for the agent.
## If not set and create is true, a name is generated using the fullname template
## @param agent.serviceAccount.annotations Additional annotations to add to the agent ServiceAccount
agent:
  podAnnotations: {}
  priorityClassName: ""

  replicaCount: 1

  ## Agent container resource requests and limits
  ## ref: https://kubernetes.io/docs/user-guide/compute-resources/
  ## We usually recommend not to specify default resources and to leave this as a conscious
  ## choice for the user. This also increases chances charts run on environments with little
  ## resources, such as Minikube. If you do want to specify resources, uncomment the following
  ## lines, adjust them as necessary, and remove the curly braces after 'resources:'.
  ## @param agent.resources.limits The resources limits for the container
  ## @param agent.resources.requests The requested resources for the container
  ##
  resources:
    ## Example:
    ## limits:
    ##    cpu: 100m
    ##    memory: 128Mi
    ##
    limits: {}
    ## Examples:
    ## requests:
    ##    cpu: 100m
    ##    memory: 128Mi
    ##
    requests: {}

  serviceAccount:
    create: true
    name: ""
    annotations: {}

  ## @param agent.updateStrategy.type Agent update strategy
  ## @skip agent.updateStrategy.rollingUpdate
  ## ref: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#update-strategies
  ##
  updateStrategy:
    ## StrategyType
    ## Can be set to RollingUpdate, OnDelete (statefulset), Recreate (deployment)
    ##
    type: RollingUpdate

  ## @param agent.terminationGracePeriodSeconds The amount of time to wait for the agent pod to gracefully terminate
  ## ref: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination
  ## Increase this value to give the operator more time to clean up finalizers during shutdown
  ##
  terminationGracePeriodSeconds: 30

  ## @param agent.tolerations Tolerations for the agent pod(s)
  tolerations: []

  ## @param agent.nodeSelector Node labels for the agent pod(s)
  nodeSelector: {}

  ## @param agent.topologySpreadConstraints Topology Spread Constraints for the agent pod(s)
  topologySpreadConstraints: []

##
## @section Kubernetes Gateway feature configuration
##
## @param gateway.enabled When true, Gateway API support will be enabled if the CRDs are detected. When false, Gateway API support will never be enabled
## @param gateway.disableReferenceGrants When true, disables required ReferenceGrants for cross-namespace references. Does nothing when gateway.enabled is false
##
gateway:
  enabled: true # Enabled by default if the Gateway API CRDs are detected
  disableReferenceGrants: false

##
## @section Kubernetes Bindings feature configuration
##
## @param bindings.enabled Whether to enable the Endpoint Bindings feature
## @param bindings.endpointSelectors List of cel expressions used to filter which kubernetes-bound endpoints should be projected into this cluster
## @param bindings.serviceAnnotations Annotations to add to projected services bound to an endpoint
## @param bindings.serviceLabels Labels to add to projected services bound to an endpoint
## @param bindings.ingressEndpoint The hostname of the ingress endpoint for the bindings
##
bindings:
  enabled: false # in-development
  endpointSelectors:
  - "true"
  serviceAnnotations: {}
  serviceLabels: {}
  ingressEndpoint: "kubernetes-binding-ingress.ngrok.io:443"

  forwarder:
    ## @param bindings.forwarder.replicaCount The number of bindings forwarders to run.
    ##
    replicaCount: 1

    ## Bindings Forwarder container resource requests and limits
    ## ref: https://kubernetes.io/docs/user-guide/compute-resources/
    ## We usually recommend not to specify default resources and to leave this as a conscious
    ## choice for the user. This also increases chances charts run on environments with little
    ## resources, such as Minikube. If you do want to specify resources, uncomment the following
    ## lines, adjust them as necessary, and remove the curly braces after 'resources:'.
    ## @param bindings.forwarder.resources.limits The resources limits for the container
    ## @param bindings.forwarder.resources.requests The requested resources for the container
    resources:
      ## Example:
      ## limits:
      ##    cpu: 100m
      ##    memory: 128Mi
      ##
      limits: {}
      ## Examples:
      ## requests:
      ##    cpu: 100m
      ##    memory: 128Mi
      ##
      requests: {}


    ## @param bindings.forwarder.serviceAccount.create Specifies whether a ServiceAccount should be created for the bindings forwarder pod(s).
    ## @param bindings.forwarder.serviceAccount.name The name of the ServiceAccount to use for the bindings forwarder pod(s).
    ## If not set and create is true, a name is generated using the fullname template
    ## @param bindings.forwarder.serviceAccount.annotations Additional annotations to add to the bindings-forwarder ServiceAccount
    ##
    serviceAccount:
      create: true
      name: ""
      annotations: {}

    ## @param bindings.forwarder.updateStrategy.type Bindings Forwarder update strategy type
    ## @skip bindings.forwarder.updateStrategy.rollingUpdate
    ## ref: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#update-strategies
    ##
    updateStrategy:
      ## StrategyType
      ## Can be set to RollingUpdate, OnDelete (statefulset), Recreate (deployment)
      ##
      type: RollingUpdate

    ## @param bindings.forwarder.terminationGracePeriodSeconds The amount of time to wait for the bindings forwarder pod to gracefully terminate
    ## ref: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination
    ## Increase this value to give the operator more time to clean up finalizers during shutdown
    ##
    terminationGracePeriodSeconds: 30

    ## @param bindings.forwarder.tolerations Tolerations for the bindings forwarder pod(s)
    tolerations: []

    ## @param bindings.forwarder.nodeSelector Node labels for the bindings forwarder pod(s)
    nodeSelector: {}

    ## @param bindings.forwarder.topologySpreadConstraints Topology Spread Constraints for the bindings forwarder pod(s)
    topologySpreadConstraints: []

## @section Custom Resource Definitions installation
##

## @param installCRDs When true, the ngrok CRDs will be installed alongside the operator
installCRDs: true

##
## @section Cleanup Hook configuration
##
## @param drainPolicy Policy for what to do with ngrok API resources while draining during an Uninstall. "Delete" removes ngrok API resources, "Retain" preserves them
## @param cleanupHook.enabled Enable the pre-delete cleanup hook that drains resources before uninstall
## @param cleanupHook.timeout Timeout in seconds for the cleanup process
## @param cleanupHook.image.repository The repository for the kubectl image used by the cleanup hook
## @param cleanupHook.image.tag The tag for the kubectl image
## @param cleanupHook.image.pullPolicy The pull policy for the cleanup hook image
## @param cleanupHook.resources.limits.cpu CPU limit for the cleanup hook container
## @param cleanupHook.resources.limits.memory Memory limit for the cleanup hook container
## @param cleanupHook.resources.requests.cpu CPU request for the cleanup hook container
## @param cleanupHook.resources.requests.memory Memory request for the cleanup hook container
##
drainPolicy: "Retain"  # "Delete" or "Retain"

cleanupHook:
  enabled: true
  timeout: 300
  image:
    repository: bitnami/kubectl
    tag: latest
    pullPolicy: IfNotPresent
  resources:
    limits:
      cpu: 100m
      memory: 128Mi
    requests:
      cpu: 50m
      memory: 64Mi

```

## Common configurations

This section provides some common use cases and recommendations when using this helm chart in a production setting.

### Deployment scaling

By default, the replica count is set to 1 via `replicaCount`. Override this to 2 or more to ensure high availability during roll-outs and failures, and to spread out the load.

### ngrok region

ngrok runs globally distributed tunnel servers around the world to enable fast, low latency traffic to your applications. See [ngrok's points of presence](/gateway/points-of-presence/) for more information on ngrok's regions.

Similar to the agent, if you do not explicitly pick a region via helm when installing the Operator, the Operator will attempt to pick the region with the least latency, which is usually the one geographically closest to your machine. Specifying a region applies this setting across all agent connect URLs in your cluster; regions cannot currently be configured on a per-connection basis.

See the [helm value `region`](https://github.com/ngrok/ngrok-operator/blob/main/helm/ngrok-operator/values.yaml#L47) to configure a specific region for the controller to use.

### Watching specific namespaces

By default, the Operator watches all namespaces. It's a common use case to need a controller to watch only a specific namespace in the case where you may run a controller in a namespace for each team or environment. In order to watch only a specific namespace for ingress objects, you can set the helm value `watchNamespace` to the namespace you want to watch.