Azure Developer CLI FAQ

There are different options for uninstalling azd depending on how you originally installed it. Visit the installation page for details.

Azure Developer CLI (azd) and Azure CLI (az) are both command-line tools, but they help you do different tasks.

azd focuses on the high level developer workflow. Apart from provisioning/managing Azure resources, azd helps to stitch cloud components, local development configuration, and pipeline automation together into a complete solution.

Azure CLI is a control plane tool for creating and administering Azure infrastructure such as virtual machines, virtual networks, and storage. The Azure CLI is designed around granular commands for specific administrative tasks.

Azure Developer CLI uses an environment name to set the AZURE_ENV_NAME environment variable that's used by Azure Developer CLI templates. AZURE_ENV_NAME is also used to prefix the Azure resource group name. Because each environment has its own set of configurations, Azure Developer CLI stores all configuration files in environment directories.

├── .Azure                          [This directory displays after you run add 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 

Yes. You can set up a various environments (for example, dev, test, production). You can use azd env to manage these environments.

The .env file path is <your-project-directory-name>\.azure\<your-environment-name>\.env.

In Azure Developer CLI, the azd commands refer to the .env file for environment configuration. Commands such as azd deploy also update the .env file with, for example, the db connection string and the Azure Key Vault endpoint.

Yes. You can continue development work locally.

1. Run azd init -t <template repo> to clone the template project to your local machine.
2. To pull down the existing env created using Codespaces, run azd env refresh. Make sure you provide the same environment name, subscription and location as before.

The azure.yaml file describes the apps and types of Azure resources that are included in the template.

The secretOrRandomPassword function retrieves a secret from Azure Key Vault if parameters for the key vault name and secret are provided. If these parameters aren't provided or a secret can't be retrieved, the function returns a randomly generated password to use instead.

The following example demonstrates a common use case of the secretOrRandomPassword in a main.parameters.json file. The ${AZURE_KEY_VAULT_NAME} and sqlAdminPassword variables are passed as parameters for the names of the Key Vault and secret. If the value can't be retrieved, a random password is generated instead.

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

The output of secretOrRandomPassword should also be saved to Key Vault using Bicep for future runs. Retrieving and reusing the same secrets across deploys can prevent errors or unintended behaviors that can surface when repeatedly generating new values. To create a Key Vault and store the generated secret in it, use the Bicep code below. You can view the full sample code for these modules in the Azure Developer CLI GitHub repository.

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
  }
}]

This Bicep setup enables the following workflow for managing your secrets:

1. If the specified secret exists, it's retrieved from Key Vault using the secretOrRandomPassword function.
2. If the secret doesn't exist, a Key Vault is created, and the randomly generated secret is stored inside of it.
3. On future deploys, the secretOrRandomPassword method retrieves the stored secret now that it exists in Key Vault. The Key Vault won't be recreated if it already exists, but the same secret value will be stored again for the next run.

Yes, but each Azure location can only have one deployment. If you've already used the selected Azure location, you'll see the deployment error:

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.

You can select a different Azure location to fix the issue.

This might happen because of our method for naming resources.

Our 'Azure Dev' authored templates allow for configuring the name of the resource. To do so, you can add an entry to the main.parameters.json in the infra folder. For example:

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

This entry creates a new resource named "my-unique-name" instead of a randomized value such as "app-web-aj84u2adj" the next time you provision your application. You can either manually remove the old resource group using the Azure portal or run azd down to remove all previous deployments. After removing the resources, run azd provision to create them again with the new name.

This name will need to be globally unique, otherwise you will receive an ARM error during azd provision when it tries to create the resource.

The command uses Bicep templates, which are found under <your-project-directory-name>/infra to provision Azure resources.

Go to https://portal.azure.com and then look for your resource group, which is rg-<your-environment-name>.

We use Bicep templates, which are found under <your-project-directory-name>/infra, to provision Azure resources. If there are issues, we include the error message in the CLI output.

You can also go to https://portal.azure.com and then look for your resource group, which is rg-<your-environment-name>. If any of the deployments fail, select the error link to get more information.

For other resources, see Troubleshoot common Azure deployment errors - Azure Resource Manager.

Coming soon. This feature is planned for a future release.

Yes.

During deploy, azd first discovers all the resource groups that make up your application by looking for groups tagged with azd-env-name and with a value that matches the name of your environment. Then, it enumerates all the resources in each of these resource groups, looking for a resource tagged with azd-service-name with a value that matches the name of your service from azure.yaml.

While we recommend using tags on resources, you can also use the resourceName property in azure.yaml to provide an explicit resource name. In that case, the above logic isn't run.

When deploying your project, you can choose to deploy specific services either by specifying the service name in the command (i.e. azd deploy api) or by navigating to a subfolder that contains just the service(s) you want to deploy. When doing so, all other services will be listed as - Skipped.

If you don't want to skip any services, be sure to either run your command from the root folder or add the --all flag to your command.

Yes. We use the incremental deployment mode.

Coming soon. This feature is planned for a future release.

An Azure service principal is an identity that's created for use with apps, hosted services, and automated tools to access Azure resources. This access is restricted by the roles that are assigned to the service principal, which gives you control over which resources can be accessed and at which level. For more information about authenticating from Azure to GitHub, see Connect GitHub and Azure | Microsoft Docs.

No. The azd pipeline config command takes care of creating the Azure service principal and performing the necessary steps to store the secrets in your GitHub repo.

The command stores four secrets in GitHub: AZURE_CREDENTIALS, AZURE_ENV_NAME, AZURE_LOCATION, and AZURE_SUBSCRIPTION_ID. You can override the value of each secret by going to https://github.com/<your-GH-account>/<your-repo>/secrets/actions.

With OpenID Connect, your workflows can exchange short-lived tokens directly from Azure.

While OIDC is supported as the default for GitHub Actions and Azure Pipeline (set as federated), it isn't supported for Azure DevOps or Terraform.

• For Azure DevOps, explicitly calling out --auth-type as federated will result in an error.
• For Terraform:
  • If --auth-type isn't defined, it will fall back to clientcredentials and will result in a warning.
  • If --auth-type is explicitly set to federated, it will result in an error.

Go to https://github.com/<your-GH-account>/<your-repo>settings/secrets/actions, and then update AZURE_CREDENTIALS by copying and pasting the entire JSON object for the new service principal. For example:

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

The GitHub Actions file path is <your-project-directory-name>\.github\workflows\azure-dev.yml.

Yes. Replace run: azd up --no-prompt with run: azd deploy --no-prompt.

Go to https://github.com/<your-GH-account>/<your-repo>/actions, and then refer to the log file in the workflow run.

When building container applications locally, you need to run azd auth login in the container for the application to work with the AzureDeveloperCliCredential. Alternatively, you could configure your application to use a service principal instead of the AzureDeveloperCliCredential.