Custom ngrok Annotations

You can use the following custom annotations with the ngrok Kubernetes Operator to extend the functionality of various resources.

Operator 0.22 (Helm chart 0.24) moved these annotations from the k8s.ngrok.com/ prefix to ngrok.com/. The legacy keys, such as k8s.ngrok.com/traffic-policy, still work until Operator 1.0, but the Operator emits a LegacyAnnotation warning event for each Ingress, Gateway, or LoadBalancer Service that uses them. If a resource sets both keys, the ngrok.com/ key wins. Operator versions before 0.22 only read the k8s.ngrok.com/ prefix.

`ngrok.com/traffic-policy`

Allows you to supply an NgrokTrafficPolicy to an Ingress or Gateway resource. For more information about using Traffic Policies with Ingresses and Gateway API, see the using Ingresses page and the using Gateway API page. Usable On: Ingress/Gateway Example:

apiVersion: ngrok.k8s.ngrok.com/v1alpha1
kind: NgrokTrafficPolicy
metadata:
  name: custom-response-example
  namespace: default
spec:
  policy:
    on_http_request:
      - name: custom-response-example
        expressions:
          - req.url.path.startsWith('/custom-response')
        actions:
          - type: custom-response
            config:
              status_code: 200
              body: "Custom response from your Traffic Policy"
              headers:
                content-type: text/plain
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ngrok.com/traffic-policy: "custom-response-example"
  name: example-ingress
  namespace: default
spec:
  ingressClassName: ngrok
  rules:
    - host: example-ingresses.ngrok.app
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

`ngrok.com/mapping-strategy`

Allows you to control the way that the Operator translates Ingress, Gateway, and LoadBalancer type Services into ngrok custom resources. These resources are always translated into CloudEndpoint and AgentEndpoint custom resources. By default ("endpoints"), when a hostname routes to only one upstream service, the Operator creates a single public AgentEndpoint for it instead of a CloudEndpoint that routes to an internal AgentEndpoint. With "endpoints-verbose", every hostname gets a CloudEndpoint and each unique upstream service gets an internal AgentEndpoint, which can cost less when you run more than one agent replica. For more information about how the Operator translates resources, see the using Ingresses page and the using Gateway API page. Usable On: Ingress/Gateway Allowed Values: "endpoints"/"endpoints-verbose"

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ngrok.com/mapping-strategy: "endpoints-verbose"
  name: example-ingress
  namespace: default
spec:
  ingressClassName: ngrok
  rules:
    - host: example-ingresses.ngrok.app
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

`ngrok.com/pooling-enabled`

Allows you to configure whether pooling should be enabled/disabled when the Operator translates Ingress and Gateway resources into CloudEndpoints. By default, translated CloudEndpoint resources have poolingEnabled set to false, but this annotation allows you to enable it. For more information about endpoint pooling, see the pooling page. Usable On: Ingress/Gateway Allowed Values: "true"/"false" Example:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ngrok.com/pooling-enabled: "true"
  name: example-ingress
  namespace: default
spec:
  ingressClassName: ngrok
  rules:
    - host: example-ingresses.ngrok.app
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: example-service
                port:
                  number: 80

Due to how Kubernetes handles annotation values, the value of ngrok.com/pooling-enabled must be a string (“true”). Setting the value to true without surrounding it with quotes doesn’t work.

`ngrok.com/bindings`

Allows you to specify the binding that should be used when the Operator translates Ingress and Gateway resources into CloudEndpoints. By default, the Operator uses a binding of "public", but this annotation allows you to create internal or Kubernetes bound CloudEndpoints instead. For more information about bindings, see the bindings page. Usable On: Ingress/Gateway Allowed Values: "internal"/"public"/"kubernetes" Example:

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: example-ingress
    namespace: default
    annotations:
      ngrok.com/bindings: "internal"
  spec:
    ingressClassName: ngrok
    rules:
      - host: example-domain.ngrok.app
        http:
          paths:
            - path: /
              pathType: Prefix
              backend:
                service:
                  name: example-service
                  port:
                    number: 80

`ngrok.com/app-protocols`

Allows you to specify the protocol of ports on your service. Accepts a value that is a JSON string which maps the name of the ports on your Service to http or https. This annotation is optional, and when not used or a named port is not included in the annotation’s value, the ngrok Kubernetes Operator defaults to using http for that port. Usable On: Service Example: The following example marks the following service as having one port that is https and one port that is http.

apiVersion: v1
kind: Service
metadata:
  name: example-service
  labels:
    app: example-app
  annotations:
    ngrok.com/app-protocols: '{"https-port":"https","http-port":"http"}'
spec:
  ports:
    - name: https-port
      port: 443
      protocol: TCP
      targetPort: 8443
    - name: http-port
      port: 80
      protocol: TCP
      targetPort: 8080
  selector:
    app: example-app

Getting Started

Use Cases

Examples

Connectivity

Traffic Policy

Observability

Network

Resources

Identity & Access

`ngrok.com/traffic-policy`

`ngrok.com/mapping-strategy`

`ngrok.com/pooling-enabled`

`ngrok.com/bindings`

`ngrok.com/app-protocols`

​ngrok.com/traffic-policy

​ngrok.com/mapping-strategy

​ngrok.com/pooling-enabled

​ngrok.com/bindings

​ngrok.com/app-protocols

`ngrok.com/traffic-policy`

`ngrok.com/mapping-strategy`

`ngrok.com/pooling-enabled`

`ngrok.com/bindings`

`ngrok.com/app-protocols`