pulumi/pulumi-kubernetes-operator

Pulumi Kubernetes Operator 镜像文档

镜像概述

Pulumi Kubernetes Operator是Pulumi官方提供的Kubernetes Operator，用于在Kubernetes集群中声明式管理Pulumi资源。通过Kubernetes自定义资源定义(CRD)扩展Kubernetes API，支持以声明式方式定义和控制Pulumi Stack、Deployment等资源，实现基础设施即代码(IaC)的自动化管理，将Pulumi的IaC能力深度集成到Kubernetes工作流中。

核心功能与特性

1. 声明式资源管理

• 通过Kubernetes CRD定义Pulumi资源（如Stack、Deployment等），支持YAML/JSON格式声明资源期望状态
• 自动协调资源实际状态与期望状态，确保基础设施与声明一致

2. 自动化工作流

• 自动触发Pulumi核心操作：支持pulumi up（部署/更新）、pulumi refresh（状态刷新）、pulumi destroy（资源销毁）等
• 内置重试机制，处理临时故障（如网络波动、后端不可用）

3. 状态与后端集成

• 无缝对接Pulumi Backend（支持Pulumi Service、AWS S3、Azure Blob、Google Cloud Storage等），统一存储资源状态
• 支持状态加密与版本控制，确保基础设施状态可追溯

4. 多环境与多租户支持

• 管理多环境（开发/测试/生产）的Pulumi Stack，通过Kubernetes Namespace实现资源隔离
• 支持多租户场景，基于Kubernetes RBAC控制不同租户对Pulumi资源的访问权限

5. 事件驱动与可观测性

• 响应资源变更事件自动触发操作（如更新Stack配置后执行pulumi up）
• 输出详细操作日志与状态信息，集成Kubernetes Events与Metrics，支持Prometheus监控

6. 安全与权限控制

• 基于Kubernetes RBAC实现细粒度权限控制，限制资源操作范围
• 支持通过Kubernetes Secret管理敏感信息（如Pulumi访问令牌、云厂商凭证）

使用场景与适用范围

典型使用场景

• Kubernetes集群内IaC管理：在Kubernetes中统一管理集群内外的基础设施资源（如云资源、数据库、网络等）
• 多云/混合云自动化：通过单个Operator管理跨AWS、Azure、GCP等多云环境的Pulumi资源
• CI/CD流水线集成：作为Kubernetes原生组件接入CI/CD流程，通过Kubernetes API触发Pulumi部署
• 大规模基础设施控制：对成百上千个Pulumi Stack实现声明式统一管理，降低人工操作成本

适用范围

• 采用Pulumi进行IaC管理的团队
• 基于Kubernetes构建云原生应用的组织
• 需要自动化基础设施部署与运维的DevOps/SRE团队
• 追求声明式、可观测、可审计基础设施管理的企业

使用方法与配置说明

前提条件

• Kubernetes集群（v1.21+）
• kubectl命令行工具（配置集群访问权限）
• Pulumi账号与访问令牌（获取方式：https://app.pulumi.com/account/tokens%EF%BC%89
• （可选）Helm 3+（用于简化部署）

部署Operator到Kubernetes集群

方式1：通过kubectl部署

1. 安装CRD

bash
kubectl apply -f https://raw.githubusercontent.com/pulumi/pulumi-kubernetes-operator/main/deploy/crds/pulumi.com_stacks.yaml
kubectl apply -f https://raw.githubusercontent.com/pulumi/pulumi-kubernetes-operator/main/deploy/crds/pulumi.com_deployments.yaml

2. 部署Operator

bash
kubectl apply -f https://raw.githubusercontent.com/pulumi/pulumi-kubernetes-operator/main/deploy/operator.yaml

方式2：通过Helm部署（推荐）

1. 添加Helm仓库

bash
helm repo add pulumi https://pulumi.github.io/pulumi-kubernetes-operator/
helm repo update

2. 安装Operator

bash
helm install pulumi-operator pulumi/pulumi-kubernetes-operator \
  --namespace pulumi-system \
  --create-namespace \
  --set manager.logLevel=info

配置Pulumi访问凭证

创建Kubernetes Secret存储Pulumi访问令牌（替换<your-pulumi-token>）：

bash
kubectl create secret generic pulumi-access-token \
  --namespace pulumi-system \
  --from-literal=accessToken=<your-pulumi-token>

定义Pulumi Stack资源示例

创建my-stack.yaml文件，定义一个Pulumi Stack资源：

yaml
apiVersion: pulumi.com/v1
kind: Stack
metadata:
  name: my-dev-stack
  namespace: pulumi-system
spec:
  # Pulumi Stack名称（格式：<org>/<project>/<stack>）
  stack: my-org/my-project/dev
  # Git仓库地址（存放Pulumi项目代码）
  projectRepo: https://github.com/my-org/my-pulumi-project.git
  # 代码分支
  branch: main
  # 项目在仓库中的路径
  projectPath: ./infrastructure/aws
  # Pulumi配置参数（对应pulumi config set）
  config:
    aws:region: us-west-2
    app:replicas: "3"
  # 引用敏感环境变量（来自Kubernetes Secret）
  envSecrets:
    - name: pulumi-access-token  # 引用上文创建的Secret
  # Pulumi Backend配置（可选，默认使用Pulumi Service）
  backend:
    url: s3://my-pulumi-backend-bucket  # 示例：使用S3作为Backend
  # 删除Stack资源时是否自动执行pulumi destroy
  destroyOnDelete: true

应用Stack资源：

bash
kubectl apply -f my-stack.yaml

资源状态与操作监控

• 查看Stack资源列表

bash
kubectl get stacks -n pulumi-system

• 查看Stack详细状态

bash
kubectl describe stack my-dev-stack -n pulumi-system

（状态信息包含最近操作结果、执行日志、错误信息等）

• 查看Operator日志

bash
kubectl logs -l app=pulumi-kubernetes-operator -n pulumi-system -f

配置参数说明

Operator配置参数（Helm安装时设置）

Stack资源配置字段（spec部分）

故障排查

常见问题与解决方法

1. Stack资源一直处于Pending状态

   • 检查Operator是否正常运行：kubectl get pods -n pulumi-system
   • 查看Operator日志：kubectl logs <operator-pod-name> -n pulumi-system
   • 检查Pulumi访问令牌是否有效：确认Secret中的accessToken字段正确

2. pulumi up执行失败

   • 查看Stack资源的status字段：kubectl get stack my-dev-stack -o yaml
   • 检查Pulumi项目代码是否存在语法错误（可本地执行pulumi up验证）
   • 确认云厂商凭证是否正确配置（通过envSecrets引用包含云凭证的Secret）

3. Backend连接失败

   • 验证Backend URL格式是否正确（如S3需指定region参数：s3://bucket?region=us-west-2）
   • 检查Operator Pod是否有权限访问Backend（如网络策略、IAM角色绑定）

版本与兼容性

• 支持Kubernetes集群版本：v1.21+
• 支持Pulumi CLI版本：v3.0.0+
• 支持Pulumi Backend类型：Pulumi Service、AWS S3、Azure Blob Storage、Google Cloud Storage、Local Filesystem