Skip to main content

CRDs

Kubernetes has the concept of Custom Resource Definitions (CRDs) which allow you to define your own custom resources. This document will cover the CRDs you might use to achieve your goals with the ngrok Kubernetes Ingress Controller.

Warning: There are other CRDs not documented here that are used internally by the controller. It is not recommended to edit these, but inspecting them to query the state of the system could be useful at times. See the internal CRDs document for more details.

Ngrok Module Sets

NgrokModuleSets is a CRD that lets you define combinations of ngrok modules that can be set on your ingress objects and applied to all of their routes. For an in-depth guide on configuring NgrokModuleSets see the Route Modules Guide.

NgrokModuleSetModules

FieldTypeDescription
compressionEndpointCompressionConfiguration for compression for this module
headersEndpointHeadersConfiguration for headers for this module
ipRestrictionEndpointIPPolicyConfiguration for IP restriction for this module
tlsTerminationEndpointTLSTerminationAtEdgeConfiguration for TLS termination for this module
webhookVerificationEndpointWebhookVerificationConfiguration for webhook verification for this module

NgrokModuleSet

FieldTypeDescription
apiVersionstringAPI version of the NgrokModuleSet custom resource definition
kindstringKind of the custom resource definition
metadataObjectMetaStandard Kubernetes metadata
modulesNgrokModuleSetModulesThe set of modules for this custom resource definition

NgrokTrafficPolicy

FieldTypeDescription
apiVersionstringAPI version of the NgrokTrafficPolicy
kindstringKind of the custom resource definition
metadataObjectMetaStandard Kubernetes metadata
policyjson.RawMessageSee policy configuration

EndpointCompression

FieldTypeDescription
enabledbooleanWhether or not compression is enabled for this endpoint

EndpointIPPolicy

FieldTypeDescription
ippolicies[]stringList of IP policies for this endpoint

EndpointRequestHeaders

FieldTypeDescription
addmap[string]stringMap of header key to header value that will be injected into the HTTP Request
remove[]stringList of header names that will be removed from the HTTP Request

EndpointResponseHeaders

FieldTypeDescription
addmap[string]stringMap of header key to header value that will be injected into the HTTP Response
remove[]stringList of header names that will be removed from the HTTP Response

EndpointHeaders

FieldTypeDescription
requestEndpointRequestHeadersConfiguration for request headers for this endpoint
responseEndpointResponseHeadersConfiguration for response headers for this endpoint

EndpointTLSTerminationAtEdge

FieldTypeDescription
minVersionstringMinimum TLS version to allow for connections to the edge

SecretKeyRef

FieldTypeDescription
namestringName of the Kubernetes secret
keystringKey in the secret to use

EndpointWebhookVerification

FieldTypeDescription
providerstringString indicating which webhook provider will be sending webhooks to this endpoint
secretSecretKeyRefReference to a secret containing the secret used to validate requests from the given provider

IP Policies

The IPPolicy CRD manages the ngrok API resource directly. It is a first class CRD that you can manage to control these policies in your account.

It's optional to create IP Policies this way vs using the ngrok dashboard or terraform provider. Once created though, you can use it in your ingress objects using the annotations.

FieldDescriptionRequiredTypeExample
metadataStandard object metadataNometav1.ObjectMetaname: my-ip-policy
spec.descriptionDescription for the IP policyNostring{}
spec.metadataMetadata for the IP PolicyNostring{}
spec.rulesA list of rules that belong to the policyNo[]IPPolicyRule[{cidr: "1.2.3.4", action: "allow"}]
status.idThe unique identifier for this policyNostring"my-ip-policy-id"
status.rulesA list of IP policy rules and their statusNo[]IPPolicyRuleStatus[{id: "my-rule-id", cidr: "1.2.3.4", action: "allow"}]

IPPolicyRule

FieldDescriptionRequiredTypeExample
cidrThe CIDR block that the rule applies toYesstring"1.2.3.4/24"
actionThe action to take for the rule, either "allow" or "deny"Yesstring"allow"

IPPolicyRuleStatus

FieldDescriptionRequiredTypeExample
idThe unique identifier for this ruleNostring"my-rule-id"
cidrThe CIDR block that the rule applies toNostring"1.2.3.4/24"
actionThe action to take for the rule, either "allow" or "deny"Nostring"allow"

TCP Edges

The Kubernetes ingress spec does not directly support TCP traffic. The ngrok Kubernetes Ingress Controller supports TCP traffic via the TCP Edge resource. This is a first class CRD that you can manage to control these edges in your account. See the TCP and TLS Edges guide for more details.

FieldTypeRequiredDescription
apiVersionstringYesThe API version for this custom resource.
kindstringYesThe kind of the custom resource.
metadatametav1.ObjectMetaNoStandard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions#metadata
specTCPEdgeSpecYesSpecification of the TCP edge.
statusTCPEdgeStatusNoObserved status of the TCP edge.

TCPEdgeSpec

FieldTypeRequiredDescription
descriptionstringNoA human-readable description of the edge.
metadatastringNoMetadata for the edge.
backendTunnelGroupBackendYesThe definition for the tunnel group backend that serves traffic for this edge.
ipRestrictionEndpointIPPolicyNoAn IPRestriction to apply to this route.

TunnelGroupBackend

FieldTypeRequiredDescription
descriptionstringNoA human-readable description of the backend.
metadatastringNoMetadata for the backend.
labelsmap[string]stringNoLabels to watch for tunnels on this backend.

TCPEdgeStatus

FieldTypeRequiredDescription
idstringNoThe unique identifier for this edge.
uristringNoThe URI of the edge.
hostports[]stringNoHostports served by this edge.
backendTunnelGroupBackendStatusNoStores the status of the tunnel group backend, mainly the ID of the backend.

TunnelGroupBackendStatus

FieldTypeRequiredDescription
idstringNoThe unique identifier for this backend.

TLS Edges

ngrok's TLS Edges function similarly to TCP Edges in that they may contain arbitrary application data, not just HTTP. As such, the Kubernetes Ingress spec isn't a perfect fit for them either. The ngrok Kubernetes Ingress Controller supports arbitrary TLS endpoints via the TLS Edge resource. This is a first class CRD that you can manage to control these edges in your account. See the TCP and TLS Edges guide for more details.

FieldTypeRequiredDescription
apiVersionstringYesThe API version for this custom resource.
kindstringYesThe kind of the custom resource.
metadatametav1.ObjectMetaNoStandard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions#metadata
specTLSEdgeSpecYesSpecification of the TCP edge.
statusTLSEdgeStatusNoObserved status of the TCP edge.

TLSEdgeSpec

FieldTypeRequiredDescription
descriptionstringNoA human-readable description of the edge.
metadatastringNoMetadata for the edge.
backendTunnelGroupBackendYesThe definition for the tunnel group backend that serves traffic for this edge.
hostports[]stringYesA list of hostports served by this edge.
ipRestrictionEndpointIPPolicyNoAn IPRestriction to apply to this edge.
tlsTerminationTLSTerminationNoTLS Termination behaviour for this edge.
mutualTlsMutualTLSNoMutual TLS validation for this edge.

TLSEdgeStatus

FieldTypeRequiredDescription
idstringNoThe unique identifier for this edge.
uristringNoThe URI of the edge.
hostports[]stringNoHostports served by this edge.
backendTunnelGroupBackendStatusNoStores the status of the tunnel group backend, mainly the ID of the backend.

Domains

Domains are automatically created by the controller based on the ingress objects host values. Standard ngrok subdomains will automatically be created and reserved for you. Custom domains will also be created and reserved, but will be up to you to configure the DNS records for them. See the custom domain guide for more details.

If you delete all the ingress objects for a particular host, as a safety precaution, the ingress controller does NOT delete the domains and thus does not unregister them. This ensures you don't lose domains while modifying or recreating ingress objects. You can still manually delete a domain CRD via kubectl delete domain <name> if you want to unregister it.

If using a TCP or TLS CRD directly, a Domain will not be created for you automatically, so you will need to create and manage it yourself. See the TCP and TLS Edges guide for details.

FieldTypeRequiredDescription
apiVersionstringYesThe API version for this custom resource.
kindstringYesThe kind of the custom resource.
metadatametav1.ObjectMetaNoStandard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions#metadata
specDomainSpecYesSpecification of the domain.
statusDomainStatusNoObserved status of the domain.

DomainSpec

FieldTypeRequiredDescription
descriptionstringNoA human-readable description of the domain.
metadatastringNoMetadata for the domain.
domainstringYesThe domain name to reserve.
regionstringYesThe region in which to reserve the domain.

DomainStatus

FieldTypeRequiredDescription
idstringNoThe unique identifier of the domain.
domainstringNoThe domain that was reserved.
regionstringNoThe region in which the domain was created.
uristringNoThe URI of the reserved domain API resource.
cnameTargetstringNoThe CNAME target for the domain.

Tunnels

Tunnels are automatically created by the controller based on the ingress objects' rules' backends. A tunnel will be created for each backend service name and port combination. This results in tunnels being created with those labels which can be matched by various edge backends. Automatically-created are useful to inspect but are fully managed by the controller and should not be edited directly.

If using a TCP or TLS CRD, you may need to create and manage a Tunnel yourself. See the TCP and TLS Edges guide for details.

FieldTypeRequiredDescription
apiVersionstringYesThe API version for this custom resource.
kindstringYesThe kind of the custom resource.
metadatametav1.ObjectMetaNoStandard object's metadata. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions#metadata
specTunnelSpecYesSpecification of the tunnel.
statusTunnelStatusNoObserved status of the tunnel.

TunnelSpec

FieldTypeRequiredDescription
forwardsTostringYesThe name and port of the service to forward traffic to.
backendTunnelBackendYesThe type of backend this tunnel forwards to.
labelsmap[string]stringNoKey/value pairs that are attached to the tunnel.

TunnelBackend

FieldTypeRequiredDescription
protocolstringYesThe protocol understood by this backend. Either TCP or TLS.

TunnelStatus

FieldTypeRequiredDescription
No fields defined.