Skip to main content

​
KubernetesOperator custom resource

​
apiVersion: ngrok.k8s.ngrok.com/v1alpha1

​
kind: KubernetesOperator

The KubernetesOperator custom resource handles synchronizing the state of your ngrok Kubernetes Operator instance with the ngrok API. A KubernetesOperator resource is created automatically when you install the ngrok Operator with Helm and has configuration that matches your installation options from Helm so that you can identify it in the ngrok cloud.

​
KubernetesOperator structure and types

The following outlines the high level structure and typings of a KubernetesOperator 
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: KubernetesOperator
metadata:
  name: <string>
  namespace: <string>
spec:
  description: <string>           # optional, default: "Created by the ngrok-operator"
  metadata: <string>              # optional, default: "{"owned-by":"ngrok-operator"}"
  enabledFeatures: <[]string>     # optional
  region: <string>                # required, default: "global"
  deployment:                     # optional
    name: <string>                # required
    namespace: <string>           # required
    version: <string>             # required
  binding:                        # optional
    endpointSelectors: <[]string> # required
    ingressEndpoint: <string>     # optional
    tlsSecretName: <string>       # required, default: "default-tls"
  drain:                          # optional
    policy: <string>              # optional, default: "Retain"

​
KubernetesOperator fields

The following sections outline each field of the KubernetesOperator custom resource, whether they are required, what their default values are (if applicable), and a description of their purpose/constraints.

​
spec

spec defines the desired state of the KubernetesOperator Type: Object Required: yes Default: none Fields:
Field NameTypeRequiredDefaultDescription
spec.descriptionstringno"Created by the ngrok-operator"Human-readable description for this KubernetesOperator to help identify/describe it
spec.metadatastringno"{"owned-by":"ngrok-operator"}"String of arbitrary data associated with the object in the ngrok API/Dashboard
spec.enabledFeatures[]string (enum)nononeList of the features that are enabled for this instance of the ngrok Kubernetes Operator
spec.regionstringyes"global"The ngrok region in which the ingress for this Operator is served
spec.deploymentObjectnononeDeployment information for this instance of the ngrok Kubernetes Operator
spec.bindingObjectnononeConfiguration of the binding feature for this instance of the ngrok Kubernetes Operator
spec.drainObjectnononeConfiguration of the drain behavior during operator uninstall

​
spec.description

Human-readable description of this object that can be used to help identify/describe it. Type: string Required: no Default: "Created by the ngrok-operator"

​
spec.metadata

String of arbitrary data associated with the object in the ngrok API/Dashboard. Type: string Required: no Default: "{"owned-by":"ngrok-operator"}"

​
spec.enabledFeatures

List of the features that are enabled for this instance of the ngrok Kubernetes Operator Type: []string Required: no Default: none Allowed Values: "ingress", "gateway", "bindings"

​
spec.region

The ngrok region in which the ingress for this Operator is served. Type: string (enum) Required: no Default: "global" Allowed Values: "au", "eu", "ap", "us", "jp", "in", "sa", "global"

​
spec.deployment

Deployment information for this instance of the ngrok Kubernetes Operator. Type: Object Required: no Default: none Fields:
Field NameTypeRequiredDefaultDescription
spec.deployment.namestringyesnoneThe name of the Kubernetes Deployment for this intance of the ngrok Kubernetes Operator
spec.deployment.namespacestringyesnoneThe namespace of the Kubernetes Deployment for this intance of the ngrok Kubernetes Operator
spec.deployment.versionstringyesnoneThe version of the Kubernetes Deployment for this intance of the ngrok Kubernetes Operator

​
spec.deployment.name

The name of the Kubernetes Deployment for this intance of the ngrok Kubernetes Operator Type: string Required: yes Default: none

​
spec.deployment.namespace

The namespace of the Kubernetes Deployment for this intance of the ngrok Kubernetes Operator Type: string Required: yes Default: none

​
spec.deployment.version

The version of the Kubernetes Deployment for this intance of the ngrok Kubernetes Operator Type: string Required: yes Default: none

​
spec.binding

Configuration of the binding feature for this intance of the ngrok Kubernetes Operator Type: Object Required: no Default: none Fields:
Field NameTypeRequiredDefaultDescription
spec.binding.endpointSelectors[]stringyesnoneList of CEL expressions that determine which kubernetes-bound Endpoints will be created by the Operator
spec.binding.ingressEndpointstringnononeThe public ingress endpoint for this Kubernetes Operator
spec.binding.tlsSecretNamestringyesnoneThe name of the Kubernetes Secret that contains the TLS private/public keys to use for the ngrok forwarding endpoint

​
spec.binding.endpointSelectors

List of cel expression that determine which kubernetes-bound Endpoints will be created by the Operator Type: []string Required: yes Default: none

​
spec.binding.ingressEndpoint

The public ingress endpoint for this Kubernetes Operator Type: string Required: no Default: none

​
spec.binding.tlsSecretName

The name of the Kubernetes Secret that contains the TLS private/public keys to use for the ngrok forwarding endpoint Type: string Required: yes Default: "default-tls"

​
spec.drain

Configuration of the drain behavior during operator uninstall. For more information, see Uninstalling the Operator. Type: Object Required: no Default: none Fields:
Field NameTypeRequiredDefaultDescription
spec.drain.policystring (enum)no"Retain"Determines whether to delete ngrok API resources or just remove finalizers during drain

​
spec.drain.policy

Determines how ngrok API resources are handled when the operator is uninstalled. Type: string (enum) Required: no Default: "Retain" Allowed Values: "Delete", "Retain"
  • Retain: removes finalizers from custom resources but preserves ngrok API resources in your account
  • Delete: deletes each custom resource and waits for the operator to clean up the corresponding ngrok API resource

​
Status fields

The KubernetesOperator resource includes status information that reflects the current state of the operator and its registration with the ngrok API.

​
status.id

The unique identifier for this Kubernetes Operator in the ngrok API. Type: string

​
status.uri

The URI for this Kubernetes Operator in the ngrok API. Type: string

​
status.registrationStatus

The status of the registration of this Kubernetes Operator with the ngrok API. Type: string (enum) Allowed Values: "registered", "error", "pending"

​
status.registrationErrorCode

The ngrok error code if registration failed. Type: string Pattern: ERR_NGROK_<number>

​
status.errorMessage

A free-form error message if the registration status is error. Type: string

​
status.enabledFeatures

String representation of the features enabled for this Kubernetes Operator. Type: string

​
status.bindingsIngressEndpoint

The URL that the operator uses to talk to the ngrok edge when forwarding traffic for kubernetes-bound endpoints. Type: string

​
status.drainStatus

Indicates the current state of the drain process during uninstall. Type: string (enum) Allowed Values: "pending", "draining", "completed", "failed"

​
status.drainMessage

Human-readable information about the current drain state. Type: string

​
status.drainProgress

Indicates how many resources have been drained versus total. Format: X/Y where X is the number processed (completed + failed) and Y is total. Type: string Example: "5/10"

​
status.drainErrors

List of the most recent errors encountered during drain. Type: []string

​
Status examples

​
Registered Operator

status:
  id: k8sop_2example123
  uri: /kubernetes_operators/k8sop_2example123
  registrationStatus: registered
  enabledFeatures: ingress,gateway,bindings

​
Operator draining during uninstall

status:
  id: k8sop_2example123
  uri: /kubernetes_operators/k8sop_2example123
  registrationStatus: registered
  drainStatus: draining
  drainMessage: "Draining resources"
  drainProgress: "3/10"

​
Drain completed with errors

status:
  id: k8sop_2example123
  uri: /kubernetes_operators/k8sop_2example123
  registrationStatus: registered
  drainStatus: failed
  drainMessage: "Drain completed with errors"
  drainProgress: "10/10"
  drainErrors:
  - "failed to delete CloudEndpoint my-endpoint: HTTP 500: internal server error"

​
Example KubernetesOperator

apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: KubernetesOperator
metadata:
  name: ngrok-operator
  namespace: ngrok-operator
spec:
  description: Created by ngrok-operator
  metadata: '{"owned-by":"ngrok-operator"}'
  binding:
    endpointSelectors:
    - "true"
    ingressEndpoint: kubernetes-binding-ingress.ngrok.io:443
    tlsSecretName: ngrok-operator-default-tls
  deployment:
    name: ngrok-operator
    namespace: ngrok-operator
    version: 0.15.0
  enabledFeatures:
  - ingress
  - gateway
  - bindings
  region: global