-
Notifications
You must be signed in to change notification settings - Fork 526
/
Copy pathfaq.yml
241 lines (190 loc) · 15 KB
/
faq.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
### YamlMime:FAQ
metadata:
title: Azure Developer CLI FAQ
description: Get answers to commonly asked questions about Azure Developer CLI.
author: alexwolfmsft
ms.author: alexwolf
ms.date: 9/14/2024
ms.topic: conceptual
ms.custom: devx-track-azdevcli, build-2023
ms.service: azure-dev-cli
title: Azure Developer CLI FAQ
summary: This article answers commonly asked questions about Azure Developer CLI.
sections:
- name: General
questions:
- question: How do I uninstall Azure Developer CLI?
answer: |
There are different options for uninstalling `azd` depending on how you originally installed it. Visit the [installation page](/azure/developer/azure-developer-cli/install-azd) for details.
- question: What's the difference between the Azure Developer CLI and the Azure CLI?
answer: |
[Azure Developer CLI](/azure/developer/azure-developer-cli/overview) (`azd`) and [Azure CLI](/cli/azure/what-is-azure-cli) (`az`) are both command-line tools, but they help you do different tasks.
[`azd`](./index.yml) 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.
- question: What is an environment name?
answer: |
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.
```txt
├── .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
```
- question: Can I set up more than one environment?
answer: |
Yes. You can set up a various environments (for example, dev, test, production). You can use `azd env` to manage these environments.
- question: Where is the environment configuration (.env) file stored?
answer: |
The .env file path is `<your-project-directory-name>\.azure\<your-environment-name>\.env`.
- question: How is the .env file used?
answer: |
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.
- question: I have run `azd up` in Codespaces. Can I continue my work in a local development environment?
answer: |
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.
- question: How is the azure.yaml file used?
answer: |
The azure.yaml file describes the apps and types of Azure resources that are included in the template.
- question: What is the behavior of the `secretOrRandomPassword` function?
answer: |
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.
```json
"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](https://github.com/Azure/azure-dev/tree/main/templates/common/infra/bicep/core/security).
```json
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.
- question: Can I use Azure Free Subscription?
answer: |
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.
- question: My app hosted with Azure App Service is triggering a "Deceptive site ahead" warning. How can I fix it?
answer: |
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:
```json
"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.
- name: "Command: azd provision"
questions:
- question: How does the command know what resources to provision?
answer: |
The command uses Bicep templates, which are found under `<your-project-directory-name>/infra` to provision Azure resources.
- question: Where can I find what resources are provisioned in Azure?
answer: |
Go to https://portal.azure.com and then look for your resource group, which is `rg-<your-environment-name>`.
- question: How do I find more information about Azure errors?
answer: |
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](/azure/azure-resource-manager/troubleshooting/common-deployment-errors).
- question: Is there a log file for `azd provision`?
answer: |
Coming soon. This feature is planned for a future release.
- name: "Command: azd deploy"
questions:
- question: Can I rerun this command?
answer: |
Yes.
- question: How does azd find the Azure resource to deploy my code to?
answer: |
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.
- question: How do I deploy specific services in my project while skipping others?
answer: |
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.
- name: "Command: azd up"
questions:
- question: Can I rerun `azd up`?
answer: |
Yes. We use the [incremental deployment mode](/azure/azure-resource-manager/templates/deployment-modes).
- question: How do I find the log file for `azd up`?
answer: |
Coming soon. This feature is planned for a future release.
- name: "Command: azd pipeline"
questions:
- question: What is an Azure service principal?
answer: |
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](../github/connect-from-azure-secret.md).
- question: Do I need to create an Azure service principal before I run `azd pipeline config`?
answer: |
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.
- question: What are all the secrets stored in GitHub?
answer: |
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-github-account>/<your-repo>/secrets/actions`.
- question: What is OpenID Connect (OIDC), and is it supported?
answer: |
With [OpenID Connect](https://docs.github.com/actions/deployment/security-hardening-your-deployments/about-security-hardening-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.
- question: How do I reset the Azure service principal that's stored in GitHub Actions?
answer: |
Go to `https://github.com/<your-github-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>",
(...)
}
```
- question: Where is the GitHub Actions file stored?
answer: |
The GitHub Actions file path is `<your-project-directory-name>\.github\workflows\azure-dev.yml`.
- question: In the azure-dev.yml file, can I deploy just the code in the build step?
answer: |
Yes. Replace `run: azd up --no-prompt` with `run: azd deploy --no-prompt`.
- question: Where can I find the log for the GitHub Actions job that I triggered when I ran `azd pipeline config`?
answer: |
Go to `https://github.com/<your-github-account>/<your-repo>/actions`, and then refer to the log file in the workflow run.
- name: "Building a container application locally"
questions:
- question: Why am I unable to locally run the container app that I'm building?
answer: |
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`.