Installation

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.

System requirements

Kubernetes v1.19.0 or higher, Linux nodes, amd64 or arm64 CPU.
PostgreSQL 11 or higher.
A certificate management solution, such as cert-manager.

Deploy

kubectl apply -k github.com/pomerium/ingress-controller/config/default\?ref=v0.27.2

The Pomerium Ingress Controller is now installed into your cluster.

note

You need complete Global Configuration for Pomerium to become fully operational, before you can configure Ingress.

Metrics

Pomerium provides a comprehensive set of Prometheus style metrics. Assuming you are running a Prometheus Operator in your cluster, you may create the following resource to enable metrics collection.

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: pomerium
  namespace: pomerium
spec:
  endpoints:
    - port: metrics
  selector:
    matchLabels:
      app.kubernetes.io/name: pomerium

Advanced

You may adjust your base installation with kustomize, that is also accessible via the kubectl apply -k.

Base Installation Summary

The following resources are created:

pomerium namespace.
pomerium deployment.
pomerium-proxy Service of type LoadBalancer, provisioning an external IP address, that listens on :80 and :443 ports. All HTTP requests are upgraded to HTTP requests.
pomerium-metrics Service of type ClusterIP, accessible from within the cluster, exposing /metrics Prometheus-style metrics endpoint.
pomerium-gen-secrets one-time Job that generates an initial set of bootstrap secrets, and stores them into the bootstrap Secret.
Pomerium CRD definitions.
RBAC rules.

The default manifest may be rebuilt by running the below command in the pomerium/ingress-controller repo.

kustomize build config/default

External-DNS

external-dns may be used to automatically update your DNS record for the Ingress. The below example adjusts the pomerium-proxy service that automatically serves your Authentication URL, so that it's external IP address is up to date in the DNS.

kustomization.yaml
resources:
  - https://raw.githubusercontent.com/pomerium/ingress-controller/v0.22.1/deployment.yaml
patchesStrategicMerge:
  - patch-proxy-external-dns.yaml

patch-proxy-external-dns.yaml
apiVersion: v1
kind: Service
metadata:
  name: pomerium-proxy
  namespace: pomerium
  annotations:
    external-dns.alpha.kubernetes.io/hostname: 'authenticate.localhost.pomerium.io'

Multiple Replicas

By default, Pomerium deploys with a single replica. You may scale Pomerium instances if necessary by adjusting the default deployment.

caution

You must configure storage persistence in order to use more then 1 replica of Pomerium.

kustomization.yaml
resources:
  - https://raw.githubusercontent.com/pomerium/ingress-controller/v0.22.1/deployment.yaml
patchesStrategicMerge:
  - deployment.yaml

deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pomerium
  namespace: pomerium
spec:
  replicas: 2

Set Pomerium as default `IngressClass`

An IngressClass may be designated as a default controller for the cluster.

kustomization.yaml
resources:
  - https://raw.githubusercontent.com/pomerium/ingress-controller/v0.22.0/deployment.yaml
patchesStrategicMerge:
  - patch-proxy-external-dns.yaml

patch-ingress-class.yaml
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: pomerium
  annotations:
    ingressclass.kubernetes.io/is-default-class: 'true'

Multiple controllers

In some cases, you may need to run multiple controllers, see this community example.

Expose Envoy Admin interface

Make sure to always restrict access to the envoy admin interface ingress.

kustomization.yaml
resources:
  - github.com/pomerium/ingress-controller/config/default?ref=v0.27.2
  - admin-service.yaml
  - admin-ingress.yaml
patches:
  - patch: |-
      - op: add
        path: /spec/template/spec/containers/0/args/-
        value: "--debug-admin-addr=localhost:9901"
    target:
      kind: Deployment
      name: pomerium

admin-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: envoy
spec:
  type: ExternalName
  externalName: 'localhost'
  ports:
    - protocol: TCP
      name: admin
      port: 9901

admin-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: envoy
spec:
  ingressClassName: pomerium
  rules:
    - host: 'envoy.localhost.pomerium.io'
      http:
        paths:
          - pathType: Prefix
            path: /
            backend:
              service:
                name: envoy
                port:
                  name: admin

Runtime parameters

Some parameters are only set by default via command line arguments to the container.

caution

Normally, you would not need to adjust the container runtime parameters.

debug: enable debug logging.
server-addr: the address HTTPS server would bind to, :8443 by default.
http-redirect-addr: the address HTTP to HTTPS redirect server would bind to, :8080.
metrics-bind-address: host:port exposes Prometheus style metrics.
debug-admin-addr: localhost:port exposes Envoy admin interface.

System requirements​

Deploy​

Metrics​

Advanced​

External-DNS​

Multiple Replicas​

Set Pomerium as default IngressClass​

Multiple controllers​

Expose Envoy Admin interface​

Runtime parameters​