# Kubernetes Ingress Controller

Use Pomerium as a first-class secure-by-default Ingress Controller. The Pomerium Ingress Controller enables workflows more native to Kubernetes environments, such as Git-Ops style actions based on pull requests. Dynamically provision routes from Ingress resources and set policy based on annotations. By defining routes as Ingress resources you can independently create and remove them from Pomerium's configuration.

# Prerequisites

A certificate management solution. If you do not already have one in place, this article covers using cert-manager (opens new window).
A Redis (opens new window) backend with high persistence (opens new window) is highly recommended.

# System Requirements

Kubernetes v1.19.0+
Pomerium Helm Chart (opens new window) v25.0.0+

# Limitations

WARNING

Only one Ingress Controller instance is supported per Pomerium cluster.

# Installation

# Helm

Our instructions for Installing Pomerium Using Helm includes the Ingress Controller as part of the documented configuration. You can confirm by looking for this line in pomerium-values.yaml:

ingressController:
  enabled: true

# Docker Image

You may deploy the Ingress controller from your own manifests by using the pomerium/ingress-controller docker image.

# Configuration

Flag	Description
`--databroker-service-url`	The databroker service url
`--databroker-tls-ca`	`base64` encoded TLS CA
`--databroker-tls-ca-file`	TLS CA file path for the databroker connection connection
`--health-probe-bind-address`	The address the probe endpoint binds to. (default ":8081")
`--metrics-bind-address`	The address the metric endpoint binds to. (default ":8080")
`--name`	IngressClass controller name (default "pomerium.io/ingress-controller")
`--namespaces`	Namespaces to watch, omit to watch all namespaces
`--prefix`	Ingress annotation prefix (default "ingress.pomerium.io")
`--shared-secret`	`base64` encoded shared secret for communicating with databroker
`--update-status-from-service`	Update ingress status from given service status (pomerium-proxy)

The helm chart exposes a subset of these flags for appropriate customization.

# Usage

# Defining Routes

If you've tested Pomerium using the all-in-one binary, you're probably familiar with configuring routes in Pomerium's config.yaml. When using the Pomerium Ingress Controller, each route is defined as an Ingress resource in the Kubernetes API.

The Ingress Controller will monitor Ingress resources in the cluster, creating a Pomerium route definition for each one. Policy and other configuration options for the route are set by using annotations starting with ingress.pomerium.io/.

Example:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    ingress.pomerium.io/policy: '[{"allow":{"and":[{"email":{"is":"user@yourdomain.com"}}]}}]' # This can also be a yaml block quote
spec:
  rules:
  - host: hello.localhost.pomerium.io
    http:
      paths:
      - backend:
          service:
            name: nginx-hello
            port:
              name: http
        path: /
        pathType: Prefix

Becomes:

routes:
  - from: https://hello.localhost.pomerium.io
    to: http://nginx-hello.default.svc.cluster.local
    policy:
    - allow:
        and:
          - email:
              is: user@yourdomain.com

Write Policies in YAML

You can also define a route's policies using YAML:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: name
  annotations:
    ingress.pomerium.io/policy: |
      - allow:
          or:
            - domain:
                is: pomerium.com

# Supported Annotations

Most configuration keys in non-Kubernetes deployments can be specified as annotation in an Ingress Resource definition. The format is ingress.pomerium.io/${OPTION_NAME}. The expandable list below contains the annotations available, which behave as described in our reference documentation (with links to the appropriate reference documentation).

Pomerium-Standard Annotations

The remaining annotations are specific to or behave differently than they do when using Pomerium without the Ingress Controller:

Annotation	Description
`ingress.pomerium.io/tls_custom_ca_secret`	Name of Kubernetes `tls` Secret containing a custom CA certificate for the upstream.
`ingress.pomerium.io/tls_client_secret`	Name of Kubernetes `tls` Secret containing a client certificate for connecting to the upstream.
`ingress.pomerium.io/tls_downstream_client_ca_secret`	Name of Kubernetes `tls` Secret containing a Client CA for validating downstream clients.
`ingress.pomerium.io/secure_upstream`	When set to true, use `https` when connecting to the upstream endpoint.

TIP

Every value for the annotations above must be in string format.

# cert-manager Integration

Pomerium Ingress Controller can use cert-manager (opens new window) to automatically provision certificates. These may come from the ingress-shim (opens new window) or explicitly configured Certificate resources (opens new window).

To use HTTP01 Challenges (opens new window) with your Issuer (opens new window), configure the solver class to match the Ingress Controller. The Ingress Controller will automatically configure policy to facilitate the HTTP01 challenge:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: example-issuer
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: example-issuer-account-key
    solvers:
    - http01:
       ingress:
         class: pomerium

An example of using the ingress-shim (opens new window) with an Ingress resource managed by Pomerium:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    cert-manager.io/issuer: example-issuer
    ingress.pomerium.io/policy: '[{"allow":{"and":[{"email":{"is":"user@exampledomain.com"}}]}}]'
  name: example
spec:
  ingressClassName: pomerium
  rules:
  - host: example.localhost.pomerium.io
    http:
      paths:
      - backend:
          service:
            name: example
            port:
              name: http
        path: /
        pathType: Prefix
  tls:
  - hosts:
    - example.localhost.pomerium.io
    secretName: example-tls

# HTTPS endpoints

The Ingress spec assumes that all communications to the upstream service is sent in plaintext. For more information, see the TLS (opens new window) section of the Ingress API documentation. Pomerium supports HTTPS communication with upstream endpoints, including mTLS.

Annotate your Ingress with

ingress.pomerium.io/secure_upstream: true

Additional TLS certificates may be supplied by creating a Kubernetes secret(s) in the same namespaces as the Ingress resource. Please note that we do not support file paths or embedded secret references.

Please note that the referenced tls_client_secret must be a TLS Kubernetes secret (opens new window). tls_custom_ca_secret and tls_downstream_client_ca_secret must contain ca.crt containing a .PEM encoded (base64-encoded DER format) public certificate.

# External services

You may refer to external services by defining a Service (opens new window) with externalName.

I.e. if you have https://my-existing-service.corp.com:

apiVersion: v1
kind: Service
metadata:
  name: external
spec:
  type: ExternalName
  externalName: "my-existing-service.corp.com"
  ports:
    - protocol: TCP
      name: https
      port: 443
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: external
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod-http
    ingress.pomerium.io/secure_upstream: "true"
    ingress.pomerium.io/policy: |
      - allow:
          and:
            - domain:
                is: pomerium.com
spec:
  ingressClassName: pomerium
  tls:
    - hosts:
        - "external.localhost.pomerium.io"
      secretName: external-localhost-pomerium.io
  rules:
    - host: "external.localhost.pomerium.io"
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: external
                port:
                  name: https

# Troubleshooting

# View Event History

Pomerium Ingress Controller will add events to the Ingress objects as it processes them.

kubectl describe ingress/my-ingress

Events:
  Type    Reason   Age   From              Message
  ----    ------   ----  ----              -------
  Normal  Updated  18s   pomerium-ingress  updated pomerium configuration

If an error occurs, it may be reflected in the events:

Events:
  Type     Reason       Age                 From              Message
  ----     ------       ----                ----              -------
  Normal   Updated      5m53s               pomerium-ingress  updated pomerium configuration
  Warning  UpdateError  3s                  pomerium-ingress  upsert routes: parsing ingress: annotations: applying policy annotations: parsing policy: invalid rules in policy: unsupported conditional "maybe", only and, or, not, nor and action are allowed

# HSTS

If your domain has HSTS (opens new window) enabled and you visit an endpoint while Pomerium is using the self-signed bootstrap certificate or a LetsEncrypt staging certificate (before cert-manager has provisioned a production certificate), the untrusted certificate may be pinned in your browser and would need to be reset. See this article (opens new window) for more information.

# More Information

For more information on the Pomerium Ingress Controller or the Kubernetes concepts discussed, see:

← Helm Certificates →