hashicorp/terraform-cloud-operator

Kubernetes Operator for Terraform Cloud

镜像概述和主要用途

该Kubernetes Operator是一款用于在Kubernetes环境中管理Terraform Cloud资源的工具。它通过Kubernetes自定义资源（CR）实现声明式管理，允许用户直接通过Kubernetes API定义和控制Terraform Cloud的workspaces、runs、variables等资源，实现Kubernetes与Terraform Cloud的无缝集成与统一管理。

核心功能和特性

• 自定义资源支持：提供TerraformWorkspace、TerraformRun等自定义资源定义（CRD），支持通过Kubernetes资源声明Terraform Cloud资源状态
• 声明式管理：采用Kubernetes声明式API范式，通过YAML配置定义资源期望状态，Operator自动协调实际状态与期望状态
• 状态同步机制：实时监控Kubernetes自定义资源与Terraform Cloud实际资源状态，确保双向状态一致性
• 自动化操作流：支持自动触发Terraform runs、处理plan/apply结果、管理workspace生命周期等自动化操作
• 安全集成：通过Kubernetes Secrets管理Terraform Cloud API令牌等敏感信息，实现安全认证

使用场景和适用范围

• Kubernetes环境中的IaC管理：适用于在Kubernetes集群内统一管理基础设施即代码（IaC）资源的DevOps团队
• 多云资源编排：需要通过Terraform Cloud管理多云资源，同时希望利用Kubernetes控制平面进行统一编排的场景
• GitOps工作流集成：可与GitOps工具（如ArgoCD、Flux）结合，实现Terraform Cloud资源的GitOps式管理
• CI/CD流水线整合：在Kubernetes CI/CD流程中嵌入Terraform Cloud资源的创建与更新操作

使用方法和配置说明

前提条件

• Kubernetes集群（v1.19+）
• Terraform Cloud账户及API令牌（需具备workspace管理权限）
• kubectl命令行工具（已配置集群访问权限）

部署步骤

1. 部署CRD

yaml
# terraform-operator-crd.yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: terraformworkspaces.terraform-operator.example.com
spec:
  group: terraform-operator.example.com
  versions:
    - name: v1alpha1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string
                terraformVersion:
                  type: string
                variables:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                      value:
                        type: string
                      valueFrom:
                        type: object
                        properties:
                          secretKeyRef:
                            type: object
                            properties:
                              name:
                                type: string
                              key:
                                type: string
                      category:
                        type: string
                      sensitive:
                        type: boolean
  scope: Namespaced
  names:
    plural: terraformworkspaces
    singular: terraformworkspace
    kind: TerraformWorkspace
    shortNames:
      - tfws

应用CRD：

bash
kubectl apply -f terraform-operator-crd.yaml

2. 配置认证信息

创建存储Terraform Cloud API令牌的Secret：

bash
kubectl create secret generic terraform-cloud-credentials \
  --from-literal=api-token="your-terraform-cloud-api-token"

3. 部署Operator

yaml
# terraform-operator-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: terraform-operator
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: terraform-operator
  template:
    metadata:
      labels:
        app: terraform-operator
    spec:
      containers:
        - name: operator
          image: docker.xuanyuan.run/[operator-image]:[version]  # 替换为实际镜像名称和版本
          env:
            - name: TERRAFORM_CLOUD_API_TOKEN
              valueFrom:
                secretKeyRef:
                  name: terraform-cloud-credentials
                  key: api-token
            - name: TF_CLOUD_ORGANIZATION
              value: "your-terraform-org"  # 替换为实际Terraform组织名
            - name: LOG_LEVEL
              value: "info"
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi

部署Operator：

bash
kubectl apply -f terraform-operator-deployment.yaml

创建Terraform Cloud资源示例

创建Terraform Workspace

yaml
# example-workspace.yaml
apiVersion: terraform-operator.example.com/v1alpha1
kind: TerraformWorkspace
metadata:
  name: production-app
spec:
  name: "production-app"
  description: "Production environment workspace managed by Kubernetes"
  terraformVersion: "1.6.0"
  variables:
    - key: "environment"
      value: "production"
      category: "terraform"
      sensitive: false
    - key: "db_password"
      valueFrom:
        secretKeyRef:
          name: db-credentials
          key: password
      category: "env"
      sensitive: true

应用资源：

bash
kubectl apply -f example-workspace.yaml

配置参数说明

环境变量配置

自定义资源字段说明（TerraformWorkspace）

注意事项

• Kubernetes集群版本需≥1.19以支持CRD子资源状态功能
• Terraform Cloud API令牌需具备workspaces:read、workspaces:write、runs:read、runs:write权限
• 敏感信息必须通过Kubernetes Secrets管理，禁止在CR中明文存储
• 建议为Operator配置资源限制，避免过度占用集群资源