+After you configure the provisioning agent and ECMA host, it's time to test connectivity from the Azure Active Directory (Azure AD) provisioning service to the provisioning agent, the ECMA host, and the application. To perform this end-to-end test, select **Test connection** in the application in the Azure portal. Be sure to wait 10 to 20 minutes after assigning an initial agent or changing the agent before testing the connection. If after this time the test connection fails, try the following troubleshooting steps:

+ 1. If you continue to see `The ECMA host is currently importing data from the target application` even after restarting the ECMA Connector Host and the provisioning agent, and waiting for the initial import to complete, then you may need to cancel and re-start configuring provisioning to the application in the Azure portal.

+ 1. When you provide the tenant URL in the Azure portal, ensure that it follows the following pattern. You can replace `localhost` with your host name, but it isn't required. Replace `connectorName` with the name of the connector you specified in the ECMA host. The error message 'invalid resource' generally indicates that the URL does not follow the expected format.

+| Invalid LDAP style of object's DN. DN: username@domain.com" or `Target Site: ValidByLdapStyle` | Ensure the 'DN is Anchor' checkbox is not checked in the 'connectivity' page of the ECMA host. Ensure the 'autogenerated' checkbox is selected in the 'object types' page of the ECMA host. See [About anchor attributes and distinguished names](on-premises-application-provisioning-architecture.md#about-anchor-attributes-and-distinguished-names) for more information.|

+By default, the generic SQL connector expects the DN to be populated using the LDAP style (when the 'DN is anchor' attribute is left unchecked in the first connectivity page). In the error message `Invalid LDAP style DN` or `Target Site: ValidByLdapStyle`, you may see that the DN field contains a user principal name (UPN), rather than an LDAP style DN that the connector expects.

+## FIPS 140 compliant for Azure AD authentication

+Beginning with version 6.6.8, Microsoft Authenticator for iOS is compliant with [Federal Information Processing Standard (FIPS) 140](https://csrc.nist.gov/publications/detail/fips/140/3/final?azure-portal=true) for all Azure AD authentications using push multi-factor authentications (MFA), passwordless Phone Sign-In (PSI), and time-based one-time passcodes (TOTP).  

+Consistent with the guidelines outlined in [NIST SP 800-63B](https://pages.nist.gov/800-63-3/sp800-63b.html?azure-portal=true), authenticators are required to use FIPS 140 validated cryptography. This helps federal agencies meet the requirements of [Executive Order (EO) 14028](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/?azure-portal=true) and healthcare organizations working with [Electronic Prescriptions for Controlled Substances (EPCS)](/azure/compliance/offerings/offering-epcs-us). 

+FIPS 140 is a US government standard that defines minimum security requirements for cryptographic modules in information technology products and systems. Testing against the FIPS 140 standard is maintained by the [Cryptographic Module Validation Program (CMVP)](https://csrc.nist.gov/Projects/cryptographic-module-validation-program?azure-portal=true).

+No changes in configurations are required in Microsoft Authenticator or the Azure portal to enable FIPS 140 compliance. Beginning with Microsoft Authenticator for iOS version 6.6.8, Azure AD authentications will be FIPS 140 compliant by default.

+Authenticator leverages the native Apple cryptography to achieve FIPS 140, Security Level 1 compliance on Apple iOS devices beginning with Microsoft Authenticator version 6.6.8. For more information about the certifications being used, see the [Apple CoreCrypto module](https://support.apple.com/guide/sccc/security-certifications-for-ios-scccfa917cb49/web?azure-portal=true). 

+FIPS 140 compliance for Microsoft Authenticator on Android is in progress and will follow soon.

+To view attribute data for a user, highlight the user, and select **View**:

+- User Match ΓÇô Allows you to specify a different on-premises Active Directory attribute for matching Azure AD UPN instead of the default match to userPrincipalName:

+ - The migration utility tries direct matching to UPN before using the on-premises Active Directory attribute.

+ - If no match is found, it calls a Windows API to find the Azure AD UPN and get the SID, which it uses to search the MFA Server user list.

+ - If the Windows API doesnΓÇÖt find the user or the SID isnΓÇÖt found in the MFA Server, then it will use the configured Active Directory attribute to find the user in the on-premises Active Directory, and then use the SID to search the MFA Server user list.

+Users will no longer be redirected to your on-premises federation server for MFA, whether theyΓÇÖre targeted by the Staged Rollout tool or not. Note this can take up to 24 hours to take effect.

+Set the **Staged Rollout for Azure MFA** to **Off**. Users will once again be redirected to your on-premises federation server for MFA.

+| CCState | Common | Contains session information state to be used between Azure AD and the [Azure AD Backup Authentication Service](../conditional-access/resilience-defaults.md). |

+| x-ms-refreshtokencredential | Specific | Available when [Primary Refresh Token (PRT)](../devices/concept-primary-refresh-token.md) is in use. |

+| CcsNtv | Specific | To control when Azure AD Gateway will send requests to [Azure AD Backup Authentication Service](../conditional-access/resilience-defaults.md). Native flows. |

+| CcsWeb | Specific | To control when Azure AD Gateway will send requests to [Azure AD Backup Authentication Service](../conditional-access/resilience-defaults.md). Web flows. |

+| Ccs* | Specific | Cookies with prefix Ccs*, have the same purpose as the ones without prefix, but only apply when [Azure AD Backup Authentication Service](../conditional-access/resilience-defaults.md) is in use. |

+[concept-mfa]: concept-mfa-howitworks.md

+- iAnnotate for Office 365

+- Microsoft Stream Mobile Native 2.0

+- Microsoft Whiteboard Services

+[Conditional Access](../conditional-access/overview.md) is the Zero Trust control plane that allows you to target policies for access to all your apps ΓÇô old or new, private, or public, on-premises, or multicloud. With [Conditional Access authentication context](../conditional-access/concept-conditional-access-cloud-apps.md#authentication-context), you can apply different policies within those apps.

+The IT administrators and regulators often struggle between balancing prompting their users with additional factors of authentication too frequently and achieving adequate security and policy adherence for applications and services where parts of them contain sensitive data and operations. It can be a choice between a strong policy that impacts users' productivity when they access most data and actions or a policy that isn't strong enough for sensitive resources.

+**Third**, today it's only available to applications that sign-in users. Applications that authenticate as themselves aren't supported. Use the [Authentication flows and application scenarios guide](authentication-flows-app-scenarios.md) to learn about the supported authentication app types and flows in the Microsoft Identity Platform.

+1. See the code sample, [Use the Conditional Access Auth Context to perform step-up authentication](https://github.com/Azure-Samples/ms-identity-ca-auth-context/blob/main/README.md) for an example on how it's done.

+ - If a matching Auth Context ID isn't found, it raises a [claims challenge](claims-challenge.md#claims-challenge-header-format).

+Don't hard-code Auth Context values in your app. Apps should read and apply auth context [using MS Graph calls](/graph/api/resources/authenticationcontextclassreference). This practice is critical for [multi-tenant applications](howto-convert-app-to-be-multi-tenant.md). The Auth Context values will vary between Azure AD tenants and won't be available in Azure AD free edition. For more information on how an app should query, set, and use auth context in their code, see the code sample, [Use the Conditional Access auth context to perform step-up authentication](https://github.com/Azure-Samples/ms-identity-ca-auth-context/blob/main/README.md) as how an app should query, set and use auth context in their code.

+Don't use auth context where the app itself is going to be a target of Conditional Access policies. The feature works best when parts of the application require the user to meet a higher bar of authentication.

+## Authentication context [ACRs] in Conditional Access expected behavior

+## Explicit auth context satisfaction in requests

+A client can explicitly ask for a token with an Auth Context (ACRS) through the claims in the request's body. If an ACRS was requested, Conditional Access will allow issuing the token with the requested ACRS if all challenges were completed.

+## Expected behavior when an auth context isn't protected by Conditional Access in the tenant

+Conditional Access may issue an ACRS in a token's claims when all Conditional Access policy assigned to the ACRS value has been satisfied. If no Conditional Access policy is assigned to an ACRS value the claim may still be issued, because all policy requirements have been satisfied.

+## Summary table for expected behavior when ACRS are explicitly requested

+ACRS requested | Policy applied | Control satisfied | ACRS added to claims |

+|--|--|--|--|--|

+|Yes | No | Yes | Yes |

+|Yes | Yes | No | No |

+|Yes | Yes | Yes | Yes |

+|Yes | No policies configured with ACRS | Yes | Yes |

+## Implicit auth context satisfaction by opportunistic evaluation

+A resource provider may opt in to the optional 'acrs' claim. Conditional Access will try to add ACRS to the token claims opportunistically in order to avoid round trips to acquire new tokens to Azure AD. In that evaluation, Conditional Access will check if the policies protecting Auth Context challenges are already satisfied and will add the ACRS to the token claims if so.

+> [!NOTE]

+> Each token type will need to be individually opted-in (ID token, Access token).

+>

+> If a resource provider doesn't opt in to the optional 'acrs' claim, the only way to get an ACRS in the token will be to explicitly ask for it in a token request. It will not get the benefits of the opportunistic evaluation, therefore every time that the required ACRS will be missing from the token claims, the resource provider will challenge the client to acquire a new token containing it in the claims.

+## Expected behavior with auth context and session controls for implicit ACRS opportunistic evaluation

+### Sign-in frequency by interval

+Conditional Access will consider "sign-in frequency by interval" as satisfied for opportunistic ACRS evaluation when all the present authentication factors auth instants are within the sign-in frequency interval. In case that the first factor auth instant is stale, or if the second factor (MFA) is present and its auth instant is stale, the sign-in frequency by interval won't be satisfied and the ACRS won't be issued in the token opportunistically.

+### Cloud App Security (CAS)

+Conditional Access will consider CAS session control as satisfied for opportunistic ACRS evaluation, when a CAS session was established during that request. For example, when a request comes in and any Conditional Access policy applied and enforced a CAS session, and in addition there's a Conditional Access policy that also requires a CAS session, since the CAS session will be enforced, that will satisfy the CAS session control for the opportunistic evaluation.

+## Expected behavior when a tenant contain Conditional Access policies protecting auth context

+The table below will show all corner cases where ACRS is added to the token's claims by opportunistic evaluation.

+**Policy A**: Require MFA from all users, excluding the user "Ariel", when asking for "c1" acrs.

+**Policy B**: Block all users, excluding user "Jay", when asking for "c2", or "c3" acrs.

+| Flow | ACRS requested | Policy applied | Control satisfied | ACRS added to claims |

+|--|--|--|--|--|

+| Ariel requests for an access token | "c1" | None | Yes for "c1". No for "c2" and "c3" | "c1" (requested) |

+| Ariel requests for an access token | "c2" | Policy B | Blocked by policy B | None |

+| Ariel requests for an access token | None | None | Yes for "c1". No for "c2" and "c3" | "c1" (opportunistically added from policy A) |

+| Jay requests for an access token (without MFA) | "c1" | Policy A | No | None |

+| Jay requests for an access token (with MFA) | "c1" | Policy A | Yes | "c1" (requested), "c2" (opportunistically added from policy B), "c3" (opportunistically added from policy B)|

+| Jay requests for an access token (without MFA) | "c2" | None | Yes for "c2" and "c3". No for "c1" | "c2" (requested), "c3" (opportunistically added from policy B) |

+| Jay requests for an access token (with MFA) | "c2" | None | Yes for "c1", "c2" and "c3" | "c1" (best effort from A), "c2" (requested), "c3" (opportunistically added from policy B) |

+| Jay requests for an access token (with MFA) | None | None | Yes for "c1", "c2" and "c3" | "c1", "c2", "c3" all opportunistically added |

+| Jay requests for an access token (without MFA) | None | None | Yes for "c2" and "c3". No for "c1"| "c2", "c3" all opportunistically added |

+When working with ADAL Node, you were likely using the **Azure AD v1.0 endpoint**. Apps migrating from ADAL to MSAL should switch to **Azure AD v2.0 endpoint**.

+The v2.0 endpoint employs a *scope-centric* model to access resources. Thus, when you request an access token for a resource, you also need to specify the scope for that resource:

+> [Investigate risk](../identity-protection/howto-identity-protection-investigate-risk.md#risky-users)

+> [Remediate risk/unblock users](../identity-protection/howto-identity-protection-remediate-unblock.md)

+> [Self-remediation guidance](../identity-protection/howto-identity-protection-remediate-unblock.md)

+- Error code and message being returned

+> Note that when using the `common` or `consumers` authority for personal Microsoft accounts, the consuming resource application must be configured to support such type of accounts in accordance with [signInAudience](./supported-accounts-validation.md).

+* [Include your own claims in tokens](active-directory-optional-claims.md).

+- If you're unfamiliar with managed identities for Azure resources, check out the [overview section](../managed-identities-azure-resources/overview.md). Be sure to review the [difference between a system-assigned and user-assigned managed identity](../managed-identities-azure-resources/overview.md#managed-identity-types).

+- To create a user-assigned managed identity and configure a federated identity credential, your account needs the [Managed Identity Contributor](../../role-based-access-control/built-in-roles.md#managed-identity-contributor) role assignment.

+- [Create a user-assigned manged identity](../managed-identities-azure-resources/how-manage-user-assigned-managed-identities.md?pivots=identity-mi-methods-powershell#list-user-assigned-managed-identities-2)

+- On an Azure AD [App registration](./quickstart-register-app.md) in the Azure portal or through Microsoft Graph. This configuration allows you to get an access token for your application without needing to manage secrets outside Azure. For more information, learn how to [configure an app to trust an external identity provider](workload-identity-federation-create-trust.md).

+- For information about the required format of JWTs created by external identity providers, read about the [assertion format](active-directory-certificate-credentials.md#assertion-format).

+Learn more about [how to manage inactive user accounts in Azure AD](../reports-monitoring/howto-manage-inactive-user-accounts.md).

+2. Create a review to remove inactive external guests. Admins define inactive as period of days. They disable and later delete guests that donΓÇÖt sign in to the tenant within that time frame. By default, this doesn't affect recently created users. [Learn more about how to identify inactive accounts](../reports-monitoring/howto-manage-inactive-user-accounts.md#how-to-detect-inactive-user-accounts).

+1. Create a [dynamic group](./groups-create-rule.md) for the guest users you want to review. For example,

+2. To [create an Access Review](../governance/create-access-review.md)

+1. Create a [dynamic group](./groups-create-rule.md) for the guest users you want to review. For example,

+2. To [create an access review](../governance/create-access-review.md) for the dynamic group, navigate to **Azure Active Directory > Identity Governance > Access Reviews**.

+needed.

+- Use [Microsoft cloud settings (preview)](cross-cloud-settings.md) to establish mutual B2B collaboration between the Microsoft Azure global cloud and [Microsoft Azure Government](../../azure-government/index.yml) or [Microsoft Azure China 21Vianet](/azure/china).

+- [Understand the invitation redemption process](redemption-experience.md)

+[here.](./secure-external-access-resources.md)

+applications.](../external-identities/hybrid-cloud-to-on-premises.md)

+Once the local accounts have their user.mail attributes populated with the external identity/email that they're mapped to, admins can [convert the local accounts to Azure AD B2B by inviting the local account.](../external-identities/invite-internal-users.md)

+1. [Convert local guest accounts to B2B](10-secure-local-guest.md) (YouΓÇÖre here)

+The ability to manage Azure resources is granted by assigning roles that provide the required permissions. Roles can be assigned to individual users or groups. To align with the [Zero Trust guiding principles](../../security/fundamentals/zero-trust.md), use Just-In-Time and Just-Enough-Access policies when assigning roles.

+- [Explore other user management tasks](../enterprise-users/index.yml)

+3. When an external user from a partner organization is created in Azure AD using B2B, MIM can automatically provision them [into AD DS](/microsoft-identity-manager/microsoft-identity-manager-2016-graph-b2b-scenario) and give those guests access to [on-premises Windows-Integrated Authentication or Kerberos-based applications](../external-identities/hybrid-cloud-to-on-premises.md). Alternatively, customers can user [PowerShell scripts](https://github.com/Azure-Samples/B2B-to-AD-Sync) to automate the creation of guest accounts on-premises.

+| 1 |Users, groups| AD DS| Azure AD| [Azure AD Connect Cloud Sync](../cloud-sync/what-is-cloud-sync.md) |

+| 2 |Users, groups, devices| AD DS| Azure AD| [Azure AD Connect Sync](../hybrid/whatis-azure-ad-connect.md) |

+[Learn more about Azure AD Lifecycle Workflows](../governance/what-are-lifecycle-workflows.md)

+3. Use the [Microsoft Identity Manager](/microsoft-identity-manager/microsoft-identity-manager-2016) for complex provisioning scenarios

+**Supported operating systems**: Signing into virtual machines in Azure using Azure AD authentication is currently supported in Windows and Linux. For more specifics on supported operating systems, refer to the documentation for [Windows](../devices/howto-vm-sign-in-azure-ad-windows.md) and [Linux](../devices/howto-vm-sign-in-azure-ad-linux.md).

+**Network Requirements**: These virtual machines will need to access Azure AD for authentication so you must ensure that the virtual machines network configuration permits outbound access to Azure AD endpoints on 443. See the documentation for [Windows](../devices/howto-vm-sign-in-azure-ad-windows.md) and [Linux](../devices/howto-vm-sign-in-azure-ad-linux.md) for more information.

+* [Best practices](secure-with-azure-ad-best-practices.md)

+> The group writeback functionality is currently in Public Preview as we are collecting customer feedback and telemetry. Please refer to [the limitations](#understand-limitations-of-public-preview) before you enable this functionality.

+If you've made changes to the out-of-box synchronization rules, then these rules are set back to the default configuration on upgrade. To make sure that your configuration is kept between upgrades, make sure that you make changes as they're described in [Best practices for changing the default configuration](how-to-connect-sync-best-practices-changing-default-configuration.md). If you already changed the default sync rules, please see how to [Fix modified default rules in Azure AD Connect](./how-to-connect-sync-best-practices-changing-default-configuration.md), before starting the upgrade process.

+ - We added a new attribute 'employeeLeaveDateTime' for syncing to Azure AD. To learn more about how to use this attribute to manage your users' life cycles, please refer to [this article](../governance/how-to-lifecycle-workflow-sync-attributes.md)

+ >[!NOTE]

+ > There's no corresponding EmployeeHireDate or EmployeeLeaveDateTime attribute in Active Directory. If you're importing from on-premises AD, you'll need to identify an attribute in AD that can be used. This attribute must be a string. For more information see, [Synchronizing lifecycle workflow attributes](../governance/how-to-lifecycle-workflow-sync-attributes.md)

+Learn more about how to [integrate your on-premises identities with Azure AD](whatis-hybrid-identity.md).

+- Allow access but require a secure password change.

+| Anomalous user activity | Offline | This risk detection baselines normal administrative user behavior in Azure AD, and spots anomalous patterns of behavior like suspicious changes to the directory. The detection is triggered against the administrator making the change or the object that was changed. |

+1. The user is informed that something unusual was detected about their sign-in. This behavior could be something like, such as signing in from a new location, device, or app.

+ 1. If the home tenant hasn't enabled self-remediation policies, an administrator in the technician's home tenant will have to [remediate the risk](howto-identity-protection-remediate-unblock.md#risk-remediation).

+| Suspicious application | Offline | This detection indicates that Microsoft has identified an application that may be violating our terms of service, but hasn't disabled it. We recommend [conducting an investigation](https://go.microsoft.com/fwlink/?linkid=2208429) of the application.|

+| Anomalous service principal activity | Offline | This risk detection baselines normal administrative service principal behavior in Azure AD, and spots anomalous patterns of behavior like suspicious changes to the directory. The detection is triggered against the administrative service principal making the change or the object that was changed. |

+ 1. Look at the userΓÇÖs past activities including at least the following properties to see if they're normal for the given user.

+After completing your [investigation](howto-identity-protection-investigate-risk.md), you need to take action to remediate the risky users or unblock them. Organizations can enable automated remediation by setting up [risk-based policies](howto-identity-protection-configure-risk-policies.md). Organizations should try to investigate and remediate all risky users in a time period that your organization is comfortable with. Microsoft recommends acting quickly, because time matters when working with risks.

+## Risk remediation

+All active risk detections contribute to the calculation of the user's risk level. The user risk level is an indicator (low, medium, high) of the probability that the user's account has been compromised. As an administrator, after thorough investigation on the risky users and the corresponding risky sign-ins and detections, you want to remediate the risky users so that they're no longer at risk and won't be blocked.

+Some risk detections and the corresponding risky sign-ins may be marked by Identity Protection as dismissed with risk state "Dismissed" and risk detail "Azure AD Identity Protection assessed sign-in safe" because those events were no longer determined to be risky.

+- Set up [risk-based policies](howto-identity-protection-configure-risk-policies.md) to allow users to self-remediate their risks

+### Self-remediation with risk-based policy

+You can allow users to self-remediate their sign-in risks and user risks by setting up [risk-based policies](howto-identity-protection-configure-risk-policies.md). If users pass the required access control, such as Azure AD multifactor authentication (MFA) or secure password change, then their risks are automatically remediated. The corresponding risk detections, risky sign-ins, and risky users will be reported with the risk state "Remediated" instead of "At risk".

+Here are the prerequisites on users before risk-based policies can be applied to them to allow self-remediation of risks:

+- To perform MFA to self-remediate a sign-in risk:

+ - The user must have registered for Azure AD MFA.

+- To perform secure password change to self-remediate a user risk:

+ - The user must have registered for Azure AD MFA.

+ - For hybrid users that are synced from on-premises to cloud, password writeback must have been enabled on them.

+If a risk-based policy is applied to a user during sign-in before the above prerequisites are met, then the user will be blocked because they aren't able to perform the required access control, and admin intervention will be required to unblock the user.

+Risk-based policies are configured based on risk levels and will only apply if the risk level of the sign-in or user matches the configured level. Some detections may not raise risk to the level where the policy will apply, and administrators will need to handle those risky users manually. Administrators may determine that extra measures are necessary like [blocking access from locations](../conditional-access/howto-conditional-access-policy-location.md) or lowering the acceptable risk in their policies.

+### Self-remediation with self-service password reset

+If a user has registered for self-service password reset (SSPR), then they can also remediate their own user risk by performing a self-service password reset.

+If requiring a password reset using a user risk policy isn't an option, administrators can remediate a risky user by requiring a password reset.

+If after investigation and confirming that the user account isn't at risk of being compromised, then you can choose to dismiss the risky user.

+To **Dismiss user risk**, search for and select **Azure AD Risky users** in the Azure portal or the Entra portal, select the affected user, and select **Dismiss user(s) risk**.

+When you select **Dismiss user risk**, the user will no longer be at risk, and all the risky sign-ins of this user and corresponding risk detections will be dismissed as well.

+Because this method doesn't have an impact on the user's existing password, it doesn't bring their identity back into a safe state.

+#### Risk state and detail based on dismissal of risk

+- Risky user:

+ - Risk state: "At risk" -> "Dismissed"

+ - Risk detail (the risk remediation detail): "-" -> "Admin dismissed all risk for user"

+- All the risky sign-ins of this user and the corresponding risk detections:

+ - Risk state: "At risk" -> "Dismissed"

+ - Risk detail (the risk remediation detail): "-" -> "Admin dismissed all risk for user"

+### Confirm a user to be compromised

+If after investigation, an account is confirmed compromised:

+ 1. Select the event or user in the **Risky sign-ins** or **Risky users** reports and choose "Confirm compromised".

+ 2. If a risk-based policy wasn't triggered, and the risk wasn't [self-remediated](#self-remediation-with-risk-based-policy), then do one or more of the followings:

+ 1. [Request a password reset](#manual-password-reset).

+ 1. Block the user if you suspect the attacker can reset the password or do multi-factor authentication for the user.

+ 1. Revoke refresh tokens.

+ 1. [Disable any devices](../devices/device-management-azure-portal.md) that are considered compromised.

+ 1. If using [continuous access evaluation](../conditional-access/concept-continuous-access-evaluation.md), revoke all access tokens.

+For more information about what happens when confirming compromise, see the section [How should I give risk feedback and what happens under the hood?](howto-identity-protection-risk-feedback.md#how-should-i-give-risk-feedback-and-what-happens-under-the-hood).

+### Deleted users

+1. **Reset password** - You can reset the user's password. If a user has been compromised or is at risk of being compromised, the user's password should be reset to protect their account and your organization.

+1. **Dismiss user risk** - The user risk policy blocks a user if the configured user risk level for blocking access has been reached. If after investigation you're confident that the user isn't at risk of being compromised, and it's safe to allow their access, then you can reduce a user's risk level by dismissing their user risk.

+1. **Exclude the user from policy** - If you think that the current configuration of your sign-in policy is causing issues for specific users, and it's safe to grant access to these users without applying this policy to them, then you can exclude them from this policy. For more information, see the section Exclusions in the article [How To: Configure and enable risk policies](howto-identity-protection-configure-risk-policies.md#exclusions).

+Understand the SP initiated flow by following the steps mentioned in [Datawiza and Azure AD authentication architecture](./datawiza-with-azure-ad.md#datawiza-with-azure-ad-authentication-architecture).

+ - See, [Quickstart: Create a new tenant in Azure Active Directory.](../fundamentals/active-directory-access-create-new-tenant.md)

+ - See, [Azure AD Connect sync: Understand and customize synchronization](../hybrid/how-to-connect-sync-whatis.md).

+ - See, [Azure AD built-in roles, all roles](../roles/permissions-reference.md#all-roles).

+portal](../authentication/tutorial-enable-azure-mfa.md).

+- [Configure Datawiza and Azure AD for secure hybrid access](./datawiza-with-azure-ad.md)

+- [Configure Datawiza with Azure AD B2C](../../active-directory-b2c/partner-datawiza.md)

+- [Datawiza documentation](https://docs.datawiza.com/)

+3. Azure Resource Manager updates the VM identity using the Azure Instance Metadata Service identity endpoint (for [Windows](../../virtual-machines/windows/instance-metadata-service.md) and [Linux](../../virtual-machines/linux/instance-metadata-service.md)), providing the endpoint with the service principal client ID and certificate.

+* [Use a Linux VM system-assigned managed identity to access Resource Manager](tutorial-linux-vm-access-arm.md)

+ Title: Azure Active Directory SSO integration with Adstream'

+description: Learn how to configure single sign-on between Azure Active Directory and Adstream.

+# Azure Active Directory SSO integration with Adstream

+In this article, you'll learn how to integrate Adstream with Azure Active Directory (Azure AD). Adstream provides the safest and easiest to use business solution for sending and receiving files. When you integrate Adstream with Azure AD, you can:

+* Control in Azure AD who has access to Adstream.

+* Enable your users to be automatically signed-in to Adstream with their Azure AD accounts.

+* Manage your accounts in one central location - the Azure portal.

+You'll configure and test Azure AD single sign-on for Adstream in a test environment. Adstream supports both **SP** initiated single sign-on.

+> [!NOTE]

+> Identifier of this application is a fixed string value so only one instance can be configured in one tenant.

+## Prerequisites

+To integrate Azure Active Directory with Adstream, you need:

+* An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.

+* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/).

+* Adstream single sign-on (SSO) enabled subscription.

+## Add application and assign a test user

+Before you begin the process of configuring single sign-on, you need to add the Adstream application from the Azure AD gallery. You need a test user account to assign to the application and test the single sign-on configuration.

+### Add Adstream from the Azure AD gallery

+Add Adstream from the Azure AD application gallery to configure single sign-on with Adstream. For more information on how to add application from the gallery, see the [Quickstart: Add application from the gallery](../manage-apps/add-application-portal.md).

+### Create and assign Azure AD test user

+Follow the guidelines in the [create and assign a user account](../manage-apps/add-application-portal-assign-users.md) article to create a test user account in the Azure portal called B.Simon.

+Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, and assign roles. The wizard also provides a link to the single sign-on configuration pane in the Azure portal. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides).

+## Configure Azure AD SSO

+Complete the following steps to enable Azure AD single sign-on in the Azure portal.

+1. In the Azure portal, on the **Adstream** application integration page, find the **Manage** section and select **single sign-on**.

+1. On the **Select a single sign-on method** page, select **SAML**.

+1. On the **Set up single sign-on with SAML** page, select the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+ a. In the **Reply URL** textbox, type the URL:

+ `https://msft.adstream.com/saml/assert`

+ b. In the **Sign on URL** textbox, type the URL:

+ `https://msft.adstream.com`

+ c. In the **Relay State** textbox, type the URL:

+ `https://a5.adstream.com/projects#/projects/projects`

+1. On the **Set-up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Federation Metadata XML** and select **Download** to download the certificate and save it on your computer.

+ 

+1. On the **Set up Adstream** section, copy the appropriate URL(s) based on your requirement.

+ 

+## Configure Adstream SSO

+To configure single sign-on on **Adstream** side, you need to send the downloaded **Federation Metadata XML** and appropriate copied URLs from Azure portal to [Adstream support team](mailto:support@adstream.com). They set this setting to have the SAML SSO connection set properly on both sides.

+### Create Adstream test user

+In this section, you create a user called Britta Simon in Seculio. Work with [Adstream support team](mailto:support@adstream.com) to add the users in the Seculio platform. Users must be created and activated before you use single sign-on.

+## Test SSO

+In this section, you test your Azure AD single sign-on configuration with following options.

+* Click on **Test this application** in Azure portal. This will redirect to Adstream Sign-on URL where you can initiate the login flow.

+* Go to Adstream Sign-on URL directly and initiate the login flow from there.

+* You can use Microsoft My Apps. When you click the Adstream tile in the My Apps, this will redirect to Adstream Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+## Additional resources

+* [What is single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+* [Plan a single sign-on deployment](../manage-apps/plan-sso-deployment.md).

+## Next steps

+Once you configure Adstream you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+1. Go to the **Settings**, click the **SSO Options** in the security options and perform the below steps.

+ a. Select **Enabled** in **Enable SAML Single Sign-On**.

+ c. In the **Identity Provider Sign In URL** textbox, paste the value of **Login URL** from Azure AD application configuration window.

+ e. For **SAML Authentication Context**, select the **Password Protected Transport** radio button.

+ f. Copy the **AtomSphere Sign In URL**, paste this value into the **Sign on URL** text box in the **Basic SAML Configuration** section in the Azure portal.

+ g. Copy the **AtomSphere MetaData URL**, go to the **MetaData URL** via the browser of your choice, and save the output to a file. Upload the **MetaData URL** in the **Basic SAML Configuration** section in the Azure portal.

+ h. Click **Save** button.

+1. After logging in, navigate to **User Management** ->**Users**.

+ Title: Azure Active Directory SSO integration with DX NetOps Portal'

+description: Learn how to configure single sign-on between Azure Active Directory and DX NetOps Portal.

+# Azure Active Directory SSO integration with DX NetOps Portal

+In this article, you'll learn how to integrate DX NetOps Portal with Azure Active Directory (Azure AD). DX NetOps Portal provides network observability, topology with fault correlation and root-cause analysis at telecom carrier level scale, over traditional and software defined networks, internal and external. When you integrate DX NetOps Portal with Azure AD, you can:

+* Control in Azure AD who has access to DX NetOps Portal.

+* Enable your users to be automatically signed-in to DX NetOps Portal with their Azure AD accounts.

+* Manage your accounts in one central location - the Azure portal.

+You'll configure and test Azure AD single sign-on for DX NetOps Portal in a test environment. DX NetOps Portal supports **IDP** initiated single sign-on.

+## Prerequisites

+To integrate Azure Active Directory with DX NetOps Portal, you need:

+* An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.

+* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/).

+* DX NetOps Portal single sign-on (SSO) enabled subscription.

+## Add application and assign a test user

+Before you begin the process of configuring single sign-on, you need to add the DX NetOps Portal application from the Azure AD gallery. You need a test user account to assign to the application and test the single sign-on configuration.

+### Add DX NetOps Portal from the Azure AD gallery

+Add DX NetOps Portal from the Azure AD application gallery to configure single sign-on with DX NetOps Portal. For more information on how to add application from the gallery, see the [Quickstart: Add application from the gallery](../manage-apps/add-application-portal.md).

+### Create and assign Azure AD test user

+Follow the guidelines in the [create and assign a user account](../manage-apps/add-application-portal-assign-users.md) article to create a test user account in the Azure portal called B.Simon.

+Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, and assign roles. The wizard also provides a link to the single sign-on configuration pane in the Azure portal. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides).

+## Configure Azure AD SSO

+Complete the following steps to enable Azure AD single sign-on in the Azure portal.

+1. In the Azure portal, on the **DX NetOps Portal** application integration page, find the **Manage** section and select **single sign-on**.

+1. On the **Select a single sign-on method** page, select **SAML**.

+1. On the **Set up single sign-on with SAML** page, select the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:

+ a. In the **Identifier** textbox, type a value using the following pattern:

+ `<DX NetOps Portal hostname>`

+ b. In the **Reply URL** textbox, type a URL using the following pattern:

+ `https://<DX NetOps Portal FQDN>:<SSO port>/sso/saml2/UserAssertionService`

+ c. In the **Relay State** textbox, type a URL using the following pattern:

+ `SsoProductCode=pc&SsoRedirectUrl=https://<DX NetOps Portal FQDN>:<https port>/pc/desktop/page`

+ > [!NOTE]

+ > These values are not real. Update these values with the actual Identifier, Reply URL and Relay State URL. Contact [DX NetOps Portal Client support team](https://support.broadcom.com/web/ecx/contact-support) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

+1. Your DX NetOps Portal application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows an example for this. The default value of **Unique User Identifier** is **user.userprincipalname** but DX NetOps Portal expects this to be mapped with the user's email address. For that you can use **user.mail** attribute from the list or use the appropriate attribute value based on your organization configuration.

+ 

+1. On the **Set-up single sign-on with SAML** page, in the **SAML Signing Certificate** section, find **Federation Metadata XML** and select **Download** to download the certificate and save it on your computer.

+ 

+1. On the **Set up DX NetOps Portal** section, copy the appropriate URL(s) as per your requirement.

+ 

+## Configure DX NetOps Portal SSO

+To configure single sign-on on **DX NetOps Portal** side, you need to send the downloaded **Federation Metadata XML** and appropriate copied URLs from Azure portal to [DX NetOps Portal support team](https://support.broadcom.com/web/ecx/contact-support). The support team will use the copied URLs to configure the single sign-on on the application.

+### Create DX NetOps Portal test user

+To be able to test and use single sign-on, you have to create and activate users in the DX NetOps Portal application.

+In this section, you create a user called Britta Simon in DX NetOps Portal that corresponds with the Azure AD user you already created in the previous section. Work with [DX NetOps Portal support team](https://support.broadcom.com/web/ecx/contact-support) to add the user in the DX NetOps Portal platform.

+## Test SSO

+In this section, you test your Azure AD single sign-on configuration with following options.

+* Click on Test this application in Azure portal and you should be automatically signed in to the DX NetOps Portal for which you set up the SSO.

+* You can use Microsoft My Apps. When you click the DX NetOps Portal tile in the My Apps, you should be automatically signed in to the DX NetOps Portal for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+## Additional resources

+* [What is single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+* [Plan a single sign-on deployment](../manage-apps/plan-sso-deployment.md).

+## Next steps

+Once you configure DX NetOps Portal you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+To configure single sign-on on FactSet side you will need to visit FactSet's [Control Center](https://controlcenter.factset.com) and configure the **Federation Metadata XML** and appropriate copied URLs from Azure portal under **Control Center's Security > Single Sign-On (SSO)** page. If you require access to this page, please contact [FactSet Support Team](https://www.factset.com/contact-us) and request FactSet product 8514 (Control Center - Source IPs, Security + Authentication).

+Work with your FactSet account support representatives or contact [FactSet Support Team](https://www.factset.com/contact-us) to add the users in the FactSet platform. Users must be created and activated before you use single sign-on.

+In this section, you test your Azure AD single sign-on configuration with following option.

+* FactSet only supports SP-initiated SAML. You may test SSO by visiting any authenticated FactSet URL such as [Issue Tracker](https://issuetracker.factset.com) or [FactSet-Web](https://my.factset.com), click on **Single Sign-On (SSO)** on the logon portal and supply your email address in the subsequent page. Please see supplied [documentation](https://download.factset.com/documents/web/FactSet_Single_Sign-On.pdf) for additional information and usage.

+> [!NOTE]

+> This document is only relevant if you're using the [Original User Model](https://docs.newrelic.com/docs/accounts/original-accounts-billing/original-users-roles/overview-user-models/) in New Relic. Please refer to [New Relic (By Organization)](new-relic-limited-release-tutorial.md) if you're using New Relic's newer user model.

+ > [!NOTE]

+ > The SAML Certificate and SAML Key files are generated separately and uploaded to the Tableau Server Manager. For example, in the linux shell, use openssl to generate the cert and key like so: `openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout private.key -out saml.crt` then upload the `saml.crt` and `private.key` files via the TSM Configruation GUI (As shown in the screenshot at the start of this step) or via the [command line according to the tableau docs](https://help.tableau.com/current/server-linux/en-us/config_saml.htm). If you are in a production environment, you may want to find a more secure way to handle SAML certs and keys.

+> To add the users in the Timetabling Solutions platform. Users must be created and activated before you use single sign-on.

+ Title: Azure Active Directory SSO integration with Tranxfer'

+description: Learn how to configure single sign-on between Azure Active Directory and Tranxfer.

+# Azure Active Directory SSO integration with Tranxfer

+In this article, you'll learn how to integrate Tranxfer with Azure Active Directory (Azure AD). Tranxfer provides the safest and easiest to use business solution for sending and receiving files. When you integrate Tranxfer with Azure AD, you can:

+* Control in Azure AD who has access to Tranxfer.

+* Enable your users to be automatically signed-in to Tranxfer with their Azure AD accounts.

+* Manage your accounts in one central location - the Azure portal.

+You'll configure and test Azure AD single sign-on for Tranxfer in a test environment. Tranxfer supports **SP** initiated single sign-on and **Just In Time** user provisioning.

+## Prerequisites

+To integrate Azure Active Directory with Tranxfer, you need:

+* An Azure AD user account. If you don't already have one, you can [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* One of the following roles: Global Administrator, Cloud Application Administrator, Application Administrator, or owner of the service principal.

+* An Azure AD subscription. If you don't have a subscription, you can get a [free account](https://azure.microsoft.com/free/).

+* Tranxfer single sign-on (SSO) enabled subscription.

+## Add application and assign a test user

+Before you begin the process of configuring single sign-on, you need to add the Tranxfer application from the Azure AD gallery. You need a test user account to assign to the application and test the single sign-on configuration.

+### Add Tranxfer from the Azure AD gallery

+Add Tranxfer from the Azure AD application gallery to configure single sign-on with Tranxfer. For more information on how to add application from the gallery, see the [Quickstart: Add application from the gallery](../manage-apps/add-application-portal.md).

+### Create and assign Azure AD test user

+Follow the guidelines in the [create and assign a user account](../manage-apps/add-application-portal-assign-users.md) article to create a test user account in the Azure portal called B.Simon.

+Alternatively, you can also use the [Enterprise App Configuration Wizard](https://portal.office.com/AdminPortal/home?Q=Docs#/azureadappintegration). In this wizard, you can add an application to your tenant, add users/groups to the app, and assign roles. The wizard also provides a link to the single sign-on configuration pane in the Azure portal. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides).

+## Configure Azure AD SSO

+Complete the following steps to enable Azure AD single sign-on in the Azure portal.

+1. In the Azure portal, on the **Tranxfer** application integration page, find the **Manage** section and select **single sign-on**.

+1. On the **Select a single sign-on method** page, select **SAML**.

+1. On the **Set up single sign-on with SAML** page, select the pencil icon for **Basic SAML Configuration** to edit the settings.

+ 

+1. On the **Basic SAML Configuration** section, perform the following steps:-

+ a. In the **Identifier** textbox, type a URL using the following pattern:

+ `https://<SUBDOMAIN>.tranxfer.com`

+ b. In the **Reply URL** textbox, type a URL using the following pattern:

+ `https://<SUBDOMAIN>.tranxfer.com/SAMLResponse`

+ c. In the **Sign on URL** textbox, type a URL using the following pattern:

+ `https://<SUBDOMAIN>.tranxfer.com/saml/login`

+ > [!NOTE]

+ > These values are not real. Update these values with the actual Identifier, Reply URL and Sign on URL. Contact [Tranxfer Client support team](mailto:soporte@tranxfer.com) to get these values. You can also refer to the patterns shown in the **Basic SAML Configuration** section in the Azure portal.

+1. Tranxfer application expects the SAML assertions in a specific format, which requires you to add custom attribute mappings to your SAML token attributes configuration. The following screenshot shows the list of default attributes.

+ 

+1. In addition to above, Tranxfer application expects few more attributes to be passed back in SAML response, which are shown below. These attributes are also pre populated but you can review them as per your requirements.

+ | Name | Source Attribute|

+ | | |

+ | groups | user.groups [All] |

+1. On the **Set up single sign-on with SAML** page, In the **SAML Signing Certificate** section, select copy button to copy **App Federation Metadata Url** and save it on your computer.

+ 

+## Configure Tranxfer SSO

+To configure single sign-on on **Tranxfer** side, you need to send the **App Federation Metadata Url** to [Tranxfer support team](mailto:soporte@tranxfer.com). The support team will use the copied URLs to configure the single sign-on on the application.

+### Create Tranxfer test user

+In this section, a user called B.Simon is created in Tranxfer. Tranxfer supports just-in-time user provisioning, which is enabled by default. There is no action item for you in this section. If a user doesn't already exist in Tranxfer, a new one is created after authentication.

+## Test SSO

+In this section, you test your Azure AD single sign-on configuration with following options.

+* Click on **Test this application** in Azure portal. This will redirect to Tranxfer Sign-on URL where you can initiate the login flow.

+* Go to Tranxfer Sign-on URL directly and initiate the login flow from there.

+* You can use Microsoft My Apps. When you click the Tranxfer tile in the My Apps, this will redirect to Tranxfer Sign-on URL. For more information about the My Apps, see [Introduction to the My Apps](../user-help/my-apps-portal-end-user-access.md).

+## Additional resources

+* [What is single sign-on with Azure Active Directory?](../manage-apps/what-is-single-sign-on.md)

+* [Plan a single sign-on deployment](../manage-apps/plan-sso-deployment.md).

+## Next steps

+Once you configure Tranxfer you can enforce session control, which protects exfiltration and infiltration of your organizationΓÇÖs sensitive data in real time. Session control extends from Conditional Access. [Learn how to enforce session control with Microsoft Cloud App Security](/cloud-app-security/proxy-deployment-aad).

+When onboarding users you can remove the need for error prone manual onboarding steps by using Verified ID with A10TIX account onboarding. Verified IDs can be used to digitally onboard employees, students, citizens, or others to securely access resources and services. For example, rather than an employee needing to go to a central office to activate an employee badge, they can use a Verified ID to verify their identity to activate a badge that is delivered to them remotely. Rather than a citizen receiving a code they must redeem to access governmental services, they can use a Verified ID to prove their identity and gain access. Learn more about [account onboarding](./plan-verification-solution.md#account-onboarding).

+- [Request Service REST API issuance specification](issuance-request-api.md)

+Verifiable Credentials can be used to onboard employees, students, citizens, or others to access services. For example, rather than an employee needing to go to a central office to activate an employee badge, they can use a verifiable credential to verify their identity to activate a badge that is delivered to them remotely. Rather than a citizen receiving a code they must redeem to access governmental services, they can use a VC to prove their identity and gain access. Learn more about [account onboarding](./plan-verification-solution.md#account-onboarding).

+- [Request Service REST API issuance specification](issuance-request-api.md)

+Learn more about [account onboarding](./plan-verification-solution.md#account-onboarding).

+- [Request Service REST API issuance specification](issuance-request-api.md)

+1. Search for the **Verifiable Credentials Service Request** service principal and select it.

+ 1. DID registration

+ 1. Domain ownership verification.

+If you have selected ION as the trust system, you will not see the DID registration section as it is not applicable for ION and you only have to distribute the did-configuration.json file.

+## Azure Spring Apps

+Learn more about the [Azure Spring Apps service](../spring-apps/index.yml).

+We have identified API calls from outdated Azure Spring Apps API for resources under this subscription. We recommend switching to the latest Azure Spring Apps API version. You need to update your existing code to use the latest API version. Also, you need to upgrade your Azure SDK and Azure CLI to the latest version. This ensures you receive the latest features and performance improvements.

+Learn more about the [Azure Spring Apps service](../spring-apps/index.yml).

+Azure Monitor for VMs monitors your Azure virtual machines (VM) and Virtual Machine Scale Sets at scale. It analyzes the performance and health of your Windows and Linux VMs, and it monitors their processes and dependencies on other resources and external processes. It includes support for monitoring performance and application dependencies for VMs that are hosted on-premises or in another cloud provider.

+ Title: Azure Kubernetes Service (AKS) Diagnostics Overview

+description: Learn about self-diagnosing clusters in Azure Kubernetes Service.

+# Azure Kubernetes Service Diagnostics (preview) overview

+Troubleshooting Azure Kubernetes Service (AKS) cluster issues plays an important role in maintaining your cluster, especially if your cluster is running mission-critical workloads. AKS Diagnostics (preview) is an intelligent, self-diagnostic experience that:

+* Helps you identify and resolve problems in your cluster.

+* Is cloud-native.

+* Requires no extra configuration or billing cost.

+## Open AKS Diagnostics

+To access AKS Diagnostics:

+1. Sign in to the [Azure portal](https://portal.azure.com)

+1. From **All services** in the Azure portal, select **Kubernetes Service**.

+1. Select **Diagnose and solve problems** in the left navigation, which opens AKS Diagnostics.

+1. Choose a category that best describes the issue of your cluster, like _Cluster Node Issues_, by:

+ * Using the keywords in the homepage tile.

+ * Typing a keyword that best describes your issue in the search bar.

+

+## View a diagnostic report

+After you click on a category, you can view a diagnostic report specific to your cluster. Diagnostic reports intelligently call out any issues in your cluster with status icons. You can drill down on each topic by clicking **More Info** to see a detailed description of:

+* Issues

+* Recommended actions

+* Links to helpful docs

+* Related-metrics

+* Logging data

+Diagnostic reports generate based on the current state of your cluster after running various checks. They can be useful for pinpointing the problem of your cluster and understanding next steps to resolve the issue.

+

+

+## Cluster insights

+The following diagnostic checks are available in **Cluster Insights**.

+### Cluster Node Issues

+Cluster Node Issues checks for node-related issues that cause your cluster to behave unexpectedly. Specifically:

+- Node readiness issues

+- Node failures

+- Insufficient resources

+- Node missing IP configuration

+- Node CNI failures

+- Node not found

+- Node power off

+- Node authentication failure

+- Node kube-proxy stale

+### Create, read, update & delete (CRUD) operations

+CRUD Operations checks for any CRUD operations that cause issues in your cluster. Specifically:

+- In-use subnet delete operation error

+- Network security group delete operation error

+- In-use route table delete operation error

+- Referenced resource provisioning error

+- Public IP address delete operation error

+- Deployment failure due to deployment quota

+- Operation error due to organization policy

+- Missing subscription registration

+- VM extension provisioning error

+- Subnet capacity

+- Quota exceeded error

+### Identity and security management

+Identity and Security Management detects authentication and authorization errors that prevent communication to your cluster. Specifically,

+- Node authorization failures

+- 401 errors

+- 403 errors

+## Next steps

+* Collect logs to help you further troubleshoot your cluster issues by using [AKS Periscope](https://aka.ms/aksperiscope).

+* Read the [triage practices section](/azure/architecture/operator-guides/aks/aks-triage-practices) of the AKS day-2 operations guide.

+* Post your questions or feedback at [UserVoice](https://feedback.azure.com/d365community/forum/aabe212a-f724-ec11-b6e6-000d3a4f0da0) by adding "[Diag]" in the title.

+description: Learn how to use the Container Storage Interface (CSI) driver for Azure Blob storage in an Azure Kubernetes Service (AKS) cluster.

+# Use Azure Blob storage Container Storage Interface (CSI) driver

+The Azure Blob storage Container Storage Interface (CSI) driver is a [CSI specification][csi-specification]-compliant driver used by Azure Kubernetes Service (AKS) to manage the lifecycle of Azure Blob storage. The CSI is a standard for exposing arbitrary block and file storage systems to containerized workloads on Kubernetes.

+The data on the object storage can be accessed by applications using BlobFuse or Network File System (NFS) 3.0 protocol. Before the introduction of the Azure Blob storage CSI driver, the only option was to manually install an unsupported driver to access Blob storage from your application running on AKS. When the Azure Blob storage CSI driver is enabled on AKS, there are two built-in storage classes: *azureblob-fuse-premium* and *azureblob-nfs-premium*.

+> [!NOTE]

+> Azure Blob CSI driver only supports NFS 3.0 protocol for Kubernetes versions 1.25 (preview) on AKS.

+## Azure Blob storage CSI driver features

+Azure Blob storage CSI driver supports the following features:

+Review the prerequisites listed in the [CSI storage drivers overview][csi-storage-driver-overview] article to verify the requirements before using this feature.

+When you use storage CSI drivers on AKS, there are two additional built-in StorageClasses that use the Azure Blob CSI storage driver.

+- To learn how to use CSI driver for Azure Disks, see [Use Azure Disks with CSI driver][azure-disk-csi-driver]

+- To learn how to use CSI driver for Azure Files, see [Use Azure Files with CSI driver][azure-files-csi-driver]

+[csi-storage-driver-overview]: csi-storage-drivers.md

+[azure-disk-csi-driver]: azure-disk-csi.md

+[azure-files-csi-driver]: azure-files-csi.md

+* Consider [stateless design](./operator-best-practices-multi-region.md#remove-service-state-from-inside-containers) to reduce unnecessary network load, data processing, and compute resources.

+* Enable [cluster auto-upgrade](./auto-upgrade-cluster.md) and [apply security updates to nodes automatically using GitHub Actions](./node-upgrade-github-actions.md), to ensure your cluster has the latest improvements.

+Add-ons and extensions covered by the [AKS support policy](./support-policies.md) provide additional and supported functionality to your cluster while allowing you to benefit from the latest performance improvements and energy optimizations throughout your cluster lifecycle.

+* Ensure you install [KEDA](./integrations.md#available-add-ons) as an add-on and [GitOps & Dapr](./cluster-extensions.md?tabs=azure-cli#currently-available-extensions) as extensions.

+* Use [Draft](./draft.md) to simplify application containerization by generating Dockerfiles and Kubernetes manifests.

+* Size your cluster to match the scalability needs of your application and [use cluster autoscaler](./cluster-autoscaler.md) in combination with [virtual nodes](./virtual-nodes.md) to rapidly scale and maximize compute resource utilization. Additionally, [enforce resource quotas](./operator-best-practices-scheduler.md#enforce-resource-quotas) at the namespace level and [scale user node pools to 0](./scale-cluster.md?tabs=azure-cli#scale-user-node-pools-to-0) when there is no demand.

+* Use the [node pool stop / start](./start-stop-nodepools.md) to turn off your node pools outside of business hours, and [KEDA CRON scaler](https://keda.sh/docs/2.7/scalers/cron/) to scale down your workloads (pods) based on time.

+* Use [Azure Advisor](../advisor/advisor-cost-recommendations.md) to identify unused resources and [ImageCleaner](./image-cleaner.md?tabs=azure-cli) to clean up stale images and remove an area of risk in your cluster.

+* Set [Azure tags on your cluster](./use-tags.md) to enable monitoring of your workloads.

+* Understand the needs of your application to [choose the appropriate storage](./operator-best-practices-storage.md#choose-the-appropriate-storage-type) and define it using [storage classes](./operator-best-practices-storage.md#create-and-use-storage-classes-to-define-application-needs) to avoid storage underutilization. Additionally, consider [provisioning volumes dynamically](./operator-best-practices-storage.md#dynamically-provision-volumes) to automatically scale the number of storage resources.

+* Consider deploying your nodes within a [proximity placement group](../virtual-machines/co-location.md) to reduce the network traversal by ensuring your compute resources are physically located close to each other. For critical workloads configure [proximity placement groups with availability zones](./reduce-latency-ppg.md#configure-proximity-placement-groups-with-availability-zones).

+* Carefully consider the increase in CPU usage and network traffic generated by [service mesh](./servicemesh-about.md) communication components before making the decision to use one.

+* Make sure you are collecting and retaining only the log data necessary to support your requirements. [Configure data collection rules for your AKS workloads](../azure-monitor/containers/container-insights-agent-config.md#data-collection-settings) and implement design considerations for [optimizing your Log Analytics costs](/azure/architecture/framework/services/monitoring/log-analytics/cost-optimization).

+* Ensure you [follow best practices](/azure/architecture/best-practices/cdn) for CDN and consider using [Azure CDN](../cdn/cdn-how-caching-works.md?toc=%2fazure%2ffrontdoor%2fTOC.json) to lower the consumed bandwidth and keep costs down.

+* Review the information on TLS termination when using [Application Gateway](../application-gateway/ssl-overview.md) or [Azure Front Door](../application-gateway/ssl-overview.md). Consider if you can terminate TLS at your border gateway and continue with non-TLS to your workload load balancer and onwards to your workload.

+* Follow recommendations from [Microsoft Defender for Cloud](/security/benchmark/azure/security-control-vulnerability-management) and run automated vulnerability scanning tools such as [Defender for Containers](../defender-for-cloud/defender-for-containers-vulnerability-assessment-azure.md) to avoid unnecessary resource usage by identifying vulnerabilities in your images and minimizing the window of opportunity for attackers.

+> [Azure Well-Architected Framework review of AKS](/azure/architecture/framework/services/compute/azure-kubernetes-service/azure-kubernetes-service)

+- You need the Azure CLI version 2.42 or later installed and configured. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][install-azure-cli].

+- If the open-source CSI Blob storage driver is installed on your cluster, uninstall it before enabling the Azure Blob storage driver.

+## Disable CSI storage drivers on a new or existing cluster

+To disable CSI storage drivers on a new cluster, include one of the following parameters depending on the storage system:

+* `--disable-disk-driver` allows you to disable the [Azure Disks CSI driver][azure-disk-csi].

+* `--disable-file-driver` allows you to disable the [Azure Files CSI driver][azure-files-csi].

+* `--disable-blob-driver` allows you to disable the [Azure Blob storage CSI driver][azure-blob-csi].

+* `--disable-snapshot-controller` allows you to disable the [snapshot controller][snapshot-controller].

+az aks create -n myAKSCluster -g myResourceGroup --disable-disk-driver --disable-file-driver --disable-blob-driver --disable-snapshot-controller

+To disable CSI storage drivers on an existing cluster, use one of the parameters listed earlier depending on the storage system:

+az aks update -n myAKSCluster -g myResourceGroup --disable-disk-driver --disable-file-driver --disable-blob-driver --disable-snapshot-controller

+To enable CSI storage drivers on a new cluster, include one of the following parameters depending on the storage system:

+* `--enable-disk-driver` allows you to enable the [Azure Disks CSI driver][azure-disk-csi].

+* `--enable-file-driver` allows you to enable the [Azure Files CSI driver][azure-files-csi].

+* `--enable-blob-driver` allows you to enable the [Azure Blob storage CSI driver][azure-blob-csi].

+* `--enable-snapshot-controller` allows you to enable the [snapshot controller][snapshot-controller].

+az aks update -n myAKSCluster -g myResourceGroup --enable-disk-driver --enable-file-driver --enable-blob-driver --enable-snapshot-controller

+- To use the CSI driver for Azure Disks, see [Use Azure Disks with CSI drivers][azure-disk-csi].

+- To use the CSI driver for Azure Files, see [Use Azure Files with CSI drivers][azure-files-csi].

+- To use the CSI driver for Azure Blob storage, see [Use Azure Blob storage with CSI drivers][azure-blob-csi]

+[azure-blob-csi]: azure-blob-csi.md

+[azure-disk-csi]: azure-disk-csi.md

+[azure-files-csi]: azure-files-csi.md

+ - name: KEYVAULT_URL

+ value: ${KEYVAULT_URL}

+[aks-solution-guidance]: /azure/architecture/reference-architectures/containers/aks-start-here

+ When performing an upgrade from an _unsupported version_ that skips two or more minor versions, the upgrade is performed without any guarantee of functionality and is excluded from the service-level agreements and limited warranty. If your version is significantly out of date, it's recommended to re-create the cluster.

+As part of the application and cluster lifecycle, you may want to upgrade to the latest available version of Kubernetes. You can upgrade your Azure Kubernetes Service (AKS) cluster by using the Azure CLI, Azure PowerShell, or the Azure portal.

+In this tutorial, part seven of seven, you learn how to:

+> * Identify current and available Kubernetes versions.

+> * Upgrade your Kubernetes nodes.

+> * Validate a successful upgrade.

+In previous tutorials, an application was packaged into a container image, and this container image was uploaded to Azure Container Registry (ACR). You also created an AKS cluster. The application was then deployed to the AKS cluster. If you have not done these steps and would like to follow along, start with [Tutorial 1: Prepare an application for AKS][aks-tutorial-prepare-app].

+* If you're using Azure CLI, this article requires that you're running Azure CLI version 2.34.1 or later. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][azure-cli-install].

+* If you're using Azure PowerShell, this tutorial requires that you're running Azure PowerShell version 5.9.0 or later. Run `Get-InstalledModule -Name Az` to find the version. If you need to install or upgrade, see [Install Azure PowerShell][azure-powershell-install].

+* If you don't have an Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin.

+Before you upgrade a cluster, use the [az aks get-upgrades][] command to check which Kubernetes releases are available.

+In the following example output, the current version is *1.18.10*, and the available versions are shown under *upgrades*.

+```output

+Before you upgrade a cluster, use the [Get-AzAksCluster][get-azakscluster] cmdlet to check which Kubernetes version you're running and the region in which it resides.

+In the following example output, the current version is *1.19.9*.

+Name KubernetesVersion Location

+- -- --

+myAKSCluster 1.19.9 eastus

+Use the [Get-AzAksVersion][get-azaksversion] cmdlet to check which Kubernetes upgrade releases are available in the region where your AKS cluster resides.

+Default IsPreview OrchestratorType OrchestratorVersion

+- - -

+ Kubernetes 1.20.2

+ Kubernetes 1.20.5

+### [Azure portal](#tab/azure-portal)

+To check which Kubernetes releases are available for your cluster:

+1. Sign in to the [Azure portal](https://portal.azure.com).

+2. Navigate to your AKS cluster.

+3. Under **Settings**, select **Cluster configuration**.

+4. In **Kubernetes version**, select **Upgrade version**. This will redirect you to a new page.

+5. In **Kubernetes version**, select the version to check for available upgrades.

+If no upgrades are available, create a new cluster with a supported version of Kubernetes and migrate your workloads from the existing cluster to the new cluster. It's not supported to upgrade a cluster to a newer Kubernetes version when no upgrades are available.

+AKS nodes are carefully cordoned and drained to minimize any potential disruptions to running applications. The following steps are performed during this process:

+1. The Kubernetes scheduler prevents additional pods from being scheduled on a node that is to be upgraded.

+1. A new node is created that runs the latest Kubernetes components.

+1. When the new node is ready and joined to the cluster, the Kubernetes scheduler begins to run pods on the new node.

+Use the [az aks upgrade][] command to upgrade your AKS cluster.

+> You can only upgrade one minor version at a time. For example, you can upgrade from *1.14.x* to *1.15.x*, but you cannot upgrade from *1.14.x* to *1.16.x* directly. To upgrade from *1.14.x* to *1.16.x*, you must first upgrade from *1.14.x* to *1.15.x*, then perform another upgrade from *1.15.x* to *1.16.x*.

+The following example output shows the result of upgrading to *1.19.1*. Notice the *kubernetesVersion* now reports *1.19.1*.

+```output

+Use the [Set-AzAksCluster][set-azakscluster] cmdlet to upgrade your AKS cluster.

+> You can only upgrade one minor version at a time. For example, you can upgrade from *1.14.x* to *1.15.x*, but you cannot upgrade from *1.14.x* to *1.16.x* directly. To upgrade from *1.14.x* to *1.16.x*, first upgrade from *1.14.x* to *1.15.x*, then perform another upgrade from *1.15.x* to *1.16.x*.

+The following example output shows the result of upgrading to *1.19.9*. Notice the *kubernetesVersion* now reports *1.20.2*.

+### [Azure portal](#tab/azure-portal)

+To upgrade your AKS cluster:

+1. In the Azure portal, navigate to your AKS cluster.

+2. Under **Settings**, select **Cluster configuration**.

+3. In **Kubernetes version**, select **Upgrade version**. This will redirect you to a new page.

+4. In **Kubernetes version**, select your desired version and then select **Save**.

+It takes a few minutes to upgrade the cluster, depending on how many nodes you have.

+When you upgrade your cluster, the following Kubernetes events may occur on the nodes:

+* **Surge**: Create surge node.

+* **Drain**: Pods are being evicted from the node. Each pod has a *5 minute timeout* to complete the eviction.

+* **Update**: Update of a node has succeeded or failed.

+* **Delete**: Delete a surge node.

+Use `kubectl get events` to show events in the default namespaces while running an upgrade.

+The following example output shows some of the above events listed during an upgrade.

+Confirm that the upgrade was successful using the [az aks show][] command.

+Name Location ResourceGroup KubernetesVersion CurrentKubernetesVersion ProvisioningState Fqdn

+ - - - -

+myAKSCluster eastus myResourceGroup 1.19.1 1.19.1 Succeeded myaksclust-myresourcegroup-19da35-bd54a4be.hcp.eastus.azmk8s.io

+Confirm that the upgrade was successful using the [Get-AzAksCluster][get-azakscluster] cmdlet.

+Name Location KubernetesVersion ProvisioningState

+- -- -- --

+myAKSCluster eastus 1.20.2 Succeeded

+### [Azure portal](#tab/azure-portal)

+To confirm that the upgrade was successful, navigate to your AKS cluster in the Azure portal. On the **Overview** page, select the **Kubernetes version** and ensure it's the latest version you installed in the previous step.

+As this tutorial is the last part of the series, you may want to delete your AKS cluster. The Kubernetes nodes run on Azure virtual machines and continue incurring charges even if you don't use the cluster.

+Use the [az group delete][az-group-delete] command to remove the resource group, container service, and all related resources.

+Use the [Remove-AzResourceGroup][remove-azresourcegroup] cmdlet to remove the resource group, container service, and all related resources.

+### [Azure portal](#tab/azure-portal)

+To delete your AKS cluster:

+1. In the Azure portal, navigate to your AKS cluster.

+2. On the **Overview** page, select **Delete**.

+3. A popup will appear that asks you to confirm the deletion of the cluster. Select **Yes**.

+> When you delete the cluster, the Azure Active Directory (AAD) service principal used by the AKS cluster isn't removed. For steps on how to remove the service principal, see [AKS service principal considerations and deletion][sp-delete]. If you used a managed identity, the identity is managed by the platform and it doesn't require that you provision or rotate any secrets.

+> * Identify current and available Kubernetes versions.

+> * Upgrade your Kubernetes nodes.

+> * Validate a successful upgrade.

+For more information on AKS, see [AKS overview][aks-intro]. For guidance on how to create full solutions with AKS, see [AKS solution guidance][aks-solution-guidance].

+> Skipping multiple versions can only be done when upgrading from an _unsupported version_ back to a _supported version_. For example, an upgrade from an unsupported *1.10.x* -> a supported *1.15.x* can be completed if available. When performing an upgrade from an _unsupported version_ that skips two or more minor versions, the upgrade is performed without any guarantee of functionality and is excluded from the service-level agreements and limited warranty. If your version is significantly out of date, it's recommended to re-create the cluster.

+> Skipping multiple versions can only be done when upgrading from an _unsupported version_ back to a _supported version_. For example, an upgrade from an unsupported *1.10.x* -> a supported *1.15.x* can be completed if available. When performing an upgrade from an _unsupported version_ that skips two or more minor versions, the upgrade is performed without any guarantee of functionality and is excluded from the service-level agreements and limited warranty. If your version is significantly out of date, it's recommended to re-create the cluster.

+For more details on optional claims, read [Provide optional claims to your app](../active-directory/develop/active-directory-optional-claims.md).

+- The MySQL Flexible Server is created behind a private [Virtual Network](../virtual-network/virtual-networks-overview.md) and can't be accessed directly. To access or manage the database, use phpMyAdmin that's deployed with the WordPress site. You can access phpMyAdmin by following these steps:

+> [Configure PHP app](configure-language-php.md)

+Learn more about Subdomain Takeover at [Dangling DNS and subdomain takeover](../security/fundamentals/subdomain-takeover.md).

+To get a domain verification ID, see the [Map a custom domain tutorial](app-service-web-tutorial-custom-domain.md#2-get-a-domain-verification-id)

+|**Business card model**| <ul><li>[**Form Recognizer labeling tool**](https://fott-2-1.azurewebsites.net/prebuilts-analyze)</li><li>[**REST API**](./how-to-guides/use-sdk-rest-api.md?pivots=programming-language-rest-api&preserve-view=true&tabs=windows&view=form-recog-2.1.0#analyze-business-cards)</li><li>[**Client-library SDK**](/azure/applied-ai-services/form-recognizer/how-to-guides/v2-1-sdk-rest-api)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=business-card#run-the-container-with-the-docker-compose-up-command)</li></ul>|

+|_**Custom model**_| <ul><li>[Form Recognizer labeling tool](https://fott-2-1.azurewebsites.net)</li><li>[REST API](./how-to-guides/use-sdk-rest-api.md?pivots=programming-language-rest-api&preserve-view=true&tabs=windows&view=form-recog-2.1.0#analyze-forms-with-a-custom-model)</li><li>[Client library SDK](/azure/applied-ai-services/form-recognizer/how-to-guides/v2-1-sdk-rest-api)</li><li>[Form Recognizer Docker container](containers/form-recognizer-container-install-run.md?tabs=custom#run-the-container-with-the-docker-compose-up-command)</li></ul>|

+> [**Compose custom models**](how-to-guides/compose-custom-models.md)

+|Custom model| <ul><li>[Form Recognizer labeling tool](https://fott-2-1.azurewebsites.net)</li><li>[REST API](./how-to-guides/use-sdk-rest-api.md?pivots=programming-language-rest-api&preserve-view=true&tabs=windows&view=form-recog-2.1.0#analyze-forms-with-a-custom-model)</li><li>[Client library SDK](/azure/applied-ai-services/form-recognizer/how-to-guides/v2-1-sdk-rest-api)</li><li>[Form Recognizer Docker container](containers/form-recognizer-container-install-run.md?tabs=custom#run-the-container-with-the-docker-compose-up-command)</li></ul>|***custom-model-id***|

+| [v2.1 quickstart](quickstarts/get-started-v2-1-sdk-rest-api.md) | [Form Recognizer API v2.1](https://westus.dev.cognitive.microsoft.com/docs/services/form-recognizer-api-v3-0-preview-2/operations/BuildDocumentModel) |

+|**ID document model**| <ul><li>[**Form Recognizer labeling tool**](https://fott-2-1.azurewebsites.net/prebuilts-analyze)</li><li>[**REST API**](./how-to-guides/use-sdk-rest-api.md?pivots=programming-language-rest-api&preserve-view=true&tabs=windows&view=form-recog-2.1.0#analyze-identity-id-documents)</li><li>[**Client-library SDK**](/azure/applied-ai-services/form-recognizer/how-to-guides/v2-1-sdk-rest-api)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=id-document#run-the-container-with-the-docker-compose-up-command)</li></ul>|

+|**Invoice model**| <ul><li>[**Form Recognizer labeling tool**](https://fott-2-1.azurewebsites.net/prebuilts-analyze)</li><li>[**REST API**](./how-to-guides/use-sdk-rest-api.md?pivots=programming-language-rest-api&preserve-view=true&tabs=windows&view=form-recog-2.1.0#analyze-invoices)</li><li>[**Client-library SDK**](/azure/applied-ai-services/form-recognizer/how-to-guides/v2-1-sdk-rest-api)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=invoice#run-the-container-with-the-docker-compose-up-command)</li></ul>|

+|**Layout API**| <ul><li>[**Form Recognizer labeling tool**](https://fott-2-1.azurewebsites.net/layout-analyze)</li><li>[**REST API**](./how-to-guides/use-sdk-rest-api.md?pivots=programming-language-rest-api&preserve-view=true&tabs=windows&view=form-recog-2.1.0#analyze-layout)</li><li>[**Client-library SDK**](/azure/applied-ai-services/form-recognizer/how-to-guides/v2-1-sdk-rest-api)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?branch=main&tabs=layout#run-the-container-with-the-docker-compose-up-command)</li></ul>|

+**Sample receipt processed with [Form Recognizer Sample Labeling tool](https://fott-2-1.azurewebsites.net/connection)**:

+|**Receipt model**| <ul><li>[**Form Recognizer labeling tool**](https://fott-2-1.azurewebsites.net/prebuilts-analyze)</li><li>[**REST API**](./how-to-guides/use-sdk-rest-api.md?pivots=programming-language-rest-api&preserve-view=true&tabs=windows&view=form-recog-2.1.0#analyze-receipts)</li><li>[**Client-library SDK**](/azure/applied-ai-services/form-recognizer/how-to-guides/v2-1-sdk-rest-api)</li><li>[**Form Recognizer Docker container**](containers/form-recognizer-container-install-run.md?tabs=receipt#run-the-container-with-the-docker-compose-up-command)</li></ul>|

+ :::image type="content" source="media/receipts-example.jpg" alt-text="Screenshot of the layout model analyze results operation.":::

+Form Recognizer service is updated on an ongoing basis. Bookmark this page to stay up to date with release notes, feature enhancements, and our newest documentation.

+### Form Recognizer versioned content

+Form Recognizer documentation has been updated to present a versioned experience. Now, you can choose to view content targeting the v3.0 GA experience or the v2.1 GA experience. The v3.0 experience is the default.

+Sample code for the [Form Recognizer Studio labeling experience](https://github.com/microsoft/Form-Recognizer-Toolkit/tree/main/SampleCode/LabelingUX) is now available on GitHub. Customers can develop and integrate Form Recognizer into their own UX or build their own new UX using the Form Recognizer Studio sample code.

+A new prebuilt that extracts information from contracts such as parties, title, contract ID, execution date and more. the contracts model is currently in preview, request access [here](https://customervoice.microsoft.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR7en2Ais5pxKtso_Pz4b1_xUQTRDQUdHMTBWUDRBQ01QUVNWNlNYMVFDViQlQCN0PWcu_).

+1. Update the application's group membership claims. Run the commands in the same directory as `oauth2-permissions.json` file. RBAC for Azure Arc-enabled Kubernetes requires [`signInAudience` to be set to **AzureADMyOrg**](../../active-directory/develop/supported-accounts-validation.md):

+4. Grant the required permissions for the client application. RBAC for Azure Arc-enabled Kubernetes requires [`signInAudience` to be set to **AzureADMyOrg**](../../active-directory/develop/supported-accounts-validation.md):

+> Securely connect to the cluster by using [Cluster Connect](cluster-connect.md).

+The steps above will resolve many common connection issues, but if you're still unable to connect successfully, generate a troubleshooting log file and then [open a support request](../../azure-portal/supportability/how-to-create-azure-support-request.md) so we can investigate the problem further.

+When you [create your support request](../../azure-portal/supportability/how-to-create-azure-support-request.md), in the **Additional details** section, use the **File upload** option to upload the generated log file.

+If the machine is executing commands behind a proxy server, you'll need to set any necessary environment variables, [explained below](#set-environment-variables).

+### Set environment variables

+For example:

+```bash

+export HTTP_PROXY=ΓÇ£http://<proxyIP>:<proxyPort>ΓÇ¥

+export HTTPS_PROXY=ΓÇ£https://<proxyIP>:<proxyPort>ΓÇ¥

+export NO_PROXY=ΓÇ£<service CIDR>,Kubernetes.default.svc,.svc.cluster.local,.svcΓÇ¥

+```

+The steps above will resolve many common connection issues, but if you're still unable to connect successfully, generate a troubleshooting log file and then [open a support request](../../azure-portal/supportability/how-to-create-azure-support-request.md) so we can investigate the problem further.

+When you [create your support request](../../azure-portal/supportability/how-to-create-azure-support-request.md), in the **Additional details** section, use the **File upload** option to upload the generated log file.

+1. Appliance VM IP and Control Plane IP must be able to communicate with the deployment machine and vCenter endpoint (for VMware) or MOC cloud agent endpoint (for HCI). Work with your network administrator to ensure the network is configured to permit this. This may require adding a firewall rule to open port 443 from the Appliance VM IP and Control Plane IP to vCenter or port 65000 and 55000 for Azure Stack HCI MOC cloud agent. Review [network requirements for Azure Stack HCI](/azure-stack/hci/manage/azure-arc-vm-management-prerequisites#network-port-requirements) and [VMware](../vmware-vsphere/quick-start-connect-vcenter-to-arc-using-script.md) for Arc resource bridge.

+- [Open an Azure support request](../../azure-portal/supportability/how-to-create-azure-support-request.md).

+description: Learn how to use audience features in the Fluid Framework

+ Title: 'How to: Use audience features in the Fluid Framework'

+# How to: Use audience features in the Fluid Framework

+In this tutorial, you'll learn about using the Fluid Framework [Audience](https://fluidframework.com/docs/build/audience/) with [React](https://reactjs.org/) to create a visual demonstration of users connecting to a container. The audience object holds information related to all users connected to the container. In this example, the Azure Client library will be used to create the container and audience.

+To jump ahead into the finished demo, check out the [Audience demo in our FluidExamples repo](https://github.com/microsoft/FluidExamples/tree/main/audience-demo).

+The following image shows ID buttons and a container ID input field. Leaving the container ID field blank and clicking a user ID button will create a new container and join as the selected user. Alternatively, the end-user can input a container ID and choose a user ID to join an existing container as the selected user.

+The next image shows multiple users connected to a container represented by boxes. The box outlined in blue represents the user who is viewing the client while the boxes outlined in black represents the other connected users. As new users attach to the container with unique ID's, the number of boxes will increase.

+> [!NOTE]

+> This tutorial assumes that you are familiar with the [Fluid Framework Overview](https://fluidframework.com/docs/) and that you have completed the [QuickStart](https://fluidframework.com/docs/start/quick-start/). You should also be familiar with the basics of [React](https://reactjs.org/), [creating React projects](https://reactjs.org/docs/create-a-new-react-app.html#create-react-app), and [React Hooks](https://reactjs.org/docs/hooks-intro.html).

+## Create the project

+1. Open a Command Prompt and navigate to the parent folder where you want to create the project; e.g., `C:\My Fluid Projects`.

+1. Run the following command at the prompt. (Note that the CLI is np**x**, not npm. It was installed when you installed Node.js.)

+ ```dotnetcli

+ npx create-react-app fluid-audience-tutorial

+ ```

+1. The project is created in a subfolder named `fluid-audience-tutorial`. Navigate to it with the command `cd fluid-audience-tutorial`.

+1. The project uses the following Fluid libraries:

+ | Library | Description |

+ |-|-|

+ | `fluid-framework` | Contains the SharedMap [distributed data structure](../concepts/data-structures.md) that synchronizes data across clients. |

+ | `@fluidframework/azure-client` | Defines the connection to a Fluid service server and defines the starting schema for the [Fluid container](../concepts/architecture.md#container). |

+ | `@fluidframework/test-client-utils` | Defines the [InsecureTokenProvider](../concepts/authentication-authorization.md#the-token-provider) needed to create the connection to a Fluid Service. |

+ Run the following command to install the libraries.

+ ```dotnetcli

+ npm install @fluidframework/azure-client @fluidframework/test-client-utils fluid-framework

+ ```

+## Code the project

+### Set up state variables and component view

+1. Open the file `\src\App.js` in the code editor. Delete all the default `import` statements. Then delete all the markup from the `return` statement. Then add import statements for components and React hooks. Note that we will be implementing the imported **AudienceDisplay** and **UserIdSelection** components in the later steps. The file should look like the following:

+ ```js

+ import { useState, useCallback } from "react";

+ import { AudienceDisplay } from "./AudienceDisplay";

+ import { UserIdSelection } from "./UserIdSelection";

+

+ export const App = () => {

+ // TODO 1: Define state variables to handle view changes and user input

+ return (

+ // TODO 2: Return view components

+ );

+ }

+ ```

+1. Replace `TODO 1` with the following code. This code initializes local state variables that will be used within the application. The `displayAudience` value determines if we render the **AudienceDisplay** component or the **UserIdSelection** component (see `TODO 2`). The `userId` value is the user identifier to connect to the container with and the `containerId` value is the container to load. The `handleSelectUser` and `handleContainerNotFound` functions are passed in as callbacks to the two views and manage state transitions. `handleSelectUser` is called when attempting to create/load a container. `handleContainerNotFound` is called when creating/loading a container fails.

+ Note, the values userId and containerId will come from a **UserIdSelection** component through the `handleSelectUser` function.

+ ```js

+ const [displayAudience, setDisplayAudience] = useState(false);

+ const [userId, setUserId] = useState();

+ const [containerId, setContainerId] = useState();

+

+ const handleSelectUser = useCallback((userId, containerId) => {

+ setDisplayAudience(true)

+ setUserId(userId);

+ setContainerId(containerId);

+ }, [displayAudience, userId, containerId]);

+

+ const handleContainerNotFound = useCallback(() => {

+ setDisplayAudience(false)

+ }, [setDisplayAudience]);

+ ```

+1. Replace `TODO 2` with the following code. As stated above, the `displayAudience` variable will determine if we render the **AudienceDisplay** component or the **UserIdSelection** component. Also, functions to update the state variables are passed into components as properties.

+ ```js

+ (displayAudience) ?

+ <AudienceDisplay userId={userId} containerId={containerId} onContainerNotFound={handleContainerNotFound}/> :

+ <UserIdSelection onSelectUser={handleSelectUser}/>

+ ```

+### Set up AudienceDisplay component

+1. Create and open a file `\src\AudienceDisplay.js` in the code editor. Add the following `import` statements:

+ ```js

+ import { useEffect, useState } from "react";

+ import { SharedMap } from "fluid-framework";

+ import { AzureClient } from "@fluidframework/azure-client";

+ import { InsecureTokenProvider } from "@fluidframework/test-client-utils";

+ ```

+

+ Note that the objects imported from the Fluid Framework library are required for defining users and containers. In the following steps, **AzureClient** and **InsecureTokenProvider** will be used to configure the client service (see `TODO 1`) while the **SharedMap** will be used to configure a `containerSchema` needed to create a container (see `TODO 2`).

+1. Add the following functional components and helper functions:

+ ```js

+ const tryGetAudienceObject = async (userId, userName, containerId) => {

+ // TODO 1: Create container and return audience object

+ }

+

+ export const AudienceDisplay = (props) => {

+ //TODO 2: Configure user ID, user name, and state variables

+ //TODO 3: Set state variables and set event listener on component mount

+ //TODO 4: Return list view

+ }

+

+ const AudienceList = (data) => {

+ //TODO 5: Append view elements to list array for each member

+ //TODO 6: Return list of member elements

+ }

+ ```

+ Note that the **AudienceDisplay** and **AudienceList** are functional components which handle getting and rendering audience data while the `tryGetAudienceObject` method handles the creation of container and audience services.

+### Getting container and audience

+You can use a helper function to get the Fluid data, from the Audience object, into the view layer (the React state). The `tryGetAudienceObject` method is called when the view component loads after a user ID is selected. The returned value is assigned to a React state property.

+1. Replace `TODO 1` with the following code. Note that the values for `userId` `userName` `containerId` will be passed in from the **App** component. If there is no `containerId`, a new container is created. Also, note that the `containerId` is stored on the URL hash. A user entering a session from a new browser may copy the URL from an existing session browser or navigate to `localhost:3000` and manually input the container ID. With this implementation, we want to wrap the `getContainer` call in a try catch in the case that the user inputs a container ID which does not exist. Visit the [React demo](https://fluidframework.com/docs/recipes/react/) and [Containers](../concepts/architecture.md#container) documentation for more information.

+ ```js

+ const userConfig = {

+ id: userId,

+ name: userName,

+ additionalDetails: {

+ email: userName.replace(/\s/g, "") + "@example.com",

+ date: new Date().toLocaleDateString("en-US"),

+ },

+ };

+

+ const serviceConfig = {

+ connection: {

+ type: "local",

+ tokenProvider: new InsecureTokenProvider("", userConfig),

+ endpoint: "http://localhost:7070",

+ },

+ };

+

+ const client = new AzureClient(serviceConfig);

+

+ const containerSchema = {

+ initialObjects: { myMap: SharedMap },

+ };

+

+ let container;

+ let services;

+ if (!containerId) {

+ ({ container, services } = await client.createContainer(containerSchema));

+ const id = await container.attach();

+ location.hash = id;

+ } else {

+ try {

+ ({ container, services } = await client.getContainer(containerId, containerSchema));

+ } catch (e) {

+ return;

+ }

+ }

+ return services.audience;

+ ```

+### Getting the audience on component mount

+Now that we've defined how to get the Fluid audience, we need to tell React to call `tryGetAudienceObject` when the Audience Display component is mounted.

+1. Replace `TODO 2` with the following code. Note that the user ID will come from the parent component as either `user1` `user2` or `random`. If the ID is `random` we use `Math.random()` to generate a random number as the ID. Additionally, a name will be mapped to the user based on their ID as specified in `userNameList`. Lastly, we define the state variables which will store the connected members as well as the current user. `fluidMembers` will store a list of all members connected to the container whereas `currentMember` will contain the member object representing the current user viewing the browser context.

+ ```js

+ const userId = props.userId == "random" ? Math.random() : props.userId;

+ const userNameList = {

+ "user1" : "User One",

+ "user2" : "User Two",

+ "random" : "Random User"

+ };

+ const userName = userNameList[props.userId];

+

+ const [fluidMembers, setFluidMembers] = useState();

+ const [currentMember, setCurrentMember] = useState();

+ ```

+1. Replace `TODO 3` with the following code. This will call the `tryGetAudienceObject` when the component is mounted and set the returned audience members to `fluidMembers` and `currentMember`. Note, we check if an audience object is returned in case a user inputs a containerId which does not exist and we need to return them to the **UserIdSelection** view (`props.onContainerNotFound()` will handle switching the view). Also, it is good practice to deregister event handlers when the React component dismounts by returning `audience.off`.

+ ```js

+ useEffect(() => {

+ tryGetAudienceObject(userId, userName, props.containerId).then(audience => {

+ if(!audience) {

+ props.onContainerNotFound();

+ alert("error: container id not found.");

+ return;

+ }

+

+ const updateMembers = () => {

+ setFluidMembers(audience.getMembers());

+ setCurrentMember(audience.getMyself());

+ }

+

+ updateMembers();

+

+ audience.on("membersChanged", updateMembers);

+

+ return () => { audience.off("membersChanged", updateMembers) };

+ });

+ }, []);

+ ```

+1. Replace `TODO 4` with the following code. Note, if the `fluidMembers` or `currentMember` has not been initialized, a blank screen is rendered. The **AudienceList** component will render the member data with styling (to be implemented in the next section).

+ ```js

+ if (!fluidMembers || !currentMember) return (<div/>);

+

+ return (

+ <AudienceList fluidMembers={fluidMembers} currentMember={currentMember}/>

+ )

+ ```

+

+ > [!NOTE]

+ > Connection transitions can result in short timing windows where `getMyself` returns `undefined`. This is because the current client connection will not have been added to the audience yet, so a matching connection ID cannot be found. To prevent React from rendering a page with no audience members, we add a listener to call `updateMembers` on `membersChanged`. This works since the service audience emits a `membersChanged` event when the container is connected.

+### Create the view

+1. Replace `TODO 5` with the following code. Note we are rendering a list component for each member passed from the **AudienceDisplay** component. For each member, we first compare `member.userId` to `currentMember.userId` to check if that member `isSelf`. This way, we can differentiate the client user from the other users and display the component with a different color. We then push the list component to a `list` array. Each component will display member data such as `userId` `userName` and `additionalDetails`.

+ ```js

+ const currentMember = data.currentMember;

+ const fluidMembers = data.fluidMembers;

+

+ const list = [];

+ fluidMembers.forEach((member, key) => {

+ const isSelf = (member.userId === currentMember.userId);

+ const outlineColor = isSelf ? 'blue' : 'black';

+

+ list.push(

+ <div style={{

+ padding: '1rem',

+ margin: '1rem',

+ display: 'flex',

+ outline: 'solid',

+ flexDirection: 'column',

+ maxWidth: '25%',

+ outlineColor

+ }} key={key}>

+ <div style={{fontWeight: 'bold'}}>Name</div>

+ <div>

+ {member.userName}

+ </div>

+ <div style={{fontWeight: 'bold'}}>ID</div>

+ <div>

+ {member.userId}

+ </div>

+ <div style={{fontWeight: 'bold'}}>Connections</div>

+ {

+ member.connections.map((data, key) => {

+ return (<div key={key}>{data.id}</div>);

+ })

+ }

+ <div style={{fontWeight: 'bold'}}>Additional Details</div>

+ { JSON.stringify(member.additionalDetails, null, '\t') }

+ </div>

+ );

+ });

+ ```

+1. Replace `TODO 6` with the following code. This will render all each of the member elements we pushed into the `list` array.

+ ```js

+ return (

+ <div>

+ {list}

+ </div>

+ );

+ ```

+### Setup UserIdSelection component

+1. Create and open a file `\src\UserIdSelection.js` in the code editor. This component will include user ID buttons and container ID input fields which allow end-users to choose their user ID and collaborative session. Add the following `import` statements and functional components:

+ ```js

+ import { useState } from 'react';

+

+ export const UserIdSelection = (props) => {

+ // TODO 1: Define styles and handle user inputs

+ return (

+ // TODO 2: Return view components

+ );

+ }

+ ```

+1. Replace `TODO 1` with the following code. Note that the `onSelectUser` function will update the state variables in the parent **App** component and prompt a view change. The `handleSubmit` method is triggered by button elements which will be implemented in `TODO 2`. Also, the `handleChange` method is used to update the `containerId` state variable. This method will be called from an input element event listener implemented in `TODO 2`. Also, note that we update the `containerId` be getting the value from an HTML element with the id `containerIdInput` (defined in `TODO 2`).

+ ```js

+ const selectionStyle = {

+ marginTop: '2rem',

+ marginRight: '2rem',

+ width: '150px',

+ height: '30px',

+ };

+

+ const [containerId, setContainerId] = (location.hash.substring(1));

+

+ const handleSubmit = (userId) => {

+ props.onSelectUser(userId, containerId);

+ }

+

+ const handleChange = () => {

+ setContainerId(document.getElementById("containerIdInput").value);

+ };

+ ```

+1. Replace `TODO 2` with the following code. This will render the user ID buttons as well as the container ID input field.

+ ```js

+ <div style={{display: 'flex', flexDirection:'column'}}>

+ <div style={{marginBottom: '2rem'}}>

+ Enter Container Id:

+ <input type="text" id="containerIdInput" value={containerId} onChange={() => handleChange()} style={{marginLeft: '2rem'}}></input>

+ </div>

+ {

+ (containerId) ?

+ (<div style={{}}>Select a User to join container ID: {containerId} as the user</div>)

+ : (<div style={{}}>Select a User to create a new container and join as the selected user</div>)

+ }

+ <nav>

+ <button type="submit" style={selectionStyle} onClick={() => handleSubmit("user1")}>User 1</button>

+ <button type="submit" style={selectionStyle} onClick={() => handleSubmit("user2")}>User 2</button>

+ <button type="submit" style={selectionStyle} onClick={() => handleSubmit("random")}>Random User</button>

+ </nav>

+ </div>

+ ```

+## Start the Fluid server and run the application

+> [!NOTE]

+> To match the rest of this how-to, this section uses `npx` and `npm` commands to start a Fluid server. However, the code in this article can also run against an Azure Fluid Relay server. For more information, see [How to: Provision an Azure Fluid Relay service](provision-fluid-azure-portal.md) and [How to: Connect to an Azure Fluid Relay service](connect-fluid-azure-service.md)

+In the Command Prompt, run the following command to start the Fluid service.

+```dotnetcli

+npx @fluidframework/azure-local-service@latest

+```

+Open a new Command Prompt and navigate to the root of the project; for example, `C:/My Fluid Projects/fluid-audience-tutorial`. Start the application server with the following command. The application opens in the browser. This may take a few minutes.

+```dotnetcli

+npm run start

+```

+Navigate to `localhost:3000` on a browser tab to view the running application. To create a new container, select a user ID button while leaving the container ID input blank. To simulate a new user joining the container session, open a new browser tab and navigate to `localhost:3000`. This time, input the container ID value which can be found from first browser tab's url proceeding `http://localhost:3000/#`.

+> [!NOTE]

+> You may need to install an additional dependency to make this demo compatible with Webpack 5. If you receive a compilation error related to a "buffer" or "url" package, please run `npm install -D buffer url` and try again. This will be resolved in a future release of Fluid Framework.

+## Next steps

+- Try extending the demo with more key/value pairs in the `additionalDetails` field in `userConfig`.

+- Consider integrating audience into a collaborative application which utilizes distributed data structures such as SharedMap or SharedString.

+- Learn more about [Audience](https://fluidframework.com/docs/build/audience/).

+> [!TIP]

+> When you make changes to the code the project will automatically rebuild and the application server will reload. However, if you make changes to the container schema, they will only take effect if you close and restart the application server. To do this, give focus to the Command Prompt and press Ctrl-C twice. Then run `npm run start` again.

+## Enable SQL query collection

+Application Insights automatically collects data on dependencies for HTTP requests, database calls, and for several bindings. For more information, see [Dependencies](./functions-monitoring.md#dependencies). For SQL calls, the name of the server and database is always collected and stored, but SQL query text isn't collected by default. You can use `dependencyTrackingOptions.enableSqlCommandTextInstrumentation` to enable SQL query text logging by setting (at minimum) the following in your [host.json file](./functions-host-json.md#applicationinsightsdependencytrackingoptions):

+```json

+"logging": {

+ "applicationInsights": {

+ "enableDependencyTracking": true,

+ "dependencyTrackingOptions": {

+ "enableSqlCommandTextInstrumentation": true

+ }

+ }

+}

+```

+For more information, see [Advanced SQL tracking to get full SQL query](../azure-monitor/app/asp-net-dependencies.md#advanced-sql-tracking-to-get-full-sql-query).

+> You can use application settings to override host.json setting values without having to change the host.json file itself. This is helpful for scenarios where you need to configure or modify specific host.json settings for a specific environment. This also lets you change host.json settings without having to republish your project. To learn more, see the [host.json reference article](functions-host-json.md#override-hostjson-values). Changes to function app settings require your function app to be restarted.

+The instrumentation key for Application Insights. Don't use both `APPINSIGHTS_INSTRUMENTATIONKEY` and `APPLICATIONINSIGHTS_CONNECTION_STRING`. When possible, use `APPLICATIONINSIGHTS_CONNECTION_STRING`. When Application Insights runs in a sovereign cloud, you must use `APPLICATIONINSIGHTS_CONNECTION_STRING`. For more information, see [How to configure monitoring for Azure Functions](configure-monitoring.md).

+The connection string for Application Insights. When possible, use `APPLICATIONINSIGHTS_CONNECTION_STRING` instead of `APPINSIGHTS_INSTRUMENTATIONKEY`. Using `APPLICATIONINSIGHTS_CONNECTION_STRING` is required in the following cases:

+Dynamic concurrency can be enabled at the host level in the host.json file. When, enabled any binding extensions used by your function app that support dynamic concurrency adjust concurrency dynamically as needed. Dynamic concurrency settings override any manually configured concurrency settings for triggers that support dynamic concurrency.

+ "concurrency": {

+ "dynamicConcurrencyEnabled": true,

+ "snapshotPersistenceEnabled": true

+ },

+ "dependencyTrackingOptions": {

+ "enableSqlCommandTextInstrumentation": true

+ },

+| dependencyTrackingOptions | n/a | See [applicationInsights.dependencyTrackingOptions](#applicationinsightsdependencytrackingoptions). |

+### applicationInsights.dependencyTrackingOptions

+|Property | Default | Description |

+| | | |

+| enableSqlCommandTextInstrumentation | false | Enables collection of the full text of SQL queries, which is disabled by default. For more information on collecting SQL query text, see [Advanced SQL tracking to get full SQL query](../azure-monitor/app/asp-net-dependencies.md#advanced-sql-tracking-to-get-full-sql-query). |

+## concurrency

+Enables dynamic concurrency for specific bindings in your function app. For more information, see [Dynamic concurrency](./functions-concurrency.md#dynamic-concurrency).

+```json

+ {

+ "concurrency": {

+ "dynamicConcurrencyEnabled": true,

+ "snapshotPersistenceEnabled": true

+ }

+ }

+```

+|Property | Default | Description |

+| | | |

+| dynamicConcurrencyEnabled | false | Enables dynamic concurrency behaviors for all triggers supported by this feature, which is off by default. |

+| snapshotPersistenceEnabled | true | Learned concurrency values are periodically persisted to storage so new instances start from those values instead of starting from 1 and having to redo the learning. |

+There may be instances where you wish to configure or modify specific settings in a host.json file for a specific environment, without changing the host.json file itself. You can override specific host.json values by creating an equivalent value as an application setting. When the runtime finds an application setting in the format `AzureFunctionsJobHost__path__to__setting`, it overrides the equivalent host.json setting located at `path.to.setting` in the JSON. When expressed as an application setting, the dot (`.`) used to indicate JSON hierarchy is replaced by a double underscore (`__`).

+Overriding host.json settings using environment variables follows the ASP.NET Core naming conventions. When the element structure includes an array, the numeric array index should be treated as an additional element name in this path. For more information, see [Naming of environment variables](/aspnet/core/fundamentals/configuration/#naming-of-environment-variables).

+1. Select **Settings > Secrets > Actions**.

+[Host daemon]: ./how-to-secure-daemon-app.md#host-a-daemon-on-non-azure-resources

+[NuGet]: https://www.nuget.org/

+## Create a Node.js project

+The example below creates a new directory then a Node.js program named _mapsDemo_ using npm:

+```powershell

+mkdir mapsDemo

+cd mapsDemo

+npm init

+```

+### Azure Maps services

+| Service Name  | npm packages | Samples  |

+| [Search][search readme] | [@azure/maps-search][search package] | [search samples][search sample] |

+[Host daemon]: ./how-to-secure-daemon-app.md#host-a-daemon-on-non-azure-resources

+[js route sample]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/maps/maps-route-rest/samples/v1-beta

+> [Azure Maps npm Package](https://www.npmjs.com/package/azure-maps-rest )

+The following is a collection of code samples for each platform that cover common use cases to help you migrate your web application from Bing Maps V8 JavaScript SDK to the Azure Maps Web SDK. Code samples related to web applications are provided in JavaScript; however, Azure Maps also provides TypeScript definitions as an additional option through an [npm module](./how-to-use-map-control.md).

+* JavaScript, TypeScript, Node.js ΓÇô [documentation](how-to-use-services-module.md) \| [npm package](https://www.npmjs.com/package/azure-maps-rest)

+description: In this article, you'll learn how to use the bubble layer in an Azure Maps Power BI visual.

+| Size | The size of each bubble. This option is hidden when a field is passed into the **Size** bucket of the **Fields** pane. More options will appear as outlined in the [Bubble size scaling](#bubble-size-scaling) section further down in this article. |

+| Blur | Amount of blur applied to the outline. A value of one blurs the bubbles such that only the center point has no transparency. A value of 0 apply any blur effect. |

+| Zoom scale | Amount the bubbles should scale relative to the zoom level. A zoom scale of one means no scaling. Large values will make bubbles smaller when zoomed out and larger when zoomed in. This helps to reduce the clutter on the map when zoomed out, yet ensures points stand out more when zoomed in. A value of 1 doesn't apply any scaling. |

+| Size scaling method | Scaling algorithm used to determine relative bubble size.<br/><br/>&nbsp;ΓÇó Linear: Range of input data linearly mapped to the min and max size. (default)<br/>&nbsp;ΓÇó Log: Range of input data logarithmically mapped to the min and max size.<br/>&nbsp;ΓÇó Cubic-Bezier: Specify X1, Y1, X2, Y2 values of a Cubic-Bezier curve to create a custom scaling method. |

+## Category labels

+When displaying a **bubble layer** map, the **Category labels** settings will become active in the **Format visual** pane.

+The **Category labels** settings enable you to customize font setting such as font type, size and color as well as the category labels background color and transparency.

+description: In this article, you'll learn how to use Azure Maps Power BI visual.

+The Azure Maps Power BI visual provides a rich set of data visualizations for spatial data on top of a map. It's estimated that over 80% of business data has a location context. The Azure Maps Power BI visual can be used to gain insights into how this location context relates to and influences your business data.

+- The Azure Maps Power BI visual must be enabled in Power BI Desktop. To enable Azure Maps Power BI visual, select **File** &gt; **Options and Settings** &gt; **Options** &gt; **Preview features**, then select the **Azure Maps Visual** checkbox. If the Azure Maps visual isn't available after enabling this setting, it's likely that a tenant admin switch in the Admin Portal needs to be enabled.

+ :::image type="content" source="media/power-bi-visual/bubble-layer.png" alt-text="A screenshot of the Azure Maps visual displaying points as bubbles on the map after latitude and longitude fields are provided." lightbox="media/power-bi-visual/bubble-layer.png":::

+ :::image type="content" source="media/power-bi-visual/bubble-layer-with-legend-color.png" alt-text="A screenshot of the Azure Maps visual displaying points as colored bubbles on the map after legend field is provided." lightbox="media/power-bi-visual/bubble-layer-with-legend-color.png":::

+ :::image type="content" source="media/power-bi-visual/bubble-layer-with-legend-color-and-size.png" alt-text="A screenshot of the Azure Maps visual displaying points as colored and scaled bubbles on the map demonstrating the size field." lightbox="media/power-bi-visual/bubble-layer-with-legend-color-and-size.png":::

+ :::image type="content" source="media/power-bi-visual/bubble-layer-styled.png" alt-text="A screenshot of the Azure Maps visual displaying points as bubbles on the map with a custom style." lightbox="media/power-bi-visual/bubble-layer-styled.png":::

+5. You can also show or hide labels in the **Format** pane. The following two images show maps with the **Show labels** setting turned on and off:

+ :::image type="content" source="media/power-bi-visual/show-labels-on.png" alt-text="A screenshot of the Azure Maps visual displaying a map with the show labels setting turned on in the style section of the format pane in Power BI." lightbox="media/power-bi-visual/show-labels-on.png":::

+ :::image type="content" source="media/power-bi-visual/show-labels-off.png" alt-text="A screenshot of the Azure Maps visual displaying a map with the show labels setting turned off in the style section of the format pane in Power BI." lightbox="media/power-bi-visual/show-labels-off.png":::

+The **Map settings** section of the **Format** pane provide options for customizing how the map is displayed and reacts to updates.

+The **Map settings** section is divided into three subsections: [style](#style), [view](#view) and [controls](#controls).

+### Style

+The following settings are available in the **Style** section:

+| Setting | Description |

+|-|--|

+| Style | The style of the map. The dropdown list contains [greyscale light][gs-light], [greyscale dark][gs-dark], [night][night], [road shaded relief][RSR], [satellite][satellite] and [satellite road labels][satellite RL]. |

+| Show labels | A toggle switch that enables you to either show or hide map labels. For more information, see list item number five in the previous section. |

+### View

+The following settings available in the **View** section enable the user to specify the default map view information when the **Auto zoom** setting is set to **Off**.

+| Auto zoom | Automatically zooms the map into the data loaded through the **Fields** pane of the visual. As the data changes, the map will update its position accordingly. When **Auto zoom** is set to **Off**, the remaining settings in this section become active that enable to user to define the default map view. |

+| Center latitude | The default latitude of the center of the map. |

+| Center longitude | The default longitude of the center of the map. |

+### Controls

+The following settings are available in the **Controls** section:

+| Setting | Description |

+|--|--|

+| World wrap | Allows the user to pan the map horizontally infinitely. |

+| Style picker | Adds a button to the map that allows the report readers to change the style of the map. |

+| Navigation | Adds buttons to the map as another method to allow the report readers to zoom, rotate, and change the pitch of the map. See this document on [Navigating the map](map-accessibility.md#navigating-the-map) for details on all the different ways users can navigate the map. |

+| Selection | Adds a button that allows the user to choose between different modes to select data on the map; circle, rectangle, polygon (lasso), or travel time or distance. To complete drawing a polygon; select the first point, or double-click on the last point on the map, or press the `c` key. |

+| Geocoding culture | The default, **Auto**, refers to the Western Address System. The only other option, **JA**, refers to the Japanese address system. In the western address system, you begin with the address details and then proceed to the larger categories such as city, state and postal code. In the Japanese address system, the larger categories are listed first and finish with the address details. |

+At this time, Azure Maps is currently available in all countries and regions except:

+[gs-light]: supported-map-styles.md#grayscale_light

+[gs-dark]: supported-map-styles.md#grayscale_dark

+[night]:supported-map-styles.md#night

+[RSR]: supported-map-styles.md#road_shaded_relief

+[satellite]: supported-map-styles.md#satellite

+[satellite RL]: supported-map-styles.md#satellite_road_labels

+| Service Name  | npm packages | Samples  |

+If self-hosting the Azure Maps Web SDK via the npm module, be sure to use the caret (^) symbol to in combination with the Azure Maps npm package version number in your `package.json` file so that it will always point to the latest minor version.

+- FIPS (Marketplace images for CentOS and RHEL 6/7 with their default settings)

+1. The Azure credentials for running `Connect-AzAccount` and `Select-AzContext`, which set the context for the script to run.

+ "storageAccountEndPoint": "https://core.windows.net"

+ "storageAccountEndPoint": "https://core.windows.net"

+ 1. Select values for each of these fields in the **Alert logic** section:

+ |Event level| Select the level of the events for this alert rule. Values are: **Critical**, **Error**, **Warning**, **Informational**, **Verbose** and **All**.|

+ |Status|Select the status levels for the alert.|

+ ### [Resource Health alert](#tab/resource-health)

+ 1. In the **Conditions** pane, select values for each of these fields:

+ |Field |Description |

+ |||

+ |Event status| Select the statuses of Resource Health events. Values are: **Active**, **In Progress**, **Resolved**, and **Updated**.|

+ |Current resource status|Select the current resource status. Values are: **Available**, **Degraded**, and **Unavailable**.|

+ |Previous resource status|Select the previous resource status. Values are: **Available**, **Degraded**, **Unavailable**, and **Unknown**.|

+ |Reason type|Select the cause(s) of the Resource Health events. Values are: **Platform Initiated**, **Unknown**, and **User Initiated**.|

+ ### [Service Health alert](#tab/service-health)

+ 1. In the **Conditions** pane, select values for each of these fields:

+ |Field |Description |

+ |||

+ |Services| Select the Azure services.|

+ |Regions|Select the Azure regions.|

+ |Event types|Select the type(s) of Service Health events. Values are: **Service issue**, **Planned maintenance**, **Health advisories**, and **Security advisories**.|

+ ### [Resource Health alert](#tab/resource-health)

+ 1. Enter values for the **Alert rule name** and the **Alert rule description**.

+ 1. (Optional) In the **Advanced options** section, select **Enable upon creation** for the alert rule to start running as soon as you're done creating it.

+ ### [Service Health alert](#tab/service-health)

+

+ 1. Enter values for the **Alert rule name** and the **Alert rule description**.

+ 1. (Optional) In the **Advanced options** section, select **Enable upon creation** for the alert rule to start running as soon as you're done creating it.

+ You can find detailed documentation on the activity log alert rule create command in the **az monitor activity-log alert create** section of the [CLI reference documentation for activity log alerts](/cli/azure/monitor/activity-log/alert).

+ ### [Resource Health alert](#tab/resource-health)

+

+ To create a new activity log alert rule, use the following commands using the `Resource Health` category:

+ - [az monitor activity-log alert create](/cli/azure/monitor/activity-log/alert#az-monitor-activity-log-alert-create): Create a new activity log alert rule resource.

+ - [az monitor activity-log alert scope](/cli/azure/monitor/activity-log/alert/scope): Add scope for the created activity log alert rule.

+ - [az monitor activity-log alert action-group](/cli/azure/monitor/activity-log/alert/action-group): Add an action group to the activity log alert rule.

+

+ You can find detailed documentation on the alert rule create command in the **az monitor activity-log alert create** section of the [CLI reference documentation for activity log alerts](/cli/azure/monitor/activity-log/alert).

+ ### [Service Health alert](#tab/service-health)

+ To create a new activity log alert rule, use the following commands using the `Service Health` category:

+ - [az monitor activity-log alert create](/cli/azure/monitor/activity-log/alert#az-monitor-activity-log-alert-create): Create a new activity log alert rule resource .

+ - [az monitor activity-log alert scope](/cli/azure/monitor/activity-log/alert/scope): Add scope for the created activity log alert rule.

+ - [az monitor activity-log alert action-group](/cli/azure/monitor/activity-log/alert/action-group): Add an action group to the activity log alert rule.

+ You can find detailed documentation on the alert rule create command in the **az monitor activity-log alert create** section of the [CLI reference documentation for activity log alerts](/cli/azure/monitor/activity-log/alert).

+

+[Azure Logic Apps](../../logic-apps/logic-apps-overview.md) allows you to build and customize workflows for integration. Use Logic Apps to customize your alert notifications.

+This table provides a brief description of each alert type.

+|[Activity log alerts](alerts-types.md#activity-log-alerts)|Activity log alerts are triggered when a new activity log event occurs that matches defined conditions. **Resource Health** alerts and **Service Health** alerts are activity log alerts that report on your service and resource health.|

+|[Prometheus alerts (preview)](alerts-types.md#prometheus-alerts-preview)|Prometheus alerts are used for alerting on performance and health of Kubernetes clusters (including AKS). The alert rules are based on PromQL, which is an open source query language.|

+There are four types of alerts:

+- [Log alerts](#log-alerts)

+ - [Service Health alerts](#service-health-alerts)

+ - [Resource Health alerts](#resource-health-alerts)

+|Activity Log alert|Activity logs provide auditing of all actions that occurred on resources. Use activity log alerts to be alerted when a specific event happens to a resource, for example, a restart, a shutdown, or the creation or deletion of a resource. Service Health alerts and Resource Health alerts can let you know when there is an issue with one of your services or resources.|For more information, see the [pricing page](https://azure.microsoft.com/pricing/details/monitor/).|

+### Service Health alerts

+Service Health alerts are a type of activity alert. [Service Health](../../service-health/overview.md) lets you know about outages, planned maintenance activities, and other health advisories because the authenticated Service Health experience knows which services and resources you currently use.

+The best way to use Service Health is to set up Service Health alerts to notify you using your preferred communication channels when service issues, planned maintenance, or other changes may affect the Azure services and regions you use.

+### Resource Health alerts

+Resource Health alerts are a type of activity alert. [Resource Health overview](../../service-health/resource-health-overview.md) helps you diagnose and get support for service problems that affect your Azure resources. It reports on the current and past health of your resources. Resource Health relies on signals from different Azure services to assess whether a resource is healthy. If a resource is unhealthy, Resource Health analyzes additional information to determine the source of the problem. It also reports on actions that Microsoft is taking to fix the problem and identifies things that you can do to address it.

+- [GitHub or Azure DevOps integration](work-item-integration.md) ΓÇô create [GitHub](/training/paths/github-administration-products/) or [Azure DevOps](/azure/devops/?view=azure-devops) work items in context of Application Insights data

+In addition, Application Insights supports [Distributed Tracing](distributed-tracing.md), also known as ΓÇ£distributed component correlationΓÇ¥. This feature allows [searching for](diagnostic-search.md) and [visualizing](transaction-diagnostics.md) an end-to-end flow of a given execution or transaction. The ability to trace activity end-to-end is increasingly important for applications that have been built as distributed components or [microservices](/azure/architecture/guide/architecture-styles/microservices).

+Application maps represent the logical structure of a distributed application. Individual components of the application are determined by their "roleName" or "name" property in recorded telemetry. These components are represented as circles on the map and are referred to as "nodes." HTTP calls between nodes are represented as arrows connecting these nodes, referred to as "connectors" or "edges." The node that makes the call is the "source" of the call, and the receiving node is the "target" of the call.

+intelligent view

+## Application Map Filters

+Application Map filters allow the user to reduce the number of nodes and edges shown by applying one or more filters. These filters can be used to reduce the scope of the map, showing a smaller and more focused map.

+### Creating Application Map filters

+To create a filter, select the "Add filter" button in the application map's toolbar.

+This pops up a dialog with three sections: 1) Select filter type, 2)

+Choose filter parameters, and 3) Review.

+The first section has two options:

+1. Node filter

+1. Connector (edge) filter

+

+The contents in the other sections change based on the option selected.

+#### Node filters

+Node filters allow the user to leave only selected nodes on the map and hide the rest. A node filter checks each node if it contains a property (its name, for example) with a value that matches a search value through a given operator. If a node is removed by a node filter, all of its connectors (edges) are also removed.

+There are three parameters available for nodes:

+- "**Nodes included**" allows the user to select only nodes with

+ matching properties or to also include source nodes, target nodes,

+ or both in the resulting map.

+ - "Nodes and sources, targets"--This means nodes that match the search parameters will be included in the resulting map, and nodes that are sources or targets for the matching node will also be included, even if they don't have property values that

+ match the search. Source and target nodes are collectively referred to as "Connected" nodes.

+ - "Nodes and sources"--Same as above, but target nodes aren't automatically included in the results.

+ - "Nodes and targets"--Same as above, but source nodes aren't automatically included.

+ - "Nodes only"--All nodes in the resulting map must have a property value that matches.

+- "**Operator**" is the type of check that will be performed on each

+ node's property values:

+ - contains

+ - !contains (not contains)

+ - == (equals)

+ - != (not equals)

+- "**Search value**" is the text that has to be contained, not

+ contained, equal, or not equal to a node property value. Some of the

+ values found in nodes that are on the map are shown in a drop-down.

+ Any arbitrary value can be entered by clicking "Create option ..."

+ in the drop-down.

+For example, in the screenshot below, the filter is being configured to

+select **Node(s)** that **contain(s)** the text **"-west".** **Source**

+and t**arget** nodes will also be included in the resulting map. In the

+same screenshot, the user is able to select one of the values found in

+the map or to create an option that isn't an exact match to one found

+in the map.

+#### Connector (edge) filters

+Connector filters examine the properties of a connector to match a value. Connectors that don't match the filter are removed from the map. The same happens to nodes with no connectors left.

+Connector filters require three parameters:

+- "**Filter connectors by**" allows the user to choose which property

+ of a connector to use:

+ - "**Error connector (highlighted red)**" selects connectors based

+ on their color (red or not). A value can't be entered for this

+ type of filter, only an operator that is "==" or "!=" meaning

+ "connector with errors" and "connector without errors."

+ - "**Error rate**" uses the average error rate for the

+ connectorthe number of failed calls divided by the number of

+ all callsexpressed as a percentage. For example, a value of

+ "1" would refer to 1% failed calls.

+ - "**Average call duration (****ms)**" uses just that: the average

+ duration of all calls represented by the connector, in

+ milliseconds. For example, a value of "1000" would refer to

+ calls that averaged 1 second.

+ - "**Calls count**" uses the total number of calls represented by

+ the connector.

+- **"Operator"** is the comparison that will be applied between the

+ connector property and the value entered below. The options change:

+ "Error connector" has equals/not equals options; all others have

+ greater/less than.

+- **"Value"** is the comparison value for the filter. There's only

+ one option for the "Error connector" filter: "Errors." Other filter

+ types require a numeric value and offer a drop-down with some

+ pre-populated entries relevant to the map.

+ - Some of these entries have a designation "(Pxx)" which are

+ percentile levels. For example, "Average call duration" filter

+ may have the value "200 (P90)" which indicates 90% of all

+ connectors (regardless of the number of calls they represent)

+ have less than 200 ms call duration..

+ - When a specific number isn't shown in the drop-down, it can be

+ typed, and created by clicking on "Create option." Typing "P"

+ shows all the percentile values in the drop-down.

+### Review section

+The Review section contains textual and visual descriptions of what the filter will do, which should be helpful when learning how filters work:

+### Using filters in Application Map

+#### Filter interactivity

+After configuring a filter in the "Add filter" pop-up, select "Apply" to create the filter. Several filters can be applied, and they work sequentially, from left to right. Each filter can remove further nodes and connectors, but can't add them back to the map.

+The filters show up as rounded buttons above the application map:

+Clicking the :::image type="content" source="media/app-map/image-8.png" alt-text="A screenshot of a rounded X button."::: on a filter will remove that filter. Clicking elsewhere on the button allows the user to edit the filter's values. As the user changes values in the filter, the new values are applied so that the map is a preview of the change. Clicking "Cancel" restores the filter as it was before editing.

+### Reusing filters

+Filters can be reused in two ways:

+- The "Copy link" button on the toolbar above the map encodes the

+ filter information in the copied URL. This link can be saved in the

+ browser's bookmarks or shared with others. "Copy link" preserves the

+ duration value, but not the absolute time, so the map shown at a

+ later time may be different from the one observed when the link was

+ created.

+- The dashboard pin :::image type="content" source="media/app-map/image-10.png" alt-text="A screenshot displaying the dashboard pin button."::: is located next to the title bar of the Application Map blade. This button pins the map to a dashboard, along with the filters applied to it. This action can be useful for filters that are frequently interesting. As an example, the user can pin a map with "Error connector" filter applied to it, and the dashboard view will only show nodes that have errors in their HTTP calls.

+#### Filter usage scenarios

+There are many filter combinations. Here are some suggestions that apply to most maps and may be useful to pin on a dashboard:

+- Show only errors that appear significant by using the "Error connector" filter along with "Intelligent view":\

+ :::image type="content" source="media/app-map/image-11.png" alt-text="A screenshot displaying the Last 24 hours and Highlighted Errors filters.":::

+ :::image type="content" source="media/app-map/image-12.png" alt-text="A screenshot displaying the Intelligent Overview toggle.":::

+- Hide low-traffic connectors with no errors to quickly focus on issues that have higher impact:

+ :::image type="content" source="media/app-map/image-13.png" alt-text="A screenshot displaying the Last 24 hours, calls greater than 876, and highlihgted errors filters.":::

+

+- Show high-traffic connectors with high average duration to focus on potential performance issues:

+ :::image type="content" source="media/app-map/image-14.png" alt-text="A screenshot displaying the Last 24 hours, calls greater than 3057, and average time greater than 467 filters.":::

+

+- Show a specific portion of a distributed application (requires suitable roleName naming convention):

+ :::image type="content" source="media/app-map/image-15.png" alt-text="A screenshot displaying the Last 24 hours and Connected Contains West filters.":::

+- Hide a dependency type that is too noisy:

+ :::image type="content" source="media/app-map/image-16.png" alt-text="A screenshot displaying the Last 24 hours and Nodes Contains Storage Accounts filters.":::

+- Show only connectors that have higher error rates than a specific value

+ :::image type="content" source="media/app-map/image-17.png" alt-text="A screenshot displaying the Last 24 hours and Errors greater than 0.01 filters.":::

+* If this dependency has been failing for a while, the model might believe it's a regular state, and not highlight the edge for you. It focuses on problem-solving in RT.

+> Azure Functions requires separate settings to enable SQL text collection. For more information, see [Enable SQL query collection](../../azure-functions/configure-monitoring.md#enable-sql-query-collection).

+ Title: Monitor with multistep web tests - Application Insights

+description: Set up multistep web tests to monitor your web applications with Application Insights.

+# Multistep web tests

+You can monitor a recorded sequence of URLs and interactions with a website via multistep web tests. This article walks you through the process of creating a multistep web test with Visual Studio Enterprise.

+> [Multistep web tests have been deprecated](https://azure.microsoft.com/updates/retirement-notice-transition-to-custom-availability-tests-in-application-insights/). We recommend using [TrackAvailability()](/dotnet/api/microsoft.applicationinsights.telemetryclient.trackavailability) to submit [custom availability tests](availability-azure-functions.md) instead of multistep web tests. With `TrackAvailability()` and custom availability tests, you can run tests on any compute you want and use C# to easily author new tests.

+Multistep web tests are categorized as classic tests and can be found under **Add Classic Test** on the **Availability** pane.

+> [!NOTE]

+> Multistep web tests *aren't supported* in the [Azure Government](../../azure-government/index.yml) cloud.

+## Multistep web test alternative

+Multistep web tests depend on Visual Studio web test files. It was [announced](https://devblogs.microsoft.com/devops/cloud-based-load-testing-service-eol/) that Visual Studio 2019 will be the last version with web test functionality. Although no new features will be added, web test functionality in Visual Studio 2019 is still currently supported and will continue to be supported during the support lifecycle of the product.

+We recommend using [TrackAvailability](/dotnet/api/microsoft.applicationinsights.telemetryclient.trackavailability) to submit [custom availability tests](./availability-azure-functions.md) instead of multistep web tests. This option is the long-term supported solution for multi-request or authentication test scenarios. With `TrackAvailability()` and custom availability tests, you can run tests on any compute you want and use C# to easily author new tests.

+## Prerequisites

+You need:

+To locate the testing tools prerequisite, select **Visual Studio Installer** > **Individual components** > **Debugging and testing** > **Web performance and load testing tools**.

+

+> Multistep web tests have extra costs associated with them. To learn more, see the [official pricing guide](https://azure.microsoft.com/pricing/details/application-insights/).

+## Record a multistep web test

+> We no longer recommend using the multistep recorder. The recorder was developed for static HTML pages with basic interactions. It doesn't provide a functional experience for modern webpages.

+For guidance on how to create Visual Studio web tests, see the [official Visual Studio 2019 documentation](/visualstudio/test/how-to-create-a-web-service-test).

+1. In the Application Insights portal on the **Availability** pane, select **Add Classic test**. Then select **Multi-step** as the **SKU**.

+1. Upload your multistep web test.

+1. Set the test locations, frequency, and alert parameters.

+1. Select **Create**.

+### Frequency and location

+|Setting| Description |

+|-|-|

+|Test frequency| Sets how often the test is run from each test location. With a default frequency of five minutes and five test locations, your site is tested on average every minute.|

+|Test locations| The places from where our servers send web requests to your URL. *Our minimum number of recommended test locations is five* to ensure that you can distinguish problems in your website from network issues. You can select up to 16 locations.

+|Setting| Description|

+|-||

+| Test timeout |Decrease this value to be alerted about slow responses. The test is counted as a failure if the responses from your site haven't been received within this period. If you selected **Parse dependent requests**, all the images, style files, scripts, and other dependent resources must have been received within this period.|

+| HTTP response | The returned status code that's counted as a success. The code 200 indicates that a normal webpage has been returned.|

+| Content match | A string, like "Welcome!" We test that an exact case-sensitive match occurs in every response. It must be a plain string, without wildcards. Don't forget that if your page content changes, you might have to update it. *Only English characters are supported with content match.* |

+|Setting| Description|

+|-||

+|Near real time (preview) | We recommend using near real time alerts. Configuring this type of alert is done after your availability test is created. |

+|Alert location threshold|We recommend a minimum of 3/5 locations. The optimal relationship between alert location threshold and the number of test locations is **alert location threshold** = **number of test locations - 2**, with a minimum of five test locations.|

+Follow these configuration steps.

+### Plug time and random numbers into your test

+Suppose you're testing a tool that gets time-dependent data, such as stock prices, from an external feed. When you record your web test, you have to use specific times, but you set them as parameters of the test, `StartTime` and `EndTime`.

+

+When you run the test, you want `EndTime` always to be the present time. `StartTime` should be 15 minutes prior.

+The Web Test Date Time Plug-in provides the way to handle parameter times.

+1. Add a Web Test Plug-in for each variable parameter value you want. On the web test toolbar, select **Add Web Test Plug-in**.

+ 

+ In this example, we use two instances of the Date Time Plug-in. One instance is for "15 minutes ago" and another is for "now."

+1. Open the properties of each plug-in. Give it a name and set it to use the current time. For one of them, set **Add Minutes = -15**.

+ 

+1. In the web test parameters, use `{{plug-in name}}` to reference a plug-in name.

+ 

+Now, upload your test to the portal. It will use dynamic values on every run of the test.

+### Consider sign-in

+In all cases, create an account in your application only for testing. If possible, restrict the permissions of this test account so that there's no possibility of the web tests affecting real users.

+#### Simple username and password

+#### SAML authentication

+|-||

+| Audience URI | The audience URI for the SAML token. This URI is for the Access Control service, including the Access Control namespace and host name. |

+| Certificate password | The password for the client certificate, which will grant access to the embedded private key. |

+| Client certificate | The client certificate value with private key in Base64-encoded format. |

+| Name identifier | The name identifier for the token. |

+| Not after | The timespan for which the token will be valid. The default is 5 minutes. |

+| Not before | The timespan for which a token created in the past will be valid (to address time skews). The default is (negative) 5 minutes. |

+| Target context parameter name | The context parameter that will receive the generated assertion. |

+#### Client secret

+If your app has a sign-in route that involves a client secret, use that route. Azure Active Directory (Azure AD) is an example of a service that provides a client secret sign-in. In Azure AD, the client secret is the app key.

+Here's a sample web test of an Azure web app using an app key.

+

+1. Get a token from Azure AD by using the client secret (the app key).

+1. Extract a bearer token from the response.

+1. Call the API by using the bearer token in the authorization header.

+1. Make sure that the web test is an actual client. That is, that it has its own app in Azure AD. Use its client ID and app key. Your service under test also has its own app in Azure AD. The app ID URI of this app is reflected in the web test in the resource field.

+### Open authentication

+An example of open authentication is the act of signing in with your Microsoft or Google account. Many apps that use OAuth provide the client secret alternative, so your first tactic should be to investigate that possibility.

+If your test must sign in by using OAuth, the general approach is:

+1. Use a tool such as Fiddler to examine the traffic between your web browser, the authentication site, and your app.

+1. Perform two or more sign-ins using different machines or browsers, or at long intervals (to allow tokens to expire).

+1. By comparing different sessions, identify the token passed back from the authenticating site that's then passed to your app server after sign-in.

+1. Record a web test by using Visual Studio.

+1. Parameterize the tokens. Set the parameter when the token is returned from the authenticator, and use it in the query to the site. (Visual Studio attempts to parameterize the test, but doesn't correctly parameterize the tokens.)

+For troubleshooting help, see the dedicated [troubleshooting](troubleshoot-availability.md) article.

+* [Availability alerts](availability-alerts.md)

+* [URL ping web tests](monitor-web-app-availability.md)

+ Title: Monitor performance on Azure VMs - Application Insights

+description: Application performance monitoring for Azure Virtual Machines and Azure Virtual Machine Scale Sets. Chart load and response time, dependency information, and set alerts on performance.

+# Deploy Application Insights Agent on virtual machines and virtual machine scale sets

+Enabling monitoring for your .NET or Java-based web applications running on [Azure Virtual Machines](https://azure.microsoft.com/services/virtual-machines/) and [Azure Virtual Machine Scale Sets](../../virtual-machine-scale-sets/index.yml) is now easier than ever. Get all the benefits of using Application Insights without modifying your code.

+This article walks you through enabling Application Insights monitoring by using Application Insights Agent. It also provides preliminary guidance for automating the process for large-scale deployments.

+Java-based applications running on Azure Virtual Machines and Azure Virtual Machine Scale Sets are monitored with the [Application Insights Java 3.0 agent](./java-in-process-agent.md), which is generally available.

+> Application Insights Agent for ASP.NET and ASP.NET Core applications running on Azure Virtual Machines and Azure Virtual Machine Scale Sets is currently in public preview. For monitoring your ASP.NET applications running on-premises, use [Application Insights Agent for on-premises servers](./status-monitor-v2-overview.md), which is generally available and fully supported.

+>

+> The preview version for Azure Virtual Machines and Azure Virtual Machine Scale Sets is provided without a service-level agreement. We don't recommend it for production workloads. Some features might not be supported, and some might have constrained capabilities.

+>

+Auto-instrumentation is easy to enable. Advanced configuration isn't required.

+> Auto-instrumentation is available for ASP.NET, ASP.NET Core IIS-hosted applications, and Java. Use an SDK to instrument Node.js and Python applications hosted on Azure Virtual Machines and Azure Virtual Machine Scale Sets.

+The Application Insights Agent autocollects the same dependency signals out-of-the-box as the SDK. To learn more, see [Dependency autocollection](./auto-collect-dependencies.md#net).

+### [.NET Core/.NET](#tab/core)

+The Application Insights Agent autocollects the same dependency signals out-of-the-box as the SDK. To learn more, see [Dependency autocollection](./auto-collect-dependencies.md#net).

+We recommend [Application Insights Java 3.0 agent](./java-in-process-agent.md) for Java. The most popular libraries, frameworks, logs, and dependencies are [autocollected](./java-in-process-agent.md#autocollected-requests) along with many [other configurations](./java-standalone-config.md).

+## Manage Application Insights Agent for .NET applications on virtual machines by using PowerShell

+Before you install Application Insights Agent, you'll need a connection string. [Create a new Application Insights resource](./create-new-resource.md) or copy the connection string from an existing Application Insights resource.

+> If you're new to PowerShell, see the [Get Started Guide](/powershell/azure/get-started-azureps).

+Install or update Application Insights Agent as an extension for virtual machines:

+> You can install or update Application Insights Agent as an extension across multiple virtual machines at scale by using a PowerShell loop.

+Uninstall Application Insights Agent extension from a virtual machine:

+Query Application Insights Agent extension status for a virtual machine:

+Get a list of installed extensions for a virtual machine:

+You can also view installed extensions in the [Azure Virtual Machine section](../../virtual-machines/extensions/overview.md) of the Azure portal.

+> Verify installation by selecting **Live Metrics Stream** within the Application Insights resource associated with the connection string you used to deploy the Application Insights Agent extension. If you're sending data from multiple virtual machines, select the target virtual machines under **Server Name**. It might take up to a minute for data to begin flowing.

+## Manage Application Insights Agent for .NET applications on virtual machine scale sets by using PowerShell

+Install or update Application Insights Agent as an extension for a virtual machine scale set:

+# Note: Depending on your update policy, you might need to run Update-AzVmssInstance for each instance.

+Uninstall the application monitoring extension from virtual machine scale sets:

+# Note: Depending on your update policy, you might need to run Update-AzVmssInstance for each instance.

+Query the application monitoring extension status for virtual machine scale sets:

+Get a list of installed extensions for virtual machine scale sets:

+Find troubleshooting tips for the Application Insights Monitoring Agent extension for .NET applications running on Azure virtual machines and virtual machine scale sets.

+> The following steps don't apply to Node.js and Python applications, which require SDK instrumentation.

+- Updated Application Insights .NET/.NET Core SDK to 2.20.1 - red field

+- Enabled SQL query collection

+- Enabled support for Azure Active Directory authentication

+Updated Application Insights .NET/.NET Core SDK to 2.18.1 - red field

+Added ASP.NET Core auto-instrumentation feature

+* Learn how to [deploy an application to a virtual machine scale set](../../virtual-machine-scale-sets/virtual-machine-scale-sets-deploy-app.md).

+* [Set up availability web tests](monitor-web-app-availability.md) to be alerted if your endpoint is down.

+No. There's no impact to [Live Metrics](live-stream.md#live-metrics-monitor-and-diagnose-with-1-second-latency) or other monitoring experiences.

+- Build a [Workbook](../visualize/workbooks-overview.md) or [export to Power BI](../logs/log-powerbi.md#integrate-queries) to create custom visualizations of click data.

+# Live Metrics: Monitor and diagnose with 1-second latency

+Monitor your live, in-production web application by using Live Metrics (also known as QuickPulse) from [Application Insights](./app-insights-overview.md). You can select and filter metrics and performance counters to watch in real time, without any disturbance to your service. You can also inspect stack traces from sample failed requests and exceptions. Together with [Profiler](./profiler.md) and [Snapshot Debugger](./snapshot-debugger.md), Live Metrics provides a powerful and noninvasive diagnostic tool for your live website.

+* Validate a fix while it's released by watching performance and failure counts.

+* Watch the effect of test loads and diagnose issues live.

+* Focus on particular test sessions or filter out known issues by selecting and filtering the metrics you want to watch.

+* Easily identify a server that's having issues and filter all the KPI/live feed to just that server.

+

+Live Metrics is currently supported for ASP.NET, ASP.NET Core, Azure Functions, Java, and Node.js apps.

+> The number of monitored server instances displayed by Live Metrics might be lower than the actual number of instances allocated for the application. This mismatch is because many modern web servers will unload applications that don't receive requests over a period of time to conserve resources. Because Live Metrics only counts servers that are currently running the application, servers that have already unloaded the process won't be included in that total.

+> [!IMPORTANT]

+> Monitoring ASP.NET Core [LTS](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) applications requires Application Insights version 2.8.0 or above. To enable Application Insights, ensure that it's activated in the Azure portal and that the Application Insights NuGet package is included. Without the NuGet package, some telemetry is sent to Application Insights, but that telemetry won't show in Live Metrics.

+1. Follow language-specific guidelines to enable Live Metrics:

+ * [ASP.NET](./asp-net.md): Live Metrics is enabled by default.

+ * [ASP.NET Core](./asp-net-core.md): Live Metrics is enabled by default.

+ * [.NET/.NET Core Console/Worker](./worker-service.md): Live Metrics is enabled by default.

+ * [.NET Applications: Enable using code](#enable-live-metrics-by-using-code-for-any-net-application).

+ * [Java](./java-in-process-agent.md): Live Metrics is enabled by default.

+1. In the [Azure portal](https://portal.azure.com), open the Application Insights resource for your app. Then open Live Stream.

+1. [Secure the control channel](#secure-the-control-channel) if you might use sensitive data like customer names in your filters.

+### Enable Live Metrics by using code for any .NET application

+> Live Metrics is enabled by default when you onboard it by using the recommended instructions for .NET applications.

+To manually set up Live Metrics:

+1. Install the NuGet package [Microsoft.ApplicationInsights.PerfCounterCollector](https://www.nuget.org/packages/Microsoft.ApplicationInsights.PerfCounterCollector).

+1. The following sample console app code shows setting up Live Metrics:

+ ```csharp

+ using Microsoft.ApplicationInsights;

+ using Microsoft.ApplicationInsights.Extensibility;

+ using Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.QuickPulse;

+ using System;

+ using System.Threading.Tasks;

+

+ namespace LiveMetricsDemo

+ class Program

+ static void Main(string[] args)

+ // Create a TelemetryConfiguration instance.

+ TelemetryConfiguration config = TelemetryConfiguration.CreateDefault();

+ config.InstrumentationKey = "INSTRUMENTATION-KEY-HERE";

+ QuickPulseTelemetryProcessor quickPulseProcessor = null;

+ config.DefaultTelemetrySink.TelemetryProcessorChainBuilder

+ .Use((next) =>

+ {

+ quickPulseProcessor = new QuickPulseTelemetryProcessor(next);

+ return quickPulseProcessor;

+ })

+ .Build();

+

+ var quickPulseModule = new QuickPulseTelemetryModule();

+

+ // Secure the control channel.

+ // This is optional, but recommended.

+ quickPulseModule.AuthenticationApiKey = "YOUR-API-KEY-HERE";

+ quickPulseModule.Initialize(config);

+ quickPulseModule.RegisterTelemetryProcessor(quickPulseProcessor);

+

+ // Create a TelemetryClient instance. It is important

+ // to use the same TelemetryConfiguration here as the one

+ // used to set up Live Metrics.

+ TelemetryClient client = new TelemetryClient(config);

+

+ // This sample runs indefinitely. Replace with actual application logic.

+ while (true)

+ {

+ // Send dependency and request telemetry.

+ // These will be shown in Live Metrics.

+ // CPU/Memory Performance counter is also shown

+ // automatically without any additional steps.

+ client.TrackDependency("My dependency", "target", "http://sample",

+ DateTimeOffset.Now, TimeSpan.FromMilliseconds(300), true);

+ client.TrackRequest("My Request", DateTimeOffset.Now,

+ TimeSpan.FromMilliseconds(230), "200", true);

+ Task.Delay(1000).Wait();

+ }

+ ```

+The preceding sample is for a console app, but the same code can be used in any .NET applications. If any other telemetry modules are enabled to autocollect telemetry, it's important to ensure that the same configuration used for initializing those modules is used for the Live Metrics module.

+## How does Live Metrics differ from metrics explorer and Log Analytics?

+| Capabilities |Live Stream | Metrics explorer and Log Analytics |

+|Latency|Data displayed within one second.|Aggregated over minutes.|

+|No retention|Data persists while it's on the chart and is then discarded.|[Data retained for 90 days.](./data-retention-privacy.md#how-long-is-the-data-kept)|

+|On demand|Data is only streamed while the Live Metrics pane is open. |Data is sent whenever the SDK is installed and enabled.|

+|Free|There's no charge for Live Stream data.|Subject to [pricing](../logs/cost-logs.md#application-insights-billing).

+|Sampling|All selected metrics and counters are transmitted. Failures and stack traces are sampled. |Events can be [sampled](./api-filtering-sampling.md).|

+|Control channel|Filter control signals are sent to the SDK. We recommend you secure this channel.|Communication is one way, to the portal.|

+These capabilities are available with ASP.NET, ASP.NET Core, and Azure Functions (v2).

+You can monitor custom KPI live by applying arbitrary filters on any Application Insights telemetry from the portal. Select the filter control that shows when you mouse-over any of the charts. The following chart plots a custom **Request** count KPI with filters on **URL** and **Duration** attributes. Validate your filters with the stream preview section that shows a live feed of telemetry that matches the criteria you've specified at any point in time.

+

+You can monitor a value different from **Count**. The options depend on the type of stream, which could be any Application Insights telemetry like requests, dependencies, exceptions, traces, events, or metrics. It can also be your own [custom measurement](./api-custom-events-metrics.md#properties).

+

+Along with Application Insights telemetry, you can also monitor any Windows performance counter. Select it from the stream options and provide the name of the performance counter.

+Live Metrics are aggregated at two points: locally on each server and then across all servers. You can change the default at either one by selecting other options in the respective dropdown lists.

+## Sample telemetry: Custom live diagnostic events

+

+As with metrics, you can specify any arbitrary criteria to any of the Application Insights telemetry types. In this example, we're selecting specific request failures and events.

+

+> Currently, for exception message-based criteria, use the outermost exception message. In the preceding example, to filter out the benign exception with an inner exception message (follows the "<--" delimiter) "The client disconnected," use a message not-contains "Error reading request content" criteria.

+To see the details of an item in the live feed, select it. You can pause the feed either by selecting **Pause** or by scrolling down and selecting an item. Live feed resumes after you scroll back to the top, or when you select the counter of items collected while it was paused.

+

+If you want to monitor a particular server role instance, you can filter by server. To filter, select the server name under **Servers**.

+

+Live Metrics custom filters allow you to control which of your application's telemetry is streamed to the Live Metrics view in the Azure portal. The filters criteria is sent to the apps that are instrumented with the Application Insights SDK. The filter value could potentially contain sensitive information, such as the customer ID. To keep this value secured and prevent potential disclosure to unauthorized applications, you have two options:

+- **Recommended:** Secure the Live Metrics channel by using [Azure Active Directory (Azure AD) authentication](./azure-ad-authentication.md#configuring-and-enabling-azure-ad-based-authentication).

+- **Legacy (no longer recommended):** Set up an authenticated channel by configuring a secret API key as explained in the "Legacy option" section.

+> On September 30, 2025, API keys used to stream Live Metrics telemetry into Application Insights will be retired. After that date, applications that use API keys won't be able to send Live Metrics data to your Application Insights resource. Authenticated telemetry ingestion for Live Metrics streaming to Application Insights will need to be done with [Azure AD authentication for Application Insights](./azure-ad-authentication.md).

+It's possible to try custom filters without having to set up an authenticated channel. Select any of the filter icons and authorize the connected servers. If you choose this option, you'll have to authorize the connected servers once every new session or whenever a new server comes online.

+> We strongly discourage the use of unsecured channels and will disable this option six months after you start using it. The **Authorize connected servers** dialog displays the date after which this option will be disabled.

+### Legacy option: Create an API key

+1. Select the **API Access** tab and then select **Create API key**.

+ 

+1. Select the **Authenticate SDK control channel** checkbox and then select **Generate key**.

+ 

+### Add an API key to configuration

+You can add an API key to configuration for ASP.NET, ASP.NET Core, WorkerService, and Azure Functions apps.

+In the *applicationinsights.config* file, add `AuthenticationApiKey` to `QuickPulseTelemetryModule`:

+For [ASP.NET Core](./asp-net-core.md) applications, follow these instructions.

+Modify `ConfigureServices` of your *Startup.cs* file as shown.

+Add the following namespace:

+Then modify the `ConfigureServices` method:

+ // Existing code which includes services.AddApplicationInsightsTelemetry() to enable Application Insights.

+For more information on how to configure ASP.NET Core applications, see [Configuring telemetry modules in ASP.NET Core](./asp-net-core.md#configuring-or-removing-default-telemetrymodules).

+For [WorkerService](./worker-service.md) applications, follow these instructions.

+Add the following namespace:

+Next, add the following line before the call `services.AddApplicationInsightsTelemetryWorkerService`:

+For more information on how to configure WorkerService applications, see [Configuring telemetry modules in WorkerServices](./worker-service.md#configure-or-remove-default-telemetry-modules).

+#### Azure Functions apps

+For Azure Functions apps (v2), you can secure the channel with an API key by using an environment variable.

+Create an API key from within your Application Insights resource and go to **Settings** > **Configuration** for your Azure Functions app. Select **New application setting**, enter a name of `APPINSIGHTS_QUICKPULSEAUTHAPIKEY`, and enter a value that corresponds to your API key.

+| Language | Basic metrics | Performance metrics | Custom filtering | Sample telemetry | CPU split by process |

+| .NET Core (target=.NET Core) | Supported ([LTS](https://dotnet.microsoft.com/platform/support/policy/dotnet-core)) | Supported* | Supported ([LTS](https://dotnet.microsoft.com/platform/support/policy/dotnet-core)) | Supported ([LTS](https://dotnet.microsoft.com/platform/support/policy/dotnet-core)) | **Not supported** |

+| Azure Functions v2 | Supported | Supported | Supported | Supported | **Not supported** |

+| Java | Supported (V2.0.0+) | Supported (V2.0.0+) | **Not supported** | Supported (V3.2.0+) | **Not supported** |

+| Node.js | Supported (V1.3.0+) | Supported (V1.3.0+) | **Not supported** | Supported (V1.3.0+) | **Not supported** |

+ PerfCounters support varies slightly across versions of .NET Core that don't target the .NET Framework:

+- PerfCounters metrics are supported when running in Azure App Service for Windows (ASP.NET Core SDK version 2.4.1 or higher).

+- PerfCounters are supported when the app is running in *any* Windows machines, like VM, Azure Cloud Service, or on-premises (ASP.NET Core SDK version 2.7.1 or higher), but only for apps that target .NET Core [LTS](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) or higher.

+- PerfCounters are supported when the app is running *anywhere* (such as Linux, Windows, app service for Linux, or containers) in the latest versions, but only for apps that target .NET Core [LTS](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) or higher.

+Live Metrics uses different IP addresses than other Application Insights telemetry. Make sure [those IP addresses](./ip-addresses.md) are open in your firewall. Also check that [outgoing ports for Live Metrics](./ip-addresses.md#outgoing-ports) are open in the firewall of your servers.

+As described in the [Azure TLS 1.2 migration announcement](https://azure.microsoft.com/updates/azuretls12/), Live Metrics now only supports TLS 1.2. If you're using an older version of TLS, Live Metrics won't display any data. For applications based on .NET Framework 4.5.1, see [Enable Transport Layer Security (TLS) 1.2 on clients - Configuration Manager](/mem/configmgr/core/plan-design/security/enable-tls-1-2-client#bkmk_net) to support the newer TLS version.

+1. Verify that you're using the latest version of the NuGet package [Microsoft.ApplicationInsights.PerfCounterCollector](https://www.nuget.org/packages/Microsoft.ApplicationInsights.PerfCounterCollector).

+1. Edit the `ApplicationInsights.config` file:

+ * Verify that the connection string points to the Application Insights resource you're using.

+ * Locate the `QuickPulseTelemetryModule` configuration option. If it isn't there, add it.

+ * Locate the `QuickPulseTelemetryProcessor` configuration option. If it isn't there, add it.

+

+ ```xml

+ <TelemetryModules>

+ <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.

+ QuickPulse.QuickPulseTelemetryModule, Microsoft.AI.PerfCounterCollector"/>

+ </TelemetryModules>

+

+ <TelemetryProcessors>

+ <Add Type="Microsoft.ApplicationInsights.Extensibility.PerfCounterCollector.

+ QuickPulse.QuickPulseTelemetryProcessor, Microsoft.AI.PerfCounterCollector"/>

+ <TelemetryProcessors>

+ ````

+1. Restart the application.

+* [Monitor usage with Application Insights](./usage-overview.md)

+* [Use Diagnostic Search](./diagnostic-search.md)

+* [Snapshot Debugger](./snapshot-debugger.md)

+* [Send Azure Diagnostics to Application Insights](../agents/diagnostics-extension-to-application-insights.md)

+ASP.NET Core applications may be configured in code or through the `appsettings.json` file. For more information, see [Configuration in ASP.NET Core](/aspnet/core/fundamentals/configuration).

+ Title: 'Design your Application Insights deployment: One vs. many resources?'

+# How many Application Insights resources should I deploy?

+To avoid confusion, send the telemetry from different development stages to separate Application Insights resources with separate instrumentation keys.

+To make it easier to change the instrumentation key as a version moves from one stage to another, it can be useful to [set the instrumentation key dynamically in code](#dynamic-instrumentation-key) instead of in the configuration file.

+If your system is an instance of Azure Cloud Services, there's [another method of setting separate instrumentation keys](../../azure-monitor/app/azure-web-apps-net-core.md).

+When you set up Application Insights monitoring for your web app, you create an Application Insights resource in Azure. You open this resource in the Azure portal to see and analyze the telemetry collected from your app. The resource is identified by an instrumentation key. When you install the Application Insights package to monitor your app, you configure it with the instrumentation key so that it knows where to send the telemetry.

+Each Application Insights resource comes with metrics that are available out of the box. If separate components report to the same Application Insights resource, it might not make sense to alert on these metrics.

+Use a single Application Insights resource:

+- If it makes sense to aggregate key performance indicators, such as response durations or failure rates in a dashboard, across all of them by default. You can choose to segment by role name in the metrics explorer.

+- If there's no need to manage Azure role-based access control differently between the application components.

+> If you want to consolidate multiple Application Insights resources, you can point your existing application components to a new, consolidated Application Insights resource. The telemetry stored in your old resource won't be transferred to the new resource. Only delete the old resource when you have enough telemetry in the new resource for business continuity.

+### Other considerations

+Be aware that:

+- You might need to add custom code to ensure that meaningful values are set into the [Cloud_RoleName](./app-map.md?tabs=net#set-or-override-cloud-role-name) attribute. Without meaningful values set for this attribute, none of the portal experiences will work.

+- For Azure Service Fabric applications and classic cloud services, the SDK automatically reads from the Azure Role Environment and sets these services. For all other types of apps, you'll likely need to set this explicitly.

+- Live Metrics doesn't support splitting by role name.

+## <a name="dynamic-instrumentation-key"></a> Dynamic instrumentation key

+To make it easier to change the instrumentation key as the code moves between stages of production, reference the key dynamically in code instead of using a hardcoded or static value.

+Set the key in an initialization method, such as `global.aspx.cs`, in an ASP.NET service:

+In this example, the instrumentation keys for the different resources are placed in different versions of the web configuration file. Swapping the web configuration file, which you can do as part of the release script, will swap the target resource.

+### Webpages

+The instrumentation key is also used in your app's webpages, in the [script that you got from the quickstart pane](../../azure-monitor/app/javascript.md). Instead of coding it literally into the script, generate it from the server state. For example, in an ASP.NET app:

+// Standard Application Insights webpage script:

+## Create more Application Insights resources

+To create an Applications Insights resource, see [Create an Application Insights resource](./create-new-resource.md).

+### Get the instrumentation key

+## Filter on the build number

+You can set the **Application Version** property so that you can filter [search](../../azure-monitor/app/diagnostic-search.md) and [metric explorer](../../azure-monitor/essentials/metrics-charts.md) results.

+There are several different methods of setting the **Application Version** property.

+* Wrap that line in a [telemetry initializer](../../azure-monitor/app/api-custom-events-metrics.md#defaults) to ensure that all `TelemetryClient` instances are set consistently.

+* ASP.NET: Set the version in `BuildInfo.config`. The web module will pick up the version from the `BuildLabel` node. Include this file in your project and remember to set the **Copy Always** property in Solution Explorer.

+* ASP.NET: Generate `BuildInfo.config` automatically in the Microsoft Build Engine. Add a few lines to your `.csproj` file:

+ This step generates a file called *yourProjectName*`.BuildInfo.config`. The Publish process renames it to `BuildInfo.config`.

+ The build label contains a placeholder (*AutoGen_...*) when you build with Visual Studio. But when built with the Microsoft Build Engine, it's populated with the correct version number.

+ To allow the Microsoft Build Engine to generate version numbers, set the version like `1.0.*` in `AssemblyReference.cs`.

+When the Application Insights web module has the build information, it automatically adds **Application Version** as a property to every item of telemetry. For this reason, you can filter by version when you perform [diagnostic searches](../../azure-monitor/app/diagnostic-search.md) or when you [explore metrics](../../azure-monitor/essentials/metrics-charts.md).

+The build version number is generated only by the Microsoft Build Engine, not by the developer build from Visual Studio.

+ Title: Application Insights funnels

+description: Learn how you can use funnels to discover how customers are interacting with your application.

+# Discover how customers are using your application with Application Insights funnels

+Understanding the customer experience is of great importance to your business. If your application involves multiple stages, you need to know if customers are progressing through the entire process or ending the process at some point. The progression through a series of steps in a web application is known as a *funnel*. You can use Application Insights funnels to gain insights into your users and monitor step-by-step conversion rates.

+Before you create your funnel, decide on the question you want to answer. For example, you might want to know how many users view the home page, view a customer profile, and create a ticket.

+1. On the **Funnels** tab, select **Edit**.

+1. Choose your **Top Step**.

+ :::image type="content" source="./media/usage-funnels/funnel.png" alt-text="Screenshot that shows the Funnel tab and selecting steps on the Edit tab." lightbox="./media/usage-funnels/funnel.png":::

+1. To apply filters to the step, select **Add filters**. This option appears after you choose an item for the top step.

+1. Then choose your **Second Step** and so on.

+ > [!NOTE]

+ > Funnels are limited to a maximum of six steps.

+1. Select the **View** tab to see your funnel results.

+ :::image type="content" source="./media/usage-funnels/funnel-2.png" alt-text="Screenshot that shows the Funnels View tab that shows results from the top and second steps." lightbox="./media/usage-funnels/funnel-2.png":::

+1. To save your funnel to view at another time, select **Save** at the top. Use **Open** to open your saved funnels.

+Funnels have the following features:

+- If your app is sampled, you'll see a sampling banner. Selecting the banner opens a context pane that explains how to turn off sampling.

+- Select a step to see more details on the right.

+- The historical conversion graph shows the conversion rates over the last 90 days.

+- Understand your users better by accessing the users tool. You can use filters in each step.

+ * [Users, sessions, and events](usage-segmentation.md)

+ * [Export to Power BI](../logs/log-powerbi.md) if you've [migrated to a workspace-based resource](convert-classic-resource.md)

+Autoscale settings help ensure that you have the right amount of resources running to handle the fluctuating load of your application. You can configure autoscale settings to be triggered based on metrics that indicate load or performance, or triggered at a scheduled date and time.

+Azure autoscale supports many resource types. For more information about supported resources, see [autoscale supported resources](./autoscale-overview.md#supported-services-for-autoscale).

+This article describes some of the common patterns you can use to scale your resources in Azure.

+## Prerequisites

+This article assumes that you're familiar with auto scale. [Get started here to scale your resource](./autoscale-get-started.md).

+## Scale based on metrics

+Scale your resource based on metrics produce by the resource itself or any other resource.

+For example:

+* Scale your Virtual Machine Scale Set based on the CPU usage of the virtual machine.

+* Ensure a minimum number of instances.

+* Set a maximum limit on the number of instances.

+The image below shows a default scale condition for a Virtual Machine Scale Set

+ * The **Scale rule** tab shows that the metric source is the scale set itself and the metric used is Percentage CPU.

+ * The minimum number of instances running is set to 2.

+ * The maximum number of instances is set to 10.

+ * When the scale set starts, the default number of instances is 3.

+## Scale based on another resource's metric

+Scale a resource based on the metrics from a different resource.

+The image below shows a scale rule that is scaling a Virtual Machine Scale Set based on the number of allocated ports on a load balancer.

+## Scale differently on weekends

+You can scale your resources differently on different days of the week..

+For example, you have a web app and want to:

+- Set a minimum of 3 instances on weekdays.

+- Scale down to 1 instance on weekends when there's less traffic.

+## Scale differently during specific events

+You can set your scale rules and instance limits differently for specific events.

+For example:

+- Set a minimum of 3 instances by default

+- For the week of Back Friday, set the minimum number of instances to 10 to handle the anticipated traffic.

+## Scale based on custom metrics

+Scale by custom metrics generated by your application.

+For example, you have a web front end and an API tier that communicates with the backend, and you want to scale the API tier based on custom events in the front end.

+Next steps

+Learn more about autoscale by referring to the following articles :

+* [Azure Monitor autoscale common metrics](./autoscale-common-metrics.md)

+* [Azure Monitor autoscale custom metrics](./autoscale-custom-metric.md)

+* [Autoscale with multiple profiles](./autoscale-multiprofile.md)

+* [Flapping in Autoscale](./autoscale-custom-metric.md)

+* [Use autoscale actions to send email and webhook alert notifications](./autoscale-webhook-email.md)

+* [Autoscale REST API](/rest/api/monitor/autoscalesettings)

+* [Tutorial: Automatically scale a Virtual Machine Scale Set with an Azure template](../../virtual-machine-scale-sets/tutorial-autoscale-template.md)

+* [Tutorial: Automatically scale a Virtual Machine Scale Set with the Azure CLI](../../virtual-machine-scale-sets/tutorial-autoscale-cli.md)

+* [Tutorial: Automatically scale a Virtual Machine Scale Set with an Azure template](../../virtual-machine-scale-sets/tutorial-autoscale-powershell.md)

+| Service | Schema & Documentation |

+||--|

+| Azure Virtual machines scale sets | [Overview of autoscale with Azure Virtual Machine Scale Sets](../../virtual-machine-scale-sets/virtual-machine-scale-sets-autoscale-overview.md) |

+| Web apps | [Scaling Web Apps](autoscale-get-started.md) |

+| Azure API Management service | [Automatically scale an Azure API Management instance](../../api-management/api-management-howto-autoscale.md) |

+| Azure Data Explorer Clusters | [Manage Azure Data Explorer clusters scaling to accommodate changing demand](/azure/data-explorer/manage-cluster-horizontal-scaling) |

+| Azure Stream Analytics | [Autoscale streaming units (Preview)](../../stream-analytics/stream-analytics-autoscale.md) |

+| Azure Machine Learning Workspace | [Autoscale an online endpoint](../../machine-learning/how-to-autoscale-endpoints.md) |

+| Azure Spring Apps | [Set up autoscale for applications](../../spring-apps/how-to-setup-autoscale.md) |

+| Media Services | [Autoscaling in Media Services](/azure/media-services/latest/release-notes#autoscaling) |

+| Service Bus | [Automatically update messaging units of an Azure Service Bus namespace](../../service-bus-messaging/automate-update-messaging-units.md) |

+| Logic Apps - Integration Service Environment(ISE) | [Add ISE capacity](../../logic-apps/ise-manage-integration-service-environment.md#add-ise-capacity) |

+* [Tutorial: Automatically scale a Virtual Machine Scale Set with an Azure template](../../virtual-machine-scale-sets/tutorial-autoscale-template.md)

+* [Tutorial: Automatically scale a Virtual Machine Scale Set with the Azure CLI](../../virtual-machine-scale-sets/tutorial-autoscale-cli.md)

+* [Tutorial: Automatically scale a Virtual Machine Scale Set with Azure PowerShell](../../virtual-machine-scale-sets/tutorial-autoscale-powershell.md)

+* [Autoscale CLI reference](/cli/azure/monitor/autoscale)

+* [ARM template resource definition](/azure/templates/microsoft.insights/autoscalesettings)

+* [PowerShell Az.Monitor Reference](/powershell/module/az.monitor/#monitor)

+* [REST API reference. Autoscale Settings](/rest/api/monitor/autoscale-settings).

+### Configure Basic Logs

+> You may not immediately see web app in-guest file changes and configuration changes. Prepare for downtime and restart your web app to view changes within 30 minutes. If you still can't see changes, refer to [the troubleshooting guide](./change-analysis-troubleshoot.md#cannot-see-in-guest-changes-for-newly-enabled-web-app).

+Try refreshing the page and checking your internet connection. If the error persists, [submit an Azure support ticket](https://azure.microsoft.com/support/).

+You'll receive this error message when the registration takes longer than 2 minutes. While unusual, it doesn't mean something went wrong.

+1. Prepare for downtime.

+1. Restart your web app to see your registration changes.

+Changes should show up within a few hours of app restart. If your changes still don't show after 6 hours, [submit an Azure support ticket](https://azure.microsoft.com/support/).

+If this is a blocking issue for you, [submit an Azure support ticket](https://azure.microsoft.com/support/) to describe how you're trying to use Change Analysis.

+Refreshing the page after a few minutes usually fixes this issue. If the error persists, [submit an Azure support ticket](https://azure.microsoft.com/support/).

+To load all change data, try waiting a few minutes and refreshing the page. If you are still only receiving partial data, [submit an Azure support ticket](https://azure.microsoft.com/support/).

+You may not immediately see web app in-guest file changes and configuration changes.

+1. Prepare for brief downtime.

+1. Restart your web app.

+You should be able to view changes within 30 minutes. If not, [submit an Azure support ticket](https://azure.microsoft.com/support/).

+Send feedback from the Change Analysis blade:

+You can save on data ingestion costs by configuring certain tables in your Log Analytics workspace that you primarily use for debugging, troubleshooting, and auditing as Basic Logs. For more information, including the limitations of Basic Logs, see [Configure Basic Logs (preview)](../best-practices-cost.md#configure-basic-logs). ContainerLogV2 is the configured version of Basic Logs that Container Insights uses. ContainerLogV2 includes verbose text-based log records.

+- Any Azure table listed in [Tables that support transformations in Azure Monitor Logs (preview)](../logs/tables-feature-support.md)

+| Storage account | Don't use an existing storage account that has other, non-monitoring data stored in it so that you can better control access to the data. If you're archiving the activity log and resource logs together, you might choose to use the same storage account to keep all monitoring data in a central location.<br><br>To send the data to immutable storage, set the immutable policy for the storage account as described in [Set and manage immutability policies for Azure Blob Storage](../../storage/blobs/immutable-policy-configure-version-scope.md). You must follow all steps in this linked article including enabling protected append blobs writes.<br><br>The storage account needs to be in the same region as the resource being monitored if the resource is regional.<br><br> Diagnostic settings can't access storage accounts when virtual networks are enabled. You must enable **Allow trusted Microsoft services** to bypass this firewall setting in storage accounts so that the Azure Monitor diagnostic settings service is granted access to your storage account.<br><br>[Azure DNS zone endpoints (preview)](../../storage/common/storage-account-overview.md#azure-dns-zone-endpoints-preview) and [Azure Premium LRS](../../storage/common/storage-redundancy.md#locally-redundant-storage) (locally redundant storage) storage accounts are not supported as a log or metric destination.|

+[Read more about Azure platform logs](./platform-logs-overview.md)

+This guide walks you through migrating from using Azure diagnostic settings storage retention to using [Azure Storage lifecycle management](../../storage/blobs/lifecycle-management-policy-configure.md?tabs=azure-portal) for retention.

+Azure Monitor managed service for Prometheus supports recording rules and alert rules using PromQL queries. Metrics recorded by recording rules are stored back in the Azure Monitor workspace and can be queried by dashboard or by other rules. Alerts fired by alert rules can trigger actions or notifications, as defined in the [action groups](../alerts/action-groups.md) configured for the alert rule. You can also view fired and resolved Prometheus alerts in the Azure portal along with other alert types. For your AKS cluster, a set of [predefined Prometheus alert rules](../containers/container-insights-metric-alerts.md) and [recording rules ](./prometheus-metrics-scrape-default.md#recording-rules)is provided to allow easy quick start.

+- [Customize scraping of Prometheus metrics](prometheus-metrics-scrape-configuration.md).

+description: Learn how to send results from Log Analytics to Power BI.

+This article focuses on ways to feed data from Log Analytics into Power BI to create more visually appealing reports and dashboards.

+## Background

+Azure Monitor Logs is a platform that provides an end-to-end solution for ingesting logs. [Azure Monitor Log Analytics](../data-platform.md) is the interface to query these logs. For more information on the entire Azure Monitor data platform including Log Analytics, see [Azure Monitor data platform](../data-platform.md).

+Power BI is the Microsoft data visualization platform. For more information on how to get started, see the [Power BI home page](https://powerbi.microsoft.com/).

+More advanced features might require purchasing a Power BI Pro or Premium account. These features include:

+ - Sharing your work.

+ - Scheduled refreshes.

+ - Power BI apps.

+ - Dataflows and incremental refresh.

+For more information, see [Learn more about Power BI pricing and features](https://powerbi.microsoft.com/pricing/).

+## Integrate queries

+Power BI uses the [M query language](/powerquery-m/power-query-m-language-specification/) as its main querying language.

+Log Analytics queries can be exported to M and used in Power BI directly. After you run a successful query, select **Export to Power BI (M query)** from the **Export** dropdown list in the Log Analytics top toolbar.

+## Connect your logs to a dataset

+A Power BI dataset is a source of data ready for reporting and visualization. To connect a Log Analytics query to a dataset, copy the M code exported from Log Analytics into a blank query in Power BI.

+For more information, see [Understanding Power BI datasets](/power-bi/service-datasets-understand/).

+## Collect data with Power BI dataflows

+Power BI dataflows also allow you to collect and store data. For more information, see [Power BI dataflows](/power-bi/service-dataflows-overview).

+## Incremental refresh

+Both Power BI datasets and Power BI dataflows have an incremental refresh option. Power BI dataflows and Power BI datasets support this feature. To use incremental refresh on dataflows, you need Power BI Premium.

+Incremental refresh runs small queries and updates smaller amounts of data per run instead of ingesting all the data again and again when you run the query. You can save large amounts of data but add a new increment of data every time the query is run. This behavior is ideal for longer-running reports.

+Power BI incremental refresh relies on the existence of a **datetime** field in the result set. Before you configure incremental refresh, make sure your Log Analytics query result set includes at least one **datetime** field.

+To learn more and how to configure incremental refresh, see [Power BI datasets and incremental refresh](/power-bi/service-premium-incremental-refresh) and [Power BI dataflows and incremental refresh](/power-bi/service-dataflows-incremental-refresh).

+For more information, see [Create and share your first Power BI report](/training/modules/build-your-first-power-bi-report/).

+You can use the same M integration used in Power BI to integrate with an Excel spreadsheet. For more information, see [Import data from data sources (Power Query)](https://support.microsoft.com/office/import-data-from-external-data-sources-power-query-be4330b3-5356-486c-a168-b68e9e616f5a). Then paste the M query exported from Log Analytics.

+For more information, see [Integrate Log Analytics and Excel](log-excel.md).

+ Title: Export data from a Log Analytics workspace to a storage account by using Logic Apps

+description: This article describes a method to use Azure Logic Apps to query data from a Log Analytics workspace and send it to Azure Storage.

+# Export data from a Log Analytics workspace to a storage account by using Logic Apps

+This article describes a method to use [Azure Logic Apps](../../logic-apps/index.yml) to query data from a Log Analytics workspace in Azure Monitor and send it to Azure Storage. Use this process when you need to export your Azure Monitor Logs data for auditing and compliance scenarios or to allow another service to retrieve this data.

+The method discussed in this article describes a scheduled export from a log query by using a logic app. Other options to export data for particular scenarios include:

+- To export data from your Log Analytics workspace to a storage account or Azure Event Hubs, use the Log Analytics workspace data export feature of Azure Monitor Logs. See [Log Analytics workspace data export in Azure Monitor](logs-data-export.md).

+- One-time export by using a logic app. See [Azure Monitor Logs connector for Logic Apps and Power Automate](logicapp-flow-connector.md).

+- One-time export to a local machine by using a PowerShell script. See [Invoke-AzOperationalInsightsQueryExport](https://www.powershellgallery.com/packages/Invoke-AzOperationalInsightsQueryExport).

+This procedure uses the [Azure Monitor Logs connector](/connectors/azuremonitorlogs), which lets you run a log query from a logic app and use its output in other actions in the workflow. The [Azure Blob Storage connector](/connectors/azureblob) is used in this procedure to send the query output to storage.

+[](media/logs-export-logic-app/logic-app-overview.png#lightbox)

+When you export data from a Log Analytics workspace, limit the amount of data processed by your Logic Apps workflow. Filter and aggregate your log data in the query to reduce the required data. For example, if you need to export sign-in events, filter for required events and project only the required fields. For example:

+When you export the data on a schedule, use the `ingestion_time()` function in your query to ensure that you don't miss late-arriving data. If data is delayed because of network or platform issues, using the ingestion time ensures that data is included in the next Logic Apps execution. For an example, see the step "Add Azure Monitor Logs action" in the [Logic Apps procedure](#logic-apps-procedure) section.

+The following prerequisites must be completed before you start this procedure:

+- **Log Analytics workspace**: The user who creates the logic app must have at least read permission to the workspace.

+- **Storage account**: The storage account doesn't have to be in the same subscription as your Log Analytics workspace. The user who creates the logic app must have write permission to the storage account.

+Log Analytics workspace and log queries in Azure Monitor are multitenancy services that include limits to protect and isolate customers and maintain quality of service. When you query for a large amount of data, consider the following limits, which can affect how you configure the Logic Apps recurrence and your log query:

+- Log queries can't return more than 500,000 rows.

+- Log queries can't return more than 64,000,000 bytes.

+- Log queries can't run longer than 10 minutes by default.

+- Log Analytics connector is limited to 100 calls per minute.

+## Logic Apps procedure

+The following sections walk you through the procedure.

+### Create a container in the storage account

+Use the procedure in [Create a container](../../storage/blobs/storage-quickstart-blobs-portal.md#create-a-container) to add a container to your storage account to hold the exported data. The name used for the container in this article is **loganalytics-data**, but you can use any name.

+### Create a logic app

+1. Go to **Logic Apps** in the Azure portal and select **Add**. Select a **Subscription**, **Resource group**, and **Region** to store the new Logic App. Then give it a unique name. You can turn on the **Log Analytics** setting to collect information about runtime data and events as described in [Set up Azure Monitor Logs and collect diagnostics data for Azure Logic Apps](../../logic-apps/monitor-logic-apps-log-analytics.md). This setting isn't required for using the Azure Monitor Logs connector.

+ [](media/logs-export-logic-app/create-logic-app.png#lightbox)

+1. Select **Review + create** and then select **Create**. After the deployment is finished, select **Go to resource** to open the **Logic Apps Designer**.

+### Create a trigger for the logic app

+Under **Start with a common trigger**, select **Recurrence**. This setting creates a logic app that automatically runs at a regular interval. In the **Frequency** box of the action, select **Day**. In the **Interval** box, enter **1** to run the workflow once per day.

+[](media/logs-export-logic-app/recurrence-action.png#lightbox)

+### Add an Azure Monitor Logs action

+The Azure Monitor Logs action lets you specify the query to run. The log query used in this example is optimized for hourly recurrence. It collects the data ingested for the particular execution time. For example, if the workflow runs at 4:35, the time range would be 3:00 to 4:00. If you change the logic app to run at a different frequency, you need to change the query too. For example, if you set the recurrence to run daily, you set `startTime` in the query to `startofday(make_datetime(year,month,day,0,0))`.

+You're prompted to select a tenant to grant access to the Log Analytics workspace with the account that the workflow will use to run the query.

+1. Select **+ New step** to add an action that runs after the recurrence action. Under **Choose an action**, enter **azure monitor**. Then select **Azure Monitor Logs**.

+ [](media/logs-export-logic-app/select-azure-monitor-connector.png#lightbox)

+1. Select **Azure Log Analytics ΓÇô Run query and list results**.

+ [](media/logs-export-logic-app/select-query-action-list.png#lightbox)

+1. Select the **Subscription** and **Resource Group** for your Log Analytics workspace. Select **Log Analytics Workspace** for the **Resource Type**. Then select the workspace name under **Resource Name**.

+1. Add the following log query to the **Query** window:

+ ```Kusto

+ let dt = now();

+ let year = datetime_part('year', dt);

+ let month = datetime_part('month', dt);

+ let day = datetime_part('day', dt);

+ let hour = datetime_part('hour', dt);

+ let startTime = make_datetime(year,month,day,hour,0)-1h;

+ let endTime = startTime + 1h - 1tick;

+ AzureActivity

+ | where ingestion_time() between(startTime .. endTime)

+ | project

+ TimeGenerated,

+ BlobTime = startTime,

+ OperationName ,

+ OperationNameValue ,

+ Level ,

+ ActivityStatus ,

+ ResourceGroup ,

+ SubscriptionId ,

+ Category ,

+ EventSubmissionTimestamp ,

+ ClientIpAddress = parse_json(HTTPRequest).clientIpAddress ,

+ ResourceId = _ResourceId

+ ```

+1. The **Time Range** specifies the records that will be included in the query based on the **TimeGenerated** column. The value should be greater than the time range selected in the query. Because this query isn't using the **TimeGenerated** column, the **Set in query** option isn't available. For more information about the time range, see [Query scope](./scope.md). Select **Last 4 hours** for the **Time Range**. This setting ensures that any records with an ingestion time larger than **TimeGenerated** will be included in the results.

+ [](media/logs-export-logic-app/run-query-list-action.png#lightbox)

+### Add a Parse JSON action (optional)

+The output from the **Run query and list results** action is formatted in JSON. You can parse this data and manipulate it as part of the preparation for the **Compose** action.

+You can provide a JSON schema that describes the payload you expect to receive. The designer parses JSON content by using this schema and generates user-friendly tokens that represent the properties in your JSON content. You can then easily reference and use those properties throughout your Logic App's workflow.

+You can use a sample output from the **Run query and list results** step.

+1. Select **Run Trigger** in the Logic Apps ribbon. Then select **Run** and download and save an output record. For the sample query in the previous stem, you can use the following sample output:

+1. Select **+ New step** and then select **+ Add an action**. Under **Choose an operation**, enter **json** and then select **Parse JSON**.

+ [](media/logs-export-logic-app/select-parse-json.png#lightbox)

+1. Select the **Content** box to display a list of values from previous activities. Select **Body** from the **Run query and list results** action. This output is from the log query.

+ [](media/logs-export-logic-app/select-body.png#lightbox)

+1. Copy the sample record saved earlier. Select **Use sample payload to generate schema** and paste.

+ [](media/logs-export-logic-app/parse-json-payload.png#lightbox)

+### Add the Compose action

+The **Compose** action takes the parsed JSON output and creates the object that you need to store in the blob.

+1. Select **+ New step**, and then select **+ Add an action**. Under **Choose an operation**, enter **compose**. Then select the **Compose** action.

+ [](media/logs-export-logic-app/select-compose.png#lightbox)

+1. Select the **Inputs** box to display a list of values from previous activities. Select **Body** from the **Parse JSON** action. This parsed output is from the log query.

+ [](media/logs-export-logic-app/select-body-compose.png#lightbox)

+### Add the Create blob action

+The **Create blob** action writes the composed JSON to storage.

+1. Select **+ New step**, and then select **+ Add an action**. Under **Choose an operation**, enter **blob**. Then select the **Create blob** action.

+ [](media/logs-export-logic-app/select-create-blob.png#lightbox)

+1. Enter a name for the connection to your storage account in **Connection Name**. Then select the folder icon in the **Folder path** box to select the container in your storage account. Select **Blob name** to see a list of values from previous activities. Select **Expression** and enter an expression that matches your time interval. For this query, which is run hourly, the following expression sets the blob name per previous hour:

+ ```json

+ subtractFromTime(formatDateTime(utcNow(),'yyyy-MM-ddTHH:00:00'), 1,'Hour')

+ ```

+ [](media/logs-export-logic-app/blob-expression.png#lightbox)

+1. Select the **Blob content** box to display a list of values from previous activities. Then select **Outputs** in the **Compose** section.

+ [](media/logs-export-logic-app/create-blob.png#lightbox)

+### Test the logic app

+To test the workflow, select **Run**. If the workflow has errors, they're indicated on the step with the problem. You can view the executions and drill in to each step to view the input and output to investigate failures. See [Troubleshoot and diagnose workflow failures in Azure Logic Apps](../../logic-apps/logic-apps-diagnosing-failures.md), if necessary.

+[](media/logs-export-logic-app/runs-history.png#lightbox)

+### View logs in storage

+Go to the **Storage accounts** menu in the Azure portal and select your storage account. Select the **Blobs** tile. Then select the container you specified in the **Create blob** action. Select one of the blobs and then select **Edit blob**.

+[](media/logs-export-logic-app/blob-data.png#lightbox)

+- Learn more about [Logic Apps](../../logic-apps/index.yml).

+For more information on connecting your own storage account, see [Customer-owned storage accounts for log ingestion](private-storage.md) and specifically [Use Private Links](private-storage.md#use-private-links) and [Link storage accounts to your Log Analytics workspace](private-storage.md#link-storage-accounts-to-your-log-analytics-workspace).

+ Title: Use customer-managed storage accounts in Azure Monitor Log Analytics

+description: Use your own Azure Storage account for Azure Monitor Log Analytics scenarios.

+# Use customer-managed storage accounts in Azure Monitor Log Analytics

+Log Analytics relies on Azure Storage in various scenarios. This use is typically managed automatically. But some cases require you to provide and manage your own storage account, which is also known as a customer-managed storage account. This article covers the use of customer-managed storage for WAD/LAD logs, Azure Private Link, and customer-managed key (CMK) encryption.

+> We recommend that you don't take a dependency on the contents that Log Analytics uploads to customer-managed storage because formatting and content might change.

+## Ingest Azure Diagnostics extension logs (WAD/LAD)

+The Azure Diagnostics extension agents (also called WAD and LAD for Windows and Linux agents, respectively) collect various operating system logs and store them on a customer-managed storage account. You can then ingest these logs into Log Analytics to review and analyze them.

+### Collect Azure Diagnostics extension logs from your storage account

+Connect the storage account to your Log Analytics workspace as a storage data source by using the [Azure portal](../agents/diagnostics-extension-logs.md#collect-logs-from-azure-storage). You can also call the [Storage Insights API](/rest/api/loganalytics/storage-insights/create-or-update).

+Supported data types are:

+* Azure Service Fabric

+* [Event Tracing for Windows (ETW) events](../agents/data-sources-event-tracing-windows.md)

+* [IIS logs](../agents/data-sources-iis-logs.md)

+## Use private links

+Customer-managed storage accounts are used to ingest custom logs when private links are used to connect to Azure Monitor resources. The ingestion process of these data types first uploads logs to an intermediary Azure Storage account, and only then ingests them to a workspace.

+> Collection of IIS logs isn't supported with private links.

+### Use a customer-managed storage account over a private link

+Meet the following requirements.

+When you connect to Azure Monitor over a private link, Log Analytics agents are only able to send logs to workspaces accessible over a private link. This requirement means you should:

+* Configure an Azure Monitor Private Link Scope (AMPLS) object.

+* Connect it to your workspaces.

+* Connect the AMPLS to your network over a private link.

+For more information on the AMPLS configuration procedure, see [Use Azure Private Link to securely connect networks to Azure Monitor](./private-link-security.md).

+* Be located on your virtual network or a peered network and connected to your virtual network over a private link.

+* Be located on the same region as the workspace it's linked to.

+* Allow Azure Monitor to access the storage account. If you chose to allow only select networks to access your storage account, select the exception **Allow trusted Microsoft services to access this storage account**.

+ 

+If your workspace handles traffic from other networks, configure the storage account to allow incoming traffic coming from the relevant networks/internet.

+Coordinate the TLS version between the agents and the storage account. We recommend that you send data to Log Analytics by using TLS 1.2 or higher. Review the [platform-specific guidance](./data-security.md#sending-data-securely-using-tls-12). If required, [configure your agents to use TLS 1.2](../agents/agent-windows.md#configure-agent-to-use-tls-12). If that's not possible, configure the storage account to accept TLS 1.0.

+### Use a customer-managed storage account for CMK data encryption

+Azure Storage encrypts all data at rest in a storage account. By default, it uses Microsoft-managed keys (MMKs) to encrypt the data. However, Azure Storage also allows you to use CMKs from Azure Key Vault to encrypt your storage data. You can either import your own keys into Key Vault or use the Key Vault APIs to generate keys.

+A customer-managed storage account is required for:

+* Encrypting log-alert queries with CMKs.

+* Encrypting saved queries with CMKs.

+#### Apply CMKs to customer-managed storage accounts

+Follow this guidance to apply CMKs to customer-managed storage accounts.

+The storage account and the key vault must be in the same region, but they also can be in different subscriptions. For more information about Azure Storage encryption and key management, see [Azure Storage encryption for data at rest](../../storage/common/storage-service-encryption.md).

+##### Apply CMKs to your storage accounts

+To configure your Azure Storage account to use CMKs with Key Vault, use the [Azure portal](../../storage/common/customer-managed-keys-configure-key-vault.md?toc=%252fazure%252fstorage%252fblobs%252ftoc.json), [PowerShell](../../storage/common/customer-managed-keys-configure-key-vault.md?toc=%252fazure%252fstorage%252fblobs%252ftoc.json), or the [Azure CLI](../../storage/common/customer-managed-keys-configure-key-vault.md?toc=%252fazure%252fstorage%252fblobs%252ftoc.json).

+> If you link a storage account for queries, or for log alerts, existing queries will be removed from the workspace. Copy saved searches and log alerts that you need before you undertake this configuration. For directions on moving saved queries and log alerts, see [Workspace move procedure](./move-workspace-region.md).

+>

+> You can connect up to:

+> - Five storage accounts for the ingestion of custom logs and IIS logs.

+> - One storage account for saved queries.

+> - One storage account for saved log alert queries.

+### Use the Azure portal

+On the Azure portal, open your workspace menu and select **Linked storage accounts**. A pane shows the linked storage accounts by the use cases previously mentioned (ingestion over Private Link, applying CMKs to saved queries or to alerts).

+

+Selecting an item on the table opens its storage account details, where you can set or update the linked storage account for this type.

+

+### Use the Azure CLI or REST API

+The applicable `dataSourceType` values are:

+* `CustomLogs`: To use the storage account for custom logs and IIS logs ingestion.

+* `Query`: To use the storage account to store saved queries (required for CMK encryption).

+* `Alerts`: To use the storage account to store log-based alerts (required for CMK encryption).

+## Manage linked storage accounts

+Follow this guidance to manage your linked storage accounts.

+When you link a storage account to a workspace, Log Analytics will start using it instead of the storage account owned by the service. You can:

+* Register multiple storage accounts to spread the load of logs between them.

+* Reuse the same storage account for multiple workspaces.

+To stop using a storage account, unlink the storage from the workspace. Unlinking all storage accounts from a workspace means Log Analytics will attempt to rely on service-managed storage accounts. If your network has limited access to the internet, these storage accounts might not be available and any scenario that relies on storage will fail.

+To replace a storage account used for ingestion:

+1. **Create a link to a new storage account**. The logging agents will get the updated configuration and start sending data to the new storage. The process could take a few minutes.

+2. **Unlink the old storage account so agents will stop writing to the removed account**. The ingestion process keeps reading data from this account until it's all ingested. Don't delete the storage account until you see that all logs were ingested.

+### Maintain storage accounts

+Follow this guidance to maintain your storage accounts.

+When you use your own storage account, retention is up to you. Log Analytics won't delete logs stored on your private storage. Instead, you should set up a policy to handle the load according to your preferences.

+Storage accounts can handle a certain load of read and write requests before they start throttling requests. For more information, see [Scalability and performance targets for Azure Blob Storage](../../storage/common/scalability-targets-standard-account.md).

+Throttling affects the time it takes to ingest logs. If your storage account is overloaded, register another storage account to spread the load between them. To monitor your storage account's capacity and performance, review its [Insights in the Azure portal](../../storage/common/storage-insights-overview.md?toc=%2fazure%2fazure-monitor%2ftoc.json).

+### Related charges

+Storage accounts are charged by the volume of stored data, the type of storage, and the type of redundancy. For more information, see [Block blob pricing](https://azure.microsoft.com/pricing/details/storage/blobs) and [Azure Table Storage pricing](https://azure.microsoft.com/pricing/details/storage/tables).

+- Learn about [using Private Link to securely connect networks to Azure Monitor](private-link-security.md).

+- Learn about [Azure Monitor customer-managed keys](../logs/customer-managed-keys.md).

+ Title: 'Tutorial: Add a workspace transformation to Azure Monitor Logs by using the Azure portal'

+description: Describes how to add a custom transformation to data flowing through Azure Monitor Logs by using the Azure portal.

+# Tutorial: Add a transformation in a workspace data collection rule by using the Azure portal (preview)

+This tutorial walks you through configuration of a sample [transformation in a workspace data collection rule (DCR)](../essentials/data-collection-transformations.md) by using the Azure portal. [Transformations](../essentials/data-collection-transformations.md) in Azure Monitor allow you to filter or modify incoming data before it's sent to its destination. Workspace transformations provide support for [ingestion-time transformations](../essentials/data-collection-transformations.md) for workflows that don't yet use the [Azure Monitor data ingestion pipeline](../essentials/data-collection.md).

+Workspace transformations are stored together in a single [DCR](../essentials/data-collection-rule-overview.md) for the workspace, which is called the workspace DCR. Each transformation is associated with a particular table. The transformation will be applied to all data sent to this table from any workflow not using a DCR.

+> This tutorial uses the Azure portal to configure a workspace transformation. For the same tutorial using Azure Resource Manager templates and REST API, see [Tutorial: Add transformation in workspace data collection rule to Azure Monitor using resource manager templates (preview)](tutorial-workspace-transformations-api.md).

+In this tutorial, you learn how to:

+> * Configure a [workspace transformation](../essentials/data-collection-transformations.md#workspace-transformation-dcr) for a table in a Log Analytics workspace.

+To complete this tutorial, you need:

+- A Log Analytics workspace where you have at least [contributor rights](manage-access.md#azure-rbac).

+- [Permissions to create DCR objects](../essentials/data-collection-rule-overview.md#permissions) in the workspace.

+- A table that already has some data.

+## Overview of the tutorial

+In this tutorial, you'll reduce the storage requirement for the `LAQueryLogs` table by filtering out certain records. You'll also remove the contents of a column while parsing the column data to store a piece of data in a custom column. The [LAQueryLogs table](query-audit.md#audit-data) is created when you enable [log query auditing](query-audit.md) in a workspace. You can use this same basic process to create a transformation for any [supported table](tables-feature-support.md) in a Log Analytics workspace.

+This tutorial uses the Azure portal, which provides a wizard to walk you through the process of creating an ingestion-time transformation. After you finish the steps, you'll see that the wizard:

+- Updates the table schema with any other columns from the query.

+- Creates a `WorkspaceTransforms` DCR and links it to the workspace if a default DCR isn't already linked to the workspace.

+You need to enable [query auditing](query-audit.md) for your workspace to create the `LAQueryLogs` table that you'll be working with. This step isn't required for all ingestion time transformations. It's just to generate the sample data that we'll be working with.

+1. On the **Log Analytics workspaces** menu in the Azure portal, select **Diagnostic settings** > **Add diagnostic setting**.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/diagnostic-settings.png" lightbox="media/tutorial-workspace-transformations-portal/diagnostic-settings.png" alt-text="Screenshot that shows diagnostic settings.":::

+1. Enter a name for the diagnostic setting. Select the workspace so that the auditing data is stored in the same workspace. Select the **Audit** category and then select **Save** to save the diagnostic setting and close the **Diagnostic setting** page.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/new-diagnostic-setting.png" lightbox="media/tutorial-workspace-transformations-portal/new-diagnostic-setting.png" alt-text="Screenshot that shows the new diagnostic setting.":::

+1. Select **Logs** and then run some queries to populate `LAQueryLogs` with some data. These queries don't need to return data to be added to the audit log.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/sample-queries.png" lightbox="media/tutorial-workspace-transformations-portal/sample-queries.png" alt-text="Screenshot that shows sample log queries.":::

+## Add a transformation to the table

+1. On the **Log Analytics workspaces** menu in the Azure portal, select **Tables (preview)**. Locate the `LAQueryLogs` table and select **Create transformation**.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/create-transformation.png" lightbox="media/tutorial-workspace-transformations-portal/create-transformation.png" alt-text="Screenshot that shows creating a new transformation.":::

+1. Because this transformation is the first one in the workspace, you must create a [workspace transformation DCR](../essentials/data-collection-transformations.md#workspace-transformation-dcr). If you create transformations for other tables in the same workspace, they'll be stored in this same DCR. Select **Create a new data collection rule**. The **Subscription** and **Resource group** will already be populated for the workspace. Enter a name for the DCR and select **Done**.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/new-data-collection-rule.png" lightbox="media/tutorial-workspace-transformations-portal/new-data-collection-rule.png" alt-text="Screenshot that shows creating a new data collection rule.":::

+1. Select **Next** to view sample data from the table. As you define the transformation, the result will be applied to the sample data. For this reason, you can evaluate the results before you apply it to actual data. Select **Transformation editor** to define the transformation.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/sample-data.png" lightbox="media/tutorial-workspace-transformations-portal/sample-data.png" alt-text="Screenshot that shows sample data from the log table.":::

+1. In the transformation editor, you can see the transformation that will be applied to the data prior to its ingestion into the table. The incoming data is represented by a virtual table named `source`, which has the same set of columns as the destination table itself. The transformation initially contains a simple query that returns the `source` table with no changes.

+1. Modify the query to the following example:

+ The modification makes the following changes:

+ - Rows related to querying the `LAQueryLogs` table itself were dropped to save space because these log entries aren't useful.

+ - A column for the name of the workspace that was queried was added.

+ - Data from the `RequestContext` column was removed to save space.

+ > Using the Azure portal, the output of the transformation will initiate changes to the table schema if required. Columns will be added to match the transformation output if they don't already exist. Make sure that your output doesn't contain any columns that you don't want added to the table. If the output doesn't include columns that are already in the table, those columns won't be removed, but data won't be added.

+ > Any custom columns added to a built-in table must end in `_CF`. Columns added to a custom table don't need to have this suffix. A custom table has a name that ends in `_CL`.

+1. Copy the query into the transformation editor and select **Run** to view results from the sample data. You can verify that the new `Workspace_CF` column is in the query.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/transformation-editor.png" lightbox="media/tutorial-workspace-transformations-portal/transformation-editor.png" alt-text="Screenshot that shows the transformation editor.":::

+1. Select **Apply** to save the transformation and then select **Next** to review the configuration. Select **Create** to update the DCR with the new transformation.

+ :::image type="content" source="media/tutorial-workspace-transformations-portal/save-transformation.png" lightbox="media/tutorial-workspace-transformations-portal/save-transformation.png" alt-text="Screenshot that shows saving the transformation.":::

+## Test the transformation

+Allow about 30 minutes for the transformation to take effect and then test it by running a query against the table. Only data sent to the table after the transformation was applied will be affected.

+For this tutorial, run some sample queries to send data to the `LAQueryLogs` table. Include some queries against `LAQueryLogs` so that you can verify that the transformation filters these records. Now the output has the new `Workspace_CF` column, and there are no records for `LAQueryLogs`.

+This section describes different error conditions you might receive and how to correct them.

+The cache that drives IntelliSense might take up to 24 hours to update.

+A known issue currently affects dynamic columns. A temporary workaround is to explicitly parse dynamic column data by using `parse_json()` prior to performing any operations against them.

+For a list of Azure resource provider namespaces, see [Resource providers for Azure services](../azure-resource-manager/management/azure-services-resource-providers.md).

+- Complete a [tutorial on creating a metrics chart to analyze data in Azure Monitor Metrics](essentials/tutorial-metrics.md).

+Alerts|[Connect Azure to ITSM tools by using IT Service Management](./alerts/itsmc-definition.md)|Deprecating support for sending ITSM actions and events to ServiceNow. Instead, use ITSM actions in action groups based on Azure alerts to create work items in your ITSM tool.|

+Alerts|[Create a new alert rule](./alerts/alerts-create-new-alert-rule.md)|New PowerShell commands to create and manage log alerts.|

+Alerts|[Customize alert notifications using Logic Apps](./alerts/alerts-logic-apps.md)|New: How to use alerts to send emails or Teams posts using logic apps|

+Application-insights|[Sampling in Application Insights](./app/sampling.md)|The "When to use sampling" and "How sampling works" sections have been prioritized as prerequisite information for the rest of the article.|

+Application-insights|[What is auto-instrumentation for Azure Monitor Application Insights?](./app/codeless-overview.md)|The auto-instrumentation overview has been visually overhauled with links and footnotes.|

+Application-insights|[Enable Azure Monitor OpenTelemetry for .NET, Node.js, and Python applications (preview)](./app/opentelemetry-enable.md)|Open Telemetry Metrics are now available for .NET, Node.js and Python applications.|

+Application-insights|[Find and diagnose performance issues with Application Insights](./app/tutorial-performance.md)|The URL Ping (Classic) Test has been replaced with the Standard Test step-by-step instructions.|

+Application-insights|[Application Insights API for custom events and metrics](./app/api-custom-events-metrics.md)|Flushing information was added to the FAQ.|

+Application-insights|[Azure AD authentication for Application Insights](./app/azure-ad-authentication.md)|We updated the `TelemetryConfiguration` code sample using .NET.|

+Application-insights|[Using Azure Monitor Application Insights with Spring Boot](./app/java-spring-boot.md)|Spring Boot information was updated to 3.4.2.|

+Application-insights|[Configuration options: Azure Monitor Application Insights for Java](./app/java-standalone-config.md)|New features include Capture Log4j Markers and Logback Markers as custom properties on the corresponding trace (log message) telemetry.|

+Application-insights|[Create custom KPI dashboards using Application Insights](./app/tutorial-app-dashboards.md)|This article has been refreshed with new screenshots and instructions.|

+Application-insights|[Share Azure dashboards by using Azure role-based access control](../azure-portal/azure-portal-dashboard-share-access.md)|This article has been refreshed with new screenshots and instructions.|

+Application-insights|[Application Monitoring for Azure App Service and ASP.NET](./app/azure-web-apps-net.md)|Important notes added regarding System.IO.FileNotFoundException after 2.8.44 auto-instrumentation upgrade.|

+Application-insights|[Geolocation and IP address handling](./app/ip-collection.md)| Geolocation lookup information has been updated.|

+Containers|[Metric alert rules in Container insights (preview)](./containers/container-insights-metric-alerts.md)|Container insights metric Alerts|

+Essentials Prometheus|[Azure Monitor managed service for Prometheus remote write - managed identity (preview)](./essentials/prometheus-remote-write-managed-identity.md)|Addition: Verify Prometheus remote write is working correctly|

+Essentials|[Azure resource logs](./essentials/resource-logs.md)|Clarification: Which blobs logs are written to, and when|

+Logs|[Manage access to Log Analytics workspaces](./logs/manage-access.md)|Table-level role-based access control (RBAC) lets you give specific users or groups read access to particular tables.|

+Logs|[Configure Basic Logs in Azure Monitor](./logs/basic-logs-configure.md)|General availability of the Basic Logs data plan, retention and archiving, search job, and the table management user experience in the Azure portal.|

+Virtual-machines|[Enable VM insights for a hybrid virtual machine](./vm/vminsights-enable-hybrid.md)|Updated versions of standalone installers.|

+Visualizations|[Retrieve legacy Application Insights workbooks](./visualize/workbooks-retrieve-legacy-workbooks.md)|New article about how to access legacy workbooks in the Azure portal.|

+Visualizations|[Azure Workbooks](./visualize/workbooks-overview.md)|New video to see how you can use Azure Workbooks to get insights and visualize your data. |

+|[Configuration options - Azure Monitor Application Insights for Java](./app/java-in-process-agent.md)|Connection string guidance updated.|

+1. To [add optional tags](../azure-resource-manager/management/tag-resources.md) to the dashboard, enter one or more name/value pairs.

+* [Create a dashboard](azure-portal-dashboards.md) in the Azure portal.

+Any role assignments that refer to a deleted principal ID become invalid. If you try to reuse a role assignment's name for another role assignment, the deployment will fail. To work around this behavior, you should either remove the old role assignment before you recreate it, or ensure that you use a unique name when you deploy a new role assignment. This [quickstart template](/samples/azure/azure-quickstart-templates/key-vault-managed-identity-role-assignment) illustrates how you can define a role assignment in a Bicep module and use a principal ID as a seed value for the role assignment name.

+ - [Create key vault, managed identity, and role assignment](/samples/azure/azure-quickstart-templates/key-vault-managed-identity-role-assignment)

+A virtual machine that is integrated with a key vault to implement [Azure Disk Encryption for Linux VMs](../../../virtual-machines/linux/disk-encryption-overview.md) or [Azure Disk Encryption for Windows VMs](../../../virtual-machines/windows/disk-encryption-overview.md) can be moved to another resource group when it is in deallocated state.

+However, to move such virtual machine to another subscription, you must disable encryption.

+- [Microsoft.Compute/virtualMachines/extensions](/azure/templates/microsoft.compute/virtualmachines/extensions)

+- [Microsoft.Compute virtualMachineScaleSets/extensions](/azure/templates/microsoft.compute/virtualmachinescalesets/extensions)

+- [Microsoft.HDInsight clusters/extensions](/azure/templates/microsoft.hdinsight/clusters)

+- [Microsoft.Sql servers/databases/extensions](/azure/templates/microsoft.sql/servers/databases/extensions)

+- [Microsoft.Web/sites/siteextensions](/azure/templates/microsoft.web/sites/siteextensions)

+In this tutorial, you add a storage account to the template. You can see the storage account's API version at [storageAccounts 2021-09-01](/azure/templates/microsoft.storage/2021-09-01/storageaccounts). Notice that you don't add all the properties to your template. Many of the properties are optional. The `Microsoft.Storage` resource provider could release a new API version, but the version you're deploying doesn't have to change. You can continue using that version and know that the results of your deployment are consistent.

+If you view an older [API version](/azure/templates/microsoft.storage/allversions) you might see that a smaller set of properties is available.

+Azure Video Indexer identifies each speaker in a video and attributes each transcribed line to a speaker. The speakers are given a unique identity such as `Speaker #1` and `Speaker #2`. To provide clarity and enrich the transcript quality, you may want to replace the assigned identity with each speaker's actual name. To edit speakers' names, use the edit actions as described in the article.

+> [!NOTE]

+> The addition or editing of a speaker name is applied throughout the transcript of the video but is not applied to other videos in your Azure Video Indexer account.

+## Start editing

+This action allows renaming an existing speaker that was identified by Azure Video Indexer. The update applies to all speakers identified by this name.

+

+To rename a speaker from the website for the selected video, do the following:

+ Title: Upgrade HCX on Azure VMware Solution

+description: This article explains how to upgrade HCX on Azure VMware Solution.

+# Upgrade HCX on Azure VMware Solution

+In this article, you'll learn how to upgrade Azure VMware Solution for HCX service updates that may include new features, software fixes, or security patches.

+You can update HCX Connector and HCX Cloud systems during separate maintenance windows, but for optimal compatibility, it's recommended you update both systems together. Apply service updates during a maintenance window where no new HCX operations are queued up.

+>[!IMPORTANT]

+>Starting with HCX 4.4.0, HCX appliances install the VMware Photon Operating System. When upgrading to HCX 4.4.x or later from an HCX version prior to version 4.4.0, you must also upgrade all Service Mesh appliances.

+## System requirements

+- For systems requirements, compatibility, and upgrade prerequisites, see the [VMware HCX release notes](https://docs.vmware.com/en/VMware-HCX/https://docsupdatetracker.net/index.html).

+- For more information about the upgrade path, see the [Product Interoperability Matrix](https://interopmatrix.vmware.com/Upgrade?productId=660).

+- Ensure HCX manager and site pair configurations are healthy.

+- As part of HCX update planning, and to ensure that HCX components are updated successfully, review the service update considerations and requirements. For planning HCX upgrade, see [Planning for HCX Updates](https://docs.vmware.com/en/VMware-HCX/4.5/hcx-user-guide/GUID-61F5CED2-C347-4A31-8ACB-A4553BFC62E3.html).

+- Ensure that you have a backup and snapshot of HCX connector in the on-premises environment, if applicable. 

+### Backup HCX 

+- Azure VMware Solution backs up HCX Cloud Manager configuration daily.

+- Use the appliance management interface to create backup of HCX in on-premises, see [Backing Up HCX Manager](https://docs.vmware.com/en/VMware-HCX/4.4/hcx-user-guide/GUID-6A9D1451-3EF3-4E49-B23E-A9A781E5214A.html). You can use the configuration backup to restore the appliance to its state before the backup. The contents of the backup file supersede configuration changes made before restoring the appliance.

+ 

+- HCX cloud manager snapshots are taken automatically during upgrades to HCX 4.4 or later. HCX retains automatic snapshots for 24 hours before deleting them. To take a manual snapshot on HCX Cloud Manager or help with reverting from a snapshot, [create a support ticket](https://ms.portal.azure.com/#view/Microsoft_Azure_Support/HelpAndSupportBlade/~/overview). 

+## Upgrade HCX

+The upgrade process is in two steps:

+1. Upgrade HCX Manager

+ 1. HCX cloud manager  

+ 1. HCX connector (You can update site-paired HCX Managers simultaneously) 

+1. Upgrade HCX Service Mesh appliances

+### Upgrade HCX manager

+The HCX update is first applied to the HCX Manager systems.

+

+**What to expect**

+- HCX manager is rebooted as part of the upgrade process.  

+- HCX vCenter Plugins will be updated.  

+- There's no data-plane outage during this procedure.

+**Prerequisites**

+- Verify the HCX Manager system reports healthy connections to the connected (vCenter Server, NSX Manager (if applicable).

+- Verify the HCX Manager system reports healthy connections to the HCX Interconnect service components. (Ensure HCX isn't in an out of sync state)

+- Verify that Site Pair configurations are healthy.

+- No VM migrations should be in progress during this upgrade.

+**Procedure**

+To follow the HCX Manager upgrade process, see [Upgrading the HCX Manager](https://docs.vmware.com/en/VMware-HCX/4.5/hcx-user-guide/GUID-02DB88E1-EC81-434B-9AE9-D100E427B31C.html)

+### Upgrade HCX Service Mesh appliances

+While Service Mesh appliances are upgraded independently to the HCX Manager, they must be upgraded. These appliances are flagged for new available updates anytime the HCX Manager has newer software available.

+**What to expect**

+- Service VMs will be rebooted as part of the upgrade.

+- There is a small data plane outage during this procedure.

+- In-service upgrade of Network-extension can be considered to reduce downtime during HCX Network extension upgrades.

+**Prerequisites**

+- All paired HCX Managers on both the source and the target site are updated and all services have returned to a fully converged state.

+- Service Mesh appliances must be initiated using the HCX plug-in of vCenter or the 443 console at the source site

+- No VM migrations should be in progress during this upgrade.

+**Procedure**

+

+To follow the Service Mesh appliances upgrade process, see [Upgrading the HCX Service Mesh Appliances](https://docs.vmware.com/en/VMware-HCX/4.5/hcx-user-guide/GUID-EF89A098-D09B-4270-9F10-AEFA37CE5C93.html)

+## FAQ

+### What is the impact of an HCX upgrade?

+Apply service updates during a maintenance window where no new HCX operations and migration are queued up. The upgrade window accounts for a brief disruption to the Network Extension service, while the appliances are redeployed with the updated code.

+For individual HCX component upgrade impact, see [Planning for HCX Updates](https://docs.vmware.com/en/VMware-HCX/4.5/hcx-user-guide/GUID-61F5CED2-C347-4A31-8ACB-A4553BFC62E3.html).

+### Do I need to upgrade the service mesh appliances?

+The HCX Service Mesh can be upgraded once all paired HCX Manager systems are updated, and all services have returned to a fully converged state. Check HCX release notes for upgrade requirements. Starting with HCX 4.4.0, HCX appliances installed the VMware Photon Operating System. When upgrading to HCX 4.4.x or later from an HCX version prior to 4.4.0 version, you must upgrade all Service Mesh appliances.

+### How do I roll back HCX upgrade using a snapshot?

+See [Rolling Back an Upgrade Using Snapshots](https://docs.vmware.com/en/VMware-HCX/4.5/hcx-user-guide/GUID-B34728B9-B187-48E5-AE7B-74E92D09B98B.html). On the cloud side, open a [support ticket](https://ms.portal.azure.com/#view/Microsoft_Azure_Support/HelpAndSupportBlade/~/overview) to roll back the upgrade.

+## Next steps

+[Software Versioning, Skew and Legacy Support Policies](https://docs.vmware.com/en/VMware-HCX/4.5/hcx-skew-policy/GUID-787FB2A1-52AF-483C-B595-CF382E728674.html)

+[Updating VMware HCX](https://docs.vmware.com/en/VMware-HCX/4.5/hcx-user-guide/GUID-508A94B2-19F6-47C7-9C0D-2C89A00316B9.html)

+When you move recovery points to archive, they're subjected to an early deletion period of 180 days. The charges are prorated. If you delete a recovery point that hasn't stayed in vault-archive for 180 days, then you're charged for the remaining retention period selected at vault-archive tier price.

+* Shareable Links isn't currently supported on peered VNets that aren't in the same subscription.

+Cloud Services Configuration pools don't support some of the current Batch features, and won't support any newly added features. You won't be able to create new 'CloudServiceConfiguration' pools or add new nodes to existing pools [after February 29, 2024](https://azure.microsoft.com/updates/azure-batch-cloudserviceconfiguration-pools-will-be-retired-on-29-february-2024/).

+ > As with Virtual Machines and Virtual Machine Scale Sets, the OS managed disk used for each node incurs a cost, which is additional to the cost of the VMs. 'virtualMachineConfiguration' pools can use [ephemeral OS disks](create-pool-ephemeral-os-disk.md), which create the OS disk on the VM cache or temporary disk, to avoid extra costs associated with managed disks.There is no OS disk cost for 'cloudServiceConfiguration' nodes, as the OS disk is created on the node's local disk.

+- The same pool ID can be used to avoid linked service configuration changes.

+- See the REST API reference for [pool addition](/rest/api/batchservice/pool/add) and [virtualMachineConfiguration](/rest/api/batchservice/pool/add#virtualmachineconfiguration).

+> Batch pools can be configured in one of two node communication modes. Classic node communication mode is

+> where the Batch service initiates communication to the compute nodes.

+> [Simplified](simplified-compute-node-communication.md) node communication mode

+> BatchNodeManagement.*region* service tag for the NSG rules indicated in the following tables. Avoid

+> populating NSG rules with specific Batch service IP addresses.

+- **`virtualMachineConfiguration` or `cloudServiceConfiguration`:** While you can currently create pools using either

+configuration, new pools should be configured using `virtualMachineConfiguration` and not `cloudServiceConfiguration`.

+All current and new Batch features will be supported by Virtual Machine Configuration pools. Cloud Service Configuration

+pools don't support all features and no new capabilities are planned. You won't be able to create new

+`cloudServiceConfiguration` pools or add new nodes to existing pools

+[after February 29, 2024](https://azure.microsoft.com/updates/azure-batch-cloudserviceconfiguration-pools-will-be-retired-on-29-february-2024/).

+For more information, see

+[Migrate Batch pool configuration from Cloud Services to Virtual Machine](batch-pool-cloud-service-to-virtual-machine-configuration.md).

+- **`classic` or `simplified` node communication mode:** Pools can be configured in one of two node communication modes,

+classic or [simplified](simplified-compute-node-communication.md). In the classic node communication model, the Batch service

+initiates communication to the compute nodes, and compute nodes also require communicating to Azure Storage. In the simplified

+node communication model, compute nodes initiate communication with the Batch service. Due to the reduced scope of

+inbound/outbound connections required, and not requiring Azure Storage outbound access for baseline operation, the recommendation

+is to use the simplified node communication model. Some future improvements to the Batch service will also require the simplified

+node communication model.

+- **Images with impending end-of-life (EOL) dates:** We strongly recommended avoiding images with impending Batch support

+end of life (EOL) dates. These dates can be discovered via the

+[`ListSupportedImages` API](/rest/api/batchservice/account/listsupportedimages),

+[PowerShell](/powershell/module/az.batch/get-azbatchsupportedimage), or

+[Azure CLI](/cli/azure/batch/pool/supported-images). It's your responsibility to periodically refresh your view of the EOL

+dates pertinent to your pools and migrate your workloads before the EOL date occurs. If you're using a custom image with a

+specified node agent, ensure that you follow Batch support end-of-life dates for the image for which your custom image is

+derived or aligned with. An image without a specified `batchSupportEndOfLife` date indicates that such a date hasn't been

+determined yet by the Batch service. Absence of a date doesn't indicate that the respective image will be supported

+indefinitely. An EOL date may be added or updated in the future at any time.

+Many security features are only available for pools configured using [Virtual Machine Configuration](nodes-and-pools.md#configurations), and not for pools with Cloud Services Configuration. We recommend using Virtual Machine Configuration pools, which utilize [Virtual Machine Scale Sets](../virtual-machine-scale-sets/overview.md), whenever possible.

+Pools can also be configured in one of two node communication modes, classic or [simplified](simplified-compute-node-communication.md).

+In the classic node communication model, the Batch service initiates communication to the compute nodes, and compute nodes

+also require communicating to Azure Storage. In the simplified node communication model, compute nodes initiate communication

+with the Batch service. Due to the reduced scope of inbound/outbound connections required, and not requiring Azure Storage

+outbound access for baseline operation, the recommendation is to use the simplified node communication model.

+- **Batch service**: The default option, where the underlying Cloud Service or Virtual Machine Scale Set resources used to allocate and manage pool nodes are created on Batch-owned subscriptions, and aren't directly visible in the Azure portal. Only the Batch pools and nodes are visible.

+- **User subscription**: The underlying Cloud Service or Virtual Machine Scale Set resources are created in the same subscription as the Batch account. These resources are therefore visible in the subscription, in addition to the corresponding Batch resources.

+With user subscription mode, Batch VMs and other resources are created directly in your subscription when a pool is created. User subscription mode is required if you want to create Batch pools using Azure Reserved VM Instances, use Azure Policy on Virtual Machine Scale Set resources, and/or manage the core quota on the subscription (shared across all Batch accounts in the subscription). To create a Batch account in user subscription mode, you must also register your subscription with Azure Batch, and associate the account with an Azure Key Vault.

+By default, endpoints with public IP addresses are used to communicate with Batch accounts, Batch pools, and pool nodes.

+By default, the public IP addresses associated with pools are dynamic; they're created when a pool is created

+and IP addresses can be added or removed when a pool is resized. When the task applications running on pool

+nodes need to access external services, access to those services may need to be restricted to specific IPs.

+In this case, having dynamic IP addresses won't be manageable.

+Use [Pool managed identities](managed-identity-pools.md) with the appropriate access permissions configured for the

+user-assigned managed identity to access Azure services that support managed identity, including Azure Key Vault. If

+you need to provision certificates on Batch nodes, utilize the available Azure Key Vault VM extension with pool

+Managed Identity to install and manage certificates on your Batch pool. For more information on deploying certificates

+from Azure Key Vault with Managed Identity on Batch pools, see

+[Enable automatic certificate rotation in a Batch pool](automatic-certificate-rotation.md).

+- Indirectly, using the Microsoft.Compute/virtualMachineScaleSets resource. Batch accounts with user subscription pool allocation mode can have policy set on the Virtual Machine Scale Set resources that are created in the Batch account subscription. For example, allowed VM sizes and ensure certain extensions are run on each pool node.

+| Description | Adds a time delay before, between, or after other actions. This fault is useful for waiting for the impact of a fault to appear in a service, or for waiting for an activity outside of the experiment to complete. For example, waiting for autohealing to occur before injecting another fault. |

+| Description | Adds CPU pressure, up to the specified value, on the VM where this fault is injected during the fault action. The artificial CPU pressure is removed at the end of the duration or if the experiment is canceled. On Windows, the "% Processor Utility" performance counter is used at fault start to determine current CPU percentage, which is subtracted from the `pressureLevel` defined in the fault so that % Processor Utility will hit approximately the `pressureLevel` defined in the fault parameters. |

+| virtualMachineScaleSetInstances | An array of instance IDs when applying this fault to a Virtual Machine Scale Set. Required for Virtual Machine Scale Sets. |

+| Description | Add physical memory pressure up to the specified value on the VM where this fault is injected during of the fault action. The artificial physical memory pressure is removed at the end of the duration or if the experiment is canceled. |

+| virtualMachineScaleSetInstances | An array of instance IDs when applying this fault to a Virtual Machine Scale Set. Required for Virtual Machine Scale Sets. |

+| Description | Add virtual memory pressure up to the specified value on the VM where this fault is injected during the fault action. The artificial virtual memory pressure is removed at the end of the duration or if the experiment is canceled. |

+| Description | Uses the [diskspd utility](https://github.com/Microsoft/diskspd/wiki) to add disk pressure to the primary storage of the VM where it's injected during the fault action. This fault has five different modes of execution. The artificial disk pressure is removed at the end of the duration or if the experiment is canceled. |

+| workerCount | Number of worker processes to run. Setting `workerCount` to 0 will generate as many worker processes as there are number of processors. |

+| Description | Uses the Windows Service Controller APIs to stop a Windows service during the fault, restarting it at the end of the duration or if the experiment is canceled. |

+| serviceName | The name of the Windows service you want to stop. You can run `sc.exe query` in command prompt to explore service names, Windows service friendly names aren't supported. |

+| Description | Changes the system time of the VM where it's injected, and resets the time at the end of the expiriment or if the experiment is canceled. |

+| dateTime | A DateTime string in [ISO8601 format](https://www.cryptosys.net/pki/manpki/pki_iso8601datetime.html). If YYYY-MM-DD values are missing, they're defaulted to the current day when the experiment runs. If Thh:mm:ss values are missing, the default value is 12:00:00 AM. If a 2-digit year is provided (YY), it's converted to a 4-digit year (YYYY) based on the current century. If \<Z\> is missing, it's defaulted to the offset of the local timezone. \<Z\> must always include a sign symbol (negative or positive). |

+| Description | Substitutes DNS lookup request responses with a specified error code. DNS lookup requests that will be substituted must:<ul><li>Originate from the VM</li><li>Match the defined fault parameters</li></ul>**Note**: DNS lookups that aren't made by the Windows DNS client won't be affected by this fault. |

+| hosts | Delimited JSON array of host names to fail DNS lookup request for.<br><br>This property accepts wildcards (`*`), but only for the first subdomain in an address and only applies to the subdomain for which they're specified. For example:<ul><li>\*.microsoft.com is supported</li><li>subdomain.\*.microsoft isn't supported</li><li>\*.microsoft.com won't account for multiple subdomains in an address such as subdomain1.subdomain2.microsoft.com.</li></ul> |

+| Prerequisites | Agent must be run as administrator. If the agent is installed as a VM extension, it runs as administrator by default. |

+| destinationFilters | Delimited JSON array of packet filters defining which outbound packets to target for fault injection. Maximum of 16. |

+| Prerequisites | Agent must be run as administrator. If the agent is installed as a VM extension, it runs as administrator by default. |

+| destinationFilters | Delimited JSON array of packet filters defining which outbound packets to target for fault injection. Maximum of 16. |

+| Prerequisites | Agent must be run as administrator. If the agent is installed as a VM extension, it runs as administrator by default. |

+| Description | Shuts down a VM for the duration of the fault, and restarts it at the end of the expiriment or if the experiment is canceled. Only Azure Resource Manager VMs are supported. |

+| Description | Shuts down or kills a virtual machine scale set instance during the fault, and restarts the VM at the end of the fault duration or if the experiment is canceled. |

+| jsonSpec | A JSON-formatted and, if created via ARM template, REST API, or Azure CLI, JSON-escaped Chaos Mesh spec that uses the [NetworkChaos kind](https://chaos-mesh.org/docs/simulate-network-chaos-on-kubernetes/#create-experiments-using-the-yaml-files). You can use a YAML-to-JSON converter like [Convert YAML To JSON](https://www.convertjson.com/yaml-to-json.htm) to convert the Chaos Mesh YAML to JSON and minify it. Then use a JSON string escape tool like [JSON Escape / Unescape](https://www.freeformatter.com/json-escape.html) to escape the JSON spec. Only include the YAML under the "jsonSpec" property, don't include metadata, kind, etc. |

+| jsonSpec | A JSON-formatted and, if created via ARM template, REST API, or Azure CLI, JSON-escaped Chaos Mesh spec that uses the [PodChaos kind](https://chaos-mesh.org/docs/simulate-pod-chaos-on-kubernetes/#create-experiments-using-yaml-configuration-files). You can use a YAML-to-JSON converter like [Convert YAML To JSON](https://www.convertjson.com/yaml-to-json.htm) to convert the Chaos Mesh YAML to JSON and minify it. Then use a JSON string escape tool like [JSON Escape / Unescape](https://www.freeformatter.com/json-escape.html) to escape the JSON spec. Only include the YAML under the "jsonSpec" property, don't include metadata, kind, etc. |

+| jsonSpec | A JSON-formatted and, if created via ARM template, REST API, or Azure CLI, JSON-escaped Chaos Mesh spec that uses the [StressChaos kind](https://chaos-mesh.org/docs/simulate-heavy-stress-on-kubernetes/#create-experiments-using-the-yaml-file). You can use a YAML-to-JSON converter like [Convert YAML To JSON](https://www.convertjson.com/yaml-to-json.htm) to convert the Chaos Mesh YAML to JSON and minify it. Then use a JSON string escape tool like [JSON Escape / Unescape](https://www.freeformatter.com/json-escape.html) to escape the JSON spec. Only include the YAML under the "jsonSpec" property, don't include metadata, kind, etc. |

+| jsonSpec | A JSON-formatted and, if created via ARM template, REST API, or Azure CLI, JSON-escaped Chaos Mesh spec that uses the [IOChaos kind](https://chaos-mesh.org/docs/simulate-io-chaos-on-kubernetes/#create-experiments-using-the-yaml-files). You can use a YAML-to-JSON converter like [Convert YAML To JSON](https://www.convertjson.com/yaml-to-json.htm) to convert the Chaos Mesh YAML to JSON and minify it. Then use a JSON string escape tool like [JSON Escape / Unescape](https://www.freeformatter.com/json-escape.html) to escape the JSON spec. Only include the YAML under the "jsonSpec" property, don't include metadata, kind, etc. |

+| jsonSpec | A JSON-formatted and, if created via ARM template, REST API, or Azure CLI, JSON-escaped Chaos Mesh spec that uses the [TimeChaos kind](https://chaos-mesh.org/docs/simulate-time-chaos-on-kubernetes/#create-experiments-using-the-yaml-file). You can use a YAML-to-JSON converter like [Convert YAML To JSON](https://www.convertjson.com/yaml-to-json.htm) to convert the Chaos Mesh YAML to JSON and minify it. Then use a JSON string escape tool like [JSON Escape / Unescape](https://www.freeformatter.com/json-escape.html) to escape the JSON spec. Only include the YAML under the "jsonSpec" property, don't include metadata, kind, etc. |

+| jsonSpec | A JSON-formatted and, if created via ARM template, REST API, or Azure CLI, JSON-escaped Chaos Mesh spec that uses the [KernelChaos kind](https://chaos-mesh.org/docs/simulate-kernel-chaos-on-kubernetes/#configuration-file).You can use a YAML-to-JSON converter like [Convert YAML To JSON](https://www.convertjson.com/yaml-to-json.htm) to convert the Chaos Mesh YAML to JSON and minify it. Then use a JSON string escape tool like [JSON Escape / Unescape](https://www.freeformatter.com/json-escape.html) to escape the JSON spec. Only include the YAML under the "jsonSpec" property, don't include metadata, kind, etc. |

+| jsonSpec | A JSON-formatted and, if created via ARM template, REST API, or Azure CLI, JSON-escaped Chaos Mesh spec that uses the [HTTPChaos kind](https://chaos-mesh.org/docs/simulate-http-chaos-on-kubernetes/#create-experiments). You can use a YAML-to-JSON converter like [Convert YAML To JSON](https://www.convertjson.com/yaml-to-json.htm) to convert the Chaos Mesh YAML to JSON and minify it. Then use a JSON string escape tool like [JSON Escape / Unescape](https://www.freeformatter.com/json-escape.html) to escape the JSON spec. Only include the YAML under the "jsonSpec" property, don't include metadata, kind, etc. |

+| jsonSpec | A JSON-formatted and, if created via ARM template, REST API, or Azure CLI, JSON-escaped Chaos Mesh spec that uses the [DNSChaos kind](https://chaos-mesh.org/docs/simulate-dns-chaos-on-kubernetes/#create-experiments-using-the-yaml-file). You can use a YAML-to-JSON converter like [Convert YAML To JSON](https://www.convertjson.com/yaml-to-json.htm) to convert the Chaos Mesh YAML to JSON and minify it. Then use a JSON string escape tool like [JSON Escape / Unescape](https://www.freeformatter.com/json-escape.html) to escape the JSON spec. Only include the YAML under the "jsonSpec" property, don't include metadata, kind, etc. |

+| Description | Enables manipulation or rule creation in an existing Azure Network Security Group or set of Azure Network Security Groups, assuming the rule definition is applicable cross security groups. Useful for simulating an outage of a downstream or cross-region dependency/non-dependency, simulating an event that's expected to trigger a logic to force a service failover, simulating an event that is expected to trigger an action from a monitoring or state management service, or as an alternative for blocking or allowing network traffic where Chaos Agent can't be deployed. |

+* When an NSG rule that is intended to deny traffic is applied existing connections won't be broken until they've been **idle** for 4 minutes. One workaround is to add another branch in the same step that uses a fault that would cause existing connections to break when the NSG fault is applied. For example, killing the process, temporarily stopping the service, or restarting the VM would cause connections to reset.

+* Creating or modifying Application Security Group rules isn't supported.

+| Prerequisites | The target Azure Cache for Redis resource must be a Redis Cluster, which requires that the cache must be a Premium Tier cache. Standard and Basic Tiers aren't supported. |

+* The reboot fault is a **discrete** fault type. Unlike continuous faults, it's a one-time action and therefore has no duration.

+| Description | Stops a deployment during the fault and restarts the deployment at the end of the fault duration or if the experiment is canceled. |

+| Prerequisites | The target Key Vault can't have any firewall rules and must not be set to allow Azure services to bypass the firewall. If the target Key Vault is set to only allow access from selected networks, there must be at least one virtual network rule. The Key Vault can't be in recover mode. |

+1. Register the `Microsoft.ContainerInstance` resource provider with your subscription (if applicable).

+ ```bash

+ az provider register --namespace 'Microsoft.ContainerInstance' --wait

+ ```

+ Verify the registration by running the following command:

+ ```bash

+ az provider show --namespace 'Microsoft.ContainerInstance' | grep registrationState

+ ```

+ You should see output similar to the following:

+ ```bash

+ "registrationState": "Registered",

+ ```

+2. Re-register the `Microsoft.Chaos` resource provider with your subscription.

+ ```bash

+ az provider register --namespace 'Microsoft.Chaos' --wait

+ ```

+ Verify the registration by running the following command:

+ ```bash

+ az provider show --namespace 'Microsoft.Chaos' | grep registrationState

+ ```

+ You should see output similar to the following:

+ ```bash

+ "registrationState": "Registered",

+ ```

+3. Create a subnet named `ChaosStudioSubnet` in the VNet you want to inject into. And delegate the subnet to `Microsoft.ContainerInstance/containerGroups` service.

+4. Set the `properties.subnetId` property when you create or update the Target resource. The value should be the resource ID of the subnet created in step 3.

+ Replace `$SUBSCRIPTION_ID` with your Azure subscription ID, `$RESOURCE_GROUP` and `$AKS_CLUSTER` with the resource group name and your AKS cluster resource name. Also, replace `$AKS_INFRA_RESOURCE_GROUP` and `$AKS_VNET` with your AKS's infrastructure resource group name and VNet name.

+ ```bash

+ URL=https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.ContainerService/managedClusters/$AKS_CLUSTER/providers/Microsoft.Chaos/targets/microsoft-azurekubernetesservicechaosmesh?api-version=2022-10-01-preview

+ SUBNET_ID=/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$AKS_INFRA_RESOURCE_GROUP/providers/Microsoft.Network/virtualNetworks/$AKS_VNET/subnets/ChaosStudioSubnet

+ BODY="{ \"properties\": { \"subnetId\": \"$SUBNET_ID\" } }"

+ az rest --method put --url $URL --body "$BODY"

+ ```

+## Create an Azure resource supported by Chaos Studio

+Create an azure resource and ensure this is one of the supported [fault providers](chaos-studio-fault-providers.md). Also validate if this resource is being created in the [region](https://azure.microsoft.com/global-infrastructure/services/?products=chaos-studio) where Chaos Studio is available. In this experiment we choose an Azure Virtual Machine which is one of the supported fault providers for Chaos Studio.

+ "value": "/subscriptions/<subscription-id>/resourceGroups/<rg-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/providers/Microsoft.Chaos/targets/microsoft-cosmosdb"

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Embed Azure Cloud Shell

+Embedding Cloud Shell enables developers and content writers to directly open Cloud Shell from a

+dedicated URL, `shell.azure.com`. This link brings the full power of Cloud Shell's authentication,

+tooling, and up-to-date Azure CLI and Azure PowerShell tools to your users.

+You can use the following images in your own webpages and app as buttons to start a Cloud Shell

+session.

+

+

+To integrate Cloud Shell's launch button into markdown files by copying the following code:

+Regular sized button

+[

+Large sized button

+```markdown

+[

+The location of these image files is subject to change. We recommend that you download the files for

+use in your applications.

+| Experience | URL |

+| | |

+| Most recently used shell | `https://shell.azure.com` |

+| Bash | `https://shell.azure.com/bash` |

+| PowerShell | `https://shell.azure.com/powershell` |

+- [Bash in Cloud Shell quickstart][07]

+- [PowerShell in Cloud Shell quickstart][06]

+<!-- updated link references -->

+[01]: https://shell.azure.com

+[06]: quickstart-powershell.md

+[07]: quickstart.md

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Azure Cloud Shell features

+Azure Cloud Shell is a browser-based shell experience to manage and develop Azure resources.

+Cloud Shell offers a browser-accessible, pre-configured shell experience for managing Azure

+resources without the overhead of installing, versioning, and maintaining a machine yourself.

+Cloud Shell allocates machines on a per-request basis and as a result machine state doesn't

+persist across sessions. Since Cloud Shell is built for interactive sessions, shells automatically

+terminate after 20 minutes of shell inactivity.

+<!--

+TODO:

+- need to verify Distro - showing Ubuntu currently

+- need to verify all experiences described here eg. cd Azure: - I have different results

+-->

+Azure Cloud Shell runs on **Common Base Linux - Mariner** (CBL-Mariner), Microsoft's Linux

+distribution for cloud-infrastructure-edge products and services.

+`tdnf list installed`. If these changes affected your Cloud Shell environment, contact Azure Support

+or create an issue in the [Cloud Shell repository][12].

+Cloud Shell securely and automatically authenticates account access for the Azure CLI and Azure

+PowerShell.

+To persist files across sessions, Cloud Shell walks you through attaching an Azure file share on

+first launch. Once completed, Cloud Shell will automatically attach your storage (mounted as

+`$HOME\clouddrive`) for all future sessions. Additionally, your `$HOME` directory is persisted as an

+.img in your Azure File share. Files outside of `$HOME` and machine state aren't persisted across

+sessions. Use best practices when storing secrets such as SSH keys. Services, like

+Azure Key Vault, have [tutorials for setup][02].

+[Learn more about persisting files in Cloud Shell.][29]

+PowerShell in Cloud Shell provides the Azure drive (`Azure:`). You can switch to the Azure drive

+with `cd Azure:` and back to your home directory with `cd ~`. The Azure drive enables easy

+discovery and navigation of Azure resources such as Compute, Network, Storage etc. similar to

+filesystem navigation. You can continue to use the familiar [Azure PowerShell cmdlets][07] to manage

+these resources regardless of the drive you are in. Any changes made to the Azure resources, either

+made directly in Azure portal or through Azure PowerShell cmdlets, are reflected in the Azure drive.

+You can run `dir -Force` to refresh your resources.

+![Screenshot of an Azure Cloud Shell being initialized and a list of directory resources.][26]

+PowerShell in Cloud Shell contains a private build of the Exchange Online module. Run

+`Connect-EXOPSSession` to get your Exchange cmdlets.

+![Screenshot of an Azure Cloud Shell running the commands Connect-EXOPSSession and Get-User.][27]

+> The module name should begin with `tmp_`, if you have installed modules with the same prefix,

+> their cmdlets will also be surfaced.

+![Screenshot of an Azure Cloud Shell running the command Get-Command -Module tmp_*.][28]

+### Deep integration with open source tooling

+Cloud Shell includes pre-configured authentication for open source tools such as Terraform, Ansible,

+and Chef InSpec. Try it out from the example walkthroughs.

+### Pre-installed tools

+<!--

+TODO:

+- remove obsolete tools

+- separate by bash vs. pwsh

+- link to docs rather than github

+-->

+Linux tools

+- bash

+- zsh

+- sh

+- tmux

+- dig

+Azure tools

+- [Azure CLI][09]

+- [AzCopy][04]

+- [Azure Functions CLI][05]

+- [Service Fabric CLI][03]

+- [Batch Shipyard][10]

+- [blobxfer][11]

+Text editors

+- code (Cloud Shell editor)

+- vim

+- nano

+- emacs

+Source control

+- git

+Build tools

+- make

+- maven

+- npm

+- pip

+Containers

+- [Docker Desktop][15]

+- [Kubectl][19]

+- [Helm][17]

+- [DC/OS CLI][14]

+Databases

+- MySQL client

+- PostgreSql client

+- [sqlcmd Utility][09]

+- [mssql-scripter][18]

+Other

+- iPython Client

+- [Cloud Foundry CLI][13]

+- [Terraform][25]

+- [Ansible][22]

+- [Chef InSpec][23]

+- [Puppet Bolt][21]

+- [HashiCorp Packer][24]

+- [Office 365 CLI][20]

+### Language support

+| Language | Version |

+| - | |

+| .NET Core | [6.0.402][16] |

+| Go | 1.9 |

+| Java | 1.8 |

+| Node.js | 8.16.0 |

+| PowerShell | [7.2][08] |

+| Python | 2.7 and 3.7 (default) |

+- [Bash in Cloud Shell Quickstart][31]

+- [PowerShell in Cloud Shell Quickstart][30]

+- [Learn about Azure CLI][06]

+- [Learn about Azure PowerShell][07]

+<!-- link references -->

+[02]: ../key-vault/general/manage-with-cli2.md#prerequisites

+[03]: ../service-fabric/service-fabric-cli.md

+[04]: ../storage/common/storage-use-azcopy-v10.md

+[05]: /azure/azure-functions/functions-run-local

+[06]: /cli/azure/

+[07]: /powershell/azure

+[08]: /powershell/scripting/whats-new/what-s-new-in-powershell-72

+[09]: /sql/tools/sqlcmd-utility

+[10]: https://batch-shipyard.readthedocs.io/en/latest/

+[11]: https://blobxfer.readthedocs.io/en/latest/

+[12]: https://github.com/Azure/CloudShell/issues

+[13]: https://docs.cloudfoundry.org/cf-cli/

+[14]: https://docs.d2iq.com/dkp/2.3/azure-quick-start

+[15]: https://docs.docker.com/desktop/

+[16]: https://dotnet.microsoft.com/download/dotnet/6.0

+[17]: https://helm.sh/docs/

+[18]: https://github.com/microsoft/mssql-scripter/blob/dev/doc/usage_guide.md

+[19]: https://kubernetes.io/docs/user-guide/kubectl-overview/

+[20]: https://pnp.github.io/office365-cli/

+[21]: https://puppet.com/docs/bolt/latest/bolt.html

+[22]: https://www.ansible.com/microsoft-azure

+[23]: https://docs.chef.io/

+[24]: https://developer.hashicorp.com/packer/docs

+[25]: https://www.terraform.io/docs/providers/azurerm/

+[26]: media/features/azure-drive.png

+[27]: media/features/exchangeonline.png

+[28]: medilets.png

+[29]: persisting-shell-storage.md

+[30]: quickstart-powershell.md

+[31]: quickstart.md

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Azure Cloud Shell limitations

+<!--

+TODO:

+- verify the regions

+-->

+The machine that provides your Cloud Shell session is temporary, and it's recycled after your

+session is inactive for 20 minutes. Cloud Shell requires an Azure file share to be mounted. As a

+result, your subscription must be able to set up storage resources to access Cloud Shell. Other

+considerations include:

+- With mounted storage, only modifications within the `$HOME` directory are persisted.

+- Azure file shares can be mounted only from within your [assigned region][02].

+ - In Bash, run `env` to find your region set as `ACC_LOCATION`.

+<!--

+TODO:

+- Do we still support Microsoft Internet Explorer?

+-->

+Cloud Shell supports the latest versions of Microsoft Edge, Microsoft Internet Explorer, Google

+Chrome, Mozilla Firefox, and Apple Safari. Safari in private mode isn't supported.

+- Windows: <kbd>Ctrl</kbd>-<kbd>C</kbd> to copy is supported but use

+ <kbd>Shift</kbd>-<kbd>Insert</kbd> to paste.

+ - FireFox/IE may not support clipboard permissions properly.

+- macOS: <kbd>Cmd</kbd>-<kbd>C</kbd> to copy and <kbd>Cmd</kbd>-<kbd>V</kbd> to paste.

+### Only one shell can be active for a given user

+Users can only launch one Cloud Shell session at a time. However, you may have multiple instances of

+Bash or PowerShell running within that session. Switching between Bash or PowerShell using the menu

+restarts the Cloud Shell session and terminate the existing session. To avoid losing your current

+session, you can run `bash` inside PowerShell and you can run `pwsh` inside of Bash.

+Cloud Shell is intended for interactive use cases. As a result, any long-running non-interactive

+sessions are ended without warning.

+Permissions are set as regular users without sudo access. Any installation outside your `$Home`

+directory isn't persisted.

+<!--

+TODO:

+- outdated info about AzureAD and SQL

+- Not running on Windows so the GUI comment not valid

+-->

+The `AzureAD` module name is currently `AzureAD.Standard.Preview`, the module provides the same

+functionality.

+The `SqlServer` module included in Cloud Shell has only prerelease support for PowerShell Core. In

+particular, `Invoke-SqlCmd` isn't available yet.

+### Default file location when created from Azure drive

+You can't create files under the `Azure:` drive. When users create new files using other tools, such

+as vim or nano, the files are saved to the `$HOME` by default.

+### GUI applications aren't supported

+If the user runs a command that would create a dialog box, one sees an error message such

+as:

+> Unable to load DLL 'IEFRAME.dll': The specified module couldn't be found.

+When the user performs an action that displays a progress bar, such as a tab completing while in the

+`Azure:` drive, it's possible that the cursor isn't set properly and a gap appears where the

+progress bar was previously.

+- [Troubleshooting Cloud Shell][05]

+- [Quickstart for Bash][04]

+- [Quickstart for PowerShell][03]

+<!-- link references -->

+[02]: persisting-shell-storage.md#mount-a-new-clouddrive

+[03]: quickstart-powershell.md

+[04]: quickstart.md

+[05]: troubleshooting.md

+description: How to acquire a token for the authenticated user in Azure Cloud Shell

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Acquiring a user token in Azure Cloud Shell

+<!--

+TODO:

+- MSI is never mentioned in this article - what is it?

+- Need powershell example - there are examples in other articles - be consistent

+-->

+Azure Cloud Shell provides an endpoint that automatically authenticates the user logged into the

+Azure portal. Use this endpoint to acquire access tokens to interact with Azure services.

+The Azure Cloud Shell has its own endpoint that interacts with your browser to automatically log you

+in. When this endpoint receives a request, it sends the request back to your browser, which forwards

+it to the parent Portal frame. The Portal window makes a request to Azure Active Directory, and the

+resulting token is returned.

+If you want to authenticate with different credentials, you can do so using `az login` or

+`Connect-AzAccount`

+Execute the following commands to set your user access token as an environment variable,

+`access_token`.

+```bash

+Execute the following command to get a list of all Virtual Machines in your account, using the token

+you acquired in the previous step.

+```bash

+The local authentication endpoint caches tokens. You can call it as often as you like. Cloud Shell

+only calls Azure Active Directory only occurs when there's no token stored in the cache or the token

+has expired.

+- There's an allowlist of resources that Cloud Shell tokens can be provided for. When you try to use

+ a token with a service that is not listed, you may see the following error message:

+ ```

+ "error":{"code":"AudienceNotSupported","message":"Audience https://newservice.azure.com/

+ isn't a supported MSI token audience...."}

+ ```

+ You can open an issue on [GitHub][02] to request for the service to be added to the allowlist.

+- If you sign in explicitly using the `az login` command, any Conditional Access rules your company

+ may have in place are evaluated based on the Cloud Shell container rather than the machine where

+ your browser runs. The Cloud Shell container doesn't count as a managed device for these policies

+ so rights may be limited by the policy.

+- Azure Managed Identities aren't available in the Azure Cloud Shell. Read more about

+ [Azure Managed Identities][01].

+<!-- link references -->

+[01]: ../active-directory/managed-identities-azure-resources/overview.md

+[02]: https://github.com/Azure/CloudShell/issues

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Azure Cloud Shell overview

+Azure Cloud Shell is an interactive, authenticated, browser-accessible shell for managing Azure

+resources. It provides the flexibility of choosing the shell experience that best suits the way you

+work, either Bash or PowerShell.

+You can access Cloud Shell in three ways:

+- **Direct link**: Open a browser to [https://shell.azure.com][11].

+- **Azure portal**: Select the Cloud Shell icon on the [Azure portal][10]:

+ ![Icon to launch Cloud Shell from the Azure portal][14]

+- **Code samples**: In Microsoft [technical documentation][02] and [training resources][05], select

+ the **Try It** button that appears with Azure CLI and Azure PowerShell code snippets:

+ The **Try It** button opens Cloud Shell directly alongside the documentation using Bash (for

+ Azure CLI snippets) or PowerShell (for Azure PowerShell snippets).

+ To run the command, use **Copy** in the code snippet, use

+ <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>V</kbd> (Windows/Linux) or

+ <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>V</kbd> (macOS) to paste the command, and then press

+ <kbd>Enter</kbd>.

+Cloud Shell enables access to a browser-based command-line experience built with Azure management

+tasks in mind. Use Cloud Shell to work untethered from a local machine in a way only the cloud

+can provide.

+ ![Cloud Shell icon][13]

+1. Select **Bash** or **PowerShell**.

+ ![Choose either Bash or PowerShell][12]

+ After first launch, you can use the shell type drop-down control to switch between Bash and

+ PowerShell:

+ ![Drop-down control to select Bash or PowerShell][15]

+Cloud Shell is managed by Microsoft so it comes with popular command-line tools and language

+support. Cloud Shell also securely authenticates automatically for instant access to your resources

+through the Azure CLI or Azure PowerShell cmdlets.

+View the full [list of tools installed in Cloud Shell.][07]

+Cloud Shell offers an integrated graphical text editor based on the open source Monaco Editor.

+Create and edit configuration files by running `code .` for seamless deployment through Azure CLI or

+Azure PowerShell.

+[Learn more about the Cloud Shell editor][20].

+- [portal.azure.com][10]

+- [shell.azure.com][11]

+- [Azure CLI documentation][03]

+- [Azure PowerShell documentation][04]

+- [Azure mobile app][08]

+- [Visual Studio Code Azure Account extension][09]

+Cloud Shell machines are temporary, but your files are persisted in two ways: through a disk image,

+and through a mounted file share named `clouddrive`. On first launch, Cloud Shell prompts to create

+a resource group, storage account, and Azure Files share on your behalf. This is a one-time step and

+the resources created are automatically attached for all future sessions. A single file share can be

+mapped and is used by both Bash and PowerShell in Cloud Shell.

+Read more to learn how to mount a [new or existing storage account][16] or to learn about the

+[persistence mechanisms used in Cloud Shell][17].

+> Azure storage firewall isn't supported for cloud shell storage accounts.

+- Cloud Shell runs on a temporary host provided on a per-session, per-user basis

+- Cloud Shell times out after 20 minutes without interactive activity

+- Cloud Shell requires an Azure file share to be mounted

+- Cloud Shell uses the same Azure file share for both Bash and PowerShell

+- Cloud Shell is assigned one machine per user account

+- Cloud Shell persists $HOME using a 5-GB image held in your file share

+- Permissions are set as a regular Linux user in Bash

+Learn more about features in [Bash in Cloud Shell][06] and [PowerShell in Cloud Shell][01].

+All Cloud Shell infrastructure is compliant with double encryption at rest by default. No action is

+required by users.

+The machine hosting Cloud Shell is free, with a pre-requisite of a mounted Azure Files share.

+Regular storage costs apply.

+- [Bash in Cloud Shell quickstart][19]

+- [PowerShell in Cloud Shell quickstart][18]

+<!-- link references -->

+[01]: ./features.md

+[02]: /samples/browse

+[03]: /cli/azure

+[04]: /powershell/azure

+[05]: /training

+[06]: features.md

+[07]: features.md#pre-installed-tools

+[08]: https://azure.microsoft.com/features/azure-portal/mobile-app/

+[09]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account

+[10]: https://portal.azure.com

+[11]: https://shell.azure.com

+[12]: media/overview/overview-choices.png

+[13]: media/overview/overview-cloudshell-icon.png

+[14]: media/overview/portal-launch-icon.png

+[15]: media/overview/select-shell-drop-down.png

+[16]: persisting-shell-storage.md

+[17]: persisting-shell-storage.md#how-cloud-shell-storage-works

+[18]: quickstart-powershell.md

+[19]: quickstart.md

+[20]: using-cloud-shell-editor.md

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Persist files in Azure Cloud Shell

+Cloud Shell uses Azure Files to persist files across sessions. On initial start, Cloud Shell prompts

+you to associate a new or existing fileshare to persist files across sessions.

+> Bash and PowerShell share the same fileshare. Only one fileshare can be associated with

+> automatic mounting in Cloud Shell.

+>

+> Azure storage firewall isn't supported for cloud shell storage accounts.

+When you use basic settings and select only a subscription, Cloud Shell creates three resources on

+your behalf in the supported region that's nearest to you:

+- Resource group: `cloud-shell-storage-<region>`

+- Storage account: `cs<uniqueGuid>`

+- fileshare: `cs-<user>-<domain>-com-<uniqueGuid>`

+![Screenshot of choosing the subscription for your storage account][09]

+The fileshare mounts as `clouddrive` in your `$HOME` directory. This is a one-time action, and the

+fileshare mounts automatically in subsequent sessions.

+The fileshare also contains a 5-GB image that automatically persists data in your `$HOME` directory.

+This fileshare is used for both Bash and PowerShell.

+Using the advanced option, you can associate existing resources. When selecting a Cloud Shell region,

+you must select a backing storage account co-located in the same region. For example, if your

+assigned region is West US then you must associate a fileshare that resides within West US as well.

+When the storage setup prompt appears, select **Show advanced settings** to view more options. The

+populated storage options filter for locally redundant storage (LRS), geo-redundant storage (GRS),

+and zone-redundant storage (ZRS) accounts.

+> Using GRS or ZRS storage accounts are recommended for additional resiliency for your backing file

+> share. Which type of redundancy depends on your goals and price preference.

+> [Learn more about replication options for Azure Storage accounts][04].

+![Screenshot of configuring your storage account][08]

+For security, each user should create their own storage account. For Azure role-based access control

+(Azure RBAC), users must have contributor access or above at the storage account level.

+Cloud Shell uses an Azure fileshare in a storage account, inside a specified subscription. Due to

+inherited permissions, users with sufficient access rights to the subscription can access all the

+storage accounts, and file shares contained in the subscription.

+Users should lock down access to their files by setting the permissions at the storage account or

+the subscription level.

+The Cloud Shell storage account contains files created by the Cloud Shell user in their home

+directory, which may include sensitive information including access tokens or credentials.

+To find your current region you may run `env` in Bash and locate the variable `ACC_LOCATION`, or

+from PowerShell run `$env:ACC_LOCATION`. File shares receive a 5-GB image created for you to persist

+your `$HOME` directory.

+| Area | Region |

+| | - |

+| Americas | East US, South Central US, West US |

+| Europe | North Europe, West Europe |

+| Asia Pacific | India Central, Southeast Asia |

+Customers should choose a primary region, unless they have a requirement that their data at rest be

+stored in a particular region. If they have such a requirement, a secondary storage region should be

+used.

+If a secondary storage region is used, the associated Azure storage account resides in a different

+region as the Cloud Shell machine that you're mounting them to. For example, you can set your

+storage account to be located in Canada East, a secondary region, but your Cloud Shell machine is

+still located in a primary region. Your data at rest is located in Canada, but it's processed in the

+United States.

+A user can run `(Get-CloudDrive | Get-AzStorageAccount).Location` in PowerShell to see the location

+of their fileshare.

+Storage accounts that you create in Cloud Shell are tagged with

+`ms-resource-usage:azure-cloud-shell`. If you want to disallow users from creating storage accounts

+in Cloud Shell, create an [Azure resource policy for tags][03] that is triggered by this specific

+tag.

+## How Cloud Shell storage works

+Cloud Shell persists files through both of the following methods:

+- Creating a disk image of your `$HOME` directory to persist all contents within the directory. The

+ disk image is saved in your specified fileshare as `acc_<User>.img` at

+ `fileshare.storage.windows.net/fileshare/.cloudconsole/acc_<User>.img`, and it automatically syncs

+ changes.

+- Mounting your specified fileshare as `clouddrive` in your `$HOME` directory for direct file-share

+ interaction. `/Home/<User>/clouddrive` is mapped to `fileshare.storage.windows.net/fileshare`.

+> All files in your `$HOME` directory, such as SSH keys, are persisted in your user disk image,

+> which is stored in your mounted fileshare. Apply best practices when you persist information in

+> your `$HOME` directory and mounted fileshare.

+In Cloud Shell, you can run a command called `clouddrive`, which enables you to manually update the

+fileshare that's mounted to Cloud Shell.

+![Screenshot of running the clouddrive command in bash][10]

+To discover which fileshare is mounted as `clouddrive`, run the `df` command.

+The file path to clouddrive shows your storage account name and fileshare in the URL. For example,

+`//storageaccountname.file.core.windows.net/filesharename`

+```bash

+You can update the fileshare that's associated with Cloud Shell using the `clouddrive mount`

+command.

+If you mount an existing fileshare, the storage accounts must be located in your select Cloud Shell

+region. Retrieve the location by running `env` and checking the `ACC_LOCATION`.

+> If you're mounting a new fileshare, a new user image is created for your `$HOME` directory. Your

+> previous `$HOME` image is kept in your previous fileshare.

+```bash

+![Screenshot of running the clouddrive mount command in bash][11]

+You can unmount a fileshare that's mounted to Cloud Shell at any time. Since Cloud Shell requires a

+mounted fileshare to be used, Cloud Shell prompts you to create and mount another fileshare on the

+next session.

+1. Acknowledge and confirm prompts.

+The unmounted fileshare continues to exist until you manually delete it. After unmounting, Cloud

+Shell no longer searches for this fileshare in subsequent sessions. To view more details, run

+`clouddrive unmount -h`, as shown here:

+![Screenshot of running the clouddrive unmount command in bash][12]

+> Although running this command doesn't delete any resources, manually deleting a resource group,

+> storage account, or fileshare that's mapped to Cloud Shell erases your `$HOME` directory disk

+> image and any files in your fileshare. This action can't be undone.

+The `Get-CloudDrive` cmdlet retrieves the Azure fileshare information currently mounted by the

+`clouddrive` in Cloud Shell.

+![Screenshot of running the Get-CloudDrive command in PowerShell][07]

+You can unmount an Azure fileshare that's mounted to Cloud Shell at any time. The

+`Dismount-CloudDrive` cmdlet unmounts an Azure fileshare from the current storage account.

+Dismounting the `clouddrive` terminates the current session.

+If the Azure fileshare has been removed, you'll be prompted to create and mount a new Azure

+fileshare in the next session.

+![Screenshot of running the Dismount-CloudDrive command in PowerShell][06]

+## Transfer local files to Cloud Shell

+The `clouddrive` directory syncs with the Azure portal storage blade. Use this blade to transfer

+local files to or from your file share. Updating files from within Cloud Shell is reflected in the

+file storage GUI when you refresh the blade.

+### Download files

+![Screenshot listing local files in the Azure portal][13]

+1. In the Azure portal, go to the mounted file share.

+2. Select the target file.

+3. Select the **Download** button.

+### Upload files

+![Screenshot showing how to upload files in the Azure portal][14]

+1. Go to your mounted file share.

+2. Select the **Upload** button.

+3. Select the file or files that you want to upload.

+4. Confirm the upload.

+You should now see the files that are accessible in your `clouddrive` directory in Cloud Shell.

+> [!NOTE]

+> If you need to define a function in a file and call it from the PowerShell cmdlets, then the

+> dot operator must be included. For example: `. .\MyFunctions.ps1`

+- [Cloud Shell Quickstart][15]

+- [Learn about Microsoft Azure Files storage][05]

+- [Learn about storage tags][02]

+<!-- link references -->

+[01]: includes/cloud-shell-persisting-shell-storage-endblock.md

+[02]: ../azure-resource-manager/management/tag-resources.md

+[03]: ../governance/policy/samples/index.md

+[04]: ../storage/common/storage-redundancy.md

+[05]: ../storage/files/storage-files-introduction.md

+[06]: media/persisting-shell-storage/dismount-clouddrive.png

+[07]: media/persisting-shell-storage/get-clouddrive.png

+[08]: media/persisting-shell-storage/advanced-storage.png

+[09]: media/persisting-shell-storage/basic-storage.png

+[10]: media/persisting-shell-storage/clouddrive-h.png

+[11]: media/persisting-shell-storage/mount-h.png

+[12]: media/persisting-shell-storage/unmount-h.png

+[13]: media/persisting-shell-storage/download.png

+[14]: media/persisting-shell-storage/upload.png

+[15]: quickstart.md

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Azure Cloud Shell pricing

+## Compute cost

+Azure Cloud Shell runs on a machine provided for free by Azure, but requires an Azure file share to

+use.

+## Storage cost

+Cloud Shell requires a new or existing Azure Files share to be mounted to persist files across

+sessions. Storage incurs regular costs.

+Check [here for details on Azure Files costs][01].

+<!-- link references -->

+[01]: https://azure.microsoft.com/pricing/details/storage/files/

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Cloud Shell in an Azure virtual network

+A regular Cloud Shell session runs in a container in a Microsoft network separate from your

+resources. Commands running inside the container can't access resources that can only be accessed

+from a specific virtual network. For example, you can't use SSH to connect from Cloud Shell to a

+virtual machine that only has a private IP address, or use `kubectl` to connect to a Kubernetes

+cluster that has locked down access.

+This optional feature addresses these limitations and allows you to deploy Cloud Shell into an Azure

+virtual network that you control. From there, the container is able to interact with resources

+within the virtual network you select.

+The following diagram shows the resource architecture that's deployed and used in this scenario.

+![Illustrates the Cloud Shell isolated VNET architecture.][06]

+Before you can use Cloud Shell in your own Azure Virtual Network, you need to create several

+resources. This article shows how to set up the required resources using an ARM template.

+> These resources only need to be set up once for the virtual network. They can then be shared by

+> all administrators with access to the virtual network.

+You need to identify the virtual network to be used for Cloud Shell. Usually, you want to use an

+existing virtual network that contains resources you want to manage or a network that peers with

+networks that contain your resources.

+Within the selected virtual network, a dedicated subnet must be used for Cloud Shell containers.

+This subnet is delegated to the Azure Container Instances (ACI) service. When a user requests a

+Cloud Shell container in a virtual network, Cloud Shell uses ACI to create a container that's in

+this delegated subnet. No other resources can be created in this subnet.

+A network profile is a network configuration template for Azure resources that specifies certain

+network properties for the resource.

+An [Azure Relay][01] allows two endpoints that aren't directly reachable to communicate. In this

+case, it's used to allow the administrator's browser to communicate with the container in the

+private network.

+The Azure Relay instance used for Cloud Shell can be configured to control which networks can access

+container resources:

+- Accessible from the public internet: In this configuration, Cloud Shell provides a way to reach

+ the internal resources from outside.

+- Accessible from specified networks: In this configuration, administrators must access the Azure

+ portal from a computer running in the appropriate network to be able to use Cloud Shell.

+As in standard Cloud Shell, a storage account is required while using Cloud Shell in a virtual

+network. Each administrator needs a fileshare to store their files. The storage account needs to be

+accessible from the virtual network that's used by Cloud Shell.

+- Starting Cloud Shell in a virtual network is typically slower than a standard Cloud Shell session.

+- All Cloud Shell primary regions, except Central India, are supported.

+- [Azure Relay][01] is a paid service. See the [pricing][04] guide. In the Cloud Shell scenario, one

+ hybrid connection is used for each administrator while they're using Cloud Shell. The connection

+ is automatically shut down after the Cloud Shell session is ended.

+The Microsoft.ContainerInstances resource provider needs to be registered in the subscription that

+holds the virtual network you want to use. Select the appropriate subscription with

+`Set-AzContext -Subscription {subscriptionName}`, and then run:

+If **RegistrationState** is `Registered`, no action is required. If it's `NotRegistered`, run

+`Register-AzResourceProvider -ProviderNamespace Microsoft.ContainerInstance`.

+In the Azure portal, or using Azure CLI, Azure PowerShell, etc. create a resource group and a

+virtual network in the new resource group, **the resource group and virtual network need to be in

+the same region**.

+Use the [Azure Quickstart Template][03] for creating Cloud Shell resources in a virtual network,

+and the [Azure Quickstart Template][05] for creating necessary storage. Take note of your resource

+names, primarily your fileshare name.

+By default the relay is only accessible from the virtual network where it was created. To open

+access, navigate to the relay created using the previous template, select "Networking" in settings,

+allow access from your browser network to the relay.

+> This step must be completed for each administrator that uses Cloud Shell.

+After deploying and completing the previous steps, open Cloud Shell. One of these experiences must

+be used each time you want to connect to an isolated Cloud Shell experience.

+> If Cloud Shell has been used in the past, the existing clouddrive must be unmounted. To do this

+> run `clouddrive unmount` from an active Cloud Shell session, refresh your page.

+Connect to Cloud Shell. You'll be prompted with the first run experience. Select your preferred

+shell experience, select **Show advanced settings** and select the **Show VNET isolation settings**

+box. Fill in the fields in the form. Most fields will be autofilled to the available resources that

+can be associated with Cloud Shell in a virtual network. You must provide a name for the fileshare.

+![Illustrates the Cloud Shell isolated VNET first experience settings.][07]

+[Learn about Azure Virtual Networks][02]

+<!-- link references -->

+[01]: ../azure-relay/relay-what-is-it.md

+[02]: ../virtual-network/virtual-networks-overview.md

+[03]: https://aka.ms/cloudshell/docs/vnet/template

+[04]: https://azure.microsoft.com/pricing/details/service-bus/

+[05]: https://azure.microsoft.com/resources/templates/cloud-shell-vnet-storage/

+[06]: media/private-vnet/data-diagram.png

+[07]: media/private-vnet/vnet-settings.png

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Quickstart for PowerShell in Azure Cloud Shell

+This document details how to use the PowerShell in Cloud Shell in the [Azure portal][06].

+The PowerShell experience in Azure Cloud Shell now runs [PowerShell 7.2][02] in a Linux environment.

+There are differences in the PowerShell experience in Cloud Shell compared Windows PowerShell.

+The filesystem in Linux is case-sensitive. Windows considers `file.txt` and `FILE.txt` to be the

+same file. In Linux, they're considered to be different files. Proper casing must be used while

+tab-completing in the filesystem. PowerShell specific experiences, such as tab-completing cmdlet

+names, parameters, and values, aren't case-sensitive.

+For a detailed list of differences, see [PowerShell differences on non-Windows platforms][01].

+1. Select on **Cloud Shell** button from the top navigation bar of the Azure portal

+ ![Screenshot showing how to start Azure Cloud Shell from the Azure portal.][09]

+1. Select the PowerShell environment from the drop-down and you'll be in Azure drive `(Azure:)`

+ ![Screenshot showing how to select the PowerShell environment for the Azure Cloud Shell.][08]

+You can find all your virtual machines under the current subscription via `VirtualMachines`

+directory.

+ > Please refer to [Troubleshooting remote management of Azure VMs][11].

+Assuming you have a VM, MyVM1, let's use `Invoke-AzVMCommand` to invoke a PowerShell script block on

+the remote machine.

+```azurepowershell-interactive

+Enable-AzVMPSRemoting -Name MyVM1 -ResourceGroupname MyResourceGroup

+Invoke-AzVMCommand -Name MyVM1 -ResourceGroupName MyResourceGroup -Scriptblock {Get-ComputerInfo} -Credential (Get-Credential)

+```

+You can also navigate to the VirtualMachines directory first and run `Invoke-AzVMCommand` as follows.

+```azurepowershell-interactive

+PS Azure:\> cd MySubscriptionName\ResourceGroups\MyResourceGroup\Microsoft.Compute\virtualMachines

+PS Azure:\MySubscriptionName\ResourceGroups\MyResourceGroup\Microsoft.Compute\virtualMachines> Get-Item MyVM1 | Invoke-AzVMCommand -Scriptblock {Get-ComputerInfo} -Credential (Get-Credential)

+```

+```output

+# You will see output similar to the following:

+PSComputerName : 65.52.28.207

+RunspaceId : 2c2b60da-f9b9-4f42-a282-93316cb06fe1

+WindowsBuildLabEx : 14393.1066.amd64fre.rs1_release_sec.170327-1835

+WindowsCurrentVersion : 6.3

+WindowsEditionId : ServerDatacenter

+WindowsInstallationType : Server

+WindowsInstallDateFromRegistry : 5/18/2017 11:26:08 PM

+WindowsProductId : 00376-40000-00000-AA947

+WindowsProductName : Windows Server 2016 Datacenter

+WindowsRegisteredOrganization :

+...

+```

+#### Interactively sign-in to a remote VM

+```azurepowershell-interactive

+Enter-AzVM -Name MyVM1 -ResourceGroupName MyResourceGroup -Credential (Get-Credential)

+```

+Get-Item MyVM1 | Enter-AzVM -Credential (Get-Credential)

+dir .\WebApps\

+publish the public key to `authorized_keys` on the remote machine, such as

+`/home/user/.ssh/authorized_keys`.

+> You can create SSH private-public keys using `ssh-keygen` and publish them to

+> `$env:USERPROFILE\.ssh` in Cloud Shell.

+Follow instructions [here][03] to create a new VM configuration using Azure PowerShell cmdlets.

+Before calling into `New-AzVM` to kick off the deployment, add SSH public key to the VM

+configuration. The newly created VM will contain the public key in the `~\.ssh\authorized_keys`

+location, thereby enabling credential-free SSH session to the VM.

+ssh-keygen -t rsa -b 2048 -f $HOME\.ssh\id_rsa

+Alternatively, you can always use `Get-Command *az* -Module Az.*` to find out the available Azure

+commands.

+You can run `Install-Module` to install modules from the [PowerShell Gallery][07].

+You can create a script, say `helloworld.ps1`, and save it to your `clouddrive` to use it across

+shell sessions.

+Next time when you use PowerShell in Cloud Shell, the `helloworld.ps1` file will exist under the

+`$HOME\clouddrive` directory that mounts your Azure Files share.

+You can customize your PowerShell environment, by creating PowerShell profiles - `profile.ps1` (or

+`Microsoft.PowerShell_profile.ps1`). Save it under `$profile.CurrentUserAllHosts` (or

+`$profile.CurrentUserCurrentHost`), so that it can be loaded in every PowerShell in Cloud Shell

+session.

+For how to create a profile, refer to [About Profiles][04].

+To clone a Git repo in Cloud Shell, you need to create a [personal access token][05] and use it as

+the username. Once you have your token, clone the repository as follows:

+git clone https://<your-access-token>@github.com/username/repo.git

+<!-- link references -->

+[01]: /powershell/scripting/whats-new/unix-support

+[02]: /powershell/scripting/whats-new/what-s-new-in-powershell-72

+[03]: ../virtual-machines/linux/quick-create-powershell.md

+[04]: /powershell/module/microsoft.powershell.core/about/about_profiles

+[05]: https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/

+[06]: https://portal.azure.com/

+[07]: https://www.powershellgallery.com/

+[08]: media/quickstart-powershell/environment-ps.png

+[09]: media/quickstart-powershell/shell-icon.png

+[11]: troubleshooting.md#troubleshooting-remote-management-of-azure-vms

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Quickstart for Bash in Azure Cloud Shell

+This document details how to use Bash in Azure Cloud Shell in the [Azure portal][03].

+> A [PowerShell in Azure Cloud Shell][09] Quickstart is also available.

+1. Launch **Cloud Shell** from the top navigation of the Azure portal.

+ ![Screenshot showing how to start Azure Cloud Shell in the Azure portal.][05]

+1. Select a subscription to create a storage account and Microsoft Azure Files share.

+1. Select "Create storage"

+Check that the environment drop-down from the left-hand side of shell window says `Bash`.

+![Screenshot showing how to select the Bash environment for the Azure Cloud Shell.][04]

+1. Set your preferred subscription:

+> Your subscription is remembered for future sessions using `/home/<user>/.azure/azureProfile.json`.

+Create an Ubuntu VM in your new resource group. The Azure CLI will create SSH keys and set up the VM

+with them.

+> Using `--generate-ssh-keys` instructs Azure CLI to create and set up public and private keys in

+> your VM and `$Home` directory. By default keys are placed in Cloud Shell at

+> `/home/<user>/.ssh/id_rsa` and `/home/<user>/.ssh/id_rsa.pub`. Your `.ssh` folder is persisted in

+> your attached file share's 5-GB image used to persist `$Home`.

+1. Select **Connect** to get your VM name and public IP address.

+ ![Screenshot showing how to connect to a Linux VM using SSH.][06]

+1. SSH into your VM with the `ssh` cmd.

+ ```bash

+Upon establishing the SSH connection, you should see the Ubuntu welcome prompt.

+![Screenshot showing the Ubuntu initialization and welcome prompt after you establish an SSH connection.][07]

+## Cleaning up

+1. Delete your resource group and any resources within it.

+- [Learn about persisting files for Bash in Cloud Shell][08]

+- [Learn about Azure CLI][02]

+- [Learn about Azure Files storage][01]

+<!-- link references -->

+[01]: ../storage/files/storage-files-introduction.md

+[02]: /cli/azure/

+[03]: https://portal.azure.com/

+[04]: media/quickstart/env-selector.png

+[05]: media/quickstart/shell-icon.png

+[06]: medi-copy.png

+[07]: media/quickstart/ubuntu-welcome.png

+[08]: persisting-shell-storage.md

+[09]: quickstart-powershell.md

+description: This article covers troubleshooting Cloud Shell common scenarios.

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Azure Cloud Shell troubleshooting

+This article covers troubleshooting Cloud Shell common scenarios.

+- **Details**: When you run AzureAD cmdlets like `Get-AzureADUser` in Cloud Shell, you might see an

+ error: `You must call the Connect-AzureAD cmdlet before calling any other cmdlets`.

+- **Resolution**: Run the `Connect-AzureAD` cmdlet. Previously, Cloud Shell ran this cmdlet

+ automatically during PowerShell startup. To speed up start time, the cmdlet no longer runs

+ automatically. You can choose to restore the previous behavior by adding `Connect-AzureAD` to the

+ $PROFILE file in PowerShell.

+- **Details**: Cloud Shell uses an open websocket to pass input/output to your browser. FireFox has

+ preset policies that can close the websocket prematurely causing early timeouts in Cloud Shell.

+- **Resolution**: Open FireFox and navigate to "about:config" in the URL box. Search for

+ "network.websocket.timeout.ping.request" and change the value from 0 to 10.

+- **Details**: Administrators may wish to disable access to Cloud Shell for their users. Cloud Shell

+ depends on access to the `ux.console.azure.com` domain, which can be denied, stopping any access

+ to Cloud Shell's entry points including `portal.azure.com`, `shell.azure.com`, Visual Studio Code

+ Azure Account extension, and `learn.microsoft.com`. In the US Government cloud, the entry point is

+ `ux.console.azure.us`; there's no corresponding `shell.azure.us`.

+- **Resolution**: Restrict access to `ux.console.azure.com` or `ux.console.azure.us` via network

+ settings to your environment. The Cloud Shell icon will still exist in the Azure portal, but can't

+ connect to the service.

+- **Details**: When creating a storage account through Cloud Shell, it's unsuccessful due to an

+ Azure Policy assignment placed by your admin. The error message includes:

+ > The resource action 'Microsoft.Storage/storageAccounts/write' is disallowed by

+ > one or more policies.

+- **Resolution**: Contact your Azure administrator to remove or update the Azure Policy assignment

+ denying storage creation.

+- **Details**: When using an Azure Active Directory subscription, you can't create storage.

+- **Resolution**: Use an Azure subscription capable of creating storage resources. Azure AD

+ subscriptions aren't able to create Azure resources.

+### Terminal output - Error: Failed to connect terminal: websocket can't be established

+- **Details**: Cloud Shell requires the ability to establish a websocket connection to Cloud Shell

+ infrastructure.

+- **Resolution**: Confirm that your network settings to allow sending HTTPS and websocket requests

+ to domains at `*.console.azure.com`.

+ - **Details**: To define the version of TLS for your connection to Cloud Shell, you must set

+ browser-specific settings.

+ - **Resolution**: Navigate to the security settings of your browser and select the checkbox next to

+ **Use TLS 1.2**.

+### You can't run the docker daemon

+- **Details**: Cloud Shell uses a container to host your shell environment, as a result running

+ the daemon is disallowed.

+- **Resolution**: Utilize [docker-machine][04], which is installed by default, to manage docker

+ containers from a remote Docker host.

+### GUI applications aren't supported

+- **Details**: If a user launches a GUI application, the prompt doesn't return. For example, when

+ one clone a private GitHub repo that has two factor authentication enabled, a dialog box is

+ displayed for completing the two factor authentication.

+- **Details**: Due to the default Windows Firewall settings for WinRM the user may see the following

+ error:

+ > Ensure the WinRM service is running. Remote Desktop into the VM for the first time and ensure

+ > it can be discovered.

+- **Resolution**: Run `Enable-AzVMPSRemoting` to enable all aspects of PowerShell remoting on the

+ target machine.

+### `dir` doesn't update the result in Azure drive

+- **Details**: By default, to optimize for user experience, the results of `dir` is cached in Azure

+ drive.

+- **Resolution**: After you create, update or remove an Azure resource, run `dir -force` to update

+ the results in the Azure drive.

+Azure Cloud Shell has a limit of 20 concurrent users per tenant per region. Opening more than 20

+simultaneous sessions produces a "Tenant User Over Quota" error. If you have a legitimate need to

+have more than 20 sessions open, such as for training sessions, contact Support to request a quota

+increase before your anticipated usage.

+Cloud Shell is provided as a free service for managing your Azure environment. It's not as a general

+purpose computing platform. Excessive automated usage may be considered in breach to the Azure Terms

+of Service and could lead to Cloud Shell access being blocked.

+The machine that provides your Cloud Shell session is temporary, and it's recycled after your

+session is inactive for 20 minutes. Cloud Shell requires an Azure fileshare to be mounted. As a

+result, your subscription must be able to set up storage resources to access Cloud Shell. Other

+considerations include:

+- With mounted storage, only modifications within the `clouddrive` directory are persisted. In Bash,

+ your `$HOME` directory is also persisted.

+- Azure fileshares can be mounted only from within your [assigned region][05].

+ - Safari in private mode isn't supported.

+- Windows: <kbd>Ctrl</kbd>-<kbd>C</kbd> to copy is supported but use

+ <kbd>Shift</kbd>-<kbd>Insert</kbd> to paste.

+ - FireFox/IE may not support clipboard permissions properly.

+- macOS: <kbd>Cmd</kbd>-<kbd>C</kbd> to copy and <kbd>Cmd</kbd>-<kbd>V</kbd> to paste.

+Cloud Shell is intended for interactive use cases. As a result, any long-running non-interactive

+sessions are ended without warning.

+Permissions are set as regular users without sudo access. Any installation outside your `$Home`

+directory isn't persisted.

+Cloud Shell entry points beside the Azure portal, such as Visual Studio Code & Windows Terminal,

+don't support various Cloud Shell functionalities:

+Currently, `AzureAD.Standard.Preview`, a preview version of .NET Standard-based, module is

+available. This module provides the same functionality as `AzureAD`.

+Azure Cloud Shell takes your personal data seriously. The Azure Cloud Shell service stores your

+preferences, such as your most recently used shell, font size, font type, and details of the

+fileshare that backs cloud drive. You can export or delete this data using the following

+instructions.

+<!--

+TODO:

+- Are there cmdlets or CLI to do this now, instead of REST API?

+-->

+Use the following commands to **export** Cloud Shell the user settings, such as preferred shell,

+font size, and font type.

+1. Launch Cloud Shell.

+1. Run the following commands in Bash or PowerShell:

+ Bash:

+<!--

+TODO:

+- Is there a way to wrap the lines for bash?

+- Why are we getting the token this way? The next example uses az cli.

+- The URLs used are not consistent across all the examples

+- Should we be using a newer API version?

+-->

+ ```bash

+ token=$(curl http://localhost:50342/oauth2/token --data "resource=https://management.azure.com/" -H Metadata:true -s | jq -r ".accessToken")

+ curl https://management.azure.com/providers/Microsoft.Portal/usersettings/cloudconsole?api-version=2017-12-01-preview -H Authorization:"Bearer $token" -s | jq

+ ```

+ PowerShell:

+ ```powershell

+ $parameters = @{

+ Uri = "$env:MSI_ENDPOINT`?resource=https://management.core.windows.net/"

+ Headers = @{Metadata='true'}

+ }

+ $token= ((Invoke-WebRequest @parameters ).content | ConvertFrom-Json).accessToken

+ $parameters = @{

+ Uri = 'https://management.azure.com/providers/Microsoft.Portal/usersettings/cloudconsole?api-version=2017-12-01-preview'

+ Headers = @{Authorization = "Bearer $token"}

+ }

+ ((Invoke-WebRequest @parameters ).Content | ConvertFrom-Json).properties | Format-List

+ ```

+Run the following commands to **delete** Cloud Shell user settings, such as preferred shell, font

+size, and font type. The next time you start Cloud Shell you'll be asked to onboard a fileshare

+again.

+> [!NOTE]

+> If you delete your user settings, the actual Azure fileshare is not deleted. Go to your Azure

+> Files to complete that action.

+1. Run the following commands in Bash or PowerShell:

+ Bash:

+ ```bash

+ token=$(az account get-access-token --resource "https://management.azure.com/" | jq -r ".accessToken")

+ curl -X DELETE https://management.azure.com/providers/Microsoft.Portal/usersettings/cloudconsole?api-version=2017-12-01-preview -H Authorization:"Bearer $token"

+ ```

+ PowerShell:

+ ```powershell

+ $token= (Get-AzAccessToken -Resource https://management.azure.com/).Token

+ $parameters = @{

+ Method = 'Delete'

+ Uri = 'https://management.azure.com/providers/Microsoft.Portal/usersettings/cloudconsole?api-version=2017-12-01-preview'

+ Headers = @{Authorization = "Bearer $token"}

+ }

+ Invoke-WebRequest @parameters

+ ```

+> [!NOTE]

+<!-- link references -->

+[04]: https://docs.docker.com/machine/overview/

+[05]: persisting-shell-storage.md#mount-a-new-clouddrive

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Using the Azure Cloud Shell editor

+Azure Cloud Shell includes an integrated file editor built from the open-source

+[Monaco Editor][02]. The Cloud Shell editor supports features such as language highlighting, the

+command palette, and a file explorer.

+![Cloud Shell editor][06]

+For simple file creation and editing, launch the editor by running `code .` in the Cloud Shell

+terminal. This action opens the editor with your active working directory set in the terminal.

+To directly open a file for quick editing, run `code <filename>` to open the editor without the file

+explorer.

+Select the `{}` icon from the toolbar to open the editor and default the file explorer to the

+`/home/<user>` directory.

+To close the editor, open the `...` action panel in the top right of the editor and select

+`Close editor`.

+![Close editor][04]

+To launch the command palette, use the `F1` key when focus is set on the editor. Opening the command

+palette can also be done through the action panel.

+![Cmd palette][05]

+<!--

+TODO:

+- Why are we talking about contributions here?

+- Need to document how to use the editor and the quirks

+-->

+- [Try the quickstart for Bash in Cloud Shell][07]

+- [View the full list of integrated Cloud Shell tools][01]

+<!-- link references -->

+[01]: features.md

+[02]: https://github.com/Microsoft/monaco-editor

+[03]: https://github.com/Microsoft/monaco-editor/blob/master/CONTRIBUTING.md

+[04]: media/using-cloud-shell-editor/close-editor.png

+[05]: medi-palette.png

+[06]: media/using-cloud-shell-editor/open-editor.png

+[07]: quickstart.md

+ms.contributor: jahelmic

+tags: azure-resource-manager

+ Title: Using the Azure Cloud Shell window

+Use the environment selector in the Cloud Shell toolbar to switch between Bash and PowerShell

+environments.

+![Select environment][02]

+Select the restart icon in the Cloud Shell toolbar to reset machine state.

+![Restart Cloud Shell][08]

+> Restarting Cloud Shell resets machine state and any files not persisted in your Azure fileshare

+> are lost.

+Select the settings icon on the top left of the window, then hover over the **Text size** option and

+select your desired text size. Your selection is persisted across sessions.

+![Text size][10]

+Select the settings icon on the top left of the window, then hover over the **Font** option and select

+your desired font. Your selection is persisted across sessions.

+![Font][09]

+Select the upload/download files icon on the top left of the window, then select **Upload** or

+**Download**.

+![Upload/download files][11]

+- For uploading files, use the pop-up to browse to the file on your local computer, select the

+ desired file, and select the **Open** button. The file is uploaded into the `/home/user`

+ directory.

+- For downloading file, enter the fully qualified file path into the pop-up window. For example, the

+ path under the `/home/user` directory that shows up by default. Then, select the **Download**

+ button.

+> [!NOTE]

+> File and path names are case sensitive in Cloud Shell. Double check your casing in your file

+> path.

+Cloud Shell enables multiple concurrent sessions across browser tabs by allowing each session to

+exist as a separate process. If exiting a session, be sure to exit from each session window as each

+process runs independently although they run on the same machine. Select the open new session icon on

+the top left of the window. A new tab opens with another session connected to the existing

+container.

+![Open new session][04]

+Refer to the [Using the Azure Cloud Shell editor][14] page.

+Select the web preview icon on the top left of the window, select **Configure**, specify the desired

+port to open.

+![Web preview][07]

+Select either **Open port** to only open the port, or **Open and browse** to open the

+port and preview the port in a new tab.

+![Configure port][05]

+To preview an open port in a new tab, select the web preview icon on the top left of the window then

+select **Preview port**.

+To close the open port, select the web preview icon on the top left of the window the select

+**Close port**.

+![Preview/close port][06]

+Select the minimize icon on the top right of the window to hide it. Select the Cloud Shell icon again

+to unhide. Select the maximize icon to set window to max height. To restore window to previous size,

+select restore.

+![Minimize or maximize the window][03]

+- Windows: <kbd>Ctrl</kbd>-<kbd>C</kbd> to copy is supported but use

+ <kbd>Shift</kbd>-<kbd>Insert</kbd> to paste.

+ - FireFox/IE may not support clipboard permissions properly.

+- macOS: <kbd>Cmd</kbd>-<kbd>C</kbd> to copy and <kbd>Cmd</kbd>-<kbd>V</kbd> to paste.

+Drag the top edge of the toolbar up or down to resize the Cloud Shell window.

+The `exit` command terminates the active session. Cloud Shell also terminates your session after 20

+minutes without interaction.

+- [Bash in Cloud Shell Quickstart][13]

+- [PowerShell in Cloud Shell Quickstart][12]

+<!-- link references -->

+[02]: media/using-the-shell-window/env-selector.png

+[03]: media/using-the-shell-window/minmax.png

+[04]: media/using-the-shell-window/newsession.png

+[05]: media/using-the-shell-window/preview-configure.png

+[06]: media/using-the-shell-window/preview-options.png

+[07]: media/using-the-shell-window/preview.png

+[08]: media/using-the-shell-window/restart.png

+[09]: media/using-the-shell-window/text-font.png

+[10]: media/using-the-shell-window/text-size.png

+[11]: media/using-the-shell-window/uploaddownload.png

+[12]: quickstart-powershell.md

+[13]: quickstart.md

+[14]: using-cloud-shell-editor.md

+ * [LUIS Endpoint APIs v2.0](./luis-migration-api-v1-to-v2.md)

+* [Managing Azure resources](./luis-how-to-azure-subscription.md?branch=pr-en-us-171715&tabs=portal#authoring-resource)

+For more information, see [Prevent anonymous public read access to containers and blobs](../../storage/blobs/anonymous-read-access-prevent.md) and [Prevent Shared Key authorization for an Azure Storage account](../../storage/common/shared-key-authorization-prevent.md).

+- [Get batch transcription results](batch-transcription-get.md)

+Embedded Speech is designed for on-device [speech-to-text](speech-to-text.md) and [text-to-speech](text-to-speech.md) scenarios where cloud connectivity is intermittent or unavailable. For example, you can use embedded speech in medical equipment, a voice enabled air conditioning unit, or a car that might travel out of range. You can also develop hybrid cloud and offline solutions. For scenarios where your devices must be in a secure environment like a bank or government entity, you should first consider [disconnected containers](../containers/disconnected-containers.md).

+- [Quickstart: Convert text to speech](get-started-text-to-speech.md)

+> [Azure Government: Translator text reference](../../azure-government/documentation-government-cognitiveservices.md#translator)

+> [Learn more about Translator](index.yml)

+* [Cognitive Services multi-key](./cognitive-services-apis-create-account.md?tabs=multiservice%2canomaly-detector%2clanguage-service%2ccomputer-vision%2cwindows)

+* [Anomaly Detector](./anomaly-detector/overview.md)

+* [Content Moderator](./content-moderator/overview.md)

+* [Custom Vision (Prediction)](./custom-vision-service/overview.md)

+* [Immersive Reader](../applied-ai-services/immersive-reader/overview.md)

+* [LUIS](./luis/what-is-luis.md)

+* [Metrics Advisor](../applied-ai-services/metrics-advisor/overview.md)

+* [Personalizer](./personalizer/what-is-personalizer.md)

+* [QnAMaker](./qnamaker/overview/overview.md)

+- Take the [Cost Management](/training/paths/control-spending-manage-bills?WT.mc_id=costmanagementcontent_docsacmhorizontal_-inproduct-learn) guided learning course.

+### How long will the registration process take?

+You'll receive communication from us about your application within 10 business days. In some cases, reviews can take longer. You'll receive an email as soon as your application is reviewed.

+> The QnA Maker service is being retired on the 31st of March, 2025. A newer version of the question and answering capability is now available as part of [Azure Cognitive Service for Language](../../index.yml). For question answering capabilities within the Language Service, see [question answering](../overview.md). Starting 1st October, 2022 you wonΓÇÖt be able to create new QnA Maker resources. For information on migrating existing QnA Maker knowledge bases to question answering, consult the [migration guide](../how-to/migrate-qnamaker.md).

+ Title: Rotate keys in Azure Cognitive Services

+description: "Learn how to rotate API keys for better security, without interrupting service"

+# Rotate subscription keys in Cognitive Services

+Each Cognitive Services resource has two API keys to enable secret rotation. This is a security precaution that lets you regularly change the keys that can access your service, protecting the privacy of your resource if a key gets leaked.

+## How to rotate keys

+Keys can be rotated using the following procedure:

+

+1. If you're using both keys in production, change your code so that only one key is in use. In this guide, assume it's key 1.

+ This is a necessary step because once a key is regenerated, the older version of that key will stop working immediately. This would cause clients using the older key to get 401 access denied errors.

+1. Once you have only key 1 in use, you can regenerate the key 2. Go to your resource's page on the Azure portal, select the **Keys and Endpoint** tab, and select the **Regenerate Key 2** button at the top of the page.

+1. Next, update your code to use the newly generated key 2.

+ It will help to have logs or availability to check that users of the key have successfully swapped from using key 1 to key 2 before you proceed.

+1. Now you can regenerate the key 1 using the same process.

+1. Finally, update your code to use the new key 1.

+## See also

+* [What is Cognitive Services?](./what-are-cognitive-services.md)

+* [Cognitive Services security features](./security-features.md)

+| [Key rotation](./authentication.md)| Each Cognitive Services resource has two API keys to enable secret rotation. This is a security precaution that lets you regularly change the keys that can access your service, protecting the privacy of your service in the event that a key gets leaked. To learn about this and other authentication options, see [Rotate keys](/azure/cognitive-services/rotate-keys). |

+| Call Automation | [REST](/rest/api/communication/callautomation/server-calling) | Service| Build customized calling workflows for PSTN and VoIP calls|

+|Call Automation||[NuGet](https://www.NuGet.org/packages/Azure.Communication.CallAutomation/)||[Maven](https://search.maven.org/artifact/com.azure/azure-communication-callautomation)

+- [Call Automation SDK Overview](../concepts/call-automation/call-automation.md)

+| Platform | Chrome | Safari | Edge (Chromium) | Firefox |

+| | | | -- | - |

+| Android | ✔️ | ❌ | ❌ | ❌ |

+| iOS | ❌ | ✔️ | ❌ | ❌ |

+| macOS | ✔️ | ✔️ | ✔️ | ✔️ |

+| Windows | ✔️ | ❌ | ✔️ | ✔️ |

+| Ubuntu/Linux | ✔️ | ❌ | ❌ | ❌ |

+* Firefox support is in public preview.

+Contains mixed audio of all participants on the call. As this is mixed audio, the participantRawID will be null.

+zone_pivot_groups: acs-web-android

+ Title: Quickstart - Handle EMAIL and delivery report events

+description: "In this quickstart, you'll learn how to handle Azure Communication Services events. See how to create, receive, and subscribe to Email delivery report and Email engagement tracking events."

+# Quickstart: Handle Email events

+Get started with Azure Communication Services by using Azure Event Grid to handle Communication Services Email events. After subscribing to Email events such as delivery reports and engagement reports, you generate and receive these events. Completing this quickstart incurs a small cost of a few USD cents or less in your Azure account.

+## Prerequisites

+- An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+- A Communication Services resource. For detailed information, see [Create an Azure Communication Services resource](../create-communication-resource.md).

+- An Email resource with a provisioned domain. [Create an Email Resource](../email/create-email-communication-resource.md).

+## About Event Grid

+[Event Grid](../../../event-grid/overview.md) is a cloud-based eventing service. In this article, you'll learn how to subscribe to [communication service events](../../../event-grid/event-schema-communication-services.md), and trigger an event to view the result. Typically, you send events to an endpoint that processes the event data and takes actions. In this article, we'll send the events to a web app that collects and displays the messages.

+## Set up the environment

+To set up the environment that we'll use to generate and receive events, take the steps in the following sections.

+### Register an Event Grid resource provider

+If you haven't previously used Event Grid in your Azure subscription, you might need to register your Event Grid resource provider. To register the provider, follow these steps:

+1. Go to the Azure portal.

+1. On the left menu, select **Subscriptions**.

+1. Select the subscription that you use for Event Grid.

+1. On the left menu, under **Settings**, select **Resource providers**.

+1. Find **Microsoft.EventGrid**.

+1. If your resource provider isn't registered, select **Register**.

+It might take a moment for the registration to finish. Select **Refresh** to update the status. When **Registered** appears under **Status**, you're ready to continue.

+### Deploy the Event Grid viewer

+For this quickstart, we'll use an Event Grid viewer to view events in near-real time. The viewer provides the user with the experience of a real-time feed. Also, the payload of each event should be available for inspection.

+To set up the viewer, follow the steps in [Azure Event Grid Viewer](/samples/azure-samples/azure-event-grid-viewer/azure-event-grid-viewer/).

+## Subscribe to Email events by using web hooks

+You can subscribe to specific events to provide Event Grid with information about where to send the events that you want to track.

+1. In the portal, go to the Communication Services resource that you created.

+1. Inside the Communication Services resource, on the left menu of the **Communication Services** page, select **Events**.

+1. Select **Add Event Subscription**.

+ :::image type="content" source="./media/handle-email-events/select-events.png" alt-text="Screenshot that shows the Events page of an Azure Communication Services resource. The Event Subscription button is called out.":::

+1. On the **Create Event Subscription** page, enter a **name** for the event subscription.

+1. Under **Event Types**, select the events that you'd like to subscribe to. For Email, you can choose `Email Delivery Report Received` and `Email Engagement Tracking Report Received`.

+1. If you're prompted to provide a **System Topic Name**, feel free to provide a unique string. This field has no impact on your experience and is used for internal telemetry purposes.

+ :::image type="content" source="./media/handle-email-events/select-events-create-eventsub.png" alt-text="Screenshot that shows the Create Event Subscription dialog. Under Event Types, Email Delivery Report Received and Email Engagement Tracking Report Received are selected.":::

+1. For **Endpoint type**, select **Web Hook**.

+ :::image type="content" source="./media/handle-email-events/select-events-create-linkwebhook.png" alt-text="Screenshot that shows a detail of the Create Event Subscription dialog. In the Endpoint Type list, Web Hook is selected.":::

+1. For **Endpoint**, select **Select an endpoint**, and then enter the URL of your web app.

+ In this case, we'll use the URL from the [Event Grid viewer](/samples/azure-samples/azure-event-grid-viewer/azure-event-grid-viewer/) that we set up earlier in the quickstart. The URL for the sample has this format: `https://{{site-name}}.azurewebsites.net/api/updates`

+1. Select **Confirm Selection**.

+ :::image type="content" source="./media/handle-email-events/select-events-create-selectwebhook-epadd.png" alt-text="Screenshot that shows the Select Web Hook dialog. The Subscriber Endpoint box contains a URL, and a Confirm Selection button is visible.":::

+## View Email events

+To generate and receive Email events, take the steps in the following sections.

+### Trigger Email events

+To view event triggers, we need to generate some events. To trigger an event, [send email](../email/send-email.md) using the Email domain resource attached to the Communication Services resource.

+- `Email Delivery Report Received` events are generated when the Email status is in terminal state, i.e. Delivered, Failed, FilteredSpam, Quarantined.

+- `Email Engagement Tracking Report Received` events are generated when the email sent is either opened or a link within the email is clicked. To trigger an event, you need to turn on the `User Interaction Tracking` option on the Email domain resource

+Check out the full list of [events that Communication Services supports](../../../event-grid/event-schema-communication-services.md).

+### Receive Email events

+After you generate an event, you'll notice that `Email Delivery Report Received` and `Email Engagement Tracking Report Received` events are sent to your endpoint. These events show up in the [Event Grid viewer](/samples/azure-samples/azure-event-grid-viewer/azure-event-grid-viewer/) that we set up at the beginning of this quickstart. Select the eye icon next to the event to see the entire payload. Events should look similar to the following data:

+Learn more about the [event schemas and other eventing concepts](../../../event-grid/event-schema-communication-services.md).

+## Clean up resources

+If you want to clean up and remove a Communication Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it. Learn more about [cleaning up resources](../create-communication-resource.md#clean-up-resources).

+## Next steps

+In this quickstart, you learned how to consume Email events. You can receive Email events by creating an Event Grid subscription.

+> [!div class="nextstepaction"]

+> [Send Email](../email/send-email.md)

+You might also want to:

+ - [Learn about event handling concepts](../../../event-grid/event-schema-communication-services.md)

+ - [Learn about Event Grid](../../../event-grid/overview.md)

+- Download our [Java](https://github.com/Azure-Samples/communication-services-java-quickstarts/tree/main/ServerRecording) and [.NET](https://github.com/Azure-Samples/communication-services-dotnet-quickstarts/tree/main/ServerRecording) call recording sample apps

+{

+ "kind": <string> // What kind of data this is, e.g. AudioMetadata, AudioData.

+ "audioMetadata": {

+ "subscriptionId": <string>, // unique identifier for a subscription request

+ "encoding":<string>, // PCM only supported

+ "sampleRate": <int>, // 16000 default

+ "channels": <int>, // 1 default

+ "length": <int> // 640 default

+ }

+{

+ "kind": <string>, // What kind of data this is, e.g. AudioMetadata, AudioData.

+ "audioData":{

+ "data": <string>, // Base64 Encoded audio buffer data

+ "timestamp": <string>, // In ISO 8601 format (yyyy-mm-ddThh:mm:ssZ)

+ "participantRawID": <string>,

+ "silent": <boolean> // Indicates if the received audio buffer contains only silence.

+ }

+This tutorial describes concepts for virtual appointment applications. After completing this tutorial and the associated [Sample Builder](https://aka.ms/acs-sample-builder), you will understand common use cases that a virtual appointments application delivers, the Microsoft technologies that can help you build those uses cases, and have built a sample application integrating Microsoft 365 and Azure that you can use to demo and explore further.

+No matter the industry, there are at least three personas involved in a virtual appointment and certain tasks they accomplish:

+- **Provider.** The provider gets on the call with the consumer. They must be able to view upcoming virtual appointments and join the virtual appointment and engage in communication.

+- **Consumer**. The consumer who schedules and motivates the appointment. They must schedule an appointment, enjoy reminders of the appointment, typically through SMS or email, and join the virtual appointment and engage in communication.

+- **Microsoft 365 + Azure hybrid.** Combine Microsoft 365 Teams and Bookings with a custom Azure application for the consumer experience. Organizations take advantage of Microsoft 365's employee familiarity but customize and embed the consumer appointment experience in their own application.

+

+| *Provider* | Managing upcoming appointments | Outlook & Teams | Outlook & Teams | Custom |

+| *Provider* | Join the appointment | Teams | Teams | ACS Calling & Chat |

+| *Consumer* | Schedule an appointment | Bookings | Bookings | ACS Rooms |

+| *Consumer*| Be reminded of a appointment | Bookings | Bookings | ACS SMS |

+| *Consumer*| Join the appointment | Teams or virtual appointments | ACS Calling & Chat | ACS Calling & Chat |

+- **Replace TeamsΓÇÖ provider experience with Azure.** You can still use Microsoft 365 and Bookings to manage meetings but have the business user launch a custom Azure application to join the Teams meeting. This might be useful where you want to split or customize virtual appointment interactions from day-to-day employee Teams activity.

+The rest of this tutorial focuses on Microsoft 365 and Azure hybrid solutions. These hybrid configurations are popular because they combine employee familiarity of Microsoft 365 with the ability to customize the consumer experience. TheyΓÇÖre also a good launching point to understanding more complex and customized architectures. The diagram below shows user steps for a virtual appointment:

+1. Consumer schedules the appointment using Microsoft 365 Bookings.

+2. Consumer gets a appointment reminder through SMS and Email.

+3. Provider joins the appointment using Microsoft Teams.

+## Building a virtual appointment sample

+The Sample Builder gives you the basics of a Microsoft 365 and Azure virtual appointment: consumer scheduling via Bookings, consumer joins via custom app, and the provider joins via Teams. However, there are several things to consider as you take this scenario to production.

+Consumers want to jump directly to the virtual appointment from the scheduling reminders they receive from Bookings. In Bookings, you can provide a URL prefix that will be used in reminders. If your prefix is `https://<YOUR URL>/VISIT`, Bookings will point users to `https://<YOUR URL>/VISIT?MEETINGURL=<MEETING URL>.`

+3. Verify that the signature over the root of the Merkle Tree (computed using the instructions in the previous subsection) is authentic using the extracted public key from the previous step. This step effectively corresponds to a standard [digital signature](https://wikipedia.org/wiki/Digital_signature) verification process using ECDSA. There are many libraries in the most popular programming languages that allow verifying an ECDSA signature using a public key certificate over some data (for example, the [cryptography library](https://cryptography.io/en/latest/) for Python).

+A container app flows through four phases: deployment, update, deactivation, and shutdown.

+As a container app is updated with a [revision scope-change](revisions.md#revision-scope-changes), a new revision is created. You can [choose](revisions.md#revision-modes) whether to automatically deactivate old revisions (single revision mode), or allow them to remain available (multiple revision mode).

+### Zero downtime deployment

+In single revision mode, Container Apps automatically ensures your app does not experience downtime when creating new a revision. The existing active revision is not deactivated until the new revision is ready. If ingress is enabled, the existing revision will continue to receive 100% of the traffic until the new revision is ready.

+> [!NOTE]

+> A new revision is considered ready when one of its replicas starts and becomes ready. A replica is ready when all of its containers start and pass their [startup and readiness probes](./health-probes.md).

+In multiple revision mode, you control when revisions are activated or deactivated and which revisions receive ingress traffic. If a [traffic splitting rule](./revisions-manage.md#traffic-splitting) is configured with `latestRevision` set to `true`, traffic does not switch to the latest revision until it is ready.

+ Title: Publish revisions with Azure Pipelines in Azure Container Apps

+description: Learn to automatically create new revisions in Azure Container Apps using an Azure DevOps pipeline

+# Deploy to Azure Container Apps from Azure Pipelines (preview)

+Azure Container Apps allows you to use Azure Pipelines to publish [revisions](revisions.md) to your container app. As commits are pushed to your [Azure DevOps repository](/azure/devops/repos/), a pipeline is triggered which updates the container image in the container registry. Azure Container Apps creates a new revision based on the updated container image.

+The pipeline is triggered by commits to a specific branch in your repository. When creating the pipeline, you decide which branch is the trigger.

+## Container Apps Azure Pipelines task

+To build and deploy your container app, add the [`AzureContainerAppsRC`](https://marketplace.visualstudio.com/items?itemName=microsoft-oryx.AzureContainerAppsRC) (preview) Azure Pipelines task to your pipeline.

+The task supports the following scenarios:

+* Build from a Dockerfile and deploy to Container Apps

+* Build from source code without a Dockerfile and deploy to Container Apps. Supported languages include .NET, Node.js, PHP, Python, and Ruby

+* Deploy an existing container image to Container Apps

+### Usage examples

+Here are some common scenarios for using the task. For more information, see the [task's documentation](https://github.com/Azure/container-apps-deploy-pipelines-task/blob/main/README.md).

+#### Build and deploy to Container Apps

+The following snippet shows how to build a container image from source code and deploy it to Container Apps.

+```yaml

+steps:

+- task: AzureContainerAppsRC@0

+ inputs:

+ appSourcePath: '$(Build.SourcesDirectory)/src'

+ azureSubscription: 'my-subscription-service-connection'

+ acrName: 'myregistry'

+ containerAppName: 'my-container-app'

+ resourceGroup: 'my-container-app-rg'

+```

+The task uses the Dockerfile in `appSourcePath` to build the container image. If no Dockerfile is found, the task attempts to build the container image from source code in `appSourcePath`.

+#### Deploy an existing container image to Container Apps

+The following snippet shows how to deploy an existing container image to Container Apps.

+```yaml

+steps:

+ - task: AzureContainerAppsRC@0

+ inputs:

+ azureSubscription: 'my-subscription-service-connection'

+ acrName: 'myregistry'

+ containerAppName: 'my-container-app'

+ resourceGroup: 'my-container-app-rg'

+ imageToDeploy: 'myregistry.azurecr.io/my-container-app:$(Build.BuildId)'

+```

+> [!IMPORTANT]

+> If you're building a container image in a separate step, make sure you use a unique tag such as the build ID instead of a stable tag like `latest`. For more information, see [Image tag best practices](../container-registry/container-registry-image-tag-version.md).

+### Authenticate with Azure Container Registry

+The Azure Container Apps task needs to authenticate with your Azure Container Registry to push the container image. The container app also needs to authenticate with your Azure Container Registry to pull the container image.

+To push images, the task automatically authenticates with the container registry specified in `acrName` using the service connection provided in `azureSubscription`.

+To pull images, Azure Container Apps uses either managed identity (recommended) or admin credentials to authenticate with the Azure Container Registry. To use managed identity, the target container app for the task must be [configured to use managed identity](managed-identity-image-pull.md). To authenticate with the registry's admin credentials, set the task's `acrUsername` and `acrPassword` inputs.

+## Configuration

+Take the following steps to configure an Azure DevOps pipeline to deploy to Azure Container Apps.

+> [!div class="checklist"]

+> * Create an Azure DevOps repository for your app

+> * Create a container app with managed identity enabled

+> * Assign the `AcrPull` role for the Azure Container Registry to the container app's managed identity

+> * Install the Azure Container Apps task from the Azure DevOps Marketplace

+> * Configure an Azure DevOps service connection for your Azure subscription

+> * Create an Azure DevOps pipeline

+### Prerequisites

+| Requirement | Instructions |

+|--|--|

+| Azure account | If you don't have one, [create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). You need the *Contributor* or *Owner* permission on the Azure subscription to proceed. Refer to [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md?tabs=current) for details. |

+| Azure Devops project | Go to [Azure DevOps](https://azure.microsoft.com/services/devops/) and select *Start free*. Then create a new project. |

+| Azure CLI | Install the [Azure CLI](/cli/azure/install-azure-cli).|

+### Create an Azure DevOps repository and clone the source code

+Before creating a pipeline, the source code for your app must be in a repository.

+1. Log in to [Azure DevOps](https://dev.azure.com/) and navigate to your project.

+1. Open the **Repos** page.

+1. In the top navigation bar, select the repositories dropdown and select **Import repository**.

+1. Enter the following information and select **Import**:

+ | Field | Value |

+ |--|--|

+ | **Repository type** | Git |

+ | **Clone URL** | `https://github.com/Azure-Samples/containerapps-albumapi-csharp.git` |

+ | **Name** | `my-container-app` |

+1. Select **Clone** to view the repository URL and copy it.

+1. Open a terminal and run the following command to clone the repository:

+ ```bash

+ git clone <REPOSITORY_URL> my-container-app

+ ```

+ Replace `<REPOSITORY_URL>` with the URL you copied.

+

+### Create a container app and configure managed identity

+Create your container app using the `az containerapp up` command with the following steps. This command creates Azure resources, builds the container image, stores the image in a registry, and deploys to a container app.

+After your app is created, you can add a managed identity to your app and assign the identity the `AcrPull` role to allow the identity to pull images from the registry.

+### Install the Azure Container Apps task

+The Azure Container Apps Azure Pipelines task is currently in preview. Before you use the task, you must install it from the Azure DevOps Marketplace.

+1. Open the [Azure Container Apps task](https://marketplace.visualstudio.com/items?itemName=microsoft-oryx.AzureContainerAppsRC) in the Azure DevOps Marketplace.

+1. Select **Get it free**.

+1. Select your Azure DevOps organization and select **Install**.

+### Create an Azure DevOps service connection

+To deploy to Azure Container Apps, you need to create an Azure DevOps service connection for your Azure subscription.

+1. In Azure DevOps, select **Project settings**.

+1. Select **Service connections**.

+1. Select **New service connection**.

+1. Select **Azure Resource Manager**.

+1. Select **Service principal (automatic)** and select **Next**.

+1. Enter the following information and select **Save**:

+ | Field | Value |

+ |--|--|

+ | **Subscription** | Select your Azure subscription. |

+ | **Resource group** | Select the resource group (`my-container-app-rg`) that contains your container app and container registry. |

+ | **Service connection name** | `my-subscription-service-connection` |

+To learn more about service connections, see [Connect to Microsoft Azure](/azure/devops/pipelines/library/connect-to-azure).

+### Create an Azure DevOps YAML pipeline

+1. In your Azure DevOps project, select **Pipelines**.

+1. Select **New pipeline**.

+1. Select **Azure Repos Git**.

+1. Select the repo that contains your source code (`my-container-app`).

+1. Select **Starter pipeline**.

+1. In the editor, replace the contents of the file with the following YAML:

+ ```yaml

+ trigger:

+ branches:

+ include:

+ - main

+ pool:

+ vmImage: ubuntu-latest

+ steps:

+ - task: AzureContainerAppsRC@0

+ inputs:

+ appSourcePath: '$(Build.SourcesDirectory)/src'

+ azureSubscription: '<AZURE_SUBSCRIPTION_SERVICE_CONNECTION>'

+ acrName: '<ACR_NAME>'

+ containerAppName: 'my-container-app'

+ resourceGroup: 'my-container-app-rg'

+ ```

+ Replace `<AZURE_SUBSCRIPTION_SERVICE_CONNECTION>` with the name of the Azure DevOps service connection (`my-subscription-service-connection`) you created in the previous step and `<ACR_NAME>` with the name of your Azure Container Registry.

+1. Select **Save and run**.

+An Azure Pipelines run starts to build and deploy your container app. To check its progress, navigate to *Pipelines* and select the run. During the first pipeline run, you may be prompted to authorize the pipeline to use your service connection.

+To deploy a new revision of your app, push a new commit to the *main* branch.

+ Title: Generate GitHub Actions workflow with Azure CLI in Azure Container Apps

+description: Learn to automatically create GitHub Actions workflow in Azure Container Apps

+# Set up GitHub Actions with Azure CLI in Azure Container Apps

+Azure Container Apps allows you to use GitHub Actions to publish [revisions](revisions.md) to your container app. As commits are pushed to your GitHub repository, a GitHub Actions workflow is triggered which updates the [container](containers.md) image in the container registry. Once the container is updated in the registry, Azure Container Apps creates a new revision based on the updated container image.

+The GitHub Actions workflow is triggered by commits to a specific branch in your repository. When creating the workflow, you decide which branch triggers the action.

+This article shows you how to generate a starter GitHub Actions workflow with Azure CLI. To create your own workflow that you can fully customize, see [Deploy to Azure Container Apps with GitHub Actions](github-actions.md).

+The return values from this command include the service principal's `appId`, `password`, and `tenant`. You need to pass these values to the `az containerapp github-action add` command.

+ Title: Publish revisions with GitHub Actions in Azure Container Apps

+description: Learn to automatically create new revisions in Azure Container Apps using a GitHub Actions workflow

+# Deploy to Azure Container Apps with GitHub Actions (preview)

+Azure Container Apps allows you to use GitHub Actions to publish [revisions](revisions.md) to your container app. As commits are pushed to your GitHub repository, a workflow is triggered which updates the container image in the container registry. Azure Container Apps creates a new revision based on the updated container image.

+The GitHub Actions workflow is triggered by commits to a specific branch in your repository. When creating the workflow, you decide which branch triggers the workflow.

+This article shows you how to create a fully customizable workflow. To generate a starter GitHub Actions workflow with Azure CLI, see [Generate GitHub Actions workflow with Azure CLI](github-actions-cli.md).

+## Azure Container Apps GitHub action

+To build and deploy your container app, you add the [`azure/container-apps-deploy-action`](https://github.com/marketplace/actions/azure-container-apps-build-and-deploy) action to your GitHub Actions workflow.

+The action supports the following scenarios:

+* Build from a Dockerfile and deploy to Container Apps

+* Build from source code without a Dockerfile and deploy to Container Apps. Supported languages include .NET, Node.js, PHP, Python, and Ruby

+* Deploy an existing container image to Container Apps

+### Usage examples

+Here are some common scenarios for using the action. For more information, see the [action's GitHub Marketplace page](https://github.com/marketplace/actions/azure-container-apps-build-and-deploy).

+#### Build and deploy to Container Apps

+The following snippet shows how to build a container image from source code and deploy it to Container Apps.

+```yaml

+steps:

+ - name: Log in to Azure

+ uses: azure/login@v1

+ with:

+ creds: ${{ secrets.AZURE_CREDENTIALS }}

+ - name: Build and deploy Container App

+ uses: azure/container-apps-deploy-action@v0

+ with:

+ appSourcePath: ${{ github.workspace }}/src

+ acrName: myregistry

+ containerAppName: my-container-app

+ resourceGroup: my-rg

+```

+The action uses the Dockerfile in `appSourcePath` to build the container image. If no Dockerfile is found, the action attempts to build the container image from source code in `appSourcePath`.

+#### Deploy an existing container image to Container Apps

+The following snippet shows how to deploy an existing container image to Container Apps.

+```yaml

+steps:

+ - name: Log in to Azure

+ uses: azure/login@v1

+ with:

+ creds: ${{ secrets.AZURE_CREDENTIALS }}

+

+ - name: Build and deploy Container App

+ uses: azure/container-apps-deploy-action@v0

+ with:

+ acrName: myregistry

+ containerAppName: my-container-app

+ resourceGroup: my-rg

+ imageToDeploy: myregistry.azurecr.io/app:${{ github.sha }}

+```

+> [!IMPORTANT]

+> If you're building a container image in a separate step, make sure you use a unique tag such as the commit SHA instead of a stable tag like `latest`. For more information, see [Image tag best practices](../container-registry/container-registry-image-tag-version.md).

+### Authenticate with Azure Container Registry

+The Azure Container Apps action needs to authenticate with your Azure Container Registry to push the container image. The container app also needs to authenticate with your Azure Container Registry to pull the container image.

+To push images, the action automatically authenticates with the container registry specified in `acrName` using the credentials provided to the `azure/login` action.

+To pull images, Azure Container Apps uses either managed identity (recommended) or admin credentials to authenticate with the Azure Container Registry. To use managed identity, the container app the action is deploying must be [configured to use managed identity](managed-identity-image-pull.md). To authenticate with the registry's admin credentials, set the action's `acrUsername` and `acrPassword` inputs.

+## Configuration

+You take the following steps to configure a GitHub Actions workflow to deploy to Azure Container Apps.

+> [!div class="checklist"]

+> * Create a GitHub repository for your app

+> * Create a container app with managed identity enabled

+> * Assign the `AcrPull` role for the Azure Container Registry to the container app's managed identity

+> * Configure secrets in your GitHub repository

+> * Create a GitHub Actions workflow

+### Prerequisites

+| Requirement | Instructions |

+|--|--|

+| Azure account | If you don't have one, [create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F). You need the *Contributor* or *Owner* permission on the Azure subscription to proceed. Refer to [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.md?tabs=current) for details. |

+| GitHub Account | Sign up for [free](https://github.com/join). |

+| Azure CLI | Install the [Azure CLI](/cli/azure/install-azure-cli).|

+### Create a GitHub repository and clone source code

+Before creating a workflow, the source code for your app must be in a GitHub repository.

+1. Log in to Azure with the Azure CLI.

+ ```azurecli

+ az login

+ ```

+1. Next, install the latest Azure Container Apps extension for the CLI.

+ ```azurecli

+ az extension add --name containerapp --upgrade

+ ```

+1. If you do not have your own GitHub repository, create one from a sample.

+ 1. Navigate to the following location to create a new repository:

+ - [https://github.com/Azure-Samples/containerapps-albumapi-csharp/generate](https://github.com/login?return_to=%2FAzure-Samples%2Fcontainerapps-albumapi-csharp%2Fgenerate)

+ 1. Name your repository `my-container-app`.

+1. Clone the repository to your local machine.

+ ```bash

+ git clone https://github.com/<YOUR_GITHUB_ACCOUNT_NAME>/my-container-app.git

+ ```

+### Create a container app with managed identity enabled

+Create your container app using the `az containerapp up` command in the following steps. This command will create Azure resources, build the container image, store the image in a registry, and deploy to a container app.

+After you create your app, you can add a managed identity to the app and assign the identity the `AcrPull` role to allow the identity to pull images from the registry.

+### Configure secrets in your GitHub repository

+The GitHub workflow requires a secret named `AZURE_CREDENTIALS` to authenticate with Azure. The secret contains the credentials for a service principal with the *Contributor* role on the resource group containing the container app and container registry.

+1. Create a service principal with the *Contributor* role on the resource group that contains the container app and container registry.

+ ```azurecli

+ az ad sp create-for-rbac \

+ --name my-container-app \

+ --role contributor \

+ --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/my-container-app-rg \

+ --sdk-auth \

+ --output json

+ ```

+ Replace `<SUBSCRIPTION_ID>` with the ID of your Azure subscription. If your container registry is in a different resource group, specify both resource groups in the `--scopes` parameter.

+1. Copy the JSON output from the command.

+1. In the GitHub repository, navigate to *Settings* > *Secrets* > *Actions* and select **New repository secret**.

+1. Enter `AZURE_CREDENTIALS` as the name and paste the contents of the JSON output as the value.

+1. Select **Add secret**.

+### Create a GitHub Actions workflow

+1. In the GitHub repository, navigate to *Actions* and select **New workflow**.

+1. Select **Set up a workflow yourself**.

+1. Paste the following YAML into the editor.

+ ```yaml

+ name: Azure Container Apps Deploy

+ on:

+ push:

+ branches:

+ - main

+

+ jobs:

+ build:

+ runs-on: ubuntu-latest

+ steps:

+ - uses: actions/checkout@v3

+ - name: Log in to Azure

+ uses: azure/login@v1

+ with:

+ creds: ${{ secrets.AZURE_CREDENTIALS }}

+ - name: Build and deploy Container App

+ uses: azure/container-apps-deploy-action@v0

+ with:

+ appSourcePath: ${{ github.workspace }}/src

+ acrName: <ACR_NAME>

+ containerAppName: my-container-app

+ resourceGroup: my-container-app-rg

+ ```

+ Replace `<ACR_NAME>` with the name of your Azure Container Registry. Confirm that the branch name under `branches` and values for `appSourcePath`, `containerAppName`, and `resourceGroup` match the values for your repository and Azure resources.

+1. Commit the changes to the *main* branch.

+A GitHub Actions workflow run should start to build and deploy your container app. To check its progress, navigate to *Actions*.

+To deploy a new revision of your app, push a new commit to the *main* branch.

+If ingress is enabled, the following default probes are automatically added to the main app container if none is defined for each type.

+| Probe type | Default values |

+| -- | -- |

+| Startup | Protocol: TCP<br>Port: ingress target port<br>Timeout: 1 second<br>Period: 1 second<br>Initial delay: 1 second<br>Success threshold: 1<br>Failure threshold: `timeoutSeconds` |

+| Readiness | Protocol: TCP<br>Port: ingress target port<br>Timeout: 5 seconds<br>Period: 5 seconds<br>Initial delay: 3 seconds<br>Success threshold: 1<br>Failure threshold: `timeoutSeconds / 5` |

+| Liveness | Protocol: TCP<br>Port: ingress target port |

+If your app takes an extended amount of time to start, which is very common in Java, you often need to customize the probes so your container won't crash.

+To create a traffic rule that always routes traffic to the latest revision, set its `latestRevision` property to `true` and don't set `revisionName`.

+By default, a container app is in *single revision mode*. In this mode, when a new revision is created, the latest revision replaces the active revision. For more information, see [Zero downtime deployment](./application-lifecycle-management.md#zero-downtime-deployment).

+> Container group deployment to a virtual network is generally available for Linux containers, in most regions where Azure Container Instances is available. For details, see [Regions and resource availability](container-instances-region-availability.md).

+* Currently, only Linux containers are supported in a container group deployed to a virtual network.

+It's not a good practice to store the endpoint URI and sensitive read-write keys directly within application code or configuration file. Ideally, this data is read from environment variables within the host. In Azure App Service, [app settings](../app-service/configure-common.md#configure-app-settings) allow you to inject runtime credentials for your Azure Cosmos DB account without the need for developers to store these credentials in an insecure clear text manner.

+- To configure virtual network service endpoint, see [secure access by using VNet service endpoint](how-to-configure-vnet-service-endpoint.md) article.

+ "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>",

+ "defaultIdentity": "UserAssignedIdentity=<identity-resource-id>",

+- [Work with a collection](how-to-javascript-manage-collections.md)

+This feature can be enabled for your database account by filing a support ticket.

+This feature can be enabled for your database account by filing a support ticket.

+In this quickstart, you'll communicate with the Azure Cosmos DBΓÇÖs API for MongoDB by using one of the open-source MongoDB client drivers for Python, [PyMongo](https://www.mongodb.com/docs/drivers/pymongo/). Also, you'll use the [MongoDB extension commands](./custom-commands.md), which are designed to help you create and obtain database resources that are specific to the [Azure Cosmos DB capacity model](../account-databases-containers-items.md).

+Check if the database exists with [list_database_names](https://pymongo.readthedocs.io/en/stable/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient.list_database_names) method. If the database doesn't exist, use the [create database extension command](./custom-commands.md#create-database) to create it with a specified provisioned throughput.

+Check if the collection exists with the [list_collection_names](https://pymongo.readthedocs.io/en/stable/api/pymongo/database.html#pymongo.database.Database.list_collection_names) method. If the collection doesn't exist, use the [create collection extension command](./custom-commands.md#create-collection) to create it.

+Create an index using the [update collection extension command](./custom-commands.md#update-collection). You can also set the index in the create collection extension command. Set the index to `name` property in this example so that you can later sort with the cursor class [sort](https://pymongo.readthedocs.io/en/stable/api/pymongo/cursor.html#pymongo.cursor.Cursor.sort) method on product name.

+> [Options to migrate your on-premises or cloud data to Azure Cosmos DB](../migration-choices.md)

+* **Monitor with diagnostic logs in Azure Monitor:** You can monitor the logs of your Azure Cosmos DB account and create dashboards from the Azure Monitor. Data such as events and traces that occur at a second granularity are stored as logs. For example, if the throughput of a container changes, the properties of an Azure Cosmos DB account are changed, and these events are captured within the logs. You can analyze these logs by running queries on the gathered data. To learn more, see the [Analyze log data](#analyzing-logs) section of this article.

+Support for Partial document update (Patch API) in the [Azure Cosmos DB JavaScript SDK](nosql/sdk-nodejs.md) is available from version *3.15.0* onwards. You can download it from the [npm Registry](https://www.npmjs.com/package/@azure/cosmos)

+The examples in this tutorial walk you through exporting your cost management data and then verify that the data was successfully exported.

+Your new export appears in the list of exports. By default, new exports are enabled. If you want to disable or delete a scheduled export, select any item in the list, and then select either **Disable** or **Delete**.

+ For the `--type` parameter, you can choose `ActualCost`, `AmortizedCost`, or `Usage`.

+Scheduled exports are affected by the time and day of week of when you initially create the export. When you create a scheduled export, the export runs at the same frequency for each export that runs later. For example, for a daily export of month-to-date costs export set at a daily frequency, the export runs during once each UTC day. Similarly for a weekly export, the export runs every week on the same UTC day as it is scheduled. Individual export runs can occur at different times throughout the day. So, avoid taking a firm dependency on the exact time of the export runs. Run timing depends on the active load present in Azure during a given UTC day. When an export run begins, your data should be available within 4 hours.

+ - Example - A weekly export is scheduled on Friday, August 19 with the local time of 2:00 AM IST (UTC+5:30) from the Azure portal. The API receives the input as 8:30 PM, Thursday, August 18. The weekly export will be scheduled to run every Thursday.

+If you have an Enterprise Agreement, then you can use a management group to aggregate subscription cost information in a single container. Then you can export cost management data for the management group. When you create an export in the Azure portal, select the **Actual Costs** option. When you create a management group export using the API, create a *usage export*. Currently, exports at the management group scope only support usage charges. Purchases including reservations and savings plans aren't present in your exports file.

+ Title: Add, update, or delete a payment method

+description: This article describes how to add, update, or delete a payment method used to pay for an Azure subscription.

+# Add, update, or delete a payment method

+In the Azure portal, you can change your default payment method to a new credit card and update your credit card details. You can also delete a payment method used to pay for an Azure subscription.

+## Delete an Azure billing payment method

+The following information helps you delete a payment method, like a credit card, from different types of Azure subscriptions. You can delete a payment method for:

+- Microsoft Customer Agreement (MCA)

+- Microsoft Online Services Program (MOSP) also referred to as pay-as-you-go

+Whatever your Azure subscription type, you must cancel it so that you can delete its associated payment method.

+Removing a payment method for other Azure subscription types like Microsoft Partner Agreement and Enterprise Agreement isn't supported.

+### Delete an MCA payment method

+Only the user who created the Microsoft Customer Agreement account can delete a payment method.

+To delete a payment method for a Microsoft Customer Agreement, do the following steps.

+1. Sign in to the Azure portal at https://portal.azure.com/.

+1. Navigate to **Cost Management + Billing**.

+1. If necessary, select a billing scope.

+1. In the left menu list under **Billing**, select **Billing profiles**.

+ :::image type="content" source="./media/change-credit-card/billing-profiles.png" alt-text="Example screenshot showing Billing profiles in the Azure portal." lightbox="./media/change-credit-card/billing-profiles.png" :::

+1. In the list of billing profiles, select the one where the payment method is being used.

+ :::image type="content" source="./media/change-credit-card/select-billing-profile.png" alt-text="Example screenshot showing the list of billing profiles." :::

+1. In the left menu list, under **Settings**, select **Payment methods**.

+1. On the payment methods page for your billing profile, a table of payment methods is shown under the **Your credit cards** section. Find the credit card that you want to delete, select the ellipsis (**…**), and then select **Delete**.

+ :::image type="content" source="./media/change-credit-card/delete-credit-card.png" alt-text="Example screenshot showing where to delete a credit card." :::

+1. The Delete a payment method page appears. Azure checks if the payment method is in use.

+ - When the payment method isn't being used, the **Delete** option is enabled. Select it to delete the credit card information.

+ - If the payment method is being used, it must be replaced or detached. Continue reading the following sections. They explain how to **detach** the payment method that's in use by your subscription.

+### Detach payment method used by an MCA billing profile

+If your payment method is being used by an MCA billing profile, you'll see a message similar to the following example.

+To detach a payment method, a list of conditions must be met. If any conditions aren't met, instructions appear explaining how to meet the condition. A link also appears that takes you to the location where you can resolve the condition.

+When all the conditions are all satisfied, you can detach the payment method from the billing profile.

+> [!NOTE]

+> When the default payment method is detached, the billing profile is put into an _inactive_ state. Anything deleted in this process will not be able to be recovered. After a billing profile is set to inactive, you must sign up for a new Azure subscription to create new resources.

+#### To detach a payment method

+1. In the Delete a payment method area, select the **Detach the current payment method** link.

+1. If all conditions are met, select **Detach**. Otherwise, continue to the next step.

+1. If Detach is unavailable, a list of conditions is shown. Take the actions listed. Select the link shown in the Detach the default payment method area. Here's an example of a corrective action that explains the actions you need to take.

+ :::image type="content" source="./media/change-credit-card/azure-subscriptions.png" alt-text="Example screenshot showing a corrective action needed to detach a payment method for MCA." :::

+1. When you select the corrective action link, you're redirected to the Azure page where you take action. Take whatever correction action is needed.

+1. If necessary, complete all other corrective actions.

+1. Navigate back to **Cost Management + Billing** > **Billing profiles** > **Payment methods**. Select **Detach**. At the bottom of the Detach the default payment method page, select **Detach**.

+> [!NOTE]

+> - After you cancel a subscription, it can take up to 90 days for the subscription to be deleted.

+> - You can only delete a payment method after all previous charges for a billing profile are settled. If you are in an active billing period, you must wait until the end of the billing period to delete your payment method. **Ensure all other detach conditions are met while waiting for your billing period to end**.

+### Delete a pay-as-you-go (MOSP) payment method

+You must be an account administrator to delete a payment method.

+If your payment method is in use by a subscription, do the following steps.

+1. Sign in to the Azure portal at https://portal.azure.com/.

+1. Navigate to **Cost Management + Billing**.

+1. If necessary, select a billing scope.

+1. In the left menu list under **Billing**, select **Payment methods**.

+1. In the Payment methods area, on the row that the payment method is on, select the ellipsis (**...**) symbol and then select **Delete**.

+ :::image type="content" source="./media/change-credit-card/delete-mosp-payment-method.png" alt-text="Example screenshot showing a corrective action needed to detach a payment method for MOSP." :::

+1. In the Delete a payment method area, select **Delete** if all conditions are met. If Delete is unavailable, continue to the next step.

+1. A list of conditions is shown. Take the actions listed. Select the link shown in the Delete a payment method area.

+ :::image type="content" source="./media/change-credit-card/payment-method-in-use-mosp.png" alt-text="Example screenshot showing that a payment method is in use by a pay-as-you-go subscription." :::

+1. When you select the corrective action link, you're redirected to the Azure page where you take action. Take whatever correction action is needed.

+1. If necessary, complete all other corrective actions.

+1. Navigate back to **Cost Management + Billing** > **Billing profiles** > **Payment methods** and delete the payment method.

+> [!NOTE]

+> After you cancel a subscription, it can take up to 90 days for the subscription to be deleted.

+For EA enrollments, you can download your invoice in the Azure portal.

+1. On the Invoices page, find the row of the invoice that you want to download. To the right of the row, select the ellipsis (**…**) symbol.

+1. Select **Prepare document** to prepare the document that you want to download.

+ :::image type="content" source="./media/direct-ea-azure-usage-charges-invoices/prepare-document.png" alt-text="Screenshot showing the Prepare document page when you prepare the invoice." lightbox="./media/direct-ea-azure-usage-charges-invoices/prepare-document.png" :::

+1. When the document is prepared, select **Download**.

+## Updated direct EA billing invoice documents

+Azure is enhancing its invoicing experience. The enhanced experience includes an improved invoice PDF file, a summary PDF, and a transactions file.

+There are no changes to invoices generated before November 18, 2022.

+The invoice notification email address is changing from `msftinv@microsoft.com` to `no-reply@microsoft.com` for customers and partners under the enhanced invoicing experience.

+We recommend that you add the new email address to your address book or safe sender list to ensure that you receive the emails.

+For more information about invoice documents, see [Direct EA billing invoice documents](direct-ea-billing-invoice-documents.md).

+Or you can update the PO number in the Invoice area for the upcoming invoice:

+> The newly added column Purchase Month will help identify in which month the refunds are updated and helps to reconcile reservation refunds.

+ Title: Direct EA billing invoice documents

+description: Learn how to understand the invoice files associated with your direct enterprise agreement.

+tags: billing

+# Direct EA billing invoice documents

+This article helps you understand the invoice files associated with your direct enterprise agreement. For information about downloading the files, see [View your Azure usage summary details and download reports for direct EA enrollments](direct-ea-azure-usage-charges-invoices.md).

+All documents are available between the 12th- 15th day of each month. However, when an invoice is unusually large, availability might be delayed.

+## Understand the invoice file

+Your invoice is a PDF file that contains at least two pages.

+The first page is the billing summary. It contains general information about the invoice, amount due, and payment instructions, if applicable. It also contains address information for your organization and high-level details about your order.

+The second page lists the individual products in your order.

+### Invoice terms

+On the top of page one, you'll find the summary with the following fields:

+**Invoice** ΓÇô The number is a unique number generated by Microsoft that identifies your spending for the corresponding billing period.

+**Invoice Date** - The date Microsoft created the invoice.

+**PO Number** - The purchase order (PO) number that you specify. The PO number can't be updated on an invoice that's already generated.

+**PO Date** ΓÇô It's generally the date when the order was entered into Microsoft systems.

+**Billing Period** - The date range covered by the invoice.

+**Payment Terms** ΓÇô They explain the arrangement for when the invoice payment is due.

+ > [!IMPORTANT]

+ > Pay using wire transfer or ACH using the instructions provided on the invoice. Don't mail a physical check to a Microsoft address shown on your invoice.

+**Due Date** - The date when the invoice payment is due to Microsoft.

+#### Addresses

+The following addresses differ, depending on the size and configuration of your organization.

+- The Sold-To address is the name and address of the organization that bought the subscription.

+- The Bill-To address is the address of your billing department.

+- The Ship-To address are details of the location to which the products are shipped or used for tax exemption (for India).

+- The End Customer Address is the address where the service is used.

+#### Billing summary

+Billing summary gives the breakdown of the total amount due. Total = Charges ΓÇô Commitment usage (if applicable) + Sales Tax.

+#### Billing details by product

+Page two lists billing details by product, including unit price, quantity, commitment usage (if applicable), net charge, tax rate, tax amount, and total corresponding to each usage charge.

+Here's an example of the first page of the invoice file.

+Here's an example of the last page of the invoice file.

+_Prices shown on the invoice are for informational purposes only._

+## Understand the summary invoice file

+The summary invoice file is a concise version of the detailed PDF file with a broad categorization of purchases at product family level. The first page is the same as the invoice PDF. The second page contains a billing summary by product family covering usages charges and corresponding amount incurred.

+Here's an example of the first page of the summary invoice file.

+Here's an example of the last page of the summary invoice file.

+## Understand the transactions file

+The transactions file is a CSV file that includes the same information as the invoice in a format that helps you quickly reconcile charges. It contains the following line-item details:

+| Invoice item | Description |

+| | |

+| Invoice Number | A Microsoft generated unique number that identifies your spending for the corresponding billing period. |

+| Invoice Date | The date Microsoft created the invoice. |

+| Document Type | Determines whether it's an invoice or credit note. |

+| Agreement Number | The Licensing ID # / enrollment # / contract number. |

+| Bill To | Customer Number, Bill To Customer Name, and Bill To Customer Country are details of the billing department. |

+| Sold To | Customer Number, Sold To Customer Name, and Sold To Customer Country are details of the organization that bought the subscription. |

+| Ship To | Customer Number, Ship To Customer Name, and Ship To Customer Country are details of the location where the products are shipped or used for tax exemption (for India). |

+| End Customer Name and End Customer Country | Details of the final consumer where the service is used. |

+| Purchase Order Number | The purchase order (PO) number that you specify. |

+| Billing Currency | Shows the currency that was chosen by the end customer in terms of payment. |

+| Transaction Type | Reflects whether it's a debit invoice or a credit memo. |

+| Line Item Number | The line ID for internal reference. |

+| Usage Country | The location where the product is used. |

+| Delivery | Shows how the invoice is being delivered. |

+| MS Part Number | A reference number for the product. |

+| Item Name | The description of the purchased product. |

+| Product Family | The logical categorization of products. |

+| License Type | Reflects the terms of buying the product. |

+| Price Level | The price categorization of product. |

+| Billing Option | The mode of payment. |

+| Taxable | Indicates whether the product is taxable. |

+| Pool | The classification of the product into a system, server, or application. |

+| Service Period Start Date, Service Period End Date | Indicates the eligible service period. |

+| Reason Code | Used at the time of return. |

+| Description | The explanation of the reason code. |

+| Quantity | The number of units bought or used. |

+| Unit Price | The price per unit product. |

+| Extended Amount | The quantity multiplied by the unit price. |

+| Commitment Usage | The amount of monetary commitment that has been used. |

+| Net Amount | The extended amount minus the commitment usage. |

+| Tax Rate | The tax rate applicable to the product based on the country of billing. |

+| Tax Amount | The net amount multiplied by tax rate. |

+| Total | The sum of the net amount and tax amount. |

+| Is Third Party | Indicates whether the product or service is a third-party product. |

+## Next steps

+- Learn how to download your Direct EA billing invoice documents at [View your Azure usage summary details and download reports for direct EA enrollments](direct-ea-azure-usage-charges-invoices.md).

+- Generate and regenerate primary and secondary access keys.

+- Revoke access keys.

+4. Under **Enrollment Access Keys**, select **regenerate** to generate either a primary or secondary key.

+

+Example: bearer \<APIKey\> |

+| SubscriptionGuid | MOSPSubscriptionGuid | SubscriptionGuid | |

+- **Microsoft Online Services Program**: A billing account for a Microsoft Online Services Program is created when you sign up for Azure through the Azure website. For example, when you sign up for an [Azure Free Account](https://azure.microsoft.com/offers/ms-azr-0044p/), [account with pay-as-you-go rates](https://azure.microsoft.com/offers/ms-azr-0003p/) or as a [Visual studio subscriber](https://azure.microsoft.com/pricing/member-offers/credit-for-visual-studio-subscribers/).

+ - The ability to create other Microsoft Online Services Program subscriptions is determined on an individual basis according to your history with Azure.

+- **Enterprise Agreement**: A billing account for an Enterprise Agreement (EA) is created when your organization signs an [Enterprise Agreement](https://azure.microsoft.com/pricing/enterprise-agreement/) to use Azure. An EA enrollment can contain an unlimited number of EA accounts.

+ - An EA account has a subscription limit of 5000. *Regardless of a subscription's state, it's included in the limit. So, deleted and disabled subscriptions are included in the limit*. If you need more subscriptions than the limit, create more EA accounts. Generally speaking, a subscription is a billing container.

+ - We recommend that you avoid creating multiple subscriptions to implement access boundaries. To separate resources with an access boundary, consider using a resource group. For more information about resource groups, see [Manage Azure resource groups by using the Azure portal](../../azure-resource-manager/management/manage-resource-groups-portal.md).

+- **Microsoft Customer Agreement**: A billing account for a Microsoft Customer Agreement is created when your organization works with a Microsoft representative to sign a Microsoft Customer Agreement. Some customers in select regions, who sign up through the Azure website for an [account with pay-as-you-go rates](https://azure.microsoft.com/offers/ms-azr-0003p/) or an [Azure Free Account](https://azure.microsoft.com/offers/ms-azr-0044p/) may have a billing account for a Microsoft Customer Agreement as well.

+ - You can have a maximum of 5 subscriptions in a Microsoft Customer Agreement for an individual. The ability to create additional subscriptions is determined on an individual basis according to your history with Azure.

+ - A Microsoft Customer Agreement for an enterprise can have up to 5000 subscriptions under it.

+A scope is a node within a billing account that you use to view and manage billing. It's where you manage billing data, payments, invoices, and conduct general account management.

+Azure savings plans help you save money by committing to an hourly spend for one-year or three-years plans for Azure compute resources. Saving plans discounts apply to usage from virtual machines, Dedicated Hosts, Container Instances, App Services and Azure Premium Functions. The hourly commitment is priced in USD for Microsoft Customer Agreement customers and local currency for Enterprise customers.

+Before you enter a commitment to buy a savings plan, review the following sections to prepare for your purchase.

+To determine if you're eligible to buy a plan, [check your billing type](../manage/view-all-accounts.md#check-the-type-of-your-account).

+By default, the recommendations are for the entire billing scope (billing account or billing profile for MCA and enrollment for EA). You can view subscription and resource group-level recommendations by restricting benefit application to one of those levels.

+Recommendations are based on terms, so you'll see the 1-year or 3-year recommendations at each level by toggling the term options. We don't currently support management group-level recommendations.

+3. Multiply the rate by the number of instances that are being returned.

+* **Partner Solution:** Diagnostic logs could be sent to Partner solutions through integration. For potential partner integrations, [click to learn more about partner integration.](../partner-solutions/overview.md)

+- [Monitor and manage pipelines programmatically](monitor-programmatically.md)

+1. Select **Next: Git configuration**. Set up the repository by following the instructions in [Configuration method 4: During factory creation](./source-control.md#configuration-method-4-during-factory-creation), or select the **Configure Git later** checkbox.

+> [Incrementally copy new and changed files based on LastModifiedDate by using the Copy Data tool](tutorial-incremental-copy-lastmodified-copy-data-tool.md)

+* **AU Analysis** shows how many AUs (analytics units) were used in the job and explore simulations of different AU allocation strategies.

+1. In **Data Lake Analytics Explorer**, select **Data Lake Analytics**.

+1. In **Data Lake Analytics Explorer**, browse to the job you submitted.

+1. Select the **Data** tab in your job.

+* **Microsoft Azure SDK for .NET** [version 2.7.1 or later](https://azure.microsoft.com/downloads/).

+This article describes how to manage Azure Data Lake Analytics accounts, data sources, users, and jobs by using the Azure portal.

+2. Select **Create a resource** and search for **Data Lake Analytics**.

+4. Select **Create**.

+2. Select **Delete**.

+4. Select **Delete**.

+2. Select **Data explorer**.

+3. Select **Add Data Source**.

+ * To add Azure Blob storage, you need the storage account and the account key. To find them, go to the storage account in the portal and select **Access keys**.

+2. On the menu on the left, select **Firewall**.