Skip to main content

CloudEndpoint

CloudEndpoint Custom Resource​

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

kind: CloudEndpoint​

The CloudEndpoint custom resource is used to create centrally managed endpoints in the cloud. Cloud Endpoints are persistent, always-on endpoints that live within the ngrok cloud. They exist permanently until they are explicitly deleted. Cloud Endpoints do not forward their traffic to an agent by default and instead only use their attached Traffic Policy to handle connections. Using the traffic policy configuration, you may configure your Cloud Endpoints to route to one or more other internal ngrok endpoints.

For more information about cloud endpoints in ngrok, refer to the cloud endpoints page

CloudEndpoint Structure and Types​

The following outlines the high level structure and typings of a CloudEndpoint

Loading…

CloudEndpoint Fields​

The following sections outline each field of the CloudEndpoint 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 CloudEndpoint

Type: Object

Required: yes

Default: none

Fields:

Field NameTypeRequiredDefaultDescription
spec.urlstringyesnoneThe unique URL for this CloudEndpoint that defines how the endpoint is accessed
spec.trafficPolicyNamestringnononeThe name of an NgrokTrafficPolicy custom resource in the same namespace as the CloudEndpoint to use for traffic policy configuration
spec.trafficPolicyObjectnononeAllows for a traffic policy to be provided to the CloudEndpoint using inline configuration
spec.descriptionstringno"Created by the ngrok-operator"Human-readable description for this CloudEndpoint 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.poolingEnabledboolnofalseWhether or not the CloudEndpoint should enable pooling with other endpoints sharing the same URL

spec.url​

The unique URL for this cloud endpoint. This URL defines how the endpoint is accessed.

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.trafficPolicyName​

Reference to an NgrokTrafficPolicy custom resource in the same namespace as the CloudEndpoint to use for traffic policy configuration. It is invalid to configure both spec.trafficPolicyName and spec.trafficPolicy at the same time.

The referenced NgrokTrafficPolicy must be in the same namespace as the CloudEndpoint.

Type: string

Required: no

Default: none

spec.trafficPolicy​

Reference to an NgrokTrafficPolicy custom resource in the same namespace as the CloudEndpoint to use for traffic policy configuration. It is invalid to configure both spec.trafficPolicyName and spec.trafficPolicy at the same time. 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.policyjson.RawMessageyesnoneThe inline traffic policy configuration to be used for this CloudEndpoint

spec.trafficPolicy.policy​

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: yes

Default: none

spec.description​

Human-readable description of this cloud 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

Default: none

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.poolingEnabled​

Configures whether pooling is always enabled for this CloudEndpoint.

When pooling is enabled, if two different 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, a CloudEndpoint can be pooled with an agent endpoint created using the ngrok CLI if they both enable pooling and share the same URL.

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.

You will receive an error back from the ngrok server if you attempt to create two different endpoints using the same URL if they do not both enable pooling. In this scenario, the older endpoint wins and the newer one will fail to be created.

Type: bool

Required: no

Default: false

Example CloudEndpoints​

CloudEndpoint with inline traffic policy​

The following CloudEndpoint:

  • Accepts traffic on the URL https://example-cloud-endpoint.ngrok.io
  • Adds an inline traffic policy that sends back a custom response
Loading…

CloudEndpoint with referenced traffic policy​

The following CloudEndpoint:

  • Accepts traffic on the URL https://example-cloud-endpoint.ngrok.io
  • Adds a reference to a traffic policy that sends back a custom response
Loading…