mcpField
A
azd-deployment

azd-deployment

github.com/sickn33云与 DevOps48.7k101 次安装今天更新
代码仓库

关于 azd-deployment

azd-deployment 是面向部署到 Azure Container Apps 的现有 Azure Developer CLI 项目的审查与部署技能。内容涵盖 Bicep 基础设施、远程构建、托管标识和经授权的部署验证，并强调云资源变更的安全措施。

主要功能

  1. 01Azure Container Apps 部署指导
  2. 02Bicep 基础设施配置
  3. 03远程镜像构建
  4. 04托管标识与 RBAC 指导
  5. 05部署后验证和回滚规划

适用场景

  1. 01审查现有 azd 部署配置
  2. 02规划 Container Apps 发布
  3. 03检查托管标识与限定范围的角色分配
  4. 04验证部署健康状况和回滚准备

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sickn33/agentic-awesome-skills --skill azd-deployment

安装后在 Claude Code 中输入/azd-deployment确认已加载。

详细介绍

Azure Developer CLI（azd）Container Apps 部署

通过远程构建、托管标识和幂等基础设施，将容器化的前端和后端应用部署到 Azure Container Apps。

授权与准备

首先检查现有项目文件以及当前活动的租户、订阅和环境。预配、部署、角色分配和钩子执行会更改云资源，并可能产生费用。准备准确的差异、目标、预估影响和回滚计划；仅在用户明确授权该部署后才执行。不要将环境变量值或凭据打印到共享日志中。

快速开始

# Initialize and deploy
azd auth login
azd init                    # Creates azure.yaml and .azure/ folder
azd env new <env-name>      # Create environment (dev, staging, prod)
azd up                      # Provision infra + build + deploy

核心文件结构

project/
├── azure.yaml              # azd service definitions + hooks
├── infra/
│   ├── main.bicep          # Root infrastructure module
│   ├── main.parameters.json # Parameter injection from env vars
│   └── modules/
│       ├── container-apps-environment.bicep
│       └── container-app.bicep
├── .azure/
│   ├── config.json         # Default environment pointer
│   └── <env-name>/
│       ├── .env            # Environment-specific values (azd-managed)
│       └── config.json     # Environment metadata
└── src/
    ├── frontend/Dockerfile
    └── backend/Dockerfile

azure.yaml 配置

最小配置
name: azd-deployment
services:
  backend:
    project: ./src/backend
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true
包含钩子的完整配置
name: azd-deployment
metadata:
  template: [email protected]

infra:
  provider: bicep
  path: ./infra

azure:
  location: eastus2

services:
  frontend:
    project: ./src/frontend
    language: ts
    host: containerapp
    docker:
      path: ./Dockerfile
      context: .
      remoteBuild: true

  backend:
    project: ./src/backend
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      context: .
      remoteBuild: true

hooks:
  preprovision:
    shell: sh
    run: |
      echo "Before provisioning..."
      
  postprovision:
    shell: sh
    run: |
      echo "After provisioning - set up RBAC, etc."
      
  postdeploy:
    shell: sh
    run: |
      echo "Frontend: ${SERVICE_FRONTEND_URI}"
      echo "Backend: ${SERVICE_BACKEND_URI}"
azure.yaml 关键选项
选项说明
remoteBuild: true在 Azure Container Registry 中构建映像（推荐）
context: .相对于项目路径的 Docker 构建上下文
host: containerapp部署到 Azure Container Apps
infra.provider: bicep使用 Bicep 管理基础设施

环境变量流转

三级配置
  1. 本地 .env - 仅用于本地开发
  2. .azure/<env>/.env - 由 azd 管理，从 Bicep 输出自动填充
  3. main.parameters.json - 将环境变量映射到 Bicep 参数
参数注入模式
// infra/main.parameters.json
{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION=eastus2}" },
    "azureOpenAiEndpoint": { "value": "${AZURE_OPENAI_ENDPOINT}" }
  }
}

语法：${VAR_NAME} 或 ${VAR_NAME=default_value}

设置环境变量
# Set for current environment
azd env set AZURE_OPENAI_ENDPOINT "https://my-openai.openai.azure.com"
azd env set AZURE_SEARCH_ENDPOINT "https://my-search.search.windows.net"

# Set during init
azd env new prod
azd env set AZURE_OPENAI_ENDPOINT "..."
Bicep 输出 → 环境变量
// In main.bicep - outputs auto-populate .azure/<env>/.env
output SERVICE_FRONTEND_URI string = frontend.outputs.uri
output SERVICE_BACKEND_URI string = backend.outputs.uri
output BACKEND_PRINCIPAL_ID string = backend.outputs.principalId

部署的可重复性

协调状态与修订版本变更
  1. Bicep 是声明式的 - 资源会协调至期望状态
  2. 远程构建会使用唯一标签 - 映像标签包含部署时间戳
  3. ACR 会复用层 - 仅上传有变化的层
有意保留非托管变更

准备部署前，盘点自定义域名、入口、角色分配和其他由 Portal 管理的设置。将期望的设置移入经过审查的基础设施代码，或准备具体的恢复计划。将属性设为 null 并不能保证 Azure 会保留通过带外方式进行的编辑。重复部署可能会创建新的映像修订版本并再次执行钩子；请检查这些影响，而不要声称每个钩子都是幂等的。

如果现有容器注册表应继续由外部管理，请在项目的 Bicep 中明确引用它。不要复制不完整的模块或覆盖无关设置来让部署成功。

Container App 服务发现

同一环境中 Container Apps 之间的内部 HTTP 路由：

// Backend reference in frontend env vars
env: [
  {
    name: 'BACKEND_URL'
    value: 'http://ca-backend-${resourceToken}'  // Internal DNS
  }
]

使用经过验证的后端内部主机名、协议和端口配置前端代理。不要假定示例 Bicep 中的 resourceToken 存在于你的项目中，也不要复制未声明的 nginx $BACKEND_URL 变量。如果使用模板，请在部署前验证渲染后的 nginx 配置。

# Schematic: replace this host with the approved internal endpoint.
location /api {
    proxy_pass http://approved-internal-backend;
}

托管标识与 RBAC

启用系统分配的标识
resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
  identity: {
    type: 'SystemAssigned'
  }
}

output principalId string = containerApp.identity.principalId
预配后的 RBAC 分配
hooks:
  postprovision:
    shell: sh
    run: |
      set -eu
      : "${BACKEND_PRINCIPAL_ID:?Set the reviewed backend principal ID}"
      : "${OPENAI_RESOURCE_ID:?Set the approved OpenAI resource scope}"
      : "${SEARCH_RESOURCE_ID:?Set the approved Search resource scope}"
      PRINCIPAL_ID="${BACKEND_PRINCIPAL_ID}"
      
      # Azure OpenAI access
      az role assignment create \
        --assignee-object-id "$PRINCIPAL_ID" \
        --assignee-principal-type ServicePrincipal \
        --role "Cognitive Services OpenAI User" \
        --scope "$OPENAI_RESOURCE_ID"
      
      # Azure AI Search access
      az role assignment create \
        --assignee-object-id "$PRINCIPAL_ID" \
        --role "Search Index Data Reader" \
        --scope "$SEARCH_RESOURCE_ID"

常用命令

# Environment management
azd env list                        # List environments
azd env select <name>               # Switch environment
azd show                            # Inspect project/resource information
azd env set KEY value               # Set variable

# Deployment
azd up                              # Full provision + deploy
azd provision                       # Infrastructure only
azd deploy                          # Code deployment only
azd deploy --service backend        # Deploy single service

# Debugging
azd show                            # Show project status
az containerapp logs show -n <app> -g <rg> --follow  # Stream logs

部署后验证

不要仅凭部署命令的退出代码就报告完成。在获准的目标范围内：

  1. 检查 azd show，并将实际环境、资源 ID 和服务端点与已批准的计划进行比较。
  2. 使用已安装 Azure CLI 支持的只读命令，检查当前 Container Apps 修订版本、映像架构、入口和就绪状态。记录观察到的修订版本和运行状况；不要假定新修订版本正在接收流量。
  3. 对明确获准的端点运行项目自有的冒烟检查。验证前后端集成和基于身份的访问，不得创建付费交易、发送消息或暴露真实客户数据。
  4. 在确切的资源范围内验证所需的角色分配。权限检查失败即表示失败，不能因此自动添加范围更广的角色。
  5. 检查范围受限且已脱敏的服务日志，并将自定义域名或其他保留设置与部署前清单进行比较。
  6. 如果某项检查失败，停止后续发布，报告失败的观察结果，并使用经过审核的回滚计划。不要执行破坏性清理，也不要自动删除资源来回滚。

记录部署目标、映像／修订版本标识、实际执行的检查、失败项和未验证的范围。缺少提供商访问权限意味着验证尚未完成。上面的钩子示例要求明确指定其资源 ID；如果缺少这些 ID，就会在更改角色之前失败。

本地资源

未附带其他 Bicep 模式、故障排除指南或架构文件。准备部署前，请根据已安装的 Azure Developer CLI 和当前 Azure 官方文档验证项目配置。

重要提醒

  1. 验证构建架构 —— 使用远程构建或明确配置的本地目标架构；ARM 映像可能与 AMD64 部署不匹配。
  2. Bicep 输出会自动填充 .azure//.env —— 不要手动编辑
  3. 保护机密 —— 使用项目批准的机密管理方式；切勿提交凭据、导出环境变量值，或将机密放入参数默认值中。
  4. 服务标记（azd-service-name） —— azd 查找 Container Apps 时必需
  5. 明确处理 RBAC 失败 —— 将重复项视为成功之前，先验证是否已有分配；切勿忽略权限或配置失败。

适用场景

在审查基础设施、构建架构、托管标识、已获授权的部署或部署后验证时，适用于面向 Azure Container Apps 的现有 azd 项目。

限制

  • 示例依赖项目自有的模块、资源 ID 和已安装的 CLI 版本；未附带完整的应用程序或基础设施模板。
  • 不要将输出视为环境专属验证、测试或专家审查的替代品。
  • 如果缺少必需输入、权限、安全边界或成功标准，请停止并请求澄清。

官方命令参考

请查阅 Azure Developer CLI 参考和 Container Apps 工作流指南，并确认其适用于已安装的工具版本。这些链接用于核对 API／命令，不代表获准安装工具或部署资源。

评论

支持 Markdown