KubernetesOperator - ngrok documentation

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 Name	Type	Required	Default	Description
`spec.description`	`string`	no	`"Created by the ngrok-operator"`	Human-readable description for this `KubernetesOperator` to help identify/describe it
`spec.metadata`	`string`	no	`"{"owned-by":"ngrok-operator"}"`	String of arbitrary data associated with the object in the ngrok API/Dashboard
`spec.enabledFeatures`	`[]string` (enum)	no	none	List of the features that are enabled for this instance of the ngrok Kubernetes Operator
`spec.region`	`string`	yes	`"global"`	The ngrok region in which the ingress for this Operator is served
`spec.deployment`	`Object`	no	none	Deployment information for this instance of the ngrok Kubernetes Operator
`spec.binding`	`Object`	no	none	Configuration of the binding feature for this instance of the ngrok Kubernetes Operator
`spec.drain`	`Object`	no	none	Configuration 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 Name	Type	Required	Default	Description
`spec.deployment.name`	`string`	yes	none	The name of the Kubernetes `Deployment` for this intance of the ngrok Kubernetes Operator
`spec.deployment.namespace`	`string`	yes	none	The namespace of the Kubernetes `Deployment` for this intance of the ngrok Kubernetes Operator
`spec.deployment.version`	`string`	yes	none	The 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 Name	Type	Required	Default	Description
`spec.binding.endpointSelectors`	`[]string`	yes	none	List of CEL expressions that determine which kubernetes-bound Endpoints will be created by the Operator
`spec.binding.ingressEndpoint`	`string`	no	none	The public ingress endpoint for this Kubernetes Operator
`spec.binding.tlsSecretName`	`string`	yes	none	The 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 Name	Type	Required	Default	Description
`spec.drain.policy`	`string` (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 network 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

​KubernetesOperator custom resource

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

​kind: KubernetesOperator

​KubernetesOperator structure and types

​KubernetesOperator fields

​spec

​spec.description

​spec.metadata

​spec.enabledFeatures

​spec.region

​spec.deployment

​spec.deployment.name

​spec.deployment.namespace

​spec.deployment.version

​spec.binding

​spec.binding.endpointSelectors

​spec.binding.ingressEndpoint

​spec.binding.tlsSecretName

​spec.drain

​spec.drain.policy

​Status fields

​status.id

​status.uri

​status.registrationStatus

​status.registrationErrorCode

​status.errorMessage

​status.enabledFeatures

​status.bindingsIngressEndpoint

​status.drainStatus

​status.drainMessage

​status.drainProgress

​status.drainErrors

​Status examples

​Registered Operator

​Operator draining during uninstall

​Drain completed with errors

​Example KubernetesOperator