通过

Azure开发人员 CLI 工具和环境常见问题解答

本文提供有关Azure开发人员 CLI（azd）工具、命令和环境的常见问题的解答。

一般问题

以下部分重点介绍一般 azd 工具和环境问题。

如何卸载Azure开发人员 CLI？

卸载 azd 有不同的选项，具体取决于最初安装的方式。 有关详细信息，请访问 安装页。

Azure 开发者 CLI 与 Azure CLI 有什么区别？

Azure开发人员 CLI（azd）和Azure CLI（az）都是命令行工具，但它们可帮助你执行不同的任务。

azd 侧重于高级开发人员工作流。 除了预配/管理Azure资源之外，azd还有助于将云组件、本地开发配置和管道自动化合并到一个完整的解决方案中。

Azure CLI是用于创建和管理Azure基础结构（例如虚拟机、虚拟网络和存储）的控制平面工具。 Azure CLI围绕特定管理任务的精细命令进行设计。

有关详细信息，请访问 Azure Developer CLI 与 Azure CLI。

什么是环境名称？

Azure开发人员 CLI 使用环境名称设置Azure开发人员 CLI 模板使用的 AZURE_ENV_NAME 环境变量。 AZURE_ENV_NAME还用于为Azure资源组名称添加前缀。 由于每个环境都有自己的配置集，因此Azure开发人员 CLI 将所有配置文件存储在环境目录中。

├── .Azure                          [This directory displays after you run `azd init` or `azd up`]
│   ├── <your environment1>         [A directory to store all environment-related configurations]
│   │   ├── .env                    [Contains environment variables]
│   │   └── main.parameters.json    [A parameter file]
│   └── <your environment2>         [A directory to store all environment-related configurations]
│   │   ├── .env                    [Contains environment variables]
│   │   └── main.parameters.json    [A parameter file]
│   └──config.json

有关工作流的详细信息，请参阅 azd init 和 azd up。

是否可以设置多个环境？

是的。 可以设置各种环境（例如开发、测试、生产）。 可以使用 azd env 来管理这些环境。

环境配置 （.env） 文件存储在何处？

.env 文件路径 <your-project-directory-name>\.azure\<your-environment-name>\.env。 有关详细信息，请参阅 “管理环境变量”。

如何使用 .env 文件？

在Azure开发人员 CLI 中，azd 命令引用用于环境配置的 .env 文件。 azd deploy 等命令也会使用 db connection string 和 Azure Key Vault 终结点等更新 .env 文件。

我在 Codespaces 中运行 azd up 。 是否可以继续在本地开发环境中工作？

是的。 可以在本地继续开发工作。

  1. 运行 azd init -t <template repo> 将模板项目克隆到本地计算机。
  2. 若要拉取使用 Codespaces 创建的现有 env，请运行 azd env refresh。 请确保提供与以前相同的环境名称、订阅和位置。

如果设备登录出现问题，如何在 Codespaces 中进行身份验证？

如果在 Codespaces 中遇到设备代码身份验证问题（例如重复的 2FA 请求或错误），请使用 VS Code Desktop 尝试以下解决方法：

  1. 使用以下方法之一在 VS Code Desktop 中打开 Codespace：
    • 使用命令面板（Windows上的 Ctrl+Shift+P 或 MacOs 上的 Cmd+Shift+P），然后选择 Codespaces：在 VS Code Desktop 中打开。
    • 单击浏览器中 Codespace 的左下角，然后选择 “在 VS Code Desktop 中打开”。
  2. 在 VS Code Desktop 终端中，运行 azd auth login 并完成基于浏览器的身份验证。
  3. 进行身份验证后，关闭 VS Code Desktop 并在浏览器中返回到 Codespace。 身份验证状态应保持。

如何使用 azure.yaml 文件？

azure.yaml 文件描述了模板中包含的Azure资源的应用和类型。

函数 secretOrRandomPassword 的行为是什么？

如果提供了密钥保管库名称和机密的参数，则 secretOrRandomPassword 函数从Azure Key Vault检索机密。 如果未提供这些参数或无法检索机密，该函数将返回随机生成的密码以改用。

以下示例演示 secretOrRandomPassword 文件中 main.parameters.json 的常见用例。 ${AZURE_KEY_VAULT_NAME} 和 sqlAdminPassword 变量作为 Key Vault 和机密名称的参数传递。 如果无法检索该值，则会生成随机密码。

"sqlAdminPassword": {
    "value": "$(secretOrRandomPassword ${AZURE_KEY_VAULT_NAME} sqlAdminPassword)"
}

还应使用 Bicep 将 secretOrRandomPassword 的输出保存到 Key Vault，以便将来运行使用。 跨部署检索和重用相同机密可能会阻止在重复生成新值时出现的错误或意外行为。 若要创建Key Vault并存储生成的机密，请使用下面的Bicep代码。 可以在 Azure 开发人员 CLI GitHub 存储库中查看这些模块的完整示例代码。

module keyVault './core/security/keyvault.bicep' = {
name: 'keyvault'
scope: resourceGroup
params: {
    name: '${take(prefix, 17)}-vault'
    location: location
    tags: tags
    principalId: principalId
}
}

module keyVaultSecrets './core/security/keyvault-secret.bicep' = {
name: 'keyvault-secret-sqlAdminPassword'
scope: resourceGroup
params: {
    keyVaultName: keyVault.outputs.name
    name: 'sqlAdminPassword'
    secretValue: sqlAdminPassword
}
}]

此Bicep设置启用以下工作流来管理机密：

  1. 如果指定的机密存在，则使用 secretOrRandomPassword 函数从Key Vault中检索它。
  2. 如果机密不存在，则会创建一个Key Vault，并且随机生成的机密存储在其中。
  3. 在未来的部署中，由于机密已存储在 Key Vault 中，secretOrRandomPassword 方法现在可以进行检索。 如果Key Vault已存在，则不会重新创建该Key Vault，但下次运行时将再次存储相同的机密值。

是否可以使用Azure免费订阅？

是的，但每个Azure位置只能有一个部署。 如果已使用所选Azure位置，则会看到部署错误：

InvalidTemplateDeployment: The template deployment '<env_name>' isn't valid according to the validation procedure. The tracking ID is '<tracking_id>'. See inner errors for details.

可以选择其他Azure位置来解决此问题。

托管在Azure App Service上的应用正在触发“欺骗性网站前方”警告。 如何修复此问题？

这可能是因为我们用于命名资源的方法。

我们的“Azure Dev”开发的模板允许配置资源的名称。 要做到这一点，可以将条目添加到 main.parameters.json 文件夹中的 infra。 例如：

"webServiceName": {
    "value": "my-unique-name"
}

该条目会在下次预配应用程序时创建名为“my-unique-name”的新资源，而不是随机值，例如“app-web-aj84u2adj”。 可以使用 Azure 门户手动删除旧资源组，也可以运行 azd down 以删除以前的所有部署。 删除资源后，请运行 azd provision 以使用新名称再次创建它们。

此名称需要全局唯一，否则在azd provision尝试创建资源时，您会收到 ARM 错误。

我能使用多个 Azure 租户吗？

是的。 若要对特定租户进行身份验证，请使用 --tenant-id 命令中的 azd auth login 参数。

azd auth login --tenant-id <tenant-id>

或者，如果想要 azd 访问所有租户，可以首先在浏览器中完成多重身份验证（MFA）步骤。

  1. 在浏览器中打开 Azure Portal。
  2. 逐个切换到每个租户。 此操作会触发必要的任何 MFA 质询并刷新令牌。
  3. 在终端中运行 azd auth login 。 azd 将使用浏览器的现有会话和访问令牌，这些令牌现在对访问的所有租户有效。

是否可以多次运行 azd up ？

是的。 我们使用 增量部署模式。 有关详细信息，请参阅 azd up。

Provisioning

以下部分重点介绍 azd 预配过程。

是否可以多次运行 azd provision ？

是的。 我们使用 增量部署模式。 有关详细信息，请参阅 azd provision。

该 azd provision 命令如何知道要预配哪些资源？

该命令使用 Bicep 模板（在 <your-project-directory-name>/infra 下找到）来预配Azure资源。

在哪里可以找到Azure中预配的资源？

转到 https://portal.azure.com，然后查找您的资源组rg-<your-environment-name>。

如何查找有关Azure错误的详细信息？

我们使用在 <your-project-directory-name>/infra 下找到的Bicep模板来预配Azure资源。 如果出现问题，我们会在 CLI 输出中包含错误消息。

还可以转到 https://portal.azure.com，然后查找您的资源组rg-<your-environment-name>。 如果任一部署失败，请选择错误链接以获取详细信息。

有关其他资源，请参阅 解决常见的 Azure 部署错误 - Azure 资源管理器。

是否有azd provision的日志文件？

即将推出。 此功能计划在将来的版本中使用。

部署

以下部分重点介绍 azd 部署过程。

是否可以多次运行 azd deploy ？

是的。 有关详细信息 ，请参阅 azd deploy 。

azd 如何查找要向其部署代码的 Azure 资源？

在部署期间，azd 首先通过查找带有 azd-env-name 标记的组以及与环境名称匹配的值来发现构成应用程序的所有资源组。 然后，它会枚举每个资源组中的所有资源，查找带有 azd-service-name 标记的资源，其值与 azure.yaml中服务的名称匹配。

虽然我们建议对资源使用标记，但也可以使用 resourceNameazure.yaml 中的属性来提供显式资源名称。 在这种情况下，上述逻辑未运行。

如何在跳过其他服务时在项目中部署特定服务？

部署项目时，可以选择通过在命令（即 azd deploy api）中指定服务名称或导航到仅包含要部署的服务的子文件夹来部署特定服务。 执行此操作时，所有其他服务将列为 - Skipped。

如果不想跳过任何服务，请确保从根文件夹运行命令，或将 --all 标志添加到命令。

管道配置

以下部分重点介绍 CI/CD 管道配置。

什么是Azure服务主体？

Azure服务主体是创建用于应用、托管服务和自动化工具以访问Azure资源的标识。 此访问受分配给服务主体的角色的限制，该角色可让你控制可以访问的资源和级别。 有关从Azure到GitHub进行身份验证的详细信息，请参阅 Connect GitHub 和 Azure |Microsoft Docs。

在运行 azd pipeline config 之前，是否需要创建Azure服务主体？

否。 azd 管道配置命令负责创建Azure服务主体并执行必要的步骤，将机密存储在GitHub存储库中。

存储在GitHub中的所有机密是什么？

该命令将四个机密存储在 GitHub：AZURE_CREDENTIALS、AZURE_ENV_NAME、AZURE_LOCATION 和 AZURE_SUBSCRIPTION_ID。 您可以通过访问 https://github.com/<your-github-account>/<your-repo>/secrets/actions 来覆盖每个密钥的值。

什么是 OpenID Connect （OIDC），它是否受支持？

使用 OpenID Connect，工作流可以直接从Azure交换生存期短的令牌。

虽然在 GitHub Actions 和 Azure Pipelines 中 OIDC 默认情况下是支持的（设置为 federated），但在 Azure DevOps 和 Terraform 中不被支持。

  • 对于Azure DevOps，将--auth-type显式调用为 federated将导致错误。
  • 对于 Terraform：
    • 如果未定义 --auth-type，它将回退到 clientcredentials，并将导致警告。
    • 如果 --auth-type 显式设置为 federated，则将导致错误。

如何重置存储在GitHub Actions中的Azure服务主体？

转到 https://github.com/<your-github-account>/<your-repo>settings/secrets/actions，然后通过复制并粘贴新服务主体的整个 JSON 对象来更新 AZURE_CREDENTIALS。 例如：

{
"clientId": "<GUID>",
"clientSecret": "<GUID>",
"subscriptionId": "<GUID>",
"tenantId": "<GUID>",
(...)
}

GitHub Actions文件存储在何处？

GitHub Actions文件路径为 <your-project-directory-name>\.github\workflows\azure-dev.yml。 有关详细信息，请参阅 Quickstart: 创建服务主体并运行 GitHub Action。

在azure-dev.yml文件中，是否可以在生成步骤中仅部署代码？

是的。 将 run: azd up --no-prompt 替换为 run: azd deploy --no-prompt。

在哪里可以找到运行 azd pipeline config 时触发的GitHub Actions作业的日志？

转到 https://github.com/<your-github-account>/<your-repo>/actions，然后引用工作流运行中的日志文件。

在本地生成容器应用程序

为什么我无法在本地运行要生成的容器应用？

在本地生成容器应用程序时，需要在容器中运行 azd auth login，以便应用程序使用 AzureDeveloperCliCredential。 或者，可以将应用程序配置为使用服务主体，而不是 AzureDeveloperCliCredential。

  • Last updated on