Skip to content

Commit 84c395f

Browse files
Update VM admin credentials in deployment guide and troubleshooting steps
1 parent 4e874e2 commit 84c395f

2 files changed

Lines changed: 3 additions & 3 deletions

File tree

docs/DeploymentGuide.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -205,8 +205,8 @@ Copy the contents from the production configuration file to your main parameters
205205
By default, random GUIDs are generated for VM credentials. To set custom credentials:
206206

207207
```shell
208-
azd env set AZURE_ENV_VM_ADMIN_USERNAME <your-username>
209-
azd env set AZURE_ENV_VM_ADMIN_PASSWORD <your-password>
208+
azd env set AZURE_ENV_JUMPBOX_ADMIN_USERNAME <your-username>
209+
azd env set AZURE_ENV_JUMPBOX_ADMIN_PASSWORD <your-password>
210210
```
211211

212212
### 3.3 Advanced Configuration (Optional)

docs/TroubleShootingSteps.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,7 @@ Use these as quick reference guides to unblock your deployments.
134134
| **Conflict - Cannot use the SKU Basic with File Change Audit for site** | File Change Audit not supported on Basic SKU | <ul><li>This error happens because File Change Audit logs aren't supported on Basic SKU App Service Plans</li><li>Upgrading to Premium/Isolated SKU (supports File Change Audit), or</li><li>Disabling File Change Audit in Diagnostic Settings if you must stay on Basic</li><li>Always cross-check the [supported log types](https://aka.ms/supported-log-types) before adding diagnostic logs to your Bicep templates</li></ul> |
135135
| **AccountPropertyCannotBeUpdated** | Read-only property cannot be modified after creation | The property **`isHnsEnabled`** (Hierarchical Namespace for Data Lake Gen2) is **read-only** and can only be set during **storage account creation**. Once a storage account is created, this property **cannot be updated**. Trying to update it via ARM template, Bicep, CLI, or Portal will fail.<br><br>**Resolution:**<br><ul><li>Create a **new storage account** with `isHnsEnabled=true` if you require hierarchical namespace</li><li>Migration may be needed if you already have data</li><li>Refer to [Storage Account Update Restrictions](https://aka.ms/storageaccountupdate) for more details</li></ul> |
136136
| **Conflict - Local authentication is disabled** | App Configuration store has local authentication disabled but application is using local auth mode | This error occurs when your Azure App Configuration store has **local authentication disabled** (`disableLocalAuth: true`) but your application is trying to access it using **connection strings or access keys** instead of **Azure AD/Managed Identity authentication**.<br><br>**Example error message:**<br>`The operation cannot be performed because the configuration store is using local authentication mode and local authentication is disabled. To enable access to data plane resources while local authentication is disabled, please use pass-through authentication mode.`<br><br>**Common causes:**<br><ul><li>App Configuration store deployed with `disableLocalAuth: true` for security compliance</li><li>Application code using connection strings instead of Managed Identity</li><li>SDK client initialized with access keys rather than `DefaultAzureCredential`</li></ul><br>**Resolution:**<br><ul><li>**Option 1: Update application to use Managed Identity (Recommended)**<br>```python<br>from azure.identity import DefaultAzureCredential<br>from azure.appconfiguration import AzureAppConfigurationClient<br><br>credential = DefaultAzureCredential()<br>client = AzureAppConfigurationClient(<br> endpoint="https://your-appconfig.azconfig.io",<br> credential=credential<br>)<br>```</li><li>**Option 2: Re-enable local authentication (Not recommended for production)**<br>Set `disableLocalAuth: false` in your Bicep/ARM template</li><li>**Ensure proper RBAC assignment:** Verify that the Managed Identity has `App Configuration Data Reader` or `App Configuration Data Owner` role assigned</li></ul><br>**Reference:**<br><ul><li>[Disable local authentication in Azure App Configuration](https://learn.microsoft.com/en-us/azure/azure-app-configuration/howto-disable-access-key-authentication)</li><li>[Use Managed Identities to access App Configuration](https://learn.microsoft.com/en-us/azure/azure-app-configuration/howto-integrate-azure-managed-service-identity)</li></ul> |
137-
| **PropertyChangeNotAllowed** | Immutable VM property cannot be changed after creation | This error occurs when you attempt to modify an immutable property (such as `osProfile.adminUsername`) on an existing VM.<br><br>**Cause (Azure Limitation):**<br>Once a VM is created, the `osProfile.adminUsername` property is immutable and cannot be changed. If you modify the VM username or password in the template and redeploy, this issue will occur.<br><br>**Resolution:**<br><ul><li>Delete the existing deployment and redeploy with new credentials:<br>`azd down --force --purge`</li><li>Set new credentials before redeployment:<br>`azd env set AZURE_ENV_VM_ADMIN_USERNAME "newusername"`<br>`azd env set AZURE_ENV_VM_ADMIN_PASSWORD "NewSecurePassword123!"`</li><li>Redeploy:<br>`azd up`</li></ul><br>**Note:** Some VM properties are immutable by design. Always plan credential and configuration changes before initial deployment. |
137+
| **PropertyChangeNotAllowed** | Immutable VM property cannot be changed after creation | This error occurs when you attempt to modify an immutable property (such as `osProfile.adminUsername`) on an existing VM.<br><br>**Cause (Azure Limitation):**<br>Once a VM is created, the `osProfile.adminUsername` property is immutable and cannot be changed. If you modify the VM username or password in the template and redeploy, this issue will occur.<br><br>**Resolution:**<br><ul><li>Delete the existing deployment and redeploy with new credentials:<br>`azd down --force --purge`</li><li>Set new credentials before redeployment:<br>`azd env set AZURE_ENV_JUMPBOX_ADMIN_USERNAME "newusername"`<br>`azd env set AZURE_ENV_JUMPBOX_ADMIN_PASSWORD "NewSecurePassword123!"`</li><li>Redeploy:<br>`azd up`</li></ul><br>**Note:** Some VM properties are immutable by design. Always plan credential and configuration changes before initial deployment. |
138138

139139

140140
----------------------------------

0 commit comments

Comments
 (0)