From 3b0b3e0ca36dcaa81dd120ee376ec5a2339d7f5b Mon Sep 17 00:00:00 2001 From: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com> Date: Thu, 10 Sep 2026 16:59:36 -0700 Subject: [PATCH 1/2] fix an error in the k8s quickstart instructions To use 'provider: hosted' we need to set an Authenticate Service URL. The quickstart already has instructions for generating an 'mkcert' wildcard certificate, so we can use a sub-domain for this URL. --- content/docs/deploy/k8s/quickstart.mdx | 4 +++- content/examples/kubernetes/pomerium-global-settings.md | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/content/docs/deploy/k8s/quickstart.mdx b/content/docs/deploy/k8s/quickstart.mdx index 70bd40fb4..03b300b57 100644 --- a/content/docs/deploy/k8s/quickstart.mdx +++ b/content/docs/deploy/k8s/quickstart.mdx @@ -90,6 +90,8 @@ kubectl create secret tls pomerium-wildcard-tls --namespace=pomerium \ +(If you are using your own domain, replace `localhost.pomerium.io` with your domain.) + 4. Apply the global settings: ```sh @@ -110,7 +112,7 @@ Metadata: ... ``` -You should now be able to access `https://authenticate.pomerium.app` which, after signing in with our hosted IdP, should redirect you to the `.pomerium` endpoint. +You should now be able to access https://authenticate.localhost.pomerium.io. This should prompt you to sign in with our hosted IdP, and then redirect you to the `.pomerium` endpoint. ## Test Service diff --git a/content/examples/kubernetes/pomerium-global-settings.md b/content/examples/kubernetes/pomerium-global-settings.md index 91f107013..e31e234a2 100644 --- a/content/examples/kubernetes/pomerium-global-settings.md +++ b/content/examples/kubernetes/pomerium-global-settings.md @@ -5,6 +5,8 @@ metadata: name: global spec: secrets: pomerium/bootstrap + authenticate: + url: https://authenticate.localhost.pomerium.io identityProvider: provider: hosted certificates: From d724fa98cbaf311e0bee66f69027c2b46a0d5267 Mon Sep 17 00:00:00 2001 From: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com> Date: Fri, 11 Sep 2026 12:11:16 -0700 Subject: [PATCH 2/2] minor improvements Correct and simplify the note at the top about the Hosted Authenticate Service, and style it as a Tip. Link directly to the relevant sections of the combined Authentication page. Tweak formatting in the 'Install Pomerium' section so that the instructions nest under the list items. --- content/docs/deploy/k8s/quickstart.mdx | 92 +++++++++++++------------- 1 file changed, 47 insertions(+), 45 deletions(-) diff --git a/content/docs/deploy/k8s/quickstart.mdx b/content/docs/deploy/k8s/quickstart.mdx index 03b300b57..b4f89863a 100644 --- a/content/docs/deploy/k8s/quickstart.mdx +++ b/content/docs/deploy/k8s/quickstart.mdx @@ -27,16 +27,18 @@ import Tabs from '@theme/Tabs'; Deploy Pomerium Core with [Kubernetes]. -This quickstart guide uses our [**Hosted Authenticate Service**](/docs/capabilities/authentication) so you don't need to configure an identity provider or authenticate service URL. +:::tip -If you want to self-host, see the [**Self-Hosted Authenticate Service**](/docs/capabilities/authentication) page. +This quickstart guide uses our [**Hosted Authenticate Service**](/docs/capabilities/authentication#hosted-authenticate-service). If you want to use a different identity provider, see [**Custom IdP**](/docs/capabilities/authentication#custom-idp). + +::: ## Prerequisites - [Install kubectl]. - A Kubernetes provider. - A cluster, with your local `kubectl` authorized to interact with it. -- A domain space. The steps below use `*.localhost.pomerium.io` as a placeholder value. We have set DNS records for this domain space to point to `127.0.0.1` (localhost), so you can use this domain space when testing Pomerium locally. +- A wildcard domain name. The steps below use `*.localhost.pomerium.io` as a placeholder value. We have set DNS records for this domain to point to `127.0.0.1` (localhost), so you can use this domain when testing Pomerium locally. - [TLS certificates]. If you don't yet have a production environment with trusted certificates, this page will cover using [mkcert] to create locally trusted certificates. ## Certificates @@ -57,60 +59,60 @@ mkcert "*.localhost.pomerium.io" 1. Install Pomerium to your cluster: -```sh -kubectl apply -k github.com/pomerium/ingress-controller/config/default\?ref=0-33-0 -``` - -This will create all the components of Pomerium in the `pomerium` namespace, as well as a bootstrap secret: + ```sh + kubectl apply -k github.com/pomerium/ingress-controller/config/default\?ref=0-33-0 + ``` -```sh -namespace/pomerium created -customresourcedefinition.apiextensions.k8s.io/pomerium.ingress.pomerium.io created -serviceaccount/pomerium-controller created -serviceaccount/pomerium-gen-secrets created -clusterrole.rbac.authorization.k8s.io/pomerium-controller created -clusterrole.rbac.authorization.k8s.io/pomerium-gen-secrets created -clusterrolebinding.rbac.authorization.k8s.io/pomerium-controller created -clusterrolebinding.rbac.authorization.k8s.io/pomerium-gen-secrets created -service/pomerium-metrics created -service/pomerium-proxy created -deployment.apps/pomerium created -job.batch/pomerium-gen-secrets created -ingressclass.networking.k8s.io/pomerium created -``` + This will create all the components of Pomerium in the `pomerium` namespace, as well as a bootstrap secret: + + ```sh + namespace/pomerium created + customresourcedefinition.apiextensions.k8s.io/pomerium.ingress.pomerium.io created + serviceaccount/pomerium-controller created + serviceaccount/pomerium-gen-secrets created + clusterrole.rbac.authorization.k8s.io/pomerium-controller created + clusterrole.rbac.authorization.k8s.io/pomerium-gen-secrets created + clusterrolebinding.rbac.authorization.k8s.io/pomerium-controller created + clusterrolebinding.rbac.authorization.k8s.io/pomerium-gen-secrets created + service/pomerium-metrics created + service/pomerium-proxy created + deployment.apps/pomerium created + job.batch/pomerium-gen-secrets created + ingressclass.networking.k8s.io/pomerium created + ``` 2. Add the certificate [created earlier](#certificates) and key to the cluster as a Secret: -```sh -kubectl create secret tls pomerium-wildcard-tls --namespace=pomerium \ - --cert=./_wildcard.localhost.pomerium.io.pem --key=./_wildcard.localhost.pomerium.io-key.pem -``` + ```sh + kubectl create secret tls pomerium-wildcard-tls --namespace=pomerium \ + --cert=./_wildcard.localhost.pomerium.io.pem --key=./_wildcard.localhost.pomerium.io-key.pem + ``` 3. Define the global Pomerium settings: - + -(If you are using your own domain, replace `localhost.pomerium.io` with your domain.) + (If you are using your own domain, replace `localhost.pomerium.io` with your domain.) 4. Apply the global settings: -```sh -kubectl apply -f pomerium.yaml -``` - -The Pomerium Proxy service should now be running in your cluster: + ```sh + kubectl apply -f pomerium.yaml + ``` -```sh {1} -kubectl describe pomerium -Name: global -Namespace: -Labels: -Annotations: -API Version: ingress.pomerium.io/v1 -Kind: Pomerium -Metadata: - ... -``` + The Pomerium Proxy service should now be running in your cluster: + + ```sh {1} + kubectl describe pomerium + Name: global + Namespace: + Labels: + Annotations: + API Version: ingress.pomerium.io/v1 + Kind: Pomerium + Metadata: + ... + ``` You should now be able to access https://authenticate.localhost.pomerium.io. This should prompt you to sign in with our hosted IdP, and then redirect you to the `.pomerium` endpoint.