基于 Helm 的 Pomerium 零信任访问代理部署指南：charts/pomerium 安装、TLS 与指标采集全解

本文以 Helm 官方 Charts 仓库中 stable/pomerium 的 README 为骨架，系统讲解如何用 Helm 在 Kubernetes 上部署 Pomerium（开源的身份感知访问代理/反向代理），覆盖最小完整安装、随机密钥与证书注入、TLS 自动/自备两种模式、全量配置参数、服务与 Ingress 访问入口、升级路径以及 Prometheus 指标发现。读完本文，你将掌握一套可直接复制的helm install命令组合，并理解底层 Helm 模板如何生成 Secret、ConfigMap 与三个核心服务（authenticate / authorize / proxy），为在生产环境定制部署打下基础。

一、Pomerium 是什么，这份 Chart 的定位

Pomerium 是一款开源的、用于管理内部应用与资源安全访问的工具，其核心思路是身份感知的访问代理（Identity-Aware Proxy）：所有对内部服务的访问都必须先经过 Pomerium 完成身份认证（对接第三方身份提供商 IdP）与策略授权，再被反向代理到目标服务。

本仓库中的stable/pomeriumChart（Chart 版本4.2.6，对应 Pomerium 应用版本v0.5.2，见 Chart.yaml）是 Helm Charts 官方仓库时代维护的社区版本。需要注意的事实是：

• 该 Chart 已被标记为deprecated（废弃），官方在其 README 中声明仅对Pomerium 0.5.x 系列继续做版本号与关键修复的更新，不再接受其他改动；
• 官方后续维护的 Chart 已迁移到独立的 Helm 仓库（可通过helm repo add pomerium添加官方仓库获取），新版部署请以官方维护版本为准；
• 本仓库整体也处于归档（Archive）状态，自 2020 年 11 月起不再更新。

因此，本文所有命令、参数与模板行为均以当前仓库内的实际内容为准，适合作为理解 Pomerium 0.5.x 部署方式与 Helm 模板实现原理的参考。

二、架构：三个服务与对应的 Helm 模板

从模板组织看，该 Chart 将 Pomerium 拆分为三个独立的 Deployment，每个 Deployment 通过环境变量SERVICES指定各自承担的职责：

三个 Deployment 共用一个镜像pomerium/pomerium:v0.5.2（默认pullPolicy: IfNotPresent），并共享同一份 Secret 中的shared-secret（服务间通信的 256 位密钥）与cookie-secret（加密用户会话的 32 字节密钥）。authenticate 与 proxy 还通过环境变量注入AUTHENTICATE_SERVICE_URL、AUTHORIZE_SERVICE_URL来互指，例如 proxy 默认使用集群内 DNS 名https://<release>-pomerium-authorize.<namespace>.svc.cluster.local访问 authorize（见 proxy-deployment.yaml）。

模板目录中还包含 Service（每个服务一个）、ingress.yaml、configmap.yaml、secret.yaml、tls-secrets.yaml 与 servicemonitor.yaml，下文将逐一展开。

三、快速安装与卸载

最简单的安装方式（TL;DR）：

helm install --name my-release stable/pomerium

注意：Pomerium 依赖第三方身份提供商（IdP）才能正常工作。如果直接使用默认值安装而不指定 IdP 配置，安装完成后必须按需修改相关配置变量。

卸载并删除 release：

helm delete --purge my-release

该命令会移除与 Chart 关联的几乎所有 Kubernetes 组件并删除 release。不过，由 Helmpre-installhook 自动生成的 TLS Secret不会随卸载被自动清理，需要手动删除（详见下文的 TLS 章节）：

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

四、最小完整安装示例（IdP + 随机密钥 + 证书）

README 给出了一段“最小但完整”的生产级安装命令，它同时覆盖了四类要素：IdP 配置、随机生成的共享密钥、TLS 证书、外部 URL。以下命令逐段说明：

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

各参数的作用与取值要点：

• service.type="NodePort"：对外暴露方式，取值可为ClusterIP、NodePort或LoadBalancer，默认ClusterIP；
• config.rootDomain：Pomerium 负责处理该通配符域名下的子域，默认corp.pomerium.io；
• config.existingConfig="config"：指定预先创建的 ConfigMap 名称（这里指第一步kubectl create configmap创建的对象），Pomerium 的完整配置文件（含 policy）将从这个 ConfigMap 加载，挂载点为/etc/pomerium/config.yaml；
• config.sharedSecret与config.cookieSecret：分别用于服务间通信与用户会话加密，这里用head -c32 /dev/urandom | base64生成随机值。若留空，secret.yaml 会用randAscii 32自动生成随机 ASCII 串；
• ingress.secret.name/cert/key：Ingress 使用的kubernetes.io/tls类型 Secret，证书与私钥以 base64 形式传入（示例中来自 acme.sh 签发的通配符证书）；
• authenticate.idp.*：身份提供商信息，provider默认google，clientID/clientSecret是必填项（模板占位值为REPLACE_ME，未替换前部署是不完整的）。

值得说明的是，即使未通过--set config.existingConfig提供外部 ConfigMap，Chart 自身也会渲染一个 ConfigMap（见 configmap.yaml），它按需组装extraOpts、metrics_address、tracing_*、forward_auth_url与policy等配置段。

五、TLS 证书管理：自动生成与自备证书

这是该 Chart 的核心功能之一，README 给出了两种互斥的证书管理方式。

5.1 自动生成（默认）

默认配置下（config.generateTLS: true），Chart 会在 Helm 的pre-installhook 中为 Pomerium 各服务自动生成一套 TLS 证书（含一个自签 CA）。实现细节见 tls-secrets.yaml：

• 用genCA "default-ca" 3650生成有效期 3650 天的自签 CA；
• 依次为 authenticate、authorize、proxy 生成由该 CA 签发的证书，SAN 默认包含authenticate.<rootDomain>、authorize.<rootDomain>及集群内部 DNS 名（<service>.<namespace>.svc.cluster.local）；
• 每个证书写入独立的kubernetes.io/tls类型 Secret（<release>-authenticate-tls、<release>-authorize-tls、<release>-proxy-tls），CA 写入 Opaque 类型的<release>-ca-tlsSecret；
• 三个 Deployment 通过 volumeMount 将cert.pem、privkey.pem、ca.pem挂载到/pomerium/目录，并以环境变量CERTIFICATE_FILE、CERTIFICATE_KEY_FILE、CERTIFICATE_AUTHORITY_FILE指向（见 authenticate-deployment.yaml）。

如需自定义 SAN，可通过authenticate.tls.defaultSANList、authorize.tls.defaultSANList与各服务的defaultIPList覆盖默认值；proxy.tls.defaultSANList默认留空（详见 values.yaml）。

卸载后，这些 hook 生成的 Secret 需要手动清理，例如：

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

若希望强制重新生成证书，将config.forceGenerateTLS设为true再执行helm upgrade。此时模板会把 hook 注释切换为pre-upgrade（见 tls-secrets.yaml）。操作顺序很关键：

1. 先删除已有 TLS Secret，避免冲突报错；
2. 升级（证书被重新生成）；
3. 将forceGenerateTLS改回false，否则下一次helm upgrade会因 Secret 已存在而失败。

证书重新生成后，各服务的 Deployment 需要重启以加载新证书。

5.2 自备证书（Self Provisioned）

如果希望使用自己管理的证书（例如公司 CA 签发的证书或已托管在 Kubernetes Secret 中），按以下步骤配置：

1. 将config.generateTLS设为false；
2. 为每个服务指定authenticate.existingTLSSecret、authorize.existingTLSSecret、proxy.existingTLSSecret，指向对应的kubernetes.io/tlsSecret。

三个服务可以共用同一个 Secret（只要证书适用即可）。另外，若不想使用现成 Secret，也可以在generateTLS: false时直接把证书内容写进 values：authenticate.tls.cert/key、authorize.tls.cert/key、proxy.tls.cert/key（均为 base64 字符串），模板会自动创建对应的 TLS Secret（见 tls-secrets.yaml）；同时可用config.existingCASecret引用已有的 CA Secret，或通过config.ca直接提供 CA 内容。

六、配置参数全表

下表完整列出 README 提供的 Chart 参数，含含义与默认值。其中config.sharedSecret、config.cookieSecret默认由模板用 32 位随机 ASCII 字符生成（secret.yaml 中实际使用randAscii 32并做双重 base64 编码）。

注意：README 中的参数表以images.server.*命名镜像配置，而 values.yaml 实际使用的键为image.repository、image.tag、image.pullPolicy，二者等价，helm set时以 values 文件中的实际键名为准。此外 values 还提供了resources、priorityClassName、affinity、tolerations、nodeSelector、podAnnotations、podLabels、extraEnv、extraArgs、extraVolumes、imagePullSecrets等通用调度与扩展参数。

七、values.yaml 深入解读与模板校验逻辑

7.1 密钥 Secret 的生成

当未指定config.existingSecret时，secret.yaml 会渲染一个 Opaque Secret，包含以下键（均 base64 编码）：

• cookie-secret：默认randAscii 32 | b64enc | b64enc；
• shared-secret：同样默认随机生成；
• idp-client-id、idp-client-secret：来自authenticate.idp.clientID/clientSecret；
• idp-service-account：仅当配置了authenticate.idp.serviceAccount时才生成。

三个 Deployment 通过secretKeyRef引用该 Secret 注入COOKIE_SECRET、SHARED_SECRET、IDP_CLIENT_ID、IDP_CLIENT_SECRET等环境变量。若已有现成 Secret，则设置config.existingSecret指向它即可。

7.2 ConfigMap 的生成与冲突校验

configmap.yaml 在未指定config.existingConfig时渲染config.yaml，其组装逻辑包含若干硬性校验：

• config.existingPolicy不能与config.extraOpts同时使用，否则helm直接fail；
• config.existingPolicy不能与config.policy同时使用；
• 启用metrics.enabled时写入metrics_address: :<port>；
• 启用tracing.enabled时强制要求tracing.provider，且 provider 为jaeger时强制要求collector_endpoint与agent_endpoint；
• 启用forwardAuth.enabled时写入forward_auth_url: https://<forwardauth 域名>；
• 配置了config.policy时以 YAML 形式渲染policy:段。

7.3 策略（Policy）的两种写法

Pomerium 的核心是“路由 + 访问策略”。在该 Chart 中有两种注入方式：

方式一：values 内联。直接编写config.policy，例如仓库 CI 测试使用的 ci/default-values.yaml：

config: policy: - from: https://httpbin.corp.pomerium.io to: http://httpbin allowed_domains: - pomerium.io - from: https://external-httpbin.corp.pomerium.io to: https://httpbin.org allowed_domains: - gmail.com - from: https://weirdlyssl.corp.pomerium.io to: http://neverssl.com allowed_users: - bdd@pomerium.io allowed_groups: - admins - developers - from: https://hello.corp.pomerium.io to: http://hello:8080 allowed_groups: - admins

每条策略由from（对外暴露的 URL）、to（后端目标）以及授权条件（allowed_domains/allowed_users/allowed_groups）组成。

方式二：外部 ConfigMap。使用config.existingConfig指向已部署的 ConfigMap，配合--config=/etc/pomerium/config.yaml启动参数加载。此时extraOpts与policy不能同时使用（见上述校验）。

7.4 安装后的自检提示（NOTES.txt）

模板中的 NOTES.txt 会检查 IdP 是否配置有效：它通过_helpers.tpl中的pomerium.providerOK判定clientID/clientSecret是否为空或仍为REPLACE_ME。若无效，安装完成后会打印一段醒目的 ERROR 提示，并给出补齐配置的helm upgrade --reuse-values命令模板；若有效，则根据service.type给出获取访问 URL 的方式（Ingress 域名、NodePort、LoadBalancer IP 或kubectl port-forward）。同时该 NOTES 也会固定输出 Chart 已废弃的警告。

八、Service 与 Ingress：访问入口是如何生成的

三个 Service 模板（authenticate-service.yaml、authorize-service.yaml、proxy-service.yaml）的生成规则：

• 每个 Service 都暴露https（端口为service.externalPort，默认 443，targetPort 为容器内https端口）与metrics（端口为metrics.port，默认 9090）两个端口；
• 若设置了service.nodePort，会附加nodePort字段；
• authorize 默认以 Headless（clusterIP: None）模式运行，便于 proxy 端做客户端侧负载均衡（这也是 2.0.0 起的行为，要求 Pomerium v0.3.0+ 配合）。

Ingress 的生成规则（ingress.yaml）值得注意：

• TLS 段固定包含authorize.<rootDomain>、authenticate.<rootDomain>与 forward-auth 域名（默认forwardauth.<rootDomain>）；
• 若未指定ingress.hosts且未启用 forward-auth，则自动从config.policy中提取每条策略的from主机名生成 host 规则，全部路由到 proxy Service；
• 若指定了ingress.hosts，则仅按显式列表生成规则；
• 若启用forwardAuth.enabled，则额外为 forward-auth 域名生成规则；
• 除非关闭service.authorize.headless，否则 authorize 不对外暴露 Ingress 规则（仅集群内部访问）。

values 中还有针对不同 Ingress Controller 的注解示例（注释形式）：nginx 需要kubernetes.io/ingress.class: nginx、nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"；GKE 负载均衡可用kubernetes.io/ingress.allow-http: "false"。

九、升级与变更历史（Changelog / Upgrading）

9.1 版本变更要点

• 4.0.0：升级到 Pomerium v0.4.0，并适配 Pomerium 的破坏性变更；对 Chart 用户无直接可见改动。
• 3.0.0：将 TLS 证书全部重构为 Kubernetes TLS Secret，并在 hook 中生成证书以避免证书频繁轮换（certificate churn）。
• 2.0.0：为各服务开放独立的replicaCount；将 authorize Service 切换为 ClusterIP 以实现客户端侧负载均衡（需 Pomerium v0.3.0+）。

9.2 从 3.0.0 升级的两种路径

README 针对 3.0.0 的证书重构给出了两类升级场景：

场景一：已有自动生成的证书

• 让 Pomerium 重新生成：将config.forceGenerateTLS设为true→ 执行升级 → 再设回false；
• 或保留现有证书：先保存现有 pomerium Secret → 设置config.existingLegacyTLSSecret: true→ 设置config.existingConfig指向原配置 Secret → 升级 → 从保存的 YAML 重建 pomerium Secret。

场景二：已有外部签发的证书（在 pomerium Secret 中）

• 先执行仓库提供的迁移脚本 scripts/upgrade-v3.0.0.sh，把旧格式 Secret 中的证书转换为标准的kubernetes.io/tlsSecret，再通过[service].existingTLSSecret指向新 Secret；
• 或继续沿用旧 Secret：设置config.existingLegacyTLSSecret: true。

upgrade-v3.0.0.sh的使用方式为./upgrade-v3.0.0.sh [secret name] [namespace]：脚本会从旧 Secret 的authenticate-key/authenticate-cert、authorize-key/authorize-cert、proxy-key/proxy-cert以及ca-cert字段提取并双重 base64 解码，分别创建<name>-authenticate-tls、<name>-authorize-tls、<name>-proxy-tls（kubectl create secret tls）和<name>-ca-tls（generic Secret）。

9.3 从 2.0.0 升级

由于 authorize Service 的类型与发现方式发生变化，需要执行helm upgrade --force来正确重建 authorize Service。

十、指标采集配置（Metrics Discovery）

Chart 提供两种将 Pomerium 指标暴露给 Prometheus 的途径，一般情况下只需配置其一。

10.1 方式一：Prometheus Operator ServiceMonitor

前提：集群已安装 Prometheus Operator 的 CRD。Chart 侧 values 配置：

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

Prometheus Operator 侧需配置 ServiceMonitor 选择器匹配该标签：

serviceMonitorSelector: matchLabels: release: prometheus # operator chart default

实现上，servicemonitor.yaml 仅在serviceMonitor.enabled时渲染monitoring.coreos.com/v1的 ServiceMonitor，其 selector 匹配 Chart 的标准标签（helm.sh/chart、app.kubernetes.io/instance），endpoints 指向名为metrics的端口。metrics.enabled会同时让 ConfigMap 写入metrics_address: :9090（见 configmap.yaml），各 Deployment 也会暴露名为metrics的 containerPort。

10.2 方式二：Prometheus kubernetes_sd_configs（注解自动发现）

不使用 Operator 时，可在 Service 上打 Prometheus 注解，配合kubernetes_sd_configs自动发现。Chart 侧 values：

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

Prometheus 侧 discovery 配置（基于role: endpoints，通过 relabel 保留带prometheus.io/scrape: true注解且 instance 为pomerium的端点，并把注解端口合并进__address__）：

- 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__

10.3 补充：分布式追踪

values 中还预留了基于 Jaeger 的分布式追踪配置（tracing.enabled/provider/debug及tracing.jaeger.collector_endpoint/agent_endpoint）。启用时 ConfigMap 会写入tracing_debug、tracing_provider等配置项，且各端点均为必填（模板用required强制校验，缺少时会直接中断渲染，见 configmap.yaml）。

十一、实践建议与注意事项

1. 务必先配置 IdP：clientID/clientSecret保持REPLACE_ME时部署不会完整生效，NOTES 输出会给出明确的补齐命令；
2. 妥善保管密钥：sharedSecret与cookieSecret建议用随机源生成并写入 Secret，而非明文放进 values；
3. 生产环境优先使用自备证书：generateTLS: false+existingTLSSecret组合便于与既有 PKI 体系集成；自动生成模式适合测试或快速验证；
4. 注意版本边界：config.existingLegacyTLSSecret仅用于从 <= 2.0.0 升级的兼容场景；service.authorize.headless依赖 Pomerium v0.3.0+ 的客户端负载均衡能力；
5. 掌握各模板的联动关系：从 values.yaml 出发，secret.yaml、configmap.yaml、tls-secrets.yaml 与三个 Deployment 模板共同决定了集群中的最终资源形态，修改任何一处配置时都应顺着这条链路验证渲染结果（可用helm template本地预览）。

最后再次提醒：本 Chart 已废弃，仅适用于理解与维护 Pomerium 0.5.x 系列部署；新项目请迁移到官方维护的 Helm Chart（helm repo add官方仓库后安装），并将此仓库内容作为参考实现来阅读。