crossplane/stack-azure

Crossplane Stack for Microsoft Azure 技术文档

一、镜像概述和主要用途

Crossplane Stack for Microsoft Azure 是一个基于 Crossplane 的扩展组件（Stack），旨在通过 Kubernetes API 统一管理 Microsoft Azure 云资源。作为 Crossplane 生态的一部分，该 Stack 提供了与 Azure 云服务的深度集成，允许用户以声明式方式定义、部署和管理 Azure 基础设施资源（如虚拟机、存储账户、网络组件等），实现基础设施即代码（IaC）与 Kubernetes 控制平面的无缝协同。

二、核心功能和特性

2.1 核心功能

• Azure 服务原生支持：覆盖 Azure 核心服务，包括计算（VM、AKS）、存储（Storage Account、Blob）、网络（VNet、Subnet）、数据库（SQL Database、Cosmos DB）等资源的声明式管理。
• Kubernetes 原生 API：通过 CustomResourceDefinitions (CRDs) 将 Azure 资源抽象为 Kubernetes 资源，支持使用 kubectl、Kubernetes API 或客户端工具（如 Terraform、ArgoCD）进行操作。
• 声明式配置与自愈：基于期望状态（Desired State）自动同步 Azure 资源，当实际状态偏离期望状态时触发自动修复，确保基础设施一致性。
• 资源依赖管理：自动解析并维护 Azure 资源间的依赖关系（如先创建 VNet 再创建 VM），无需手动编排顺序。

2.2 关键特性

• 版本化与兼容性：与 Azure API 版本同步，支持资源属性的版本控制和向后兼容。
• 权限集成：通过 Kubernetes RBAC 控制对 Azure 资源的操作权限，与现有 Kubernetes 权限体系统一。
• GitOps 友好：支持与 GitOps 工具（如 Flux、ArgoCD）集成，实现基础设施配置的版本控制和自动化部署。
• 合成资源抽象：支持自定义合成资源（Composite Resources）和资源类（ResourceClass），实现基础设施标准化和多环境复用。

三、使用场景和适用范围

3.1 典型使用场景

• 多云资源统一管理：在混合云/多云环境中，通过 Crossplane 控制平面统一管理 Azure 与其他云厂商（如 AWS、GCP）的资源。
• Kubernetes 原生基础设施管理：开发/运维团队通过熟悉的 Kubernetes API 或工具链（如 kubectl、kustomize）管理 Azure 资源，无需切换至 Azure CLI 或 Portal。
• 团队协作与权限隔离：基于 Kubernetes Namespace 和 RBAC 实现多团队对 Azure 资源的权限控制，确保资源管理的安全性和隔离性。
• GitOps 工作流落地：将 Azure 资源配置存储于 Git 仓库，通过 GitOps 工具自动同步至 Kubernetes 集群，实现基础设施变更的可审计和可追溯。

3.2 适用范围

• 目标用户：云原生开发团队、平台工程团队、DevOps 团队。
• 环境要求：运行 Kubernetes v1.21+ 的集群（自管理或托管，如 AKS）、Crossplane v1.10+、Azure 账户及对应资源操作权限。
• 限制：当前 Stack 支持的 Azure 服务版本需与 Crossplane 版本兼容（具体参考 Crossplane Azure Provider 文档）。

四、使用方法和配置说明

4.1 前提条件

• 已安装 Kubernetes 集群（v1.21+）。
• 已安装 Crossplane（v1.10+），参考 Crossplane 安装指南。
• 拥有 Azure 账户，且已创建具备资源管理权限的 Service Principal（需获取 tenantID、clientID、clientSecret、subscriptionID）。

4.2 部署 Azure Stack

4.2.1 安装 Azure Provider

Azure Stack 通过 Crossplane Provider 实现与 Azure API 的交互，需先部署 Provider CRD 和控制器：

bash
# 部署 Azure Provider CRD
kubectl apply -f https://raw.githubusercontent.com/crossplane-contrib/provider-azure/v0.31.0/package/crds/core.crossplane.io_providerconfigs.yaml
kubectl apply -f https://raw.githubusercontent.com/crossplane-contrib/provider-azure/v0.31.0/package/crds/...  # 其他 CRDs（根据版本调整）

# 部署 Provider 控制器（通过 Crossplane Package）
kubectl apply -f - <<EOF
apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-azure
spec:
  package: xpkg.upbound.io/crossplane-contrib/provider-azure:v0.31.0
EOF

4.2.2 验证 Provider 部署

确认 Provider 状态为 HEALTHY：

bash
kubectl get providers
# 输出示例：
# NAME             INSTALLED   HEALTHY   PACKAGE                                           AGE
# provider-azure   True        True      xpkg.upbound.io/crossplane-contrib/provider-azure:v0.31.0   5m

4.3 配置 Azure 认证

4.3.1 创建 Azure 认证 Secret

将 Azure Service Principal 信息存储为 Kubernetes Secret：

bash
kubectl create secret generic azure-creds -n crossplane-system --from-literal=credentials='{
  "tenantId": "your-azure-tenant-id",
  "clientId": "your-azure-client-id",
  "clientSecret": "your-azure-client-secret",
  "subscriptionId": "your-azure-subscription-id"
}'

4.3.2 定义 ProviderConfig

创建 ProviderConfig 以关联认证信息，供 Azure 资源管理使用：

yaml
# azure-provider-config.yaml
apiVersion: azure.crossplane.io/v1beta1
kind: ProviderConfig
metadata:
  name: default
spec:
  credentials:
    source: Secret
    secretRef:
      namespace: crossplane-system
      name: azure-creds
      key: credentials
  subscriptionID: "your-azure-subscription-id"  # 可选，若 Secret 中已包含可省略

应用配置：

bash
kubectl apply -f azure-provider-config.yaml

4.4 管理 Azure 资源

4.4.1 示例：创建 Azure 存储账户

通过 Crossplane ManagedResource 定义 Azure 存储账户：

yaml
# azure-storage-account.yaml
apiVersion: storage.azure.crossplane.io/v1alpha1
kind: Account
metadata:
  name: example-storage
spec:
  forProvider:
    accountTier: Standard
    accountReplicationType: LRS
    location: eastus
  providerConfigRef:
    name: default  # 关联上文定义的 ProviderConfig
  writeConnectionSecretToRef:
    name: storage-conn
    namespace: default

部署资源：

bash
kubectl apply -f azure-storage-account.yaml

4.4.2 验证资源状态

检查存储账户是否创建成功：

bash
kubectl get accounts.storage.azure.crossplane.io example-storage
# 输出示例（状态为 READY 表示成功）：
# NAME              READY   SYNCED   EXTERNAL-NAME       AGE
# example-storage   True    True     example-storage     3m

4.5 自定义资源抽象（可选）

通过 合成资源（Composite Resources） 和 资源类（ResourceClass） 抽象通用 Azure 资源配置，实现标准化复用。例如，定义一个“开发环境存储账户”资源类：

yaml
# storage-resource-class.yaml
apiVersion: core.crossplane.io/v1alpha1
kind: ResourceClass
metadata:
  name: azure-storage-dev
spec:
  provisioner: account.storage.azure.crossplane.io/v1alpha1
  parameters:
    accountTier: Standard
    accountReplicationType: LRS
    location: eastus
  providerConfigRef:
    name: default

五、镜像信息与部署资源

5.1 镜像拉取

Azure Stack 相关镜像（Provider 控制器）托管于 Upbound Registry：

bash
docker pull xpkg.upbound.io/crossplane-contrib/provider-azure:v0.31.0

5.2 Kubernetes 部署清单（参考）

Provider 控制器部署 YAML（由 Crossplane 自动管理，通常无需手动修改）：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: crossplane-contrib-provider-azure
  namespace: crossplane-system
spec:
  replicas: 1
  selector:
    matchLabels:
      pkg.crossplane.io/provider: provider-azure
  template:
    metadata:
      labels:
        pkg.crossplane.io/provider: provider-azure
    spec:
      containers:
      - name: provider
        image: xpkg.upbound.io/crossplane-contrib/provider-azure:v0.31.0
        args:
        - --debug
        resources:
          limits:
            cpu: 1000m
            memory: 1Gi
          requests:
            cpu: 100m
            memory: 20Mi

六、配置参数说明

七、故障排除

• Provider 状态异常：检查 Provider 资源事件：kubectl describe provider provider-azure。
• 资源创建失败：查看资源事件和控制器日志：kubectl describe account example-storage 或 kubectl logs -n crossplane-system deployment/crossplane-contrib-provider-azure。
• 认证错误：验证 Azure Service Principal 权限及 Secret 中的 tenantID/clientID/clientSecret 是否正确。

八、参考链接

• Crossplane 官方文档
• Azure Provider 文档
• https://github.com/crossplane/crossplane