Once Pomerium is installed into your cluster, you need to complete its global configuration to become fully operational.

Individual routes are configured via [Ingress](https://www.pomerium.com/docs/deploy/k8s/ingress.md) objects.

## Configuration

While Pomerium distributions for bare-metal installations are configured via a config file and/or environment variables, Pomerium distribution for Kubernetes should be configured via [Pomerium CRD](https://www.pomerium.com/docs/deploy/k8s/reference.md), that brings the following benefits:

- Supply sensitive parts of the configuration via Kubernetes `Secrets`.
- Seamless configuration updates.
- Configuration validation.
- Centralized place to observe events.
- `/status` endpoint posts `Ingress` status.

The default installation uses [Pomerium Settings CRD](https://www.pomerium.com/docs/deploy/k8s/reference.md) named `global`. This is a cluster-wide resource. The below is a minimum configuration you need to set up.

```yaml
apiVersion: ingress.pomerium.io/v1
kind: Pomerium
metadata:
  name: global
spec:
  authenticate:
    url: https://authenticate.localhost.pomerium.io
  certificates:
    - pomerium/authenticate-localhost-pomerium-io-prod
  identityProvider:
    provider: google
    secret: pomerium/idp-google
  secrets: pomerium/bootstrap
```

### Bootstrap Secrets

Bootstrap secrets are provisioned via `secrets` property of the [CRD](https://www.pomerium.com/docs/deploy/k8s/ingress.md#tls-certificates). The default installation would run a one-off Job that would generate them and store into `bootstrap` Secret of the `pomerium` namespace.

### Identity Provider

Integration with your Identity Provider is configured using [`identityProvider`](https://www.pomerium.com/docs/integrations/user-identity/identity-providers.md) parameter.

### Authenticate Endpoint

Each Pomerium installation has a special route that unauthenticated users are redirected to that handles sign-in via your Identity Provider. It is configured via the [`authenticate`](https://www.pomerium.com/docs/deploy/k8s/reference.md#authenticate) parameter of the [CRD](https://www.pomerium.com/docs/deploy/k8s/reference.md#authenticate).

The authenticate endpoint DNS address should resolve to an external IP address assigned by your Kubernetes Load Balancer to the `pomerium-proxy` service. If you use [external-dns](https://github.com/kubernetes-sigs/external-dns), DNS records can be managed automatically.

You should not create a separate Ingress resource for the Authenticate URL.

However, you should provision a matching certificate, and supply it via [`certificates`](https://www.pomerium.com/docs/deploy/k8s/reference.md#spec) section of the CRD.

### Certificate Auto-Provisioning

Generally [`cert-manager`](https://www.pomerium.com/docs/deploy/k8s/ingress.md#cert-manager-integration) can be used with ingress definitions to provision certificates. However if routes are created through a different mechanism, for example with the [Enterprise Console](https://www.pomerium.com/docs/deploy/enterprise.md#enterprise-console), the Pomerium Ingress controller can also be configured to provision certificates for those routes via the `certificateAutoProvision` option. When enabled cert-manager Certificates will automatically be created for any routes which lack a matching certificate.

```yaml
apiVersion: ingress.pomerium.io/v1
kind: Pomerium
metadata:
  name: global
spec:
  certificateAutoProvision:
    issuer: pomerium/self-signed
  # other global options ...
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  namespace: pomerium
  name: self-signed
spec:
  selfSigned: {}
```

### Routes (Ingress)

See a [dedicated Ingress guide](https://www.pomerium.com/docs/deploy/k8s/ingress.md) for details on how to configure Pomerium to serve Ingress.

### Supported Configuration Options

All Pomerium features are available in the Kubernetes deployment, except for `autocert`. Use [`cert-manager`](https://www.pomerium.com/docs/deploy/k8s/ingress.md#cert-manager-integration) or other Kubernetes-native certificate solution instead.

See [Configuration Reference](https://www.pomerium.com/docs/deploy/k8s/reference.md) for full description of all CRD configuration options.

## Status

Pomerium posts updates about its internal state to the [`/status` section of the `Pomerium CRD`](https://www.pomerium.com/docs/deploy/k8s/ingress.md#view-event-history).

```console
Name:         global
Namespace:
Labels:       app.kubernetes.io/name=pomerium
API Version:  ingress.pomerium.io/v1
Kind:         Pomerium
 ... some details omitted ...
Spec:
  Authenticate:
    URL:  https://authenticate.localhost.pomerium.io
  Certificates:
    pomerium/authenticate-localhost-pomerium-io-prod
  Identity Provider:
    Provider:  google
    Secret:    pomerium/idp-google
  Secrets:     pomerium/bootstrap
Status:
  Ingress:
    httpbin/httpbin:
      Observed At:          2022-11-18T03:04:23Z
      Observed Generation:  1
      Reconciled:           true
  Settings Status:
    Observed At:          2022-11-18T03:04:23Z
    Observed Generation:  4
    Reconciled:           true
Events:
  Type     Reason      Age   From                                 Message
  ----     ------      ----  ----                                 -------
  Normal   Updated     5s    bootstrap-pomerium-69fcccc487-wcztn  config updated
  Normal   Updated     2s    pomerium-crd                         config updated
  Normal   Updated     2s    pomerium-ingress                     httpbin/httpbin: config updated
```