Kubernetes Operators - ngrok documentation

These endpoints are not intended to be accessed directly by users. They exist to be accessed by the Kubernetes Operator. They are documented here for completeness.

Create Kubernetes Operator

Create a new Kubernetes Operator

Request

POST /kubernetes_operators

Example Request

curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"deployment":{"name":"ngrok-operator","namespace":"ngrok-operator"},"description":"Example Kubernetes Operator","enabled_features":["Ingress"],"metadata":"{\"environment\": \"staging\"}","region":"global"}' \
https://api.ngrok.com/kubernetes_operators

Parameters

Name	Type	Description
`description`	string	human-readable description of this Kubernetes Operator. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Kubernetes Operator. optional, max 4096 bytes.
`enabled_features`	List<string>	features enabled for this Kubernetes Operator. a subset of “bindings”, “ingress”, and “gateway”
`region`	string	the ngrok region in which the ingress for this Operator is served. defaults to “global”
`deployment`	KubernetesOperatorDeployment	information about the deployment of this Kubernetes Operator
`binding`	KubernetesOperatorBindingCreate	configuration for the Bindings feature of this Kubernetes Operator. set only if enabling the “bindings” feature

KubernetesOperatorDeployment parameters

Name	Type	Description
`name`	string	the deployment name
`namespace`	string	the namespace this Kubernetes Operator is deployed to
`version`	string	the version of this Kubernetes Operator
`cluster_name`	string	user-given name for the cluster the Kubernetes Operator is deployed to

KubernetesOperatorBindingCreate parameters

Name	Type	Description
`endpoint_selectors`	List<string>	the list of cel expressions that filter the k8s bound endpoints for this Operator
`csr`	string	CSR is supplied during initial creation to enable creating a mutual TLS secured connection between ngrok and the Operator. This is an internal implementation detail and subject to change.
`ingress_endpoint`	string	the public ingress endpoint for this Kubernetes Operator

Response

Returns a 201 response on success

Example Response

{
  "binding": {
    "cert": {
      "cert": "",
      "not_after": "0001-01-01T00:00:00Z",
      "not_before": "0001-01-01T00:00:00Z"
    },
    "endpoint_selectors": null
  },
  "created_at": "2025-09-04T10:11:43Z",
  "deployment": {
    "cluster_name": "",
    "name": "ngrok-operator",
    "namespace": "ngrok-operator",
    "version": ""
  },
  "description": "Example Kubernetes Operator",
  "enabled_features": [
    "ingress"
  ],
  "id": "k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT",
  "metadata": "{\"environment\": \"staging\"}",
  "principal": {
    "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
    "uri": ""
  },
  "region": "global",
  "updated_at": "2025-09-04T10:11:43Z",
  "uri": "https://api.ngrok.com/kubernetes_operators/k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT"
}

Fields

Name	Type	Description
`id`	string	unique identifier for this Kubernetes Operator
`uri`	string	URI of this Kubernetes Operator API resource
`created_at`	string	timestamp when the Kubernetes Operator was created. RFC 3339 format
`updated_at`	string	timestamp when the Kubernetes Operator was last updated. RFC 3339 format
`description`	string	human-readable description of this Kubernetes Operator. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Kubernetes Operator. optional, max 4096 bytes.
`principal`	Ref	the principal who created this Kubernetes Operator
`enabled_features`	List<string>	features enabled for this Kubernetes Operator. a subset of “bindings”, “ingress”, and “gateway”
`region`	string	the ngrok region in which the ingress for this Operator is served. defaults to “global”
`deployment`	KubernetesOperatorDeployment	information about the deployment of this Kubernetes Operator
`binding`	KubernetesOperatorBinding	information about the Bindings feature of this Kubernetes Operator, if enabled

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

KubernetesOperatorDeployment fields

Name	Type	Description
`name`	string	the deployment name
`namespace`	string	the namespace this Kubernetes Operator is deployed to
`version`	string	the version of this Kubernetes Operator
`cluster_name`	string	user-given name for the cluster the Kubernetes Operator is deployed to

KubernetesOperatorBinding fields

Name	Type	Description
`endpoint_selectors`	List<string>	the list of cel expressions that filter the k8s bound endpoints for this Operator
`cert`	KubernetesOperatorCert	the binding certificate information
`ingress_endpoint`	string	the public ingress endpoint for this Kubernetes Operator

KubernetesOperatorCert fields

Name	Type	Description
`cert`	string	the public client certificate generated for this Kubernetes Operator from the CSR supplied when enabling the Bindings feature
`not_before`	string	timestamp when the certificate becomes valid. RFC 3339 format
`not_after`	string	timestamp when the certificate becomes invalid. RFC 3339 format

Update Kubernetes Operator

Update an existing Kubernetes Operator by ID.

Request

PATCH /kubernetes_operators/{id}

Example Request

curl \
-X PATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"production\"}"}' \
https://api.ngrok.com/kubernetes_operators/k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT

Parameters

Name	Type	Description
`id`	string	unique identifier for this Kubernetes Operator
`description`	string	human-readable description of this Kubernetes Operator. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Kubernetes Operator. optional, max 4096 bytes.
`enabled_features`	List<string>	features enabled for this Kubernetes Operator. a subset of “bindings”, “ingress”, and “gateway”
`region`	string	the ngrok region in which the ingress for this Operator is served. defaults to “global”
`binding`	KubernetesOperatorBindingUpdate	configuration for the Bindings feature of this Kubernetes Operator. set only if enabling the “bindings” feature
`deployment`	KubernetesOperatorDeploymentUpdate	configuration for the Deployment info

KubernetesOperatorBindingUpdate parameters

Name	Type	Description
`endpoint_selectors`	List<string>	the list of cel expressions that filter the k8s bound endpoints for this Operator
`csr`	string	CSR is supplied during initial creation to enable creating a mutual TLS secured connection between ngrok and the Operator. This is an internal implementation detail and subject to change.
`ingress_endpoint`	string	the public ingress endpoint for this Kubernetes Operator

KubernetesOperatorDeploymentUpdate parameters

Name	Type	Description
`name`	string	the deployment name
`version`	string	the version of this Kubernetes Operator

Response

Returns a 200 response on success

Example Response

{
  "binding": {
    "cert": {
      "cert": "",
      "not_after": "0001-01-01T00:00:00Z",
      "not_before": "0001-01-01T00:00:00Z"
    },
    "endpoint_selectors": null,
    "ingress_endpoint": "connect.ngrok-endpoints.com:443"
  },
  "created_at": "2025-09-04T10:11:43Z",
  "deployment": {
    "cluster_name": "",
    "name": "ngrok-operator",
    "namespace": "ngrok-operator",
    "version": ""
  },
  "description": "Example Kubernetes Operator",
  "enabled_features": [
    "ingress"
  ],
  "id": "k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT",
  "metadata": "{\"environment\": \"production\"}",
  "principal": {
    "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
    "uri": ""
  },
  "region": "global",
  "updated_at": "2025-09-04T10:11:43Z",
  "uri": "https://api.ngrok.com/kubernetes_operators/k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT"
}

Fields

Name	Type	Description
`id`	string	unique identifier for this Kubernetes Operator
`uri`	string	URI of this Kubernetes Operator API resource
`created_at`	string	timestamp when the Kubernetes Operator was created. RFC 3339 format
`updated_at`	string	timestamp when the Kubernetes Operator was last updated. RFC 3339 format
`description`	string	human-readable description of this Kubernetes Operator. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Kubernetes Operator. optional, max 4096 bytes.
`principal`	Ref	the principal who created this Kubernetes Operator
`enabled_features`	List<string>	features enabled for this Kubernetes Operator. a subset of “bindings”, “ingress”, and “gateway”
`region`	string	the ngrok region in which the ingress for this Operator is served. defaults to “global”
`deployment`	KubernetesOperatorDeployment	information about the deployment of this Kubernetes Operator
`binding`	KubernetesOperatorBinding	information about the Bindings feature of this Kubernetes Operator, if enabled

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

KubernetesOperatorDeployment fields

Name	Type	Description
`name`	string	the deployment name
`namespace`	string	the namespace this Kubernetes Operator is deployed to
`version`	string	the version of this Kubernetes Operator
`cluster_name`	string	user-given name for the cluster the Kubernetes Operator is deployed to

KubernetesOperatorBinding fields

Name	Type	Description
`endpoint_selectors`	List<string>	the list of cel expressions that filter the k8s bound endpoints for this Operator
`cert`	KubernetesOperatorCert	the binding certificate information
`ingress_endpoint`	string	the public ingress endpoint for this Kubernetes Operator

KubernetesOperatorCert fields

Name	Type	Description
`cert`	string	the public client certificate generated for this Kubernetes Operator from the CSR supplied when enabling the Bindings feature
`not_before`	string	timestamp when the certificate becomes valid. RFC 3339 format
`not_after`	string	timestamp when the certificate becomes invalid. RFC 3339 format

Delete Kubernetes Operator

Delete a Kubernetes Operator

Request

DELETE /kubernetes_operators/{id}

Example Request

curl \
-X DELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/kubernetes_operators/k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT

Response

Returns a 204 response with no body on success

Get Kubernetes Operator

Get of a Kubernetes Operator

Request

GET /kubernetes_operators/{id}

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/kubernetes_operators/k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT

Response

Returns a 200 response on success

Example Response

{
  "binding": {
    "cert": {
      "cert": "",
      "not_after": "0001-01-01T00:00:00Z",
      "not_before": "0001-01-01T00:00:00Z"
    },
    "endpoint_selectors": null
  },
  "created_at": "2025-09-04T10:11:43Z",
  "deployment": {
    "cluster_name": "",
    "name": "ngrok-operator",
    "namespace": "ngrok-operator",
    "version": ""
  },
  "description": "Example Kubernetes Operator",
  "enabled_features": [
    "ingress"
  ],
  "id": "k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT",
  "metadata": "{\"environment\": \"staging\"}",
  "principal": {
    "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
    "uri": ""
  },
  "region": "global",
  "updated_at": "2025-09-04T10:11:43Z",
  "uri": "https://api.ngrok.com/kubernetes_operators/k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT"
}

Fields

Name	Type	Description
`id`	string	unique identifier for this Kubernetes Operator
`uri`	string	URI of this Kubernetes Operator API resource
`created_at`	string	timestamp when the Kubernetes Operator was created. RFC 3339 format
`updated_at`	string	timestamp when the Kubernetes Operator was last updated. RFC 3339 format
`description`	string	human-readable description of this Kubernetes Operator. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Kubernetes Operator. optional, max 4096 bytes.
`principal`	Ref	the principal who created this Kubernetes Operator
`enabled_features`	List<string>	features enabled for this Kubernetes Operator. a subset of “bindings”, “ingress”, and “gateway”
`region`	string	the ngrok region in which the ingress for this Operator is served. defaults to “global”
`deployment`	KubernetesOperatorDeployment	information about the deployment of this Kubernetes Operator
`binding`	KubernetesOperatorBinding	information about the Bindings feature of this Kubernetes Operator, if enabled

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

KubernetesOperatorDeployment fields

Name	Type	Description
`name`	string	the deployment name
`namespace`	string	the namespace this Kubernetes Operator is deployed to
`version`	string	the version of this Kubernetes Operator
`cluster_name`	string	user-given name for the cluster the Kubernetes Operator is deployed to

KubernetesOperatorBinding fields

Name	Type	Description
`endpoint_selectors`	List<string>	the list of cel expressions that filter the k8s bound endpoints for this Operator
`cert`	KubernetesOperatorCert	the binding certificate information
`ingress_endpoint`	string	the public ingress endpoint for this Kubernetes Operator

KubernetesOperatorCert fields

Name	Type	Description
`cert`	string	the public client certificate generated for this Kubernetes Operator from the CSR supplied when enabling the Bindings feature
`not_before`	string	timestamp when the certificate becomes valid. RFC 3339 format
`not_after`	string	timestamp when the certificate becomes invalid. RFC 3339 format

List Kubernetes operators

List all Kubernetes Operators owned by this account

Request

GET /kubernetes_operators

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/kubernetes_operators

Response

Returns a 200 response on success

Example Response

{
  "next_page_uri": null,
  "operators": [
    {
      "binding": {
        "cert": {
          "cert": "",
          "not_after": "0001-01-01T00:00:00Z",
          "not_before": "0001-01-01T00:00:00Z"
        },
        "endpoint_selectors": null
      },
      "created_at": "2025-09-04T10:11:43Z",
      "deployment": {
        "cluster_name": "",
        "name": "ngrok-operator",
        "namespace": "ngrok-operator",
        "version": ""
      },
      "description": "Example Kubernetes Operator",
      "enabled_features": [
        "ingress"
      ],
      "id": "k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT",
      "metadata": "{\"environment\": \"staging\"}",
      "principal": {
        "id": "usr_32ELAUA7XkJHRP2DgH2JjDRLp81",
        "uri": ""
      },
      "region": "global",
      "updated_at": "2025-09-04T10:11:43Z",
      "uri": "https://api.ngrok.com/kubernetes_operators/k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT"
    }
  ],
  "uri": "https://api.ngrok.com/kubernetes_operators"
}

Fields

Name	Type	Description
`operators`	KubernetesOperator	the list of Kubernetes Operators for this account
`uri`	string
`next_page_uri`	string	URI of the next page, or null if there is no next page

KubernetesOperator fields

Name	Type	Description
`id`	string	unique identifier for this Kubernetes Operator
`uri`	string	URI of this Kubernetes Operator API resource
`created_at`	string	timestamp when the Kubernetes Operator was created. RFC 3339 format
`updated_at`	string	timestamp when the Kubernetes Operator was last updated. RFC 3339 format
`description`	string	human-readable description of this Kubernetes Operator. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Kubernetes Operator. optional, max 4096 bytes.
`principal`	Ref	the principal who created this Kubernetes Operator
`enabled_features`	List<string>	features enabled for this Kubernetes Operator. a subset of “bindings”, “ingress”, and “gateway”
`region`	string	the ngrok region in which the ingress for this Operator is served. defaults to “global”
`deployment`	KubernetesOperatorDeployment	information about the deployment of this Kubernetes Operator
`binding`	KubernetesOperatorBinding	information about the Bindings feature of this Kubernetes Operator, if enabled

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

KubernetesOperatorDeployment fields

Name	Type	Description
`name`	string	the deployment name
`namespace`	string	the namespace this Kubernetes Operator is deployed to
`version`	string	the version of this Kubernetes Operator
`cluster_name`	string	user-given name for the cluster the Kubernetes Operator is deployed to

KubernetesOperatorBinding fields

Name	Type	Description
`endpoint_selectors`	List<string>	the list of cel expressions that filter the k8s bound endpoints for this Operator
`cert`	KubernetesOperatorCert	the binding certificate information
`ingress_endpoint`	string	the public ingress endpoint for this Kubernetes Operator

KubernetesOperatorCert fields

Name	Type	Description
`cert`	string	the public client certificate generated for this Kubernetes Operator from the CSR supplied when enabling the Bindings feature
`not_before`	string	timestamp when the certificate becomes valid. RFC 3339 format
`not_after`	string	timestamp when the certificate becomes invalid. RFC 3339 format

GetBoundEndpoints Kubernetes Operator

List Endpoints bound to a Kubernetes Operator

Request

GET /kubernetes_operators/{id}/bound_endpoints

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/kubernetes_operators/k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT/bound_endpoints

Response

Returns a 200 response on success

Example Response

{
  "endpoints": [],
  "next_page_uri": null,
  "uri": "https://api.ngrok.com/kubernetes_operators/k8sop_32ELIMnXLu9Qkpj1OddUYoLIHfT/bound_endpoints"
}

Fields

Name	Type	Description
`endpoints`	Endpoint	the list of all active endpoints on this account
`uri`	string	URI of the endpoints list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

Endpoint fields

Name	Type	Description
`id`	string	unique endpoint resource identifier
`region`	string	identifier of the region this endpoint belongs to
`created_at`	string	timestamp when the endpoint was created in RFC 3339 format
`updated_at`	string	timestamp when the endpoint was updated in RFC 3339 format
`public_url`	string	URL of the hostport served by this endpoint
`proto`	string	protocol served by this endpoint. one of `http`, `https`, `tcp`, or `tls`
`scheme`	string
`hostport`	string	hostport served by this endpoint (hostname:port) -> soon to be deprecated
`host`	string
`port`	int64
`type`	string	whether the endpoint is `ephemeral` (served directly by an agent-initiated tunnel) or `edge` (served by an edge) or `cloud (represents a Cloud Endpoint)`
`metadata`	string	user-supplied metadata of the associated tunnel or edge object
`description`	string	user-supplied description of the associated tunnel
`domain`	Ref	the domain reserved for this endpoint
`tcp_addr`	Ref	the address reserved for this endpoint
`tunnel`	Ref	the tunnel serving requests to this endpoint, if this is an ephemeral endpoint
`edge`	Ref	the edge serving requests to this endpoint, if this is an edge endpoint
`upstream_url`	string	the local address the tunnel forwards to
`upstream_protocol`	string	the protocol the agent uses to forward with
`url`	string	the URL of the endpoint
`principal`	Ref	The ID of the owner (bot or user) that owns this endpoint
`traffic_policy`	string	The Traffic Policy attached to this endpoint
`bindings`	List<string>	the bindings associated with this endpoint
`tunnel_session`	Ref	The tunnel session of the agent for this endpoint
`uri`	string	URI of the clep API resource
`name`	string	user supplied name for the endpoint
`pooling_enabled`	boolean	whether the endpoint allows pooling

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

​Create Kubernetes Operator

​Request

​Example Request

​Parameters

​KubernetesOperatorDeployment parameters

​KubernetesOperatorBindingCreate parameters

​Response

​Example Response

​Fields

​Ref fields

​KubernetesOperatorDeployment fields

​KubernetesOperatorBinding fields

​KubernetesOperatorCert fields

​Update Kubernetes Operator

​Request

​Example Request

​Parameters

​KubernetesOperatorBindingUpdate parameters

​KubernetesOperatorDeploymentUpdate parameters

​Response

​Example Response

​Fields

​Ref fields

​KubernetesOperatorDeployment fields

​KubernetesOperatorBinding fields

​KubernetesOperatorCert fields

​Delete Kubernetes Operator

​Request

​Example Request

​Response

​Get Kubernetes Operator

​Request

​Example Request

​Response

​Example Response

​Fields

​Ref fields

​KubernetesOperatorDeployment fields

​KubernetesOperatorBinding fields

​KubernetesOperatorCert fields

​List Kubernetes operators

​Request

​Example Request

​Response

​Example Response

​Fields

​KubernetesOperator fields

​Ref fields

​KubernetesOperatorDeployment fields

​KubernetesOperatorBinding fields

​KubernetesOperatorCert fields

​GetBoundEndpoints Kubernetes Operator

​Request

​Example Request

​Response

​Example Response

​Fields

​Endpoint fields

​Ref fields

Create Kubernetes Operator

Request

Example Request

Parameters

KubernetesOperatorDeployment parameters

KubernetesOperatorBindingCreate parameters

Response

Example Response

Fields

Ref fields

KubernetesOperatorDeployment fields

KubernetesOperatorBinding fields

KubernetesOperatorCert fields

Update Kubernetes Operator

Request

Example Request

Parameters

KubernetesOperatorBindingUpdate parameters

KubernetesOperatorDeploymentUpdate parameters

Response

Example Response

Fields

Ref fields

KubernetesOperatorDeployment fields

KubernetesOperatorBinding fields

KubernetesOperatorCert fields

Delete Kubernetes Operator

Request

Example Request

Response

Get Kubernetes Operator

Request

Example Request

Response

Example Response

Fields

Ref fields

KubernetesOperatorDeployment fields

KubernetesOperatorBinding fields

KubernetesOperatorCert fields

List Kubernetes operators

Request

Example Request

Response

Example Response

Fields

KubernetesOperator fields

Ref fields

KubernetesOperatorDeployment fields

KubernetesOperatorBinding fields

KubernetesOperatorCert fields

GetBoundEndpoints Kubernetes Operator

Request

Example Request

Response

Example Response

Fields

Endpoint fields

Ref fields