spvest/azure-keyvault-controller

Azure Key Vault Controller 镜像文档

镜像概述和主要用途

该Docker镜像包含一个Kubernetes控制器，旨在实现Azure Key Vault与Kubernetes集群之间的密钥同步。通过自动化将Azure Key Vault中的对象（如密钥、证书、机密）同步为Kubernetes Secrets，解决手动管理敏感信息的复杂性，提升密钥管理的安全性和效率。

核心功能和特性

• 自动同步：支持将Azure Key Vault中的密钥（Key）、证书（Certificate）、机密（Secret）自动同步至Kubernetes Secrets
• 多策略支持：提供实时同步（基于Key Vault事件通知）和定期同步（可配置时间间隔）两种模式
• 权限集成：通过Azure AD实现身份验证，支持基于RBAC的细粒度权限控制
• 配置灵活：支持自定义同步规则，包括对象过滤、Secret元数据设置、更新策略等
• 状态监控：暴露Prometheus指标，便于监控同步状态和控制器运行情况

使用场景和适用范围

• 容器化应用：需要在Kubernetes中安全使用Azure Key Vault存储的敏感信息的应用
• CI/CD流水线：在自动化部署流程中动态获取最新密钥，避免硬编码敏感数据
• 多环境管理：跨开发、测试、生产环境统一管理密钥，确保环境一致性
• 合规需求：满足密钥自动轮换、审计跟踪等安全合规要求的场景

使用方法和配置说明

前置条件

• 运行中的Kubernetes集群（v1.19+）
• Azure Key Vault实例（已创建并包含需同步的对象）
• Azure AD服务主体（具备Key Vault访问权限和Kubernetes集群访问权限）

部署方式

通过Kubernetes资源部署

1. 创建命名空间

   bash
   kubectl create namespace azure-keyvault-controller
   

2. 配置Azure认证信息
   创建包含Azure AD服务主体凭证的Secret：

   yaml
   apiVersion: v1
   kind: Secret
   metadata:
     name: azure-keyvault-credentials
     namespace: azure-keyvault-controller
   type: Opaque
   data:
     clientId: <base64-encoded-client-id>
     clientSecret: <base64-encoded-client-secret>
     tenantId: <base64-encoded-tenant-id>
   

   应用配置：

   bash
   kubectl apply -f azure-credentials-secret.yaml
   

3. 部署控制器
   创建控制器Deployment：

   yaml
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: azure-keyvault-controller
     namespace: azure-keyvault-controller
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: azure-keyvault-controller
     template:
       metadata:
         labels:
           app: azure-keyvault-controller
       spec:
         serviceAccountName: azure-keyvault-controller-sa
         containers:
         - name: controller
           image: sparebankenvest/azure-keyvault-controller:latest
           env:
           - name: AZURE_TENANT_ID
             valueFrom:
               secretKeyRef:
                 name: azure-keyvault-credentials
                 key: tenantId
           - name: AZURE_CLIENT_ID
             valueFrom:
               secretKeyRef:
                 name: azure-keyvault-credentials
                 key: clientId
           - name: AZURE_CLIENT_SECRET
             valueFrom:
               secretKeyRef:
                 name: azure-keyvault-credentials
                 key: clientSecret
           - name: SYNC_INTERVAL
             value: "300"  # 定期同步间隔（秒），默认300s
           resources:
             requests:
               cpu: 100m
               memory: 128Mi
             limits:
               cpu: 500m
               memory: 256Mi
   

   应用部署：

   bash
   kubectl apply -f controller-deployment.yaml
   

4. 创建同步规则
   通过自定义资源AzureKeyVaultSecret定义同步规则：

   yaml
   apiVersion: spv.no/v2beta1
   kind: AzureKeyVaultSecret
   metadata:
     name: example-secret
     namespace: default
   spec:
     vault:
       name: my-keyvault  # Azure Key Vault名称
       object:
         name: my-secret  # Key Vault中对象的名称
         type: secret     # 对象类型：secret, key, certificate
     output:
       secret:
         name: my-k8s-secret  # 生成的Kubernetes Secret名称
         type: Opaque         # Secret类型
   

   应用规则：

   bash
   kubectl apply -f example-azure-keyvault-secret.yaml
   

配置参数说明

注意事项

• 确保Azure AD服务主体具备最小权限原则，仅授予必要的Key Vault访问权限
• 对于证书类型对象，控制器会自动转换为包含证书链和私钥的Kubernetes TLS Secret
• 实时同步依赖Azure Key Vault事件网格配置，需额外部署事件接收器组件（参考GitHub文档）
• 在生产环境中建议启用控制器的高可用部署（replicas ≥ 2）