企业官网建设流程全解析

本指南以 stable/kiam 的官方 README 为核心，结合 charts 仓库中 kiam chart 的模板源码与默认配置，系统讲解如何在 Kubernetes 集群中通过 Helm 部署 kiam（AWS IAM 与 Kubernetes 的集成组件），涵盖快速安装、TLS 证书三种注入方式、Agent/Server 双组件架构、全部可配置参数及部署后的验证方法。读者学完后可以独立完成 kiam 的安装、证书配置、参数调优与故障排查。

kiam 是什么：将 AWS IAM 引入 Kubernetes

kiam（Kubernetes IAM）是一个运行在 Kubernetes 集群内的代理组件，用于把 AWS IAM 的角色授权能力无缝地注入到集群的 Pod 中。它通过在每台节点上运行的 Agent 拦截 Pod 对 AWS 元数据服务（169.254.169.254）的访问请求，并由集群内的 Server 组件根据 Pod 上的iam.amazonaws.com/role注解，向 STS 换取临时凭证，从而让 Pod 无需在镜像内硬编码任何 AWS 密钥即可安全访问 AWS 资源。

本仓库中的stable/kiamchart（当前版本 Chart.yaml 中记录为version: 2.5.3、appVersion: 3.3）正是用于将 kiam 以 Helm 方式一键部署到集群中的官方封装。它同时创建 Agent 与 Server 两套 DaemonSet，并自动生成或挂载 TLS 证书、Service、RBAC 等全套资源。

重要：本 chart 的废弃说明

在深入使用之前必须了解：根据 README 的 Deprecation Notice 以及 Chart.yaml 中deprecated: true的标记，这个stable/kiamchart 已正式废弃，所有后续更新都转移到了由 uSwitch 官方维护的 Helm chart（位于 uswitch/kiam 项目仓库的helm/kiam目录）以及 Helm Hub 上的uswitch/kiamchart。

这意味着：

• 新问题与 Pull Request 应提交到 uSwitch 官方仓库；
• 对于已在使用该 chart 的存量环境，本指南中的安装与配置方法仍然有效；
• 新项目建议直接改用 uSwitch 官方维护的 chart 版本，以获得持续更新的支持。

架构速览：Agent 与 Server 双组件

从模板结构可以清晰看到 kiam 的部署形态——本 chart 在 templates 目录中为每个组件都准备了独立的资源模板：

• Agent（每节点代理）：由 agent-daemonset.yaml 定义为 DaemonSet，运行在集群的每一台节点上，监听--host-interface（默认cali+）上的元数据代理流量。Agent 本身以hostNetwork: true方式运行，通过 iptables 或接口监听将 Pod 对 AWS 元数据服务的请求转发给 Server。
• Server（凭证签发中心）：由 server-daemonset.yaml 定义为 DaemonSet（默认），负责读取集群中 Pod 与 Namespace 的注解（server-read-clusterrole.yaml 授予对namespaces、pods的watch/get/list权限），向 AWS STS 申请临时凭证，并通过 gRPC 把凭证下发给 Agent。

Server 通过 Service（见 server-service.yaml）暴露grpclb端口（默认 443），Agent 在启动参数中用--server-address指向<release-name>-server:443与之通信。这一"本地代理 + 集中签发"的架构，使得业务 Pod 完全无感地获得按角色隔离的 AWS 临时凭证。

前置条件

在安装前需要确认集群满足以下要求（来自 README）：

• Kubernetes 1.8+，且已启用 Beta API（本 chart 的 DaemonSet 使用apps/v1beta2API，模板见 agent-daemonset.yaml 与 server-daemonset.yaml）；
• 集群工作节点需要能够访问 AWS 元数据服务与 STS 服务；
• 若启用 RBAC（默认开启），需要集群支持 RBAC 授权。

快速安装：一条命令启动

最简安装方式（即 README 中的 TL;DR）：

$ helm install stable/kiam

如需指定 release 名称，则使用：

$ helm install stable/kiam --name my-release

该命令会以默认配置把 kiam 部署到集群。默认配置下，Agent 与 Server 都会安装（agent.enabled/server.enabled均为true），镜像使用quay.io/uswitch/kiam:v3.3，并自动生成自签名的 TLS 证书用于 Agent 与 Server 之间的安全通信。

安装后验证

安装完成后，NOTES.txt 会提示用以下命令确认 kiam 已启动：

$ kubectl --namespace=<namespace> get pods -l "app=kiam,release=<release-name>"

其中<namespace>与<release-name>需替换为实际部署的命名空间与 release 名称。

TLS 证书配置：三种方式任选

Agent 与 Server 之间的 gRPC 通信使用 mTLS，因此证书配置是部署的核心环节。README 提供了三种注入方式，本 chart 在模板中对应实现了全部逻辑。

方式一：默认自动生成自签名证书（开箱即用）

如果未做任何证书配置，agent-secret.yaml 与 server-secret.yaml 会在安装时自动创建包含 CA、证书与私钥的 Secret。证书生成逻辑位于 _helpers.tpl：

• Agent 证书通过genCA "kiam-ca" 365+genSignedCert生成；
• Server 证书的 SAN（Subject Alternative Name）会包含<release-name>-server、<release-name>-server:<port>以及127.0.0.1:<targetPort>三个地址，确保 Agent 通过 Service DNS 连接 Server 时证书校验通过。

方式二：使用自定义证书（tlsFiles）

README 提示，如果希望自己签发并管理证书，可以将 PEM 文件的 base64 编码内容（用base64命令生成）填入tlsFiles配置：

agent: tlsFiles: key: LS0tL... cert: LS0tL... ca: LS0tL... server: tlsFiles: key: LS0tL... cert: LS0tL... ca: LS0tL...

模板中的判断逻辑为：当tlsFiles.ca有值时，直接把tlsFiles渲染进 Secret 的data字段；否则才走自动生成逻辑（见 agent-secret.yaml）。仓库的 CI 冒烟测试 test-values.yaml 中即提供了完整的 base64 PEM 示例，可作为配置格式参考。

重要提示（来自 README）：hosts字段（即证书的 SAN）必须包含_release-name_-server:_server-service-port这个地址，例如my-release-server:443。如果证书中没有包含 Agent 实际用来连接 Server 的主机名，Agent 日志中会出现如下告警（实质是错误），并且 Pod 将无法获得凭证：

{"level":"warning","msg":"error finding role for pod: rpc error: code = Unavailable desc = there is no connection available","pod.ip":"100.120.0.2","time":"2018-05-24T04:11:25Z"}

方式三：复用已存在的 Secret（tlsSecret）

如果 TLS 证书 Secret 已经在集群中创建好，可以直接指定 Secret 名称而无需再提供证书内容：

agent: tlsSecret: kiam-agent-tls server: tlsSecret: kiam-server-tls

此时模板中的条件not .Values.agent.tlsSecret/not .Values.server.tlsSecret为假，Secret 不会被 chart 创建（见 agent-secret.yaml），而 DaemonSet 会改用该 Secret 作为 TLS 卷挂载来源（见 agent-daemonset.yaml）。

证书文件名映射（tlsCerts）

无论采用哪种方式，Agent/Server 进程内约定的证书文件名都可以通过tlsCerts配置：

agent: tlsCerts: certFileName: cert keyFileName: key caFileName: ca server: tlsCerts: certFileName: cert keyFileName: key caFileName: ca

这些文件名会被拼接到--cert=/etc/kiam/tls/...、--key=/etc/kiam/tls/...、--ca=/etc/kiam/tls/...启动参数中（见 agent-daemonset.yaml），默认挂载路径为/etc/kiam/tls。

完整配置参数详解

以下参数表完整取自 README，并与 values.yaml 的默认值一一对应，可在安装时按需覆盖：

几个关键参数背后的源码行为

• server.roleBaseArn：设置后模板会追加--role-base-arn=<值>参数；留空（默认null）时则追加--role-base-arn-autodetect，由 Server 启动时通过 EC2 元数据服务自动探测 ARN 前缀（见 server-daemonset.yaml）。
• server.sessionDuration：直接映射为--session-duration参数（默认15m），控制 Server 向 STS 申请的临时凭证有效期。
• agent.host.iptables：置为true时，Agent 容器会获得NET_ADMINcapability，并追加--iptables参数（见 agent-daemonset.yaml）；同时 agent-daemonset.yaml 会挂载/run/xtables.lockhostPath，用于并发修改 iptables 时的锁协调。
• agent.host.interface：默认cali+（Calico 网络接口前缀），映射为--host-interface参数，决定 Agent 在哪些接口上代理元数据流量；若使用 Flannel 等 CNI，需要按需调整。
• server.useHostNetwork：默认false；values.yaml 注释说明，当 Server 与 Agent 运行在同一批节点上时，可以置为true使用 hostNetwork 绕过 Agent 的 iptables 规则。
• server.probes.serverAddress：默认127.0.0.1，Server 的存活/就绪探针通过exec执行/kiam health命令，并携带--server-address、--server-address-refresh=2s、--timeout=5s与--gateway-timeout-creation参数（见 server-daemonset.yaml）；Agent 的存活探针则使用 HTTPGET /ping探测自身监听端口（agent-daemonset.yaml）。
• Prometheus 指标：当prometheus.scrape为true时，Agent/Server 各自生成的 Service 会自动加上prometheus.io/scrape: "true"与prometheus.io/port注解（见 agent-service.yaml 与 server-service.yaml），可直接被 Prometheus 自动发现并抓取。

安装时的参数指定方式

方式一：--set 命令行覆盖

每个参数都可以通过helm install的--set key=value[,key=value]参数指定。README 给出的示例：

$ helm install stable/kiam --name my-release \ --set=extraArgs.base-role-arn=arn:aws:iam::0123456789:role/,extraArgs.default-role=kube2iam-default,host.iptables=true,host.interface=cbr0

说明：上述示例中extraArgs.*与host.*实际会分别映射到 Server 与 Agent 的启动参数。更严谨的写法是把 Agent 相关参数放在agent.前缀下，例如--set=agent.host.iptables=true,agent.host.interface=cbr0。

方式二：-f 指定 values 文件

也可以把参数整理成 YAML 文件后在安装时传入：

$ helm install stable/kiam --name my-release -f values.yaml

完整的默认值文件可在本仓库的 values.yaml 中查看，其中包含每个参数的注释说明，例如agent.extraHostPathMounts还给出了在 Amazon Linux / RHEL（/etc/pki/ca-trust/extracted/pem）与其他发行版（/usr/share/ca-certificates）挂载 CA 证书目录的示例。

部署后的使用与验证

kiam 通过注解（annotation）声明 Pod 要使用的 IAM 角色，完整使用流程记录在 NOTES.txt 中：

Step 1：给命名空间添加允许角色注解

在需要启用 kiam 的命名空间上添加iam.amazonaws.com/permitted注解，值为允许的角色 ARN 或匹配角色 ARN 的正则表达式：

kind: Namespace metadata: name: iam-example annotations: iam.amazonaws.com/permitted: "<Role ARN or a Regex matching role ARN(s)>"

Step 2：给 Pod 添加角色注解

在 Pod 上添加iam.amazonaws.com/role注解，声明该 Pod 要承担的 IAM 角色。kiam 的 Server 会读取命名空间与 Pod 的注解（对应 server-read-clusterrole.yaml 授予的 RBAC 权限），校验后向 STS 申请临时凭证并通过 Agent 注入。

Step 3：在 Pod 内验证凭证

进入 Pod 后，用curl访问 AWS 元数据服务地址验证是否获得了角色凭证：

$ curl http://169.254.169.254/latest/meta-data/iam/security-credentials/

如果输出返回了对应角色的临时安全凭证，说明 kiam 的 Agent→Server→STS 链路已打通。若出现前文所述 "error finding role for pod: ... there is no connection available" 之类的 Agent 日志，请优先检查 Server 证书的 SAN 是否包含 Agent 实际使用的连接地址。

卸载 kiam

卸载my-release这个 release：

$ helm delete my-release

该命令会删除与该 chart 关联的所有 Kubernetes 组件（DaemonSet、Service、Secret、RBAC、ServiceAccount、PodSecurityPolicy 等）并删除 release 记录。

相关资源索引

• 核心文档：stable/kiam/README.md
• Chart 元数据（含废弃标记与版本信息）：stable/kiam/Chart.yaml
• 默认配置值：stable/kiam/values.yaml
• 模板实现：templates/agent-daemonset.yaml、templates/server-daemonset.yaml、templates/_helpers.tpl、templates/agent-secret.yaml、templates/server-secret.yaml
• RBAC 与安全：templates/server-read-clusterrole.yaml、templates/server-write-clusterrole.yaml
• 使用指引：templates/NOTES.txt
• CI 测试配置示例（含完整 base64 证书）：ci/test-values.yaml

需要提醒的是，由于本 chart 已标记为 deprecated，生产环境新部署建议优先评估 uSwitch 官方维护的 kiam Helm chart；但了解本 chart 的架构与参数体系，仍然对理解 kiam 的工作原理和迁移旧环境具有直接的参考价值。