企业官网建设流程全解析

• 网络安全
• 认证鉴权
• 运维
• 后端

本指南以 Teleport 仓库中 examples/chart/access/jira 下的 Helm Chart 为核心，系统讲解如何通过teleport-plugin-jira这个官方 Helm Chart 在 Kubernetes 中部署 Teleport Access Request Jira 审批插件。读完本文，你将掌握该 Chart 的完整 Values 配置体系（Teleport 连接、Jira 凭据、Webhook 回调、tbot 免密集成、日志与安全上下文等），理解其模板如何生成插件所需的 TOML 配置文件，并能结合源码快速定位参数的真实含义与校验逻辑，直接照抄可用的配置示例完成生产级部署。

一、Chart 定位：它解决的问题

Teleport 的 Access Request（访问请求）工作流允许用户通过tsh发起访问申请，由审批人决定放行或拒绝。当团队习惯使用 Jira 管理工单时，Teleport 官方提供了 Jira 审批插件：审批人以 Jira Issue 为载体验证访问请求——申请会以 Issue 的形式自动创建在指定的 Jira 项目板上，审批人在 Jira 中对 Issue 执行"已批准/已拒绝"的流转，插件通过 Webhook 收到状态变更后再回调 Teleport 完成对应的审批动作。

该插件同时兼容 Jira Cloud 与 Jira Server 8 及更高版本（见 integrations/access/jira/README.md）。而本文的主角——examples/chart/access/jira下的 Helm Chart（Chart 名为teleport-plugin-jira），正是把插件部署到 Kubernetes 的官方封装：它以声明式的方式管理 Deployment、ConfigMap、Secret、Service 以及可选的 tbot 凭据自动续期组件。

Chart 的元信息（Chart.yaml）显示：

• apiVersion: v2，type: application；
• version与appVersion同步为19.0.0-prealpha.2，即插件镜像版本与 Chart 版本保持一致，升级插件应通过升级 Chart 完成；
• 依赖tbot子 Chart，仅在tbot.enabled: true时才会被引入（condition: tbot.enabled）。

Chart 目录结构如下，模板与测试一一对应：

examples/chart/access/jira/ ├── Chart.yaml # Chart 元信息与 tbot 依赖声明 ├── values.yaml # 全部可配置项及默认值（核心文档） ├── values.schema.json # 配置项的 JSON Schema 校验 ├── templates/ │ ├── _helpers.tpl # 名称、标签、identity 取值辅助模板 │ ├── configmap.yaml # 生成插件 TOML 配置 │ ├── deployment.yaml # 插件 Deployment │ ├── secret.yaml # 可选：Jira API Token 自动建 Secret │ └── service.yaml # Webhook 回调 Service └── tests/ # helm-unittest 快照测试

二、安装方式

原 README 指向了官方 "Access Requests with JIRA" 指南。在仓库内，与部署最相关的配套资料是插件源码目录下的 integrations/access/jira/README.md（含 Jira Cloud / Jira Server 的项目板搭建指引），以及 example_config.toml（插件自身的裸配置示例，可辅助理解 Chart 生成配置的对应关系）。

使用 Chart 的标准流程是：

# 1. 准备一份 values 文件（见下文配置章节） helm install teleport-plugin-jira \ --values my-values.yaml \ examples/chart/access/jira

也可以指定版本安装（--version与 Chart 版本对齐，镜像 tag 会默认取 Chart 的appVersion）。

部署成功后，Kubernetes 集群中会创建以下资源：

三、Values 完整配置指南

这是本 Chart 的核心内容。所有配置项及默认值都定义在 values.yaml 中，并配套 values.schema.json 做参数合法性约束。下面按功能域逐一展开。

3.1 teleport：插件与 Teleport 集群的连接

teleport: # 必填（未启用 tbot 时）：Teleport 集群地址，必须包含域名和端口。 # - 连 Proxy：teleport.example.com:443 或 teleport.example.com:3080 # - 连 Auth：teleport-auth.example.com:3025 # 地址为空时，会依次回退到 tbot.teleportProxyAddress / tbot.teleportAuthAddress。 address: "" # 存放 Teleport 连接凭据的 Kubernetes Secret 名称。 identityFromSecret: "" # 上述 Secret 中存放凭据的 key。若 key 就是 "auth_id"，可省略。 identitySecretPath: "auth_id"

凭据 Secret 的推荐格式如下（values.yaml 注释中的示例）：

apiVersion: v1 kind: Secret type: Opaque metadata: name: teleport-plugin-identity data: auth_id: #... # tctl auth sign --format=file 等工具产出的身份文件

从模板实现（configmap.yaml）可以看到addr的取值优先级：teleport.address为空时依次回退到tbot.teleportProxyAddress、tbot.teleportAuthAddress；而身份文件路径被固定挂载到容器内/var/lib/teleport/plugins/jira/teleport-identity/<identitySecretPath>，并设置了refresh_identity = true以支持身份文件的周期性刷新。

3.2 jira：Jira 侧的连接与 Issue 参数

jira: # 必填：Jira 实例地址。 # - Jira Cloud：https://[your-jira].atlassian.net # - 自建 Jira：https://jira.example.com/ url: "" # 必填：与 API Token 关联的 Jira 用户名或邮箱。 username: "" # Jira API Token。设置后 Chart 会为你自动创建 Kubernetes Secret。 # 若同时设置了 apiTokenFromSecret，本值不生效。 apiToken: "" # 已有 Secret 的名称（需在 helm install 之前创建好）。 apiTokenFromSecret: "" # 已有 Secret 中存放 API Token 的 key。 apiTokenSecretPath: "jiraApiToken" # 必填：创建 Issue 的 Jira 项目 key（如 "ACC"、"EXAM"）。 project: "" # 创建 Issue 时使用的 Issue 类型。 issueType: "Task"

两种 API Token 注入方式二选一：

• 方式 A（自动建 Secret）：直接填jira.apiToken，Chart 会在 secret.yaml 中创建一个名为<release>-teleport-plugin-jira-secret的 Opaque Secret，key 为jiraApiToken，值为 base64 编码后的 Token；
• 方式 B（复用已有 Secret）：设置jira.apiTokenFromSecret，此时 Chart 不会创建 Secret，而是直接把该 Secret 挂载进容器。

无论哪种方式，最终 Token 都会出现在容器内固定路径/var/lib/teleport/plugins/jira/jira_api_token，并在生成的 TOML 中由api_token指向该路径（见 configmap.yaml），从而避免明文 Token 进入配置文件。

3.3 http：Jira Webhook 回调服务器

当审批人在 Jira 中把 Issue 流转为"已批准/已拒绝"时，Jira 通过 Webhook 反向通知插件，插件再回调 Teleport 完成审批。因此回调服务器的公网可达性、TLS 与 Basic Auth 都至关重要：

http: # Webhook 回调服务器的外部访问地址，例如 [https://]teleport-proxy.example.com。 publicAddress: "" # 存放 TLS 私钥和证书的 Kubernetes Secret 名称。 tlsFromSecret: "" # 该 Secret 中 TLS 私钥的 key。 tlsKeySecretPath: "tls.key" # 该 Secret 中 TLS 证书的 key。 tlsCertSecretPath: "tls.crt" # 可选的 Basic Auth 保护，Jira Webhook 侧需配置相同凭据。 basicAuth: user: "" password: ""

从 service.yaml 看，Service 默认类型为LoadBalancer（对应 values 的serviceType: LoadBalancer），监听443端口并把流量转发到 Pod 的8443端口（即容器内 TOML 中的listen_addr = ":8443"）。TLS 私钥与证书会分别以 subPath 方式挂载到/var/lib/teleport/plugins/jira/tls/tls.key和tls.crt（见 deployment.yaml）。

3.4 tbot：可选的免密凭据自动续期

tbot是 Teleport 的 Machine ID 机器人，负责为插件自动生成并周期性续期连接 Teleport 的短期凭据，这样就不需要手动维护teleport.identityFromSecret。本 Chart 直接内置了 tbot 子 Chart 作为依赖：

tbot: # 是否随插件一起部署 tbot。 enabled: false # 必填（启用 tbot 时）：要加入的 Teleport 集群名称。 clusterName: "" # 二选一：Proxy 地址（推荐，云上必须用 Proxy），如 test.teleport.sh:443。 teleportProxyAddress: "" # 二选一：Auth 地址，如同集群内联调时 # teleport-auth.teleport-namespace.svc.cluster.local:3025。 teleportAuthAddress: "" # 加入集群的方式，默认 kubernetes。 joinMethod: "kubernetes" token: ""

启用 tbot 后，模板会自动切换凭据来源（见 _helpers.tpl 中的jira.identitySecretName与jira.identitySecretPath）：

• 身份 Secret 名称变为<release>-tbot-out（tbot 默认输出 Secret）；
• 身份文件在 Secret 中的 key 变为identity（而非手动模式下的auth_id）。

values.yaml 中特别注明：nameOverride: tbot与defaultOutput.enabled: true这两个值不要改动，它们保证 tbot 的输出 Secret 命名稳定，改动会破坏 Chart 的挂载逻辑。

3.5 chartMode、log 与通用 Kubernetes 配置

# 云平台辅助模式，当前仅支持 "aws"。 # 设为 aws 后，Service 会自动附加 AWS 负载均衡器注解 # （nlb、backend-protocol tcp、跨可用区负载均衡）。 chartMode: "" # 插件日志 log: severity: INFO # DEBUG / INFO / WARN / ERROR，生产推荐 INFO，排障可临时用 DEBUG output: stdout # stdout / stderr，或文件路径如 /var/log/teleport.log # 镜像 image: repository: public.ecr.aws/gravitational/teleport-plugin-jira pullPolicy: IfNotPresent tag: "" # 默认取 Chart appVersion；仅开发/自定义场景使用

其中image.tag有明确警告：不要用它来控制生产环境插件版本——Chart 与插件版本必须配套（helm install --version X.Y.Z才是正确做法），强行用 tag 覆盖会带来兼容性问题。

其余通用项（默认值均见 values.yaml）：

podAnnotations与serviceAnnotations已标记为废弃，应改用annotations.pod与annotations.service。

四、一份可直接运行的完整 values 示例

综合上述参数，下面是一份同时启用 tbot（推荐）的完整配置：

teleport: address: "" # 留空，交由 tbot 提供连接信息 jira: url: "https://your-jira.atlassian.net" username: "teleport-bot@example.com" apiTokenFromSecret: "jira-token" # 方式 B：复用已有 Secret apiTokenSecretPath: "jiraApiToken" project: "ACC" issueType: "Task" http: publicAddress: "https://jira-webhook.example.com" tlsFromSecret: "jira-webhook-tls" # 内含 tls.key / tls.crt basicAuth: user: "webhook-user" password: "webhook-password" tbot: enabled: true clusterName: "teleport.example.com" teleportProxyAddress: "teleport.example.com:443" joinMethod: "kubernetes" token: "" # 按实际 join 方式填充 log: severity: INFO output: stdout resources: requests: cpu: "100m" memory: "128Mi" limits: cpu: "100m" memory: "128Mi" securityContext: runAsNonRoot: true readOnlyRootFilesystem: true

若不想使用 tbot，则改为手动凭据模式：

teleport: address: "teleport.example.com:443" identityFromSecret: "teleport-plugin-identity" identitySecretPath: "auth_id" tbot: enabled: false

五、源码级原理：模板如何生成插件配置

理解 Chart 内部机制的关键在 configmap.yaml，它把 Values 渲染成插件实际读取的 TOML：

[teleport] addr = "" # 依次回退 teleport.address / tbot.teleportProxyAddress / tbot.teleportAuthAddress identity = "/var/lib/teleport/plugins/jira/teleport-identity/auth_id" refresh_identity = true [jira] url = "https://your-jira.atlassian.net" username = "teleport-bot@example.com" api_token = "/var/lib/teleport/plugins/jira/jira_api_token" project = "ACC" issue_type = "Task" [http] listen_addr = ":8443" public_addr = "https://jira-webhook.example.com" https_key_file = "/var/lib/teleport/plugins/jira/tls/tls.key" https_cert_file = "/var/lib/teleport/plugins/jira/tls/tls.crt" [log] output = "stdout" severity = "INFO"

测试目录下的快照文件（configmap_test.yaml.snap）展示了渲染后的完整结果，例如：

[teleport] addr = "teleport.example.com:1234" identity = "/var/lib/teleport/plugins/jira/teleport-identity/auth_id" refresh_identity = true [jira] url = "https://jira.example.com" username = "user@example.com" api_token = "/var/lib/teleport/plugins/jira/jira_api_token" project = "ACC" issue_type = "Task"

这与 Chart 自带测试（tests/configmap_test.yaml、tests/deployment_test.yaml）使用helm-unittest快照断言一一对应，测试覆盖了镜像覆盖、TLS Secret 自定义、Basic Auth、日志路径等场景。

六、与插件源码的对应关系：参数校验与默认值

Chart 生成的 TOML 最终由插件源码解析，可在 integrations/access/jira/config.go 中看到对应结构体JiraConfig（url、username、api_token、project、issue_type）以及Config.CheckAndSetDefaults()的校验逻辑，这解释了 Chart 中若干"必填"标注的底层原因：

• jira.url缺失直接报错，且必须以https://开头（Jira Server 场景需确保地址符合此要求）；
• jira.username、jira.api_token缺失都会报missing required value；
• jira.issue_type为空时默认补为Task（与 Chart 默认值一致）；
• 插件侧默认http.listen_addr为:8081，而 Chart 固定使用:8443并通过 Service 映射；
• 日志默认值插件侧为stderr，Chart 侧默认stdout，以 Chart 渲染结果为准。

也就是说，即便绕过 Chart 直接用插件二进制部署（参考 example_config.toml），上述校验规则同样生效，二者配置语义完全互通。

七、部署后的验证与排障要点

1. 确认 Pod 就绪：kubectl get pods，查看插件容器是否正常启动；容器启动命令固定为teleport-plugin start --config /etc/teleport-jira.toml，并设置了环境变量TELEPORT_PLUGIN_FAIL_FAST=true——连接失败会快速退出以便于故障暴露（见 deployment.yaml）。
2. 检查回调可达性：在 Jira 中配置 Webhook 时，URL 需指向http.publicAddress（含 TLS），并在 Jira 侧填写与http.basicAuth一致的凭据。
3. 日志排障：首次联调可将log.severity临时调为DEBUG观察插件与 Teleport/Jira 的交互细节，稳定后改回INFO。
4. 权限与安全：生产环境建议按需配置securityContext（如runAsNonRoot: true、readOnlyRootFilesystem: true，values.yaml 中有对应注释示例）与resources资源限额；凭据一律走 Kubernetes Secret 挂载，不写入 ConfigMap 明文。

八、小结

teleport-plugin-jiraHelm Chart 将 Teleport Access Request 与 Jira 的审批闭环完整封装进了 Kubernetes 生态：通过teleport.*定义集群连接、jira.*定义工单参数、http.*打通 Webhook 回调、tbot.*实现凭据免运维续期，并辅以完善的注解、安全上下文与调度配置。部署时只需对照 values.yaml 填写上述参数，即可让"tsh 申请 → Jira Issue 审批 → 自动放行/拒绝"的流程在集群内稳定运行。

• 网络安全
• 认证鉴权
• 运维
• 后端