document ingress-controller sync mode by kenjenkins · Pull Request #2313 · pomerium/documentation

kenjenkins · 2026-07-14T20:53:03Z

Summary

Add a new page under Deploy > Kubernetes to document the new API sync functionality in ingress-controller. Provide a basic overview of the feature, instructions for syncing to Pomerium Zero or Pomerium Enterprise, some details about how the sync works, and a short troubleshooting section.

AI disclosure

Claude generated an initial draft of Pomerium Enterprise setup instructions.

Checklist

netlify · 2026-07-14T20:53:08Z

✅ Deploy Preview for pomerium-docs ready!

Name	Link
🔨 Latest commit	`f5d7e9b`
🔍 Latest deploy log	https://app.netlify.com/projects/pomerium-docs/deploys/6a5a8c6eefe17900084039f9
😎 Deploy Preview	https://deploy-preview-2313--pomerium-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

greptile-apps · 2026-07-14T22:56:26Z

Greptile Summary

This PR adds a new sync-api.mdx documentation page under Deploy > Kubernetes explaining how to sync the Pomerium Ingress Controller with Pomerium Zero or Pomerium Enterprise, along with supporting kustomize overlays and a screenshot asset.

New doc page (sync-api.mdx): covers prerequisites, step-by-step setup for both Zero and Enterprise targets, naming conventions for synced entities, and a troubleshooting section.
install.mdx tab values normalized to lowercase kebab-case (docker, os-packages, kustomize, terraform) so the new page can deep-link directly to the Kustomize tab via ?method=kustomize.
k8s/core/kustomization.yaml updated the ingress-controller resource ref from the pinned v0.32.0 to the mutable ref=main; k8s/ic-console/kustomization.yaml (new overlay) inherits this via ../core.

Confidence Score: 4/5

Safe to merge once the ingress-controller ref in k8s/core/kustomization.yaml is re-pinned to a stable or release-candidate tag.

The core kustomization now tracks ingress-controller's live main branch instead of a pinned release, meaning every kubectl apply -k can silently deploy a different, potentially unreleased ingress-controller version. This affects all users of the shared k8s/core overlay, not only new sync-api adopters.

k8s/core/kustomization.yaml — the ref=main change affects all downstream kustomizations that include ../core

Important Files Changed

Filename	Overview
k8s/core/kustomization.yaml	Changed ingress-controller resource ref from pinned v0.32.0 to mutable ref=main, breaking reproducibility for all users of the core Kustomization
content/docs/deploy/k8s/sync-api.mdx	New documentation page for ingress-controller sync mode; correctly structured with Tabs, inline code blocks, and troubleshooting sections
k8s/ic-console/kustomization.yaml	New kustomization combining console and core overlays; inherits the mutable ref=main from k8s/core via ../core reference
content/docs/deploy/enterprise/install.mdx	Tab query-string parameter values normalized to lowercase kebab-case to support direct-linking via ?method=kustomize URL from the new sync-api page
content/docs/deploy/k8s/img/pomerium-zero-cluster-id.png	New screenshot of the Pomerium Zero cluster selector dialog, referenced correctly from sync-api.mdx

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant User as User / kubectl
    participant IC as Pomerium Ingress Controller
    participant K8s as Kubernetes API
    participant API as Pomerium Zero / Enterprise API

    User->>K8s: apply Ingress / HTTPRoute object
    K8s-->>IC: watch event (object created/updated)
    IC->>K8s: read Ingress spec + TLS secrets
    IC->>API: sync route / policy / certificate (API token auth)
    API-->>IC: 200 OK (entity ID)
    IC->>K8s: attach finalizer to Ingress object

    User->>K8s: delete Ingress object
    K8s-->>IC: watch event (deletion requested)
    Note over IC,K8s: Finalizer holds object open
    IC->>API: delete corresponding route / policy
    API-->>IC: 200 OK
    IC->>K8s: remove finalizer → object deleted

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant User as User / kubectl
    participant IC as Pomerium Ingress Controller
    participant K8s as Kubernetes API
    participant API as Pomerium Zero / Enterprise API

    User->>K8s: apply Ingress / HTTPRoute object
    K8s-->>IC: watch event (object created/updated)
    IC->>K8s: read Ingress spec + TLS secrets
    IC->>API: sync route / policy / certificate (API token auth)
    API-->>IC: 200 OK (entity ID)
    IC->>K8s: attach finalizer to Ingress object

    User->>K8s: delete Ingress object
    K8s-->>IC: watch event (deletion requested)
    Note over IC,K8s: Finalizer holds object open
    IC->>API: delete corresponding route / policy
    API-->>IC: 200 OK
    IC->>K8s: remove finalizer → object deleted

_{Reviews (4): Last reviewed commit: "docs: fix double dash" | Re-trigger Greptile}

Add a new page under Deploy > Kubernetes to document the new API sync functionality in ingress-controller. Provide a basic overview of the feature, instructions for syncing to Pomerium Zero or Pomerium Enterprise, some details about how the sync works, and a short troubleshooting section.

desimone

lgtm; one nit possibly and do we want to keep on main or tagged. Given this will stay on main on docs makes sense for me but wanted to highlight.

desimone · 2026-07-17T19:56:10Z

 namespace: pomerium
 resources:
-  - github.com/pomerium/ingress-controller/config/default?ref=v0.32.0
+  - github.com/pomerium/ingress-controller/config/default?ref=main


Update to tagged?

I think I can update the tags to point to v0.33.0 once I do the branch related stuff

greptile-apps · 2026-07-17T20:15:43Z

 namespace: pomerium
 resources:
-  - github.com/pomerium/ingress-controller/config/default?ref=v0.32.0
+  - github.com/pomerium/ingress-controller/config/default?ref=main


Pinned version replaced with mutable ref=main

Changing from ref=v0.32.0 to ref=main means every kubectl apply -k now fetches whatever is on the ingress-controller's main branch at that instant — including unreleased code, RCs, or breaking changes. This affects all users of the core Kustomization, not just users of the new sync feature. Two identical-looking commands run a week apart can deploy different ingress-controller versions with no visible difference in the kustomization YAML.

Red test:

# Day 1 – user deploys; main is at commit abc123 (dev build post-0.33-rc1) kubectl apply -k github.com/pomerium/documentation//k8s/core?ref=main # Day 14 – user re-applies after a cluster upgrade; main is now at def456 kubectl apply -k github.com/pomerium/documentation//k8s/core?ref=main # Silently upgrades ingress-controller to a new dev build with breaking CRD changes # Cluster starts rejecting ingress resources; no obvious root cause

If the intent is to document the v0.33 feature before the tag is cut, the safest approach is to keep this file pinned to ref=v0.32.0 (or use a release candidate tag) and update it to ref=v0.33.0 when that tag is published.

* document ingress-controller sync mode Add a new page under Deploy > Kubernetes to document the new API sync functionality in ingress-controller. Provide a basic overview of the feature, instructions for syncing to Pomerium Zero or Pomerium Enterprise, some details about how the sync works, and a short troubleshooting section. * fix missing databroker service port * docs: base64 decode before creating api token secret * docs: fix double dash --------- Co-authored-by: Alexandre Lamarre <alex7285@gmail.com>

kenjenkins force-pushed the kenjenkins/ingress-sync-api branch 2 times, most recently from 4f9faa6 to 5d3ef47 Compare July 14, 2026 22:28

kenjenkins marked this pull request as ready for review July 14, 2026 22:51

kenjenkins requested a review from a team as a code owner July 14, 2026 22:51

kenjenkins requested review from nickytonline and ssveta7ak and removed request for a team July 14, 2026 22:51

greptile-apps Bot reviewed Jul 14, 2026

View reviewed changes

Comment thread content/docs/deploy/k8s/sync-api.mdx

kenjenkins added 2 commits July 14, 2026 17:17

fix missing databroker service port

2bdddfb

kenjenkins force-pushed the kenjenkins/ingress-sync-api branch from 5d3ef47 to 2bdddfb Compare July 15, 2026 00:19

greptile-apps Bot reviewed Jul 15, 2026

View reviewed changes

Comment thread content/docs/deploy/k8s/sync-api.mdx

docs: base64 decode before creating api token secret

e382ce7

desimone approved these changes Jul 17, 2026

View reviewed changes

docs: fix double dash

f5d7e9b

greptile-apps Bot reviewed Jul 17, 2026

View reviewed changes

alexandreLamarre merged commit 87a86cd into main Jul 17, 2026
10 checks passed

alexandreLamarre deleted the kenjenkins/ingress-sync-api branch July 17, 2026 20:15

alexandreLamarre mentioned this pull request Jul 17, 2026

chore: nav link updates for latest release #2323

Open

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

document ingress-controller sync mode#2313

document ingress-controller sync mode#2313
alexandreLamarre merged 4 commits into
mainfrom
kenjenkins/ingress-sync-api

kenjenkins commented Jul 14, 2026

Uh oh!

netlify Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

desimone left a comment

Uh oh!

desimone Jul 17, 2026

Uh oh!

alexandreLamarre Jul 17, 2026

Uh oh!

Uh oh!

greptile-apps Bot Jul 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

kenjenkins commented Jul 14, 2026

Summary

Related

AI disclosure

Checklist

Uh oh!

netlify Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for pomerium-docs ready!

Uh oh!

greptile-apps Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

Uh oh!

desimone left a comment

Choose a reason for hiding this comment

Uh oh!

desimone Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

alexandreLamarre Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

greptile-apps Bot Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify Bot commented Jul 14, 2026 •

edited

Loading

greptile-apps Bot commented Jul 14, 2026 •

edited

Loading