> ## 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 Agent Endpoints

> Learn about Kubernetes endpoints that provide secure, private connectivity to ngrok endpoints within Kubernetes clusters.

Kubernetes endpoints are secure, private endpoints that are only addressable
inside of Kubernetes clusters where you install the [Kubernetes
operator](/k8s/). They enable you to connect to ngrok endpoints without making
them publicly addressable.

Kubernetes endpoints have a
[binding](/gateway/bindings) of `kubernetes`.

## Quickstart

Create a Kubernetes endpoint by specifying binding of `kubernetes` when you
create an endpoint.

### 1. Install the ngrok Kubernetes Operator

```bash theme={null}
helm install ngrok-operator ngrok/ngrok-operator \
  --namespace ngrok-operator \
  --create-namespace \
  --set description="example Operator" \
  --set bindings.enabled=true \
  --set credentials.apiKey=$NGROK_API_KEY \
  --set credentials.authtoken=$NGROK_AUTHTOKEN
```

### 2. Create a new namespace

```bash theme={null}
kubectl create ns prod
```

### 3. Create an ngrok endpoint

Run the following command in the same ngrok account to create the kubernetes
bound endpoint. After the command completes, the ngrok Operator will [create
`Service` objects](#service-creation) in the kubernetes cluster matching the
endpoint's URL.

```bash theme={null}
ngrok http 80 --url http://customer-2.prod --binding kubernetes
```

### 4. Connect to the endpoint

Other pods in the Kubernetes cluster where the ngrok Operator is running can
connect to the bound endpoint.

```bash theme={null}
$ kubectl run -i --tty --rm debug --restart=Never --image=appropriate/curl -- /bin/sh
# curl http://customer-2.prod
```

Now your application is connected via a private Kubernetes endpoint.

## URLs

Kubernetes endpoint URL hostnames must be in the following format:

* `[http|tcp]://name.namespace[:port]`

The following restrictions are enforced:

* **Scheme** - Must be `http` or `tcp`. `https` and `tls` are not supported.
* **Hostname** - Hostnames must always be two parts separated by a single dot,
  for example, `foo.bar`. Wildcard hostnames are not allowed.
* **Port** - All port numbers \[1-65535] are valid. Port must be specified for
  `tcp` endpoints.
* **Namespacing** - Kubernetes endpoints are namespaced on a per-account basis.
  Two accounts may have kubernetes endpoints with the same URL (for example,
  [http://api.internal](http://api.internal)). Those endpoints will not conflict or
  [pool](/gateway/endpoint-pooling).

### URL examples

* `http://app.example`
* `http://app.example:12345`
* `tcp://app.example:443`
* `tcp://app.example:12345`
* `https://app.example` - invalid scheme `https`
* `tls://app.example:12345` - invalid scheme `tls`
* `http://app.foo.bar` - invalid hostname, must have only two parts
* `tcp://app.example` - tcp endpoint must specify port number

## Types and pooling

* Kubernetes endpoints support all [Endpoint
  Types](/gateway/types) (`agent` and `cloud`).
* Kubernetes endpoints support [Endpoint
  Pooling](/gateway/endpoint-pooling).

## Service creation

After a kubernetes-bound endpoint is created, the ngrok cloud service notifies
Kubernetes Operators that a new kubernetes-bound endpoint exists. Kubernetes
Operators create `v1.Service` objects in their Kubernetes clusters which
forward traffic they receive to the operators' pods.

### Cluster IP service

A Cluster IP service is created in the Operator's namespace.

```yaml theme={null}
apiVersion: v1
kind: Service
metadata:
  name: <endpoint-id> # the endpoint's ID
  namespace: ngrok-operator
spec:
  selector:
    app.kubernetes.io/name: ngrok-operator-forwarder
  ports:
    - protocol: TCP
      port: 80 # the endpoint url's port
      targetPort: <randomly_assigned> # assigned by Operator to target the ngrok-operator-forwarder container
```

### External name service

An External Name service is created in the namespace targeted by the second part
of the URL's hostname.

```yaml theme={null}
apiVersion: v1
kind: Service
metadata:
  name: customer-2 # first part of the URL's hostname
  namespace: prod ## second part of the URL's hostname
spec:
  # Point service at the Operator Forwarder
  type: ExternalName
  externalName: <endpoint-id>.ngrok-operator.svc.cluster.local
```

## How to update endpoint selectors

If you don't want all kubernetes endpoints in your account to appear inside of
a cluster, you may specify an Endpoint Selector which filters which Kubernetes
endpoints are projected into the cluster it runs in. Endpoint Selectors are a
CEL expression which is evaluated against each Kubernetes Endpoint in your
account. The Operator will only projects endpoints that the selector returns
`true` for.

See [the docs on enabling bindings](/k8s/guides/bindings/#enable-bindings-for-the-operator) to learn more.

## How to enable or disable Kubernetes endpoints on an existing installation

By default, if you don't change the default endpoint selector, all endpoints with a Kubernetes binding will be bound to the cluster the Operator is installed on. Changing the binding allows you to restrict which endpoints that Operator will handle.

See [the docs on enabling bindings](/k8s/guides/bindings/#enable-bindings-for-the-operator) to learn more.

## Coming soon

This feature is in developer preview—more documentation is coming soon.

## API

Kubernetes endpoints can be created programmatically. Consult the documentation
on \[Endpoint APIs]\(/api-reference/endpoints/list.

## Pricing

Kubernetes endpoints are available on the Pay-as-you-go plan. Consult the
[Endpoints Pricing](/gateway/endpoints/#pricing)
documentation for billing details.