> ## 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.

# KubernetesOperator

> Reference documentation for the KubernetesOperator custom resource that synchronizes ngrok operator state with the ngrok API.

## 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`

```yaml theme={null}
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`](#specdescription)         | `string`          | no       | `"Created by the ngrok-operator"` | Human-readable description for this `KubernetesOperator` to help identify/describe it    |
| [`spec.metadata`](#specmetadata)               | `string`          | no       | `"{"owned-by":"ngrok-operator"}"` | String of arbitrary data associated with the object in the ngrok API/Dashboard           |
| [`spec.enabledFeatures`](#specenabledfeatures) | `[]string` (enum) | no       | none                              | List of the features that are enabled for this instance of the ngrok Kubernetes Operator |
| [`spec.region`](#specregion)                   | `string`          | yes      | `"global"`                        | The ngrok region in which the ingress for this Operator is served                        |
| [`spec.deployment`](#specdeployment)           | `Object`          | no       | none                              | Deployment information for this instance of the ngrok Kubernetes Operator                |
| [`spec.binding`](#specbinding)                 | `Object`          | no       | none                              | Configuration of the binding feature for this instance of the ngrok Kubernetes Operator  |
| [`spec.drain`](#specdrain)                     | `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`](#specdeploymentname)           | `string` | yes      | none    | The name of the Kubernetes `Deployment` for this intance of the ngrok Kubernetes Operator      |
| [`spec.deployment.namespace`](#specdeploymentnamespace) | `string` | yes      | none    | The namespace of the Kubernetes `Deployment` for this intance of the ngrok Kubernetes Operator |
| [`spec.deployment.version`](#specdeploymentversion)     | `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`](#specbindingendpointselectors) | `[]string` | yes      | none    | List of CEL expressions that determine which kubernetes-bound Endpoints will be created by the Operator              |
| [`spec.binding.ingressEndpoint`](#specbindingingressendpoint)     | `string`   | no       | none    | The public ingress endpoint for this Kubernetes Operator                                                             |
| [`spec.binding.tlsSecretName`](#specbindingtlssecretname)         | `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](/k8s/installation/uninstall).

**Type:** `Object`

**Required:** no

**Default:** none

**Fields:**

| Field Name                              | Type            | Required | Default    | Description                                                                             |
| --------------------------------------- | --------------- | -------- | ---------- | --------------------------------------------------------------------------------------- |
| [`spec.drain.policy`](#specdrainpolicy) | `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

```yaml theme={null}
status:
  id: k8sop_2example123
  uri: /kubernetes_operators/k8sop_2example123
  registrationStatus: registered
  enabledFeatures: ingress,gateway,bindings
```

### Operator draining during uninstall

```yaml theme={null}
status:
  id: k8sop_2example123
  uri: /kubernetes_operators/k8sop_2example123
  registrationStatus: registered
  drainStatus: draining
  drainMessage: "Draining resources"
  drainProgress: "3/10"
```

### Drain completed with errors

```yaml theme={null}
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

```yaml theme={null}
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
```