AgentEndpoint - ngrok documentation

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, 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

apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: AgentEndpoint
metadata:
  name: <string>
  namespace: <string>
spec:
  url: <string>               # required
  upstream:                   # required
    url: <string>             # required
  trafficPolicy:              # optional
    targetRef:                # optional, one of inline or targetRef must be supplied
      name: <string>          # required
    inline:                   # optional, one of inline or targetRef must be supplied
      <Traffic Policy config>
  description: <string>       # optional, default: "Created by the ngrok-operator"
  metadata: <string>          # optional, default: "{"owned-by":"ngrok-operator"}"
  bindings: <[]string>        # optional
  clientCertificateRefs:      # optional
  - name: <string>            # required
    namespace: <string>       # 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`	`string`	yes	none	The unique URL for this Agent Endpoint that defines how the endpoint is accessed
`spec.upstream`	`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`	`Object`	no	none	Allows a Traffic Policy to be supplied for the endpoint
`spec.description`	`string`	no	`"Created by the ngrok-operator"`	Human-readable description for this `AgentEndpoint` to help identify/describe it
`spec.metadata`	`string`	no	`"{"owned-by":"ngrok-operator"}"`	String of arbitrary data associated with the object in the ngrok API/Dashboard
`spec.bindings`	`[]string` (enum)	no	none	List of Binding IDs to associate with the endpoint
`spec.clientCertificateRefs`	`[]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 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`	`string`	yes	none	The local or remote address that incoming traffic should be forwarded to
`spec.upstream.protocol`	`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. Type: Object Required: no Default: none Fields:

Field Name	Type	Required	Default	Description
`spec.trafficPolicy.inline`	`json.RawMessage`	no	none	Inline Traffic Policy configuration for this `AgentEndpoint`
`spec.trafficPolicy.targetRef`	`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. 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. 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
<policy-name> - 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:

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:

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:

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:

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:

conditions:
- type: DomainReady
  status: "True"
  reason: DomainActive
  message: "Domain ready for use"
  lastTransitionTime: "2025-10-29T00:39:25Z"
  observedGeneration: 1

Example (Domain DNS Error):

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

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

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

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:

# 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

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

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

​AgentEndpoint custom resource

​apiVersion: ngrok.k8s.ngrok.com/v1alpha1

​kind: AgentEndpoint

​AgentEndpoint structure and types

​AgentEndpoint fields

​spec

​spec.url

​spec.upstream

​spec.upstream.url

​spec.upstream.protocol

​spec.trafficPolicy

​spec.trafficPolicy.inline

​spec.trafficPolicy.targetRef

​spec.description

​spec.metadata

​spec.bindings

​spec.clientCertificateRefs

​Status fields

​status.assignedURL

​status.trafficPolicy

​status.domainRef

​status.conditions

​Condition types

Ready

EndpointCreated

TrafficPolicyApplied

DomainReady

​Status examples

​Successfully created Agent Endpoint

​Agent Endpoint with domain not ready

​Agent Endpoint with Traffic Policy error

​Checking Agent Endpoint status

​Example AgentEndpoints

​AgentEndpoint with inline Traffic Policy

​AgentEndpoint with referenced Traffic Policy

AgentEndpoint custom resource

apiVersion: `ngrok.k8s.ngrok.com/v1alpha1`

kind: `AgentEndpoint`

AgentEndpoint structure and types

AgentEndpoint fields

`spec`

`spec.url`

`spec.upstream`

`spec.upstream.url`

`spec.upstream.protocol`

`spec.trafficPolicy`

`spec.trafficPolicy.inline`

`spec.trafficPolicy.targetRef`

`spec.description`

`spec.metadata`

`spec.bindings`

`spec.clientCertificateRefs`

Status fields

`status.assignedURL`

`status.trafficPolicy`

`status.domainRef`

`status.conditions`

Condition types

`Ready`

`EndpointCreated`

`TrafficPolicyApplied`

`DomainReady`

Status examples

Successfully created Agent Endpoint

Agent Endpoint with domain not ready

Agent Endpoint with Traffic Policy error

Checking Agent Endpoint status

Example AgentEndpoints

AgentEndpoint with inline Traffic Policy

AgentEndpoint with referenced Traffic Policy