deprecated-helm-charts/stable/pomerium

⚠️ Repo Archive Notice

As of Nov 13, 2020, charts in this repo will no longer be updated. For more information, see the Helm Charts Deprecation and Archive Notice, and Update.

⚠️ DEPRECATION NOTICE ⚠️

This chart is deprecated. Please use the chart maintained at https://helm.pomerium.io/

Update your deployments accordingly.

helm repo add pomerium https://helm.pomerium.io

Deprecation Plan

This version of the chart will be updated through the end of the Pomerium 0.5.x series for verison bumps and critical fixes. No other changes will be accepted.

We welcome contributions in the new repository.

Pomerium

Pomerium is an open-source tool for managing secure access to internal applications and resources.

• ⚠️ DEPRECATION NOTICE ⚠️
  • Deprecation Plan
• Pomerium
  • TL;DR;
  • Install the chart
  • Uninstalling the Chart
  • TLS Certificates
    • Auto Generation
    • Self Provisioned
  • Configuration
  • Changelog
    • 4.0.0
    • 3.0.0
    • 2.0.0
  • Upgrading
    • 4.0.0
    • 3.0.0
    • 2.0.0
  • Metrics Discovery Configuration
    • Prometheus Operator
    • Prometheus kubernetes_sd_configs

TL;DR;

helm install --name my-release stable/pomerium

Note: Pomerium depends on being configured with a third party identity providers to function properly. If you run pomerium without specifying default values, you will need to change those configuration variables following setup.

Install the chart

An example of a minimal, but complete installation of pomerium with identity provider settings, random secrets, certificates, and external URLs is as follows:

kubectl create configmap config --from-file="config.yaml"="$HOME/pomerium/docs/docs/examples/config/config.example.yaml"

helm install $HOME/pomerium-helm \
	--set service.type="NodePort" \
	--set config.rootDomain="corp.beyondperimeter.com" \
	--set config.existingConfig="config" \
	--set config.sharedSecret=$(head -c32 /dev/urandom | base64) \
	--set config.cookieSecret=$(head -c32 /dev/urandom | base64) \
	--set ingress.secret.name="pomerium-tls" \
	--set ingress.secret.cert=$(base64 -i "$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer") \
	--set ingress.secret.key=$(base64 -i "$HOME/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key") \
	--set authenticate.idp.provider="google" \
	--set authenticate.idp.clientID="REPLACE_ME" \
	--set authenticate.idp.clientSecret="REPLACE_ME" \
	stable/pomerium

Uninstalling the Chart

To uninstall/delete the my-release deployment:

helm delete --purge my-release

The command removes nearly all the Kubernetes components associated with the chart and deletes the release.

TLS Certificates

Auto Generation

In default configuration, this chart will automatically generate TLS certificates in a helm pre-install hook for the Pomerium services to communicate with.

Upon delete, you will need to manually delete the generated secrets. Example:

kubectl delete secret -l app.kubernetes.io/name=pomerium

You may force recreation of your TLS certificates by setting config.forceGenerateTLS to true. Delete any existing TLS secrets first to prevent errors, and make sure you set back to false for your next helm upgrade command or your deployment will fail due to existing Secrets.

Self Provisioned

If you wish to provide your own TLS certificates in secrets, you should:

1. turn generateTLS to false
2. specify authenticate.existingTLSSecret, authorize.existingTLSSecret, and proxy.existingTLSSecret, pointing at the appropriate TLS certificate for each service.

All services can share the secret if appropriate.

Configuration

A full listing of Pomerium's configuration variables can be found on the config reference page.

Parameter	Description	Default
nameOverride	Name of the chart.	pomerium
fullnameOverride	Full name of the chart.	pomerium
config.rootDomain	Root Domain specifies the sub-domain handled by pomerium. See more.	corp.pomerium.io
config.existingSecret	Name of the existing Kubernetes Secret.
config.existingConfig	Name of the existing Config Map deployed on Kubernetes.
config.existingLegacyTLSSecret	Use a Pre-3.0.0 secret for the service TLS data. Only use if upgrading from <= 2.0.0	false
config.existingCASecret	Name of the existing CA Secret.
config.generateTLS	Generate a dummy Certificate Authority and certs for service communication. Manual CA and certs can be set in values.	true
config.forceGenerateTLS	Force recreation of generated TLS certificates. You will need to restart your deployments after running	false
config.sharedSecret	256 bit key to secure service communication. See more.	32 random ascii chars
config.cookieSecret	Cookie secret is a 32 byte key used to encrypt user sessions.	32 random ascii chars
config.policy	Base64 encoded string containing the routes, and their access policies.
config.policyFile	Relative file location of the policy file which contains the routes, and their access policies.	See example in values
authenticate.nameOverride	Name of the authenticate service.	authenticate
authenticate.fullnameOverride	Full name of the authenticate service.	authenticate
authenticate.redirectUrl	Redirect URL is the url the user will be redirected to following authentication with the third-party identity provider (IdP). See more.	https://{{authenticate.name}}.{{config.rootDomain}}/oauth2/callback
authenticate.idp.provider	Identity Provider Name.	google
authenticate.idp.clientID	Identity Provider oauth client ID.	Required
authenticate.idp.clientSecret	Identity Provider oauth client secret.	Required
authenticate.idp.url	Identity Provider URL.	Optional
authenticate.idp.serviceAccount	Identity Provider service account.	Optional
authenticate.replicaCount	Number of Authenticate pods to run	1
authenticate.existingTLSSecret	Name of existing TLS Secret for authenticate service
authenticate.deployment.annotations	Annotations for the authenticate deployment. If none given, then use value of annotations	{}
authenticate.service.annotations	Annotations for the authenticate service. If none given, then use value of service.annotations	{}
proxy.nameOverride	Name of the proxy service.	proxy
proxy.fullnameOverride	Full name of the proxy service.	proxy
proxy.authenticateServiceUrl	The externally accessible url for the authenticate service.	https://{{authenticate.name}}.{{config.rootDomain}}
proxy.authorizeServiceUrl	The externally accessible url for the authorize service.	https://{{authorize.name}}.{{config.rootDomain}}
proxy.replicaCount	Number of Proxy pods to run	1
proxy.existingTLSSecret	Name of existing TLS Secret for proxy service
proxy.deployment.annotations	Annotations for the proxy deployment. If none given, then use value of annotations	{}
proxy.service.annotations	Annotations for the proxy service. If none given, then use value of service.annotations	{}
authorize.nameOverride	Name of the authorize service.	authorize
authorize.fullnameOverride	Full name of the authorize service.	authorize
authorize.replicaCount	Number of Authorize pods to run	1
authorize.existingTLSSecret	Name of existing TLS Secret for authorize service
forwardAuth.nameOverride	External name of the forward-auth endpoint	forwardauth.${rootDomain}
forwardAuth.enabled	Enable forward-auth endpoint for third party ingress controllers to use for auth checks. Setting this disables automatic enumeration of from hostnames in the Pomerium Ingress object to prevent conflicts. Use ingress.hosts to mix forward-auth and proxy mode on a single Pomerium instance	false
authorize.deployment.annotations	Annotations for the authorize deployment. If none given, then use value of annotations	{}
authorize.service.annotations	Annotations for the authorize service. If none given, then use value of service.annotations	{}
images.server.repository	Pomerium image	pomerium/pomerium
images.server.tag	Pomerium image tag	v0.5.2
images.server.pullPolicy	Pomerium image pull policy	IfNotPresent
service.annotations	Service annotations	{}
service.externalPort	Pomerium's port	443
service.type	Service type (ClusterIP, NodePort or LoadBalancer)	ClusterIP
service.authorize.headless	Run Authorize service in Headless mode. Turn off if you require NodePort or LoadBalancer access to Authorize	true
serviceMonitor.enabled	Create Prometheus Operator ServiceMonitor	false
serviceMonitor.namespace	Namespace to create the ServiceMonitor resource in	The namespace of the chart
serviceMonitor.labels	Additional labels to apply to the ServiceMonitor resource	release: prometheus
tracing.enabled	Enable distributed tracing	false
tracing.debug	Set trace sampling to 100%. Use with caution!	false
tracing.provider	Specifies the tracing provider to configure (Valid options: Jaeger)	Required
tracing.jaeger.collector_endpoint	The jaeger collector endpoint	Required
tracing.jaeger.agent_endpoint	The jaeger agent endpoint	Required
ingress.enabled	Enables Ingress for pomerium	true
ingress.annotations	Ingress annotations	{}
ingress.hosts	Ingress accepted hostnames	[]
ingress.tls	Ingress TLS configuration	[]
metrics.enabled	Enable prometheus metrics endpoint	false
metrics.port	Prometheus metrics endpoint port	9090

Changelog

4.0.0

• Upgrade to Pomerium v0.4.0
• Handle breaking changes from Pomerium

3.0.0

• Refactor TLS certificates to use Kubernetes TLS secrets
• Generate TLS certificates in a hook to prevent certificate churn

2.0.0

• Expose replica count for individual services
• Switch Authorize service to ClusterIP for client side load balancing
  • You must run pomerium v0.3.0+ to support this feature correctly

Upgrading

4.0.0

• There are no user facing changes in this chart release
• See Pomerium Changelog for internal details

3.0.0

• This version moves all certificates to TLS secrets.
  • If you have existing generated certificates:
    • Let pomerium regenerate your certificates during upgrade
      • set config.forceGenerateTLS to true
      • upgrade
      • set config.forceGenerateTLS to false
    • OR: To retain your certificates
      • save your existing pomerium secret
      • set config.existingLegacyTLSSecret to true
      • set config.existingConfig to point to your configuration secret
      • upgrade
      • re-create pomerium secret from saved yaml
  • If you have externally sourced certificates in your pomerium secret:
    • Move and convert your certificates to type TLS Secrets and configure [service].existingTLSSecret to point to your secrets
    • OR: To continue using your certificates from the existing config, set config.existingLegacyTLSSecret to true

---

2.0.0

• You will need to run helm upgrade --force to recreate the authorize service correctly

Metrics Discovery Configuration

This chart provides two ways to surface metrics for discovery. Under normal circumstances, you will only set up one method.

Prometheus Operator

This chart assumes you have already installed the Prometheus Operator CRDs.

Example chart values:

metrics:
  enabled: true
  port: 9090 # default
serviceMonitor:
  enabled: true
  labels:
    release: prometheus # default

Example ServiceMonitor configuration:

serviceMonitorSelector:
  matchLabels:
    release: prometheus # operator chart default

Prometheus kubernetes_sd_configs

Example chart values:

metrics:
  enabled: true
  port: 9090 # default
service:
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "9090"

Example prometheus discovery config:

- job_name: 'pomerium'
metrics_path: /metrics
kubernetes_sd_configs:
- role: endpoints
relabel_configs:
- source_labels: [__meta_kubernetes_service_annotation_prometheus_io_scrape]
  action: keep
  regex: true
- source_labels: [__meta_kubernetes_service_label_app_kubernetes_io_instance]
  action: keep
  regex: pomerium
- action: labelmap
  regex: __meta_kubernetes_service_label_(.+)
- source_labels: [__meta_kubernetes_namespace]
  action: replace
  target_label: kubernetes_namespace
- source_labels: [__meta_kubernetes_service_name]
  action: replace
  target_label: kubernetes_name
- source_labels: [__address__, __meta_kubernetes_service_annotation_prometheus_io_port]
  action: replace
  regex: ([^:]+)(?::\d+)?;(\d+)
  replacement: $1:$2
  target_label: __address__