Skip to main content

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 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 NameTypeRequiredDefaultDescription
spec.urlstringyesnoneThe unique URL for this Agent Endpoint that defines how the endpoint is accessed
spec.upstreamObjectyesnoneThe upstream that will receive traffic sent to the endpoint (unless a response is sent by a Traffic Policy action first)
spec.trafficPolicyObjectnononeAllows a Traffic Policy to be supplied for the endpoint
spec.descriptionstringno"Created by the ngrok-operator"Human-readable description for this AgentEndpoint to help identify/describe it
spec.metadatastringno"{"owned-by":"ngrok-operator"}"String of arbitrary data associated with the object in the ngrok API/Dashboard
spec.bindings[]string (enum)nononeList of Binding IDs to associate with the endpoint
spec.clientCertificateRefs[]ObjectnononeList 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 NameTypeRequiredDefaultDescription
spec.upstream.urlstringyesnoneThe local or remote address that incoming traffic should be forwarded to
spec.upstream.protocolstring (enum)nohttp1The 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 NameTypeRequiredDefaultDescription
spec.trafficPolicy.inlinejson.RawMessagenononeInline Traffic Policy configuration for this AgentEndpoint
spec.trafficPolicy.targetRefObjectnononeReference 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 NameTypeRequiredDefaultDescription
spec.trafficPolicy.targetRef.namestringyesnoneName 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 NameTypeRequiredDefaultDescription
spec.clientCertificateRefs.namestringyesnoneName of a Secret resource to pull the client certificate data from
spec.clientCertificateRefs.namespacestringnononeNamespace 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:
ReasonStatusMeaning
EndpointActiveTrueAgent endpoint is successfully created and active
PendingFalseEndpoint creation is pending
UnknownFalseEndpoint state is unknown
DomainNotReadyFalseAssociated 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:
ReasonStatusMeaning
EndpointCreatedTrueEndpoint successfully created
NgrokAPIErrorFalseAPI call to create endpoint failed
ConfigurationErrorFalseEndpoint configuration is invalid
UpstreamErrorFalseUpstream 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:
ReasonStatusMeaning
TrafficPolicyAppliedTrueTraffic policy successfully applied
TrafficPolicyErrorFalseError 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