Install

Pomerium offers several ways to install the Enterprise Console to suit your organization's needs. Watch the video below for a quick primer on deploying Pomerium Core and Enterprise, or view the sections below for specific installation instructions.

Install Pomerium Enterprise

Docker

The Pomerium Enterprise Docker image is available at a private Cloudsmith Docker registry.

To access the Pomerium Enterprise Docker image:

1. In your terminal, run the following command:

docker login docker.cloudsmith.io

2. Enter your username and password:

 % docker login docker.cloudsmith.io
Username: <username>
Password: <password>

3. Pull a specific tagged release of the Pomerium Enterprise image:

docker pull docker.cloudsmith.io/pomerium/enterprise/pomerium-console:${vX.X.X}

See the Enterprise Quickstart for instructions to run and deploy the Enterprise Console with Docker Compose.

OS Packages

You can find the latest rpm and deb packages on Cloudsmith or download them from the GitHub releases page.

Supported Operating Systems	Supported Architectures
linux	amd64
darwin	arm64

DEB installation

To automatically configure the repository for Debian and Ubuntu distributions:

1. Replace [access-key] in the command below and run it:

curl -1sLf \
'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.deb.sh' \
| sudo -E bash

To manually configure the repository, import the apt-key and create a new .list file in /etc/apt/source.list.d:

curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key' | apt-key add -

echo "deb https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/deb/debian buster main" | sudo tee /apt/sources.list.d/pomerium-console.list

2. Update apt and install Pomerium Enterprise:

sudo apt update; sudo apt install pomerium-console

After you've installed the package, enable and start the system service:

sudo systemctl enable --now pomerium-console

RPM installation

To automatically configure the repository for RHEL based distributions:

1. Replace [access-key] in the command below and run it:

curl -1sLf \
'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.rpm.sh' \
| sudo -E bash

To manually configure the repository, run:

yum install yum-utils pygpgme
rpm --import 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key'
curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/config.rpm.txt?distro=el&codename=8' > /tmp/pomerium-enterprise.repo
yum-config-manager --add-repo '/tmp/pomerium-enterprise.repo'
yum -q makecache -y --disablerepo='*' --enablerepo='pomerium-enterprise'

2. Update yum and install Pomerium Enterprise:

yum -y install pomerium-console

After you've installed the package, enable and start the system service:

sudo systemctl enable --now pomerium-console

Kubernetes with Kustomize

These steps cover installing Pomerium Enterprise into your existing Kubernetes cluster. It's designed to work with an existing cluster running Pomerium, as described in Pomerium Kustomize. Follow that document before continuing here.

The assumption is that Pomerium is installed into the pomerium namespace, and Enterprise would be installed into the pomerium-enterprise namespace.

Prepare Core

The below command will expose the Pomerium Core Databroker gRPC interface.

kubectl apply -k github.com/pomerium/documentation/k8s/core\?ref=0-27-0

Deploy Enterprise Console

kubectl apply -k github.com/pomerium/documentation/k8s/console\?ref=0-27-0

The Enterprise Console need be configured before it becomes fully operational.

Create Cloudsmith Directory Secret

kubectl create secret docker-registry pomerium-enterprise-docker \
    --namespace pomerium-enterprise \
    --docker-server=docker.cloudsmith.io \
    --docker-username=pomerium/enterprise \
    --docker-password="your password provided by Pomerium Sales"

Configure Enterprise Console

Create a config directory, and fill in the configuration parameters for the following template files:

kustomization.yaml

resources:
  - config.yaml
  - ingress-console.yaml
  - secret.yaml
namespace: pomerium-enterprise

See Environment Variables for Config and Secret keys description.

config.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: enterprise
data:
  # should match authenticate service URL from Pomerium Settings CRD
  authenticate_service_url: https://authenticate.domain.com/
  # audience should correspond to the name in the ingress you created for the console
  # without the protocol part
  audience: console.domain.com
  # administrators is a comma separated list of emails that would be granted admin privileges
  # only use it for bootstrapping, and grant explicit permissions via the UI to the Global namespace
  administrators: me@domain.com
  # databroker service URL allows Console to communicate to Pomerium Core
  databroker_service_url: https://pomerium-databroker.pomerium.svc.cluster.local
  # external Prometheus service URL, to enable metrics.
  # see https://www.pomerium.com#metrics
  # prometheus_url: ""

secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: enterprise
type: Opaque
stringData:
  database_url: postgres://user:password@host/database
  database_encryption_key: ''
  license_key: ''
  # shared_secret must match a base64 encrypted key from the Pomerium Core secret - i.e.
  # kubectl get secret bootstrap -n pomerium -o jsonpath="{.data.shared_secret}"
  shared_secret: ''

Create Ingress for Console.

ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: pomerium-console
  annotations:
    cert-manager.io/cluster-issuer: your-cluster-issuer
    external-dns.alpha.kubernetes.io/hostname: 'console.domain.com'
    # console requires user identity headers
    ingress.pomerium.io/pass_identity_headers: 'true'
    # console has internal access control. alternatively, use PPL
    ingress.pomerium.io/allow_any_authenticated_user: 'true'
    # since v0.21.0, console is using TLS by default
    ingress.pomerium.io/secure_upstream: 'true'
spec:
  ingressClassName: pomerium
  tls:
    - secretName: console-domain-com
      hosts:
        - console.domain.com
  rules:
    - host: 'console.domain.com'
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: pomerium-console
                port:
                  name: app

kubectl apply -k ./config