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

# Using ngrok Custom Resources

> Learn how to use ngrok's custom resources with the ngrok Kubernetes Operator.

The following sections offer a brief guide on how using each of ngrok's custom resources work.
You can also head to the [Custom Resource Definition docs](/k8s/crds) for more detailed information about the structure of each resource and all of their fields.

## Using `AgentEndpoint`

The `AgentEndpoint` resource is used to create [Agent Endpoints](/gateway/agent-endpoints/) using the Operator.

At a high level, Agent Endpoints are endpoints that accept traffic and forward it to an upstream of your choice.
They may optionally include [Traffic Policy](/traffic-policy/) configuration specified in-line or as a reference to an `NgrokTrafficPolicy` resource.
The lifetime of these endpoints is tied to the lifetime of the "agent" responsible for them, in this scenario, the Operator is the "agent", so if the Operator is deleted, then the endpoint will be deleted.

The [endpoint types page](/k8s/guides/endpoint-types) showcases using different protocols with `AgentEndpoint` and/or `CloudEndpoint` resources.
See the [AgentEndpoint Reference](/k8s/crds/agentendpoint) for more detailed information about `AgentEndpoint` structure and fields.

### Public `AgentEndpoint`

The following example will create a publicly accessible `AgentEndpoint` that forwards traffic to a `Service` in the Kubernetes cluster.

```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
  name: example-agent-endpoint
spec:
  url: https://example-agent-endpoint.ngrok.io
  upstream:
    url: http://my-service.my-namespace:8080
```

### `AgentEndpoint` with in-line Traffic Policy

The following example showcases an `AgentEndpoint` with in-line Traffic Policy configuration

```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
  name: example-agent-endpoint
spec:
  url: https://example-agent-endpoint.ngrok.io
  upstream:
    url: http://my-service.my-namespace:8080
  trafficPolicy:
    inline:
      on_http_request:
      - name: example-rule
        expressions:
        - req.url.query_params['debug'][0]=='true'
        actions:
        - type: custom-response
          config:
            body: Example response from Traffic Policy
            headers:
              content-type: text/plain
            status_code: 200
```

### `AgentEndpoint` with referenced `NgrokTrafficPolicy`

The following example showcases an `AgentEndpoint` with Traffic Policy configuration from a referenced `NgrokTrafficPolicy` resource.

```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
  name: example-tp
  namespace: default
spec:
  policy:
    on_http_request:
    - name: example-rule
      expressions:
      - req.url.query_params['debug'][0]=='true'
      actions:
      - type: custom-response
        config:
          body: Example response from Traffic Policy
          headers:
            content-type: text/plain
          status_code: 200
---
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
  name: example-agent-endpoint
spec:
  url: https://example-agent-endpoint.ngrok.io
  upstream:
    url: http://my-service.my-namespace:8080
  trafficPolicy:
    targetRef:
      name: example-tp
```

### `AgentEndpoint` with client certificates

If you would like to enforce mutual TLS, you can reference `Secret` objects that contain client certificates that the Operator should use for the
`AgentEndpoint` when connecting to the upstream.

* The secrets are expected to contain the data in the keys `tls.crt` and `tls.key`.
* The `namespace` field is optional, and when not supplied, the namespace of the `AgentEndpoint` will be used.

```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
  name: example-agent-endpoint
spec:
  url: https://example-agent-endpoint.ngrok.io
  upstream:
    url: https://my-https-service.my-namespace:8443
  clientCertificateRefs:
  - name: my-client-cert
    namespace: default
```

## `AgentEndpoint` public URL versus upstream URL

With AgentEndpoints, while the public URL of an endpoint may have a scheme such as `http://`, the `upstream.url` for that endpoint does not need to also use the same scheme as the public URL.
You can create an endpoint with an `http://` scheme as the public URL and still use `https://` as the scheme for the upstream URL.
The following Agent Endpoint accepts cleartext HTTP connections at [http://example-http-domain.ngrok.app](http://example-http-domain.ngrok.app), and forwards to the kubernetes service `https://example-service.default` on port `443` over HTTPS.

```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
  name: example-agent-endpoint
  namespace: default
spec:
  url: http://example-http-domain.ngrok.app
  upstream:
    url: https://example-service.default:443
```

## Using `CloudEndpoint`

The `CloudEndpoint` resource is used to create [Cloud Endpoints](/gateway/cloud-endpoints/) using the Operator.

At a high level, Cloud Endpoints are endpoints that live in the ngrok cloud and are always online.
They may optionally include [Traffic Policy](/traffic-policy/) configuration specified in-line or as a reference to an `NgrokTrafficPolicy` resource.
Since they live in the ngrok cloud, Cloud Endpoints are always accessible, even if the cluster running your ngrok Operator goes down.

Unlike Agent Endpoints, Cloud Endpoints do not directly specify a local upstream to forward traffic to since they live in the cloud.
Their primary purpose is to run Traffic Policies which can be used to forward traffic to other endpoints.

A very common pattern is to make a publicly accessible Cloud Endpoint for a hostname that has Traffic Policy to forward traffic to one of several other Cloud or Agent endpoints depending on the path/headers/etc.

The [endpoint types page](/k8s/guides/endpoint-types) showcases using different protocols with `AgentEndpoint` and/or `CloudEndpoint` resources.
See the [CloudEndpoint Reference](/k8s/crds/cloudendpoint) for more detailed information about `CloudEndpoint` structure and fields.

### `CloudEndpoint` with in-line Traffic Policy

The following example showcases an `CloudEndpoint` with in-line Traffic Policy configuration

```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: CloudEndpoint
metadata:
  name: example-cloud-endpoint
spec:
  url: https://example-cloud-endpoint.ngrok.io
  trafficPolicy:
    policy:
      on_http_request:
      - name: example-rule
        actions:
        - type: custom-response
          config:
            body: Example response from Traffic Policy
            headers:
              content-type: text/plain
            status_code: 200
```

### `CloudEndpoint` with referenced `NgrokTrafficPolicy`

The following example showcases an `CloudEndpoint` with Traffic Policy configuration from a referenced `NgrokTrafficPolicy` resource.

```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
  name: static-response
  namespace: default
spec:
  policy:
    on_http_request:
    - name: example-rule
      actions:
      - type: custom-response
        config:
          body: Example response from Traffic Policy
          headers:
            content-type: text/plain
          status_code: 200
---
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: CloudEndpoint
metadata:
  name: example-cloud-endpoint
spec:
  url: https://example-cloud-endpoint.ngrok.io
  trafficPolicyName: static-response
```

### `CloudEndpoint` routing

For a more in-depth guide on using `CloudEndpoints` to forward requests to other endpoints using the `forward-internal` action, see the [request routing guide](/k8s/guides/how-to/request-routing)

## Using `NgrokTrafficPolicy`

`NgrokTrafficPolicy` allows you to specify a [Traffic Policy](/traffic-policy/) configuration to be used on one or more `Ingress`, `Gateway`, `CloudEndpoint`, or `AgentEndpoint` resources.

On their own, `NgrokTrafficPolicy` resources do not do anything unless attached to a `CloudEndpoint`, `Ingress`, etc.

The `CloudEndpoint` and `AgentEndpoint` custom resources allow you to choose whether you would like to supply Traffic Policy configuration in-line or as a reference to an `NgrokTrafficPolicy` resource.
This makes it easy to create common `NgrokTrafficPolicy` resources and reuse them on multiple different resources.

`Ingress` and Gateway API resources have several methods of accepting `NgrokTrafficPolicy` resources outlined in the [using ingresses](/k8s/guides/using-ingresses) and [using Gateway API](/k8s/guides/using-gwapi) pages.

The following example showcases creating an `NgrokTrafficPolicy` resource that will return a custom response when the `?debug=true` query parameter is sent with the request.

```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
  name: example-ngroktrafficpolicy
  namespace: default
spec:
  policy:
    on_http_request:
    - name: debug
      expressions:
      - req.url.query_params['debug'][0]=='true'
      actions:
      - type: custom-response
        config:
          body: Custom response from Traffic Policy
          headers:
            content-type: text/plain
          status_code: 200
```

See the [NgrokTrafficPolicy Reference](/k8s/crds/ngroktrafficpolicy) for more detailed information about `NgrokTrafficPolicy` structure and fields.

## Using `Domain`, `AgentEndpoint`, `BoundEndpoint`, and `KubernetesOperator`

`Domain`, `AgentEndpoint`, `BoundEndpoint`, and `KubernetesOperator` are all custom resources that you should not need to interface with directly very much.
They are created by the Operator in response to `AgentEndpoint`, `CloudEndpoint`, `Ingress`, and Gateway API resources. They exist primarily to provide feedback to the user about events and resources that are created in response to your configuration and help keep the state of your cluster configuration in-sync with the resources in your ngrok account.

You can use `kubectl describe` on any of them to check their status and conditions when debugging configuration.

**Domains**:

* Domains reserve domains in your ngrok that are used in hostnames across `Ingress`, etc. resources.
  * [Domain Reference](/k8s/crds/domain)
* **AgentEndpoints**:
  * AgentEndpoints establish connections to your upstream services to handle forwarding traffic.
  * [AgentEndpoint Reference](/k8s/crds/agentendpoint)
* **BoundEndpoints**:
  * BoundEndpoints project endpoints with a binding type of `kubernetes` into one or more Kubernetes clusters running the ngrok Operator.
  * For more information on endpoint bindings, refer to [the bindings page](/k8s/guides/bindings).
  * [BoundEndpoint Reference](/k8s/crds/boundendpoint)
* **KubernetesOperators**:
  * KubernetesOperators are used to synchronize the state of any instances of the ngrok Kubernetes Operator with your ngrok account.
  * [KubernetesOperator Reference](/k8s/crds/kubernetesoperator)

## Using edges

Edges are a deprecated custom resource that are not documented as they will be removed soon, so you should not start using Edges or create any new ones now.
For those who have installed an early release of the Operator and created any `HTTPSEdge` resources, they can be rewritten as `CloudEndpoint` and/or `AgentEndpoint` custom resources.
The same is true of the `NgrokModuleSet` resources that were the precursor to `NgrokTrafficPolicy`.
Edges will be completely removed prior to the 1.0 release of the ngrok Kubernetes Operator.