> ## 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. # AgentEndpoint > Reference documentation for the AgentEndpoint Kubernetes custom resource for managing agent-based endpoints with the ngrok operator. ## AgentEndpoint custom resource ### **apiVersion:** `ngrok.k8s.ngrok.com/v1alpha1` ### **kind:** `AgentEndpoint` Agent Endpoints are endpoints that are only available when an agent is running. When used with the ngrok Kubernetes Operator, this means that the Agent Endpoints are tied to the Operator's `operator-agent` pod (which is deployed by default when installing the Operator). The Operator will manage, create, and delete Agent Endpoints for you according to the configuration of the `AgentEndpoint` custom resources you create. So long as at least one instance of the `operator-agent` pod is running, your Agent Endpoints will be available. You may occasionally notice the IDs of Agent Endpoints managed by the Operator change if the Operator pods restart, this will not halt traffic through your Agent Endpoints unless all of the Operator pods have stopped. See the [ngrok agent CLI configuration page](/agent/config/v3/#endpoint-definitions), for more information about using the CLI to start Agent Endpoints outside of Kubernetes. Note that while using `AgentEndpoint` resources, an Agent Endpoint will be created in your ngrok account for each replica of the `ngrok-operator-agent` `Deployment`. This enables high-availability when running the `ngrok-operator-agent` deployment at a high replica count, but will result in additional charges for your ngrok account. The lifetime of these Agent Endpoints are tied to the lifetime of the `ngrok-operator-agent` pods, so scaling the deployment up/down will cause the additional Agent Endpoints in your ngrok account to be created as needed and deleted when no longer needed. ## AgentEndpoint structure and types The following outlines the high level structure and typings of an `AgentEndpoint` ```yaml theme={null} apiVersion: ngrok.k8s.ngrok.com/v1alpha1 kind: AgentEndpoint metadata: name: namespace: spec: url: # required upstream: # required url: # required trafficPolicy: # optional targetRef: # optional, one of inline or targetRef must be supplied name: # required inline: # optional, one of inline or targetRef must be supplied description: # optional, default: "Created by the ngrok-operator" metadata: # optional, default: "{"owned-by":"ngrok-operator"}" bindings: <[]string> # optional clientCertificateRefs: # optional - name: # required namespace: # optional ``` ## AgentEndpoint fields The following sections outline each field of the `AgentEndpoint` 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 `AgentEndpoint` **Type:** `Object` **Required:** yes **Default:** none **Fields:** | Field Name | Type | Required | Default | Description | | ---------------------------------------------------------- | ----------------- | -------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | [`spec.url`](#specurl) | `string` | yes | none | The unique URL for this Agent Endpoint that defines how the endpoint is accessed | | [`spec.upstream`](#specupstream) | `Object` | yes | none | The upstream that will receive traffic sent to the endpoint (unless a response is sent by a Traffic Policy action first) | | [`spec.trafficPolicy`](#spectrafficpolicy) | `Object` | no | none | Allows a Traffic Policy to be supplied for the endpoint | | [`spec.description`](#specdescription) | `string` | no | `"Created by the ngrok-operator"` | Human-readable description for this `AgentEndpoint` 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.bindings`](#specbindings) | `[]string` (enum) | no | none | List of Binding IDs to associate with the endpoint | | [`spec.clientCertificateRefs`](#specclientcertificaterefs) | `[]Object` | no | none | List of client certificates to present to the upstream when performing a TLS handshake | ### `spec.url` The unique URL for this Agent Endpoint. This URL defines how the endpoint is accessed. **Note:** [Pooling](/gateway/endpoint-pooling) is always enabled for `AgentEndpoint` resources. This means that if two (or more) endpoints share the same `spec.url` then requests will be balanced between them. This is not limited to endpoints within the same cluster, or endpoints of the same type. For example, an `AgentEndpoint` can be pooled with a Cloud Endpoint created in the ngrok dashboard if they share the same URL and both enable pooling. It is recommended to include a prefix/suffix in the URL to prevent unintended pooling. For example, if you are running a service `foo` in the namespace `bar` in two different Kubernetes clusters, you may want to give each one a slightly different `spec.url` that includes something such as a cluster identifier to prevent requests from being balanced between them. Unlike `AgentEndpoint` resources, the `CloudEndpoint` resource gives you the ability to configure whether pooling should be allowed or not. **Type:** `string` **Required:** yes **Default:** none The following formats are accepted: * **Domain** * When using the domain format you are only defining the domain. The scheme and port will be inferred. * example: `example.org` * **Origin** * When using the origin format you are defining the protocol, domain and port. HTTP endpoints accept ports 80 or 443 with respective protocol. * examples: * `https://example.ngrok.app` * `https://example.ngrok.app:443` * `tcp://1.tcp.ngrok.io:12345` * `tls://example.ngrok.app` * **Scheme (shorthand)** * When using scheme you are defining the protocol and will receive back a randomly assigned ngrok address. * examples: * `https://` * `tcp://` * `tls://` * `http://` * **Empty** * When empty your endpoint will default to be https and receive back a randomly assigned ngrok address. * **Internal** * When ending your URL with .internal, an internal endpoint will be created. Internal Endpoints cannot be accessed directly, but rather can only be accessed using the forward-internal Traffic Policy action. * example: `some.domain.internal` ### `spec.upstream` Configures the upstream for the `AgentEndpoint` that should receive traffic sent to the `AgentEndpoint` **Type:** `Object` **Required:** yes **Default:** none **Fields:** | Field Name | Type | Required | Default | Description | | ------------------------------------------------- | --------------- | -------- | ------- | ------------------------------------------------------------------------ | | [`spec.upstream.url`](#specupstreamurl) | `string` | yes | none | The local or remote address that incoming traffic should be forwarded to | | [`spec.upstream.protocol`](#specupstreamprotocol) | `string` (enum) | no | `http1` | The protocol to use when connecting to the upstream | ### `spec.upstream.url` The local or remote address you would like to incoming traffic to be forwarded to. **Type:** `string` **Required:** yes **Default:** none Accepted formats are: * **Origin** * When using the origin format you are defining the protocol, domain and port. When no port is present and scheme is https or http the port will be inferred. * For https port will be `443` * For http port will be `80` * examples: * `https://example.org` * `http://example.org:80` * `tcp://127.0.0.1:80` * **Domain** * This is only allowed for https and http endpoints. For TCP and TLS endpoints host and port is required. * When using the domain format you are only defining the host. - Scheme will default to `http` - Port will default to `80` * example: `example.org` * **Scheme (shorthand)** * This only works for https and http. For tcp and tls host and port is required. * When using scheme you are defining the protocol and the port will be inferred on the local host. * For https port will be `443` * For http port will be `80` * Host will be `localhost` * example: `https://` * **Port (shorthand)** * When using port you are defining the port on the local host that will receive traffic. * Scheme will default to `http` * Host will default to `localhost` * example: `8080` ### `spec.upstream.protocol` Specifies the protocol to use when connecting to the upstream. Currently only `http1` and `http2` are supported with prior knowledge (defaulting to `http1`). **Type:** `string` (enum) **Required:** no **Default:** `http1` **Allowed Values:** `http1`,`http2` ### `spec.trafficPolicy` `spec.trafficPolicy` allows for an ngrok Traffic Policy to be used for this `AgentEndpoint`. It may be supplied inline or via a reference to an `NgrokTrafficPolicy` custom resource in the same namespace as the `AgentEndpoint`. * If `spec.trafficPolicy` is configured, then one of `spec.trafficPolicy.inline` or `spec.trafficPolicy.targetRef` must be supplied * It is invalid to supply both `spec.trafficPolicy.inline` and `spec.trafficPolicy.targetRef` For more information about writing ngrok Traffic Policies, refer to the [Traffic Policy section](/traffic-policy/). **Type:** `Object` **Required:** no **Default:** none **Fields:** | Field Name | Type | Required | Default | Description | | ------------------------------------------------------------- | ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------- | | [`spec.trafficPolicy.inline`](#spectrafficpolicyinline) | `json.RawMessage` | no | none | Inline Traffic Policy configuration for this `AgentEndpoint` | | [`spec.trafficPolicy.targetRef`](#spectrafficpolicytargetref) | `Object` | no | none | Reference to an `NgrokTrafficPolicy` custom resource in the same namespace as the `AgentEndpoint` | ### `spec.trafficPolicy.inline` Allows you to supply a Traffic Policy for this `AgentEndpoint` with inline configuration. An example has been included below. For more information about writing ngrok Traffic Policies, refer to the [Traffic Policy section](/traffic-policy/). **Type:** `json.RawMessage` **Required:** no **Default:** none ### `spec.trafficPolicy.targetRef` Allows you to supply a Traffic Policy for this `AgentEndpoint` as a reference to an `NgrokTrafficPolicy` custom resource in the same namespace as the `AgentEndpoint`. An example has been included below. For more information about writing ngrok Traffic Policies, refer to the [Traffic Policy section](/traffic-policy/). **Type:** `Object` **Required:** no **Default:** none **Fields:** | Field Name | Type | Required | Default | Description | | ----------------------------------- | -------- | -------- | ------- | -------------------------------------------------------------------------------------------- | | `spec.trafficPolicy.targetRef.name` | `string` | yes | none | Name of an `NgrokTrafficPolicy` custom resource in the same namespace as the `AgentEndpoint` | ### `spec.description` Human-readable description of this Agent Endpoint 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.bindings` List of Binding IDs to associate with the endpoint **Type:** `string` (enum) **Required:** no **Accepted Values:** `"public"`, `"internal"`, or `"kubernetes"` * A binding of `"internal"` will create an internal `AgentEndpoint` that is only accessible from other endpoints using the `forward-internal` Traffic Policy action. * Aside from setting `bindings: ["internal"]`, the `spec.url` of the `AgentEndpoint` must end in `.internal` * Setting `bindings: ["public"]` will not work for internal endpoints (endpoints that have a `spec.url` ending in `.internal`) * A binding of `"public"` will create a standard `AgentEndpoint` with its `spec.url` accessible to the public internet * Setting `bindings: ["internal"]` will not work for public endpoints * A binding of `"kubernetes"` will create a Kubernetes bound endpoint. This causes the endpoint to not be publicly accessible to the public internet and will be projected into one or more of your Kubernetes clusters that are running the ngrok Operator (depending on their endpoint selector configuration) as `Services`. * With a `"kubernetes"` binding, the `spec.url` becomes the `name.namespace` of the projected Service. * For example, with a `spec.url` of `http://my-service.my-namespace` then a Service with name `my-service` in the `my-namespace` namespace will be created by the ngrok Operator. Other services within the Kubernetes cluster can make requests to this endpoint. This enables many different use-cases such as being able to project a service in one Kubernetes cluster to another Kubernetes cluster so that services running in the other cluster can make requests to it. This has the benefit of not needing to expose the endpoint to the public internet behind a publicly accessible URL. ### `spec.clientCertificateRefs` List of references to secrets that contain client certificates to present to the upstream when performing a TLS handshake. These will be ignored if the upstream is not using TLS. For example, if the `spec.upstream.url` is `http://service.default:80` then the `clientCertificateRefs` will not be used. 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. When the `spec.upstream.url` has an `https://` scheme, the client certificates will have no effect because no TLS is being used when connecting to the upstream. **Type:** `[]Object` **Required:** no **Default:** none **Fields:** | Field Name | Type | Required | Default | Description | | -------------------------------------- | -------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `spec.clientCertificateRefs.name` | `string` | yes | none | Name of a `Secret` resource to pull the client certificate data from | | `spec.clientCertificateRefs.namespace` | `string` | no | none | Namespace of a `Secret` resource to pull the client certificate data from. When not supplied, the namespace of the `AgentEndpoint` is used | ## Status fields The `AgentEndpoint` resource includes status information that reflects the current state of the Agent Endpoint in the ngrok system. ### `status.assignedURL` The actual URL assigned to the endpoint. This may differ from `spec.url` when using shorthand formats (like `https://` or empty). **Type:** `string` **Example:** `https://example-agent-endpoint.ngrok.app` ### `status.trafficPolicy` Indicates which Traffic Policy is attached to the endpoint. **Type:** `string` **Possible Values:** * `inline` - Endpoint uses an inline Traffic Policy * `none` - No Traffic Policy is attached * `` - Name of the referenced NgrokTrafficPolicy resource **Example:** `inline` ### `status.domainRef` Reference to the Domain resource associated with this Agent Endpoint. **Type:** `Object` **Fields:** * `name` - Name of the Domain resource * `namespace` - Namespace of the Domain resource **Example:** ```yaml theme={null} domainRef: name: example-agent-endpoint-ngrok-app namespace: default ``` ### `status.conditions` Standard Kubernetes conditions that indicate the state of the Agent Endpoint. **Type:** `[]Condition` Each condition includes: * `type` - The condition type * `status` - `True`, `False`, or `Unknown` * `reason` - A programmatic identifier for the condition state * `message` - A human-readable description * `lastTransitionTime` - When the condition last changed * `observedGeneration` - The resource generation this condition applies to #### Condition types ##### `Ready` Indicates whether the Agent Endpoint is fully operational and ready to receive traffic. **Status Values:** * `True` - Agent endpoint is active and ready * `False` - Agent endpoint is not ready (see reason for details) **Reasons:** | Reason | Status | Meaning | | ---------------- | ------- | ------------------------------------------------- | | `EndpointActive` | `True` | Agent endpoint is successfully created and active | | `Pending` | `False` | Endpoint creation is pending | | `Unknown` | `False` | Endpoint state is unknown | | `DomainNotReady` | `False` | Associated domain is not ready | Additionally, the `Ready` condition may reflect reasons from the associated Domain resource when domain issues prevent endpoint creation. **Example:** ```yaml theme={null} conditions: - type: Ready status: "True" reason: EndpointActive message: "AgentEndpoint is active and ready" lastTransitionTime: "2025-10-29T00:39:26Z" observedGeneration: 1 ``` ##### `EndpointCreated` Indicates whether the endpoint was successfully created in the ngrok API. **Status Values:** * `True` - Endpoint was successfully created * `False` - Failed to create endpoint **Reasons:** | Reason | Status | Meaning | | -------------------- | ------- | ---------------------------------- | | `EndpointCreated` | `True` | Endpoint successfully created | | `NgrokAPIError` | `False` | API call to create endpoint failed | | `ConfigurationError` | `False` | Endpoint configuration is invalid | | `UpstreamError` | `False` | Upstream configuration is invalid | **Example:** ```yaml theme={null} conditions: - type: EndpointCreated status: "True" reason: EndpointCreated message: "Endpoint successfully created" lastTransitionTime: "2025-10-29T00:39:26Z" observedGeneration: 1 ``` ##### `TrafficPolicyApplied` Indicates whether the Traffic Policy was successfully applied to the endpoint. **Status Values:** * `True` - Traffic policy is applied * `False` - Failed to apply Traffic Policy **Reasons:** | Reason | Status | Meaning | | ---------------------- | ------- | ------------------------------------------- | | `TrafficPolicyApplied` | `True` | Traffic policy successfully applied | | `TrafficPolicyError` | `False` | Error applying or validating Traffic Policy | **Example:** ```yaml theme={null} conditions: - type: TrafficPolicyApplied status: "True" reason: TrafficPolicyApplied message: "Traffic policy successfully applied" lastTransitionTime: "2025-10-29T00:39:26Z" observedGeneration: 1 ``` ##### `DomainReady` Indicates whether the associated domain is ready for use. This condition propagates the state from the referenced Domain resource. **Status Values:** * `True` - Domain is ready * `False` - Domain is not ready **Reasons:** This condition propagates reasons from the Domain resource's `Ready` condition, including: * `DomainActive` - Domain is successfully reserved and ready * `ProvisioningError` - Domain has DNS or certificate provisioning errors * `DomainCreationFailed` - Domain failed to be created * `DomainInvalid` - Domain format or configuration is invalid **Example:** ```yaml theme={null} conditions: - type: DomainReady status: "True" reason: DomainActive message: "Domain ready for use" lastTransitionTime: "2025-10-29T00:39:25Z" observedGeneration: 1 ``` **Example (Domain DNS Error):** ```yaml theme={null} conditions: - type: DomainReady status: "False" reason: ProvisioningError message: 'DNS_ERROR Reserved domain "*.wildcard-test.example.com" NS DNS records are not pointing at the ngrok infrastructure' lastTransitionTime: "2025-10-29T00:39:24Z" observedGeneration: 1 ``` ## Status examples ### Successfully created Agent Endpoint ```yaml theme={null} status: assignedURL: https://example-agent-endpoint.ngrok.app trafficPolicy: inline domainRef: name: example-agent-endpoint-ngrok-app namespace: default conditions: - type: DomainReady status: "True" reason: DomainActive message: "Domain ready for use" lastTransitionTime: "2025-10-29T00:39:25Z" observedGeneration: 1 - type: EndpointCreated status: "True" reason: EndpointCreated message: "Endpoint successfully created" lastTransitionTime: "2025-10-29T00:39:26Z" observedGeneration: 1 - type: TrafficPolicyApplied status: "True" reason: TrafficPolicyApplied message: "Traffic policy successfully applied" lastTransitionTime: "2025-10-29T00:39:26Z" observedGeneration: 1 - type: Ready status: "True" reason: EndpointActive message: "AgentEndpoint is active and ready" lastTransitionTime: "2025-10-29T00:39:26Z" observedGeneration: 1 ``` ### Agent Endpoint with domain not ready ```yaml theme={null} status: domainRef: name: wildcard-wildcard-test-example-com namespace: default conditions: - type: DomainReady status: "False" reason: ProvisioningError message: 'DNS_ERROR Reserved domain "*.wildcard-test.example.com" NS DNS records are not pointing at the ngrok infrastructure' lastTransitionTime: "2025-10-29T00:39:24Z" observedGeneration: 1 - type: EndpointCreated status: "False" reason: Pending message: "Waiting for domain to be ready" lastTransitionTime: "2025-10-29T00:39:24Z" observedGeneration: 1 - type: Ready status: "False" reason: ProvisioningError message: 'DNS_ERROR Reserved domain "*.wildcard-test.example.com" NS DNS records are not pointing at the ngrok infrastructure' lastTransitionTime: "2025-10-29T00:39:24Z" observedGeneration: 1 ``` ### Agent Endpoint with Traffic Policy error ```yaml theme={null} status: assignedURL: https://example-agent-endpoint.ngrok.app trafficPolicy: example-tp domainRef: name: example-agent-endpoint-ngrok-app namespace: default conditions: - type: DomainReady status: "True" reason: DomainActive message: "Domain ready for use" lastTransitionTime: "2025-10-29T00:39:25Z" observedGeneration: 1 - type: EndpointCreated status: "True" reason: EndpointCreated message: "Endpoint successfully created" lastTransitionTime: "2025-10-29T00:39:26Z" observedGeneration: 1 - type: TrafficPolicyApplied status: "False" reason: TrafficPolicyError message: "Invalid policy action type 'rate-limit-fake'. ERR_NGROK_2201" lastTransitionTime: "2025-10-29T00:39:26Z" observedGeneration: 1 - type: Ready status: "False" reason: TrafficPolicyError message: "AgentEndpoint not ready due to Traffic Policy error" lastTransitionTime: "2025-10-29T00:39:26Z" observedGeneration: 1 ``` ## Checking Agent Endpoint status You can check the status of an Agent Endpoint using kubectl: ```bash theme={null} # Check if Agent Endpoint is ready kubectl get agentendpoint example-agent-endpoint -o jsonpath='{.status.conditions[?(@.type=="Ready")]}' # Watch for Agent Endpoint to become ready kubectl wait --for=condition=Ready agentendpoint/example-agent-endpoint --timeout=60s # Get all Agent Endpoints with their ready status kubectl get agentendpoints -A -o custom-columns=\ NAME:.metadata.name,\ NAMESPACE:.metadata.namespace,\ URL:.status.assignedURL,\ TRAFFIC_POLICY:.status.trafficPolicy,\ READY:.status.conditions[?(@.type==\'Ready\')].status,\ REASON:.status.conditions[?(@.type==\'Ready\')].reason # Check domain readiness for an Agent Endpoint kubectl get agentendpoint example-agent-endpoint -o jsonpath='{.status.conditions[?(@.type=="DomainReady")]}' # Check Traffic Policy status kubectl get agentendpoint example-agent-endpoint -o jsonpath='{.status.conditions[?(@.type=="TrafficPolicyApplied")]}' ``` ## Example AgentEndpoints ### AgentEndpoint with inline Traffic Policy The following `AgentEndpoint`: * Accepts traffic on the URL `https://example-agent-endpoint.ngrok.io` * Sends traffic to `http://my-service.my-namespace:8080` * If a Traffic Policy "terminates" the request, then the traffic will not be sent to the upstream * Adds an inline Traffic Policy * If the request URL contains `?debug=true` query parameter, then the Traffic Policy will "terminate" the request and send back a custom response ```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 Traffic Policy The following `AgentEndpoint`: * Accepts traffic on the URL `https://example-agent-endpoint.ngrok.io` * Sends traffic to `http://my-https-service.my-namespace:8443` * Includes a client certificate from the `Secret` `my-client-cert` in the `default` namespace * If a Traffic Policy "terminates" the request, then the traffic will not be sent to the upstream * Adds a reference to a Traffic Policy that * If the request URL contains `?debug=true` query parameter, then the Traffic Policy will "terminate" the request and send back a custom response ```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: https://my-https-service.my-namespace:8443 trafficPolicy: targetRef: name: example-tp clientCertificateRefs: - name: my-client-cert namespace: default ```