Skip to main content

Install Pomerium Enterprise in Helm

This document covers installing Pomerium Enterprise into your existing helm-managed Kubernetes cluster. It's designed to work with an existing cluster running Pomerium, as described im Pomerium using Helm. Follow that document before continuing here.

Before You Begin

Pomerium Enterprise requires:

  • An accessible RDBMS. We support PostgreSQL 9+.
    • A database and user with full permissions for it.
  • A certificate management solution. This page will assume a store of certificates using cert-manager as the solution. If you use another certificate solution, adjust the steps accordingly.
  • An existing Pomerium installation. If you don't already have open-source Pomerium installed in your cluster, see Pomerium using Helm before you continue.

System Requirements

One of the advantages of a Kubernetes deployment is automatic scaling, but if your database solution is outside of your k8s configuration, refer to the requirements below:

  • Each Postgres instance should have at least:
    • 4 vCPUs
    • 8G RAM
    • 20G for data files

Issue a Certificate

This setup assumes an existing certificate solution using cert-manager, as described in Pomerium using Helm. If you already have a different certificate solution, create and implement a certificate for pomerium-console.pomerium.svc.cluster.local. Then you can move on to the next stage.

  1. Create a certificate configuration file for Pomerium Enterprise Our example is named pomerium-console-certificate.yaml:

    kind: Certificate
    name: pomerium-cert
    namespace: pomerium
    secretName: pomerium-tls
    name: pomerium-issuer
    kind: Issuer
    - server auth
    - client auth
    - pomerium-proxy.pomerium.svc.cluster.local
    - pomerium-authorize.pomerium.svc.cluster.local
    - pomerium-databroker.pomerium.svc.cluster.local
    - pomerium-authenticate.pomerium.svc.cluster.local
    # TODO - If you're not using the Pomerium Ingress controller, you may want a wildcard entry as well.
    #- "*" # Quotes are required to escape the wildcard
  2. Apply the required certificate configurations, and confirm:

    kubectl apply -f pomerium-console-certificate.yaml
    kubectl get certificate
    pomerium-cert True pomerium-tls 92m
    pomerium-console-cert True pomerium-console-tls 6s

Update Pomerium

  1. Set your local context to your Pomerium namespace:

    kubectl config set-context --current --namespace=pomerium
  2. Open your pomerium values file. If you followed Pomerium Using Helm, the file is named pomerium-values.yaml. In the config section, set a list item in the routes block for the Enterprise Console:

    - from:
    to: https://pomerium-console.pomerium.svc.cluster.local
    - allow:
    - domain:
    pass_identity_headers: true
  3. If you haven't already, set generateSigningKey as false, and set a static signingKey value to be shared with the Enterprise Console. See Reference: Signing Key for information on generating a key:

    generateSigningKey: false
    signingKey: "LR0tMS1BRUdHTiBFQ...."

    If signingKey wasn't already set, delete the generated pomerium-signing-key secret and restart the pomerium-authorize deployment:

    kubectl delete secret pomerium-signing-key
    kubectl rollout restart deployment pomerium-authorize
  4. Use Helm to update your Pomerium installation:

    helm upgrade --install pomerium pomerium/pomerium --values=./pomerium-values.yaml

Install Pomerium Enterprise

  1. Create pomerium-console-values.yaml as shown below, replacing placeholder values:

    type: pg
    username: pomeriumDbUser
    name: pomeriumDbName
    sslmode: require
    sharedSecret: #Shared with Pomerium
    databaseEncryptionKey: #Generate from "head -c32 /dev/urandom | base64"
    administrators: "" #This is a hard-coded access, remove once setup is complete
    signingKey: "ZZZZZZZ" #This base64-encoded key is shared with open-source Pomerium
    audience: # This should match the "from" value in your Pomerium route, excluding protocol.
    licenseKey: "XXXYYYYZZZZ" # This should be provided by your account team.
    existingCASecret: pomerium-tls
    caSecretKey: ca.crt
    existingSecret: pomerium-console-tls
    generate: false
    pullUsername: pomerium/enterprise
    pullPassword: your-access-key
  2. The Pomerium repository should already be in your Helm configuration per Pomerium using Helm. If not, add it now:

    helm repo add pomerium
    helm repo update
  3. Install Pomerium Enterprise:

    helm install pomerium-console pomerium/pomerium-console --values=pomerium-console-values.yaml
  4. If you haven't configured a public DNS record for your Pomerium domain space, you can use kubectl to generate a local proxy:

    sudo -E kubectl --namespace pomerium port-forward service/pomerium-proxy 443:443
  5. When visiting, you should see the Traffic:

    The Traffic List page after installing Pomerium Enterprise


Updating Service Types:

If, while updating the open-source Pomerium values, you change any block's service.type you may need to manually delete corresponding service before applying the new configuration. For example:

kubectl delete svc pomerium-proxy

Generate Recovery Token

In the event that you lose access to the console via delegated access (the policy defined in Pomerium), there exists a fallback procedure to regain access to the console via a generated recovery token.

Pomerium Enterprise Recovery Sign In

To generate a token, run the pomerium-console generate-recovery token command with the following flags:

--database-encryption-keybase64-encoded encryption key for encrypting sensitive data in the database.
--database-urlThe database to connect to (default "postgresql://pomerium:pomerium@localhost:5432/dashboard?sslmode=disable").
--namespaceThe namespace to use (default "9d8dbd2c-8cce-4e66-9c1f-c490b4a07243" for Global).
--outWhere to save the JWT. If not specified, it will be printed to stdout.
--ttlThe amount of time before the recovery token expires. Requires a unit (example: 30s, 5m).

You can run the pomerium-console binary from any device with access to the database.