+> You shouldn't use built-in or extension attributes to store sensitive personal data, such as account credentials, government identification numbers, cardholder data, financial account data, healthcare information, or sensitive background information.

+```bash

+```config

+```bash

+ ```bash

+ ```bash

+ sudo kinit contosoadmin@AADDSCONTOSO.COM

+ ```bash

+ ```bash

+ ```bash

+ ```bash

+ ```bash

+ ```config

+ ```bash

+ sudo ssh -l contosoadmin@AADDSCONTOSO.com centos.aaddscontoso.com

+ ```bash

+ sudo pwd

+ ```bash

+ sudo id

+ ```bash

+```bash

+```config

+# [RHEL 6](#tab/rhel)

+> [!IMPORTANT]

+> Keep in consideration Red Hat Enterprise Linux 6.X and Oracle Linux 6.x is already EOL.

+> RHEL 6.10 has available [ELS support](https://www.redhat.com/en/resources/els-datasheet), which [will end on 06/2024]( https://access.redhat.com/product-life-cycles/?product=Red%20Hat%20Enterprise%20Linux,OpenShift%20Container%20Platform%204).

+## Install required packages

+The VM needs some additional packages to join the VM to the managed domain. To install and configure these packages, update and install the domain-join tools using `yum`.

+```bash

+Now that the required packages are installed on the VM, join the VM to the managed domain.

+ ```bash

+ ```bash

+ Open the `/etc/krb5.conf` file with an editor:

+ ```bash

+ ```config

+ ```bash

+ ```config

+ ```bash

+ ```bash

+ sudo authconfig --enablesssd --enablesssd auth --update

+ ```bash

+```bash

+ ```bash

+ ```config

+ ```bash

+ sudo service sshd restart

+ ```

+# [RHEL 7](#tab/rhel7)

+## Install required packages

+The VM needs some additional packages to join the VM to the managed domain. To install and configure these packages, update and install the domain-join tools using `yum`.

+```bash

+sudo yum install realmd sssd krb5-workstation krb5-libs oddjob oddjob-mkhomedir samba-common-tools

+```

+## Join VM to the managed domain

+Now that the required packages are installed on the VM, join the VM to the managed domain. Again, use the appropriate steps for your RHEL distro version.

+1. Use the `realm discover` command to discover the managed domain. The following example discovers the realm *AADDSCONTOSO.COM*. Specify your own managed domain name in ALL UPPERCASE:

+ ```bash

+ sudo realm discover AADDSCONTOSO.COM

+ If the `realm discover` command can't find your managed domain, review the following troubleshooting steps:

+ * Make sure that the domain is reachable from the VM. Try `ping aaddscontoso.com` to see if a positive reply is returned.

+ * Check that the VM is deployed to the same, or a peered, virtual network in which the managed domain is available.

+ * Confirm that the DNS server settings for the virtual network have been updated to point to the domain controllers of the managed domain.

+1. Now initialize Kerberos using the `kinit` command. Specify a user that's a part of the managed domain. If needed, [add a user account to a group in Azure AD](../active-directory/fundamentals/active-directory-groups-members-azure-portal.md).

+ Again, the managed domain name must be entered in ALL UPPERCASE. In the following example, the account named `contosoadmin@aaddscontoso.com` is used to initialize Kerberos. Enter your own user account that's a part of the managed domain:

+ ```bash

+ sudo kinit contosoadmin@AADDSCONTOSO.COM

+ ```

+1. Finally, join the VM to the managed domain using the `realm join` command. Use the same user account that's a part of the managed domain that you specified in the previous `kinit` command, such as `contosoadmin@AADDSCONTOSO.COM`:

+ ```bash

+ sudo realm join --verbose AADDSCONTOSO.COM -U 'contosoadmin@AADDSCONTOSO.COM'

+ ```

+It takes a few moments to join the VM to the managed domain. The following example output shows the VM has successfully joined to the managed domain:

+```output

+Successfully enrolled machine in realm

+```

+## Allow password authentication for SSH

+By default, users can only sign in to a VM using SSH public key-based authentication. Password-based authentication fails. When you join the VM to a managed domain, those domain accounts need to use password-based authentication. Update the SSH configuration to allow password-based authentication as follows.

+1. Open the *sshd_conf* file with an editor:

+ ```bash

+ sudo vi /etc/ssh/sshd_config

+1. Update the line for *PasswordAuthentication* to *yes*:

+ ```bash

+ PasswordAuthentication yes

+ ```

+ When done, save and exit the *sshd_conf* file using the `:wq` command of the editor.

+1. To apply the changes and let users sign in using a password, restart the SSH service.

+ ```bash

+ sudo systemctl restart sshd

+ ```

+ ```bash

+ ```config

+ ```bash

+ sudo ssh -l contosoadmin@AADDSCONTOSO.com rhel.aaddscontoso.com

+ ```bash

+ sudo pwd

+ ```bash

+ sudo id

+ ```bash

+```bash

+```config

+ ```bash

+ ```bash

+ ```config

+ ```config

+ ```config

+ ```config

+ 1. Add the following line to `/etc/ntp.conf`:

+ ```config

+ ```bash

+ ```bash

+ ```bash

+ config pam-config --add --winbind

+ ```bash

+ sudo pam-config -a --mkhomedir

+ ```bash

+ ```bash

+ ```config

+ ```bash

+ ```bash

+ ```config

+ ```bash

+ sudo ssh -l contosoadmin@AADDSCONTOSO.com linux-q2gr.aaddscontoso.com

+ ```bash

+ sudo pwd

+ ```bash

+ sudo id

+ ```bash

+```bash

+```config

+```bash

+ ```bash

+ ```config

+ ```bash

+ ```bash

+ ```bash

+ sudo kinit -V contosoadmin@AADDSCONTOSO.COM

+ ```bash

+```config

+ ```bash

+ ```config

+ ```bash

+ ```bash

+ ```config

+ ```bash

+1. Open the `/etc/pam.d/common-session` file in an editor:

+ ```bash

+ ```config

+ ```bash

+ ```config

+ ```bash

+ sudo ssh -l contosoadmin@AADDSCONTOSO.com ubuntu.aaddscontoso.com

+ ```bash

+ sudo pwd

+ ```bash

+ sudo id

+ ```bash

+ - Ensure that multiple roles aren't assigned to a user. There's no guarantee which role is provisioned.

+Should you need to start over and reset your existing mappings back to their default state, you can select the **Restore default mappings** check box and save the configuration. Doing so sets all mappings and scoping filters as if the application was added to your Azure AD tenant from the application gallery.

+Selecting this option forces a resynchronization of all users while the provisioning service is running.

+- The attribute `IsSoftDeleted` is often part of the default mappings for an application. `IsSoftdeleted` can be true in one of four scenarios: 1) The user is out of scope due to being unassigned from the application. 2) The user is out of scope due to not meeting a scoping filter. 3) The user has been soft deleted in Azure AD. 4) The property `AccountEnabled` is set to false on the user. It's not recommended to remove the `IsSoftDeleted` attribute from your attribute mappings.

+Credentials are required for Azure AD to connect to the application's user management API. While you're configuring automatic user provisioning for an application, you need to enter valid credentials. For gallery applications, you can find credential types and requirements for the application by referring to the app tutorial. For non-gallery applications, you can refer to the [SCIM](./use-scim-to-provision-users-and-groups.md#authorization-to-provisioning-connectors-in-the-application-gallery) documentation to understand the credential types and requirements. In the Azure portal, you're able to test the credentials by having Azure AD attempt to connect to the app's provisioning app using the supplied credentials.

+- A new initial cycle is triggered using the **Restart provisioning** option in the Azure portal, or using the appropriate Microsoft Graph API command. This action clears any stored watermark and causes all source objects to be evaluated again. This won't break the links between source and target objects. To break the links use [Restart synchronizationJob](/graph/api/synchronization-synchronizationjob-restart?view=graph-rest-beta&tabs=http&preserve-view=true) with the following request:

+Confirm the checkobx for updates is selected.

+Confirm the mapping for *active* for your application. If your using an application from the app gallery, the mapping may be slightly different. In this case, use the default mapping for gallery applications.

+ 30 days after a user is deleted in Azure AD, they're permanently deleted from the tenant. At this point, the provisioning service sends a DELETE request to permanently delete the user in the application. At any time during the 30-day window, you can [manually delete a user permanently](../fundamentals/active-directory-users-restore.md), which sends a delete request to the application.

+If one of the above four events occurs and the target application doesn't support soft deletes, the provisioning service will send a DELETE request to permanently delete the user from the app.

+If you see an attribute IsSoftDeleted in your attribute mappings, it's used to determine the state of the user and whether to send an update request with active = false to soft delete the user.

+|When a user is disabled in Azure AD, unassigned from an app, soft-deleted in Azure AD, or blocked from sign-in, send a DELETE request to the target application.|This is currently supported for a limited set of gallery applications where the functionality is required. It's not configurable by customers.|

+|When a user is deleted in Azure AD, do nothing in the target application.|Ensure that "Delete" isn't selected as one of the target object actions in the [attriubte configuration experience](skip-out-of-scope-deletions.md).|

+* If a user that was previously managed by the provisioning service is unassigned from an app, or from a group assigned to an app we will send a disable request. At that point, the user isn't managed by the service and we won't send a delete request when they're deleted from the directory.

+* Provisioning a user that is disabled in Azure AD isn't supported. They must be active in Azure AD before they're provisioned.

+* When a user goes from soft-deleted to active, the Azure AD provisioning service will activate the user in the target app, but won't automatically restore the group memberships. The target application should maintain the group memberships for the user in inactive state. If the target application doesn't support this, you can restart provisioning to update the group memberships.

+To begin the migration process, enter the name or GUID of the Azure AD group you want to migrate. Once complete, press Tab or click outside the window to begin searching for the appropriate group. All users in the group are populated. A large group can take several minutes to finish.

+This window displays the attributes for the selected user in both Azure AD and the on-premises MFA Server. You can use this window to view how data was written to a user after migration.

+The **Settings** option allows you to change the settings for the migration process:

+- Automatic synchronization ΓÇô Starts a background service that will continually monitor any authentication method changes to users in the on-premises MFA Server, and write them to Azure AD at the specified time interval defined.

+- Synchronization server ΓÇô Allows the MFA Server Migration Sync service to run on a secondary MFA Server rather than only run on the primary. To configure the Migration Sync service to run on a secondary server, the `Configure-MultiFactorAuthMigrationUtility.ps1` script must be run on the server to register a certificate with the MFA Server Migration Utility app registration. The certificate is used to authenticate to Microsoft Graph.

+The migration process can be automatic or manual.

+1. You can migrate users even if they are unchanged. By default, the utility is set to **Only migrate users that have changed**. Click **Migrate all users** to re-migrate previously migrated users that are unchanged. Migrating unchanged users can be useful during testing if an administrator needs to reset a userΓÇÖs Azure MFA settings and wants to re-migrate them.

+ :::image type="content" border="true" source="./media/how-to-mfa-server-migration-utility/migrate-users.png" alt-text="Screenshot of Migrate users dialog.":::

+For the automatic process, click **Automatic synchronization** in **Settings**, and then select whether you want all users to be synced, or only members of a given Azure AD group.

+

+## Disable resilience defaults

+## Require token protection for sign-in sessions (preview)

+Token protection (sometimes referred to as token binding in the industry) attempts to reduce attacks using token theft by ensuring a token is usable only from the intended device. When an attacker is able to steal a token, by hijacking or replay, they can impersonate their victim until the token expires or is revoked. Token theft is thought to be a relatively rare event, but the damage from it can be significant.

+The preview works for specific scenarios only. For more information, see the article [Conditional Access: Token protection (preview)](concept-token-protection.md).

+

+

+

+You can also investigate the sign-ins of a specific user by searching for sign-ins at the bottom of the dashboard. The query displays the most frequent users. Selecting a user filters the query.

+

+[Migrate approved client app to application protection policy in Conditional Access](migrate-approved-client-app.md)

+ Title: Migrate approved client app to application protection policy in Conditional Access

+description: The approved client app control is going away. Migrate to App protection policies.

+# Migrate approved client app to application protection policy in Conditional Access

+In this article, you learn how to migrate from the approved client app Conditional Access grant to the application protection policy grant. App protection policies provide the same data loss and protection as approved client app policies, but with other benefits. For more information about the benefits of using app protection policies, see the articleΓÇ»[App protection policies overview](/mem/intune/apps/app-protection-policy).

+The approved client app grant is retiring in early March 2026. Organizations must transition all current Conditional Access policies that use only the Require Approved Client App grant to Require Approved Client App or Application Protection Policy by March 2026. Additionally, for any new Conditional Access policy, only apply the Require application protection policy grant.

+After March 2026, Microsoft will stop enforcing require approved client app control, and it will be as if this grant isn't selected. Use the following steps before March 2026 to protect your organizationΓÇÖs data.

+## Edit an existing Conditional Access policy

+Require approved client apps or app protection policy with mobile devices

+The following steps make an existing Conditional Access policy require an approved client app or an app protection policy when using an iOS/iPadOS or Android device. This policy works in tandem with an app protection policy created in Microsoft Intune.

+Organizations can choose to update their policies using the following steps.

+1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

+1. Browse to **Azure Active Directory** > **Security** > **Conditional Access**.

+1. Select a policy that uses the approved client app grant.

+1. Under **Access controls** > **Grant**, select **Grant access**.

+ 1. Select **Require approved client app** and **Require app protection policy**

+ 1. **For multiple controls** select **Require one of the selected controls**

+1. Confirm your settings and set **Enable policy** to **Report-only**.

+1. Select **Create** to create to enable your policy.

+After confirming your settings using [report-only mode](howto-conditional-access-insights-reporting.md), an administrator can move the **Enable policy** toggle from **Report-only** to **On**.

+Repeat the previous steps on all of your policies that use the approved client app grant.

+> [!WARNING]

+> Not all applications that are supported as approved applications or support application protection policies. For a list of some common client apps, seeΓÇ»[App protection policy requirement](concept-conditional-access-grant.md#require-app-protection-policy). If your application is not listed there, contact the application developer.

+## Create a Conditional Access policy

+Require app protection policy with mobile devices

+The following steps help create a Conditional Access policy requiring an approved client app or an app protection policy when using an iOS/iPadOS or Android device. This policy works in tandem with an [app protection policy created in Microsoft Intune](/mem/intune/apps/app-protection-policies).

+Organizations can choose to deploy this policy using the following steps.

+1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

+1. Browse to **Azure Active Directory** > **Security** > **Conditional Access**.

+1. Select **New policy**.

+1. Give your policy a name. We recommend that organizations create a meaningful standard for the names of their policies.

+1. Under **Assignments**, select **Users or workload identities**.

+ 1. Under **Include**, select **All users**.

+ 1. Under **Exclude**, select **Users and groups** and exclude at least one account to prevent yourself from being locked out. If you don't exclude any accounts, you can't create the policy.

+1. Under **Cloud apps or actions**, select **All cloud apps**.

+1. Under **Conditions** > **Device platforms**, set **Configure** to **Yes**.

+ 1. Under **Include**, **Select device platforms**.

+ 1. Choose **Android** and **iOS**

+ 1. Select **Done**.

+1. Under **Access controls** > **Grant**, select **Grant access**.

+ 1. Select **Require approved client app** and **Require app protection policy**

+ 1. **For multiple controls** select **Require one of the selected controls**

+1. Confirm your settings and set **Enable policy** to **Report-only**.

+1. Select **Create** to create to enable your policy.

+After confirming your settings using [report-only mode](howto-conditional-access-insights-reporting.md), an administrator can move the **Enable policy** toggle from **Report-only** to **On**.

+> [!NOTE]

+> If an app does not support **Require app protection policy**, end users trying to access resources from that app will be blocked.

+## Next steps

+For more information on application protection policies, see:

+[App protection policies overview](/mem/intune/apps/app-protection-policy)

+Organizations can use terms of use along with Conditional Access policies to require employees or guests to accept your terms of use policy before getting access. These terms of use statements can be generalized or specific to groups or users and provided in multiple languages. Administrators can determine who has or hasn't accepted terms of use with the provided logs or APIs.

+* A working Azure AD tenant with Azure AD Premium P1, or trial license enabled. If needed, [create one for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+* Administrators who interact with terms of use must have one or more of the following role assignments depending on the tasks they're performing. To follow the [Zero Trust principle of least privilege](/security/zero-trust/), consider using [Privileged Identity Management (PIM)](../privileged-identity-management/pim-configure.md) to just-in-time activate privileged role assignments.

+ * Read terms of use configuration and Conditional Access policies

+ * [Security Reader](../roles/permissions-reference.md#security-reader)

+ * [Global Reader](../roles/permissions-reference.md#global-reader)

+ * Create or modify terms of use and Conditional Access policies

+ * [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator)

+ * [Security Administrator](../roles/permissions-reference.md#security-administrator)

+1. Sign in to the **Azure portal** as a Conditional Access Administrator or Security Administrator.

+1. In the **Name** box, enter a name for the terms of use policy used in the Azure portal.

+1. Select the language for your terms of use policy document. The language option allows you to upload multiple terms of use policies, each with a different language. The version of the terms of use policy that an end user sees is based on their browser preferences.

+ | Date in the future | Monthly | Starting today, users must accept the terms of use policy. When the future date occurs, consents expire, and then users must reaccept every month. |

+1. Use the **Duration before re-acceptance required (days)** setting to specify the number of days before the user must reaccept the terms of use policy. This option allows users to follow their own schedule. For example, if you set the duration to **30** days, this is how expirations might occur for two users:

+ | **Custom policy** | Select the users, groups, and apps that this terms of use policy is applied to. |

+ | **Create Conditional Access policy later** | This terms of use policy appears in the grant control list when creating a Conditional Access policy. |

+Once a ToU policy is created and enforced, users, who are in scope, see the following screen during sign-in.

+ - **Require users to expand the terms of use** ΓÇô Setting this option to **On** forces the end user to expand the terms of use policy document before accepting it.

+1. There's also a toggle option here **Require reaccept** if you want to require your users to accept this new version the next time they sign in. If you require your users to reaccept, next time they try to access the resource defined in your conditional access policy they'll be prompted to accept this new version. If you donΓÇÖt require your users to reaccept, their previous consent stays current and only new users who haven't consented before or whose consent expires see the new version. Until the session expires, **Require reaccept** not require users to accept the new TOU. If you want to ensure reaccept, delete and recreate or create a new TOU for this case.

+1. You see the most recent version under the Document column.

+The **Require users to consent on every device** setting enables you to require end users to accept your terms of use policy on every device they're accessing from. The end user is required to register their device in Azure AD. When the device is registered, the device ID is used to enforce the terms of use policy on each device.

+Per-device terms of use have the following constraints:

+If the user's device isn't joined, they receive a message that they need to join their device. Their experience is dependent on the platform and software.

+If they're using Chrome, they're prompted to install the [Windows 10 Accounts extension](https://chrome.google.com/webstore/detail/windows-10-accounts/ppnbnpeolgkicgegkbkbjmhlideopiji).

+If a user is using an iOS device, they're prompted to install the [Microsoft Authenticator app](https://apps.apple.com/us/app/microsoft-authenticator/id983156458).

+If a user is using an Android device, they're prompted to install the [Microsoft Authenticator app](https://play.google.com/store/apps/details?id=com.azure.authenticator).

+If a user is using browser that isn't supported, they're asked to use a different browser.

+Conditional Access policies take effect immediately. When this happens, the administrator starts to see ΓÇ£sad cloudsΓÇ¥ or "Azure AD token issues". The administrator must sign out and sign in to satisfy the new policy.

+You can configure a Conditional Access policy for the Azure Information Protection app and require a terms of use policy when a user accesses a protected document. This configuration triggers a terms of use policy before a user accessing a protected document for the first time.

+A: The terms of use details overview reflect aggregated acceptances of the current version of the policy (updated once every day). If expiration is enabled or a TOU agreement is updated (with reacceptance required), the count on the details overview is reset since the acceptances are expired, thereby showing the count of the current version. All acceptance history is still captured in the CSV report.

+A: If you've configured both Azure AD terms of use and [Intune terms and conditions](/intune/terms-and-conditions-create), the user is required to accept both. For more information, see the [Choosing the right Terms solution for your organization blog post](https://go.microsoft.com/fwlink/?linkid=2010506&clcid=0x409).

+A: Terms of use utilize the following endpoints for authentication: https://tokenprovider.termsofuse.identitygovernance.azure.com, https://myaccount.microsoft.com and https://account.activedirectory.windowsazure.com. If your organization has an allowlist of URLs for enrollment, you need to add these endpoints to your allowlist, along with the Azure AD endpoints for sign-in.

+

+

+POST https://graph.microsoft.com/v1.0/{tenant-id}/domains/foo.contoso.com/promote

+>This information last updated on March 30th, 2023.<br/>You can also download a CSV version of this table [here](https://download.microsoft.com/download/e/3/e/e3e9faf2-f28b-490a-9ada-c6089a1fc5b0/Product%20names%20and%20service%20plan%20identifiers%20for%20licensing.csv).

+| Microsoft Power Automate Free | FLOW_FREE | f30db892-07e9-47e9-837c-80727f46fd3d | DYN365_CDS_VIRAL (17ab22cd-a0b3-4536-910a-cb6eb12696c0)<br/>EXCHANGE_S_FOUNDATION (113feb6c-3fe4-4440-bddc-54d774bf0318)<br/>FLOW_P2_VIRAL (50e68c76-46c6-4674-81f9-75456511b170) | COMMON DATA SERVICE (17ab22cd-a0b3-4536-910a-cb6eb12696c0)<br/>EXCHANGE FOUNDATION (113feb6c-3fe4-4440-bddc-54d774bf0318)<br/>FLOW FREE (50e68c76-46c6-4674-81f9-75456511b170) |

+| [Integrate supported SaaS applications from the gallery to Azure AD and enable Single sign on](../manage-apps/add-application-portal.md) | Azure AD has a gallery that contains thousands of preintegrated applications. Some of the applications your organization uses are probably in the gallery accessible directly from the Azure portal. Provide access to corporate SaaS applications remotely and securely with improved user experience (SSO) |

+| [Integrate supported SaaS applications from the gallery to Azure AD and enable Single sign on](../manage-apps/add-application-portal.md) | Azure AD has a gallery that contains thousands of preintegrated applications. Some of the applications your organization uses are probably in the gallery accessible directly from the Azure portal. Provide access to corporate SaaS applications remotely and securely with improved user experience (SSO). |

+| [Integrate supported SaaS applications from the gallery to Azure AD and enable Single sign on](../manage-apps/add-application-portal.md) | Azure AD has a gallery that contains thousands of preintegrated applications. Some of the applications your organization uses are probably in the gallery accessible directly from the Azure portal. Provide access to corporate SaaS applications remotely and securely with improved user experience (SSO). |

+## March 2023

+### Public Preview - New provisioning connectors in the Azure AD Application Gallery - March 2023

+**Type:** New feature

+**Service category:** App Provisioning

+**Product capability:** 3rd Party Integration

+

+We've added the following new applications in our App gallery with Provisioning support. You can now automate creating, updating, and deleting of user accounts for these newly integrated apps:

+- [Acunetix 360](../saas-apps/acunetix-360-provisioning-tutorial.md)

+- [Akamai Enterprise Application Access](../saas-apps/akamai-enterprise-application-access-provisioning-tutorial.md)

+- [Ardoq](../saas-apps/ardoq-provisioning-tutorial.md)

+- [Torii](../saas-apps/torii-provisioning-tutorial.md)

+For more information about how to better secure your organization by using automated user account provisioning, see: [Automate user provisioning to SaaS applications with Azure AD](../app-provisioning/user-provisioning.md).

+### General Availability - Workload identity Federation for Managed Identities

+**Type:** New feature

+**Service category:** Managed identities for Azure resources

+**Product capability:** Developer Experience

+Workload Identity Federation enables developers to use managed identities for their software workloads running anywhere and access Azure resources without needing secrets. Key scenarios include:

+- Accessing Azure resources from Kubernetes pods running in any cloud or on-premises

+- GitHub workflows to deploy to Azure, no secrets necessary

+- Accessing Azure resources from other cloud platforms that support OIDC, such as Google Cloud Platform.

+For more information, see:

+- [Workload identity federation](../workload-identities/workload-identity-federation.md).

+- [Configure a user-assigned managed identity to trust an external identity provider (preview)](../workload-identities/workload-identity-federation-create-trust-user-assigned-managed-identity.md)

+- [Use Azure AD workload identity (preview) with Azure Kubernetes Service (AKS)](../../aks/workload-identity-overview.md)

+### Public Preview - New My Groups Experience

+**Type:** Changed feature

+**Service category:** Group Management

+**Product capability:** End User Experiences

+A new and improved My Groups experience is now available at https://www.myaccount.microsoft.com/groups. My Groups enables end users to easily manage groups, such as finding groups to join, managing groups they own, and managing existing group memberships. Based on customer feedback, the new My Groups support sorting and filtering on lists of groups and group members, a full list of group members in large groups, and an actionable overview page for membership requests.

+This experience replaces the existing My Groups experience at https://www.mygroups.microsoft.com in May.

+For more information, see: [Update your Groups info in the My Apps portal](https://support.microsoft.com/account-billing/update-your-groups-info-in-the-my-apps-portal-bc0ca998-6d3a-42ac-acb8-e900fb1174a4).

+### Public preview - Customize tokens with Custom Claims Providers

+**Type:** New feature

+**Service category:** Authentications (Logins)

+**Product capability:** Extensibility

+A custom claims provider lets you call an API and map custom claims into the token during the authentication flow. The API call is made after the user has completed all their authentication challenges, and a token is about to be issued to the app. For more information, see: [Custom authentication extensions (preview)](../develop/custom-claims-provider-overview.md).

+### General Availability - Converged Authentication Methods

+**Type:** New feature

+**Service category:** MFA

+**Product capability:** User Authentication

+The Converged Authentication Methods Policy enables you to manage all authentication methods used for MFA and SSPR in one policy, migrate off the legacy MFA and SSPR policies, and target authentication methods to groups of users instead of enabling them for all users in your tenant. For more information, see: [Manage authentication methods](../authentication/concept-authentication-methods-manage.md).

+### General Availability - Provisioning Insights Workbook

+**Type:** New feature

+**Service category:** Provisioning

+**Product capability:** Monitoring & Reporting

+This new workbook makes it easier to investigate and gain insights into your provisioning workflows in a given tenant. This includes HR-driven provisioning, cloud sync, app provisioning, and cross-tenant sync.

+Some key questions this workbook can help answer are:

+- How many identities have been synced in a given time range?

+- How many create, delete, update, or other operations were performed?

+- How many operations were successful, skipped, or failed?

+- What specific identities failed? And what step did they fail on?

+- For any given user, what tenants / applications were they provisioned or deprovisioned to?

+For more information, see: [Provisioning insights workbook](../app-provisioning/provisioning-workbook.md).

+### General Availability - Number Matching for Microsoft Authenticator notifications

+**Type:** Plan for Change

+**Service category:** Microsoft Authenticator App

+**Product capability:** User Authentication

+Microsoft Authenticator appΓÇÖs number matching feature has been Generally Available since Nov 2022! If you haven't already used the rollout controls (via Azure portal Admin UX and MSGraph APIs) to smoothly deploy number matching for users of Microsoft Authenticator push notifications, we highly encourage you to do so. We previously announced that we'll remove the admin controls and enforce the number match experience tenant-wide for all users of Microsoft Authenticator push notifications starting February 27, 2023. After listening to customers, we'll extend the availability of the rollout controls for a few more weeks. Organizations can continue to use the existing rollout controls until May 8, 2023, to deploy number matching in their organizations. Microsoft services will start enforcing the number matching experience for all users of Microsoft Authenticator push notifications after May 8, 2023. We'll also remove the rollout controls for number matching after that date.

+If customers donΓÇÖt enable number match for all Microsoft Authenticator push notifications prior to May 8, 2023, Authenticator users may experience inconsistent sign-ins while the services are rolling out this change. To ensure consistent behavior for all users, we highly recommend you enable number match for Microsoft Authenticator push notifications in advance.

+For more information, see: [How to use number matching in multifactor authentication (MFA) notifications - Authentication methods policy](../authentication/how-to-mfa-number-match.md)

+### Public Preview - IPv6 coming to Azure AD

+**Type:** Plan for Change

+**Service category:** Identity Protection

+**Product capability:** Platform

+Earlier, we announced our plan to bring IPv6 support to Microsoft Azure Active Directory (Azure AD), enabling our customers to reach the Azure AD services over IPv4, IPv6 or dual stack endpoints. This is just a reminder that we have started introducing IPv6 support into Azure AD services in a phased approach in late March 2023.

+

+If you utilize Conditional Access or Identity Protection, and have IPv6 enabled on any of your devices, you likely must take action to avoid impacting your users. For most customers, IPv4 won't completely disappear from their digital landscape, so we aren't planning to require IPv6 or to deprioritize IPv4 in any Azure AD features or services. We'll continue to share additional guidance on IPv6 enablement in Azure AD at this link: [IPv6 support in Azure Active Directory](https://learn.microsoft.com/troubleshoot/azure/active-directory/azure-ad-ipv6-support)

+### General Availability - Microsoft cloud settings for Azure AD B2B

+**Type:** New feature

+**Service category:** B2B

+**Product capability:** B2B/B2C

+Microsoft cloud settings let you collaborate with organizations from different Microsoft Azure clouds. With Microsoft cloud settings, you can establish mutual B2B collaboration between the following clouds:

+- Microsoft Azure commercial and Microsoft Azure Government

+- Microsoft Azure commercial and Microsoft Azure China 21Vianet

+For more information about Microsoft cloud settings for B2B collaboration., see: [Microsoft cloud settings](../external-identities/cross-tenant-access-overview.md#microsoft-cloud-settings).

+### Modernizing Terms of Use Experiences

+**Type:** Plan for Change

+**Service category:** Access Reviews

+**Product capability:** AuthZ/Access Delegation

+Starting July 2023, we're modernizing the following Terms of Use end user experiences with an updated PDF viewer, and moving the experiences from https://account.activedirectory.windowsazure.com to https://myaccount.microsoft.com:

+- View previously accepted terms of use.

+- Accept or decline terms of use as part of the sign-in flow.

+No functionalities will be removed. The new PDF viewer adds functionality and the limited visual changes in the end-user experiences will be communicated in a future update. If your organization has allow-listed only certain domains, you must ensure your allowlist includes the domains ΓÇÿmyaccount.microsoft.comΓÇÖ and ΓÇÿ*.myaccount.microsoft.comΓÇÖ for Terms of Use to continue working as expected.

+As part of our ongoing initiative to improve the developer experience, service reliability, and security of customer applications, we'll end support for the Azure Active Directory Authentication Library (ADAL). The final deadline to migrate your applications to Azure Active Directory Authentication Library (MSAL) has been extended to **June 30, 2023**.

+As we consolidate and evolve the Microsoft Identity platform, we're also investing in making significant improvements to the developer experience and service features that make it possible to build secure, robust and resilient applications. To make these features available to our customers, we needed to update the architecture of our software development kits. As a result of this change, weΓÇÖve decided that the path forward requires us to sunset Azure Active Directory Authentication Library. This allows us to focus on developer experience investments with Azure Active Directory Authentication Library.

+ > The **Self-service** menu item isn't available if the corresponding app registration's setting for public client flows is enabled. To access this setting, the app registration needs to exist in your tenant. Locate the app registration, select **Authentication** in the left navigation, then locate **Allow public client flows**.

+## Troubleshoot

+### Symptom - Access denied when you try to register an application

+When you try to register an application in Azure AD, you get a message similar to the following:

+```

+Access denied

+You do not have access

+You don't have permission to register applications in the <directoryName> directory. To request access, contact your administrator.

+```

+**Cause**

+You can't register the application in the directory because your directory administrator has [restricted who can create applications](#restrict-who-can-create-applications).

+**Solution**

+Contact your administrator to do one of the following:

+- Grant you permissions to create and consent to applications by [assigning you the Application Developer role](#grant-individual-permissions-to-create-and-consent-to-applications-when-the-default-ability-is-disabled).

+- Create the application registration for you and [assign you as the application owner](#assign-application-owners).

+ Title: 'Tutorial: Azure Active Directory SSO integration with GitHub Enterprise Cloud - Enterprise Account'

+# Tutorial: Azure Active Directory SSO integration with GitHub Enterprise Cloud - Enterprise Account

+In this tutorial, you learn how to setup an Azure Active Directory (Azure AD) SAML integration with a GitHub Enterprise Cloud - Enterprise Account. When you integrate GitHub Enterprise Cloud - Enterprise Account with Azure AD, you can:

+In this tutorial, you will configure a SAML integration for a GitHub Enterprise Account, and test enterprise account owner and enterprise/organization member authentication and access.

+> [!NOTE]

+> The GitHub `Enterprise Cloud - Enterprise Account` application does not support enabling [automatic SCIM provisioning](../fundamentals/sync-scim.md). If you need to setup provisioning for your GitHub Enterprise Cloud environment, SAML must be configured at the organization level and the `GitHub Enterprise Cloud - Organization` Azure AD application must be used instead. If you are setting up a SAML and SCIM provisioning integration for an enterprise that is enabled for [Enterprise Managed Users (EMUs)](https://docs.github.com/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users), then you must use the `GitHub Enterprise Managed User` Azure AD application for SAML/Provisioning integrations or the `GitHub Enterprise Managed User (OIDC)` Azure AD application for OIDC/Provisioning integrations.

+ 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, assign roles, and walk through the SSO configuration as well. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides)

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

+1. Perform the following step if you wish to configure the application in **SP** initiated mode:

+ Title: Azure Active Directory SSO integration with RevSpace

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

+# Tutorial: Azure Active Directory SSO integration with RevSpace

+In this tutorial, you learn how to integrate RevSpace with Azure Active Directory (Azure AD). When you integrate RevSpace with Azure AD, you can:

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

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

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

+## Prerequisites

+To get started, you need the following items:

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

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

+## Scenario description

+In this tutorial, you configure and test Azure AD SSO in a test environment.

+* RevSpace supports **SP and IDP** initiated SSO.

+* RevSpace supports **Just In Time** user provisioning.

+## Adding RevSpace from the gallery

+To configure the integration of RevSpace into Azure AD, you need to add RevSpace from the gallery to your list of managed SaaS apps.

+1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.

+1. On the left navigation pane, select the **Azure Active Directory** service.

+1. Navigate to **Enterprise Applications** and then select **All Applications**.

+1. To add new application, select **New application**.

+1. In the **Add from the gallery** section, type **RevSpace** in the search box.

+1. Select **RevSpace** from results panel and then add the app. Wait a few seconds while the app is added to your tenant.

+ 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, assign roles and walk through the SSO configuration as well. [Learn more about Microsoft 365 wizards.](/microsoft-365/admin/misc/azure-ad-setup-guides)

+## Configure and test Azure AD SSO for RevSpace

+Configure and test Azure AD SSO with RevSpace using a test user called **B.Simon**. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in RevSpace.

+To configure and test Azure AD SSO with RevSpace, perform the following steps:

+1. **[Configure Azure AD SSO](#configure-azure-ad-sso)** - to enable your users to use this feature.

+ 1. **[Create an Azure AD test user](#create-an-azure-ad-test-user)** - to test Azure AD single sign-on with B.Simon.

+ 1. **[Assign the Azure AD test user](#assign-the-azure-ad-test-user)** - to enable B.Simon to use Azure AD single sign-on.

+1. **[Configure RevSpace SSO](#configure-revspace-sso)** - to configure the single sign-on settings on application side.

+ 1. **[Create RevSpace test user](#create-revspace-test-user)** - to have a counterpart of B.Simon in RevSpace that is linked to the Azure AD representation of user.

+1. **[Test SSO](#test-sso)** - to verify whether the configuration works.

+## Configure Azure AD SSO

+Follow these steps to enable Azure AD SSO in the Azure portal.

+1. In the Azure portal, on the **RevSpace** 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, click 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** text box, type a URL using the following pattern:

+ `https://<CUSTOMER_SUBDOMAIN>.revspace.io/login/callback`

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

+ `https://<CUSTOMER_SUBDOMAIN>.revspace.io/login/callback`

+1. Perform the following step if you wish to configure the application in **SP** initiated mode:

+ In the **Sign on URL** text box, type a URL using the following pattern:

+ `https://<CUSTOMER_SUBDOMAIN>.revspace.io/login/callback`

+ > [!NOTE]

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

+1. RevSpace 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, RevSpace 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 |

+ | - | |

+ | Firstname | user.givenname |

+ | Lastname | user.surname |

+ | jobtitle | user.jobtitle |

+ | department | user.department |

+ | employeeid | user.employeeid |

+ | postalcode | user.postalcode |

+ | country | user.country |

+ | role | user.assignedroles |

+ > [!NOTE]

+ > RevSpace expects roles for users assigned to the application. Please set up these roles in Azure AD so that users can be assigned the appropriate roles. To understand how to configure roles in Azure AD, see [here](../develop/howto-add-app-roles-in-azure-ad-apps.md#app-roles-ui).

+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 RevSpace** section, copy the appropriate URL(s) based on your requirement.

+ 

+### Create an Azure AD test user

+In this section, you create a test user in the Azure portal called B.Simon.

+1. From the left pane in the Azure portal, select **Azure Active Directory**, select **Users**, and then select **All users**.

+1. Select **New user** at the top of the screen.

+1. In the **User** properties, follow these steps:

+ 1. In the **Name** field, enter `B.Simon`.

+ 1. In the **User name** field, enter the username@companydomain.extension. For example, `B.Simon@contoso.com`.

+ 1. Select the **Show password** check box, and then write down the value that's displayed in the **Password** box.

+ 1. Click **Create**.

+### Assign the Azure AD test user

+In this section, you enable B.Simon to use Azure single sign-on by granting access to RevSpace.

+1. In the Azure portal, select **Enterprise Applications**, and then select **All applications**.

+1. In the applications list, select **RevSpace**.

+1. In the app's overview page, find the **Manage** section and select **Users and groups**.

+1. Select **Add user**, then select **Users and groups** in the **Add Assignment** dialog.

+1. In the **Users and groups** dialog, select **B.Simon** from the Users list, then click the **Select** button at the bottom of the screen.

+1. If you have setup the roles as explained in the above, you can select it from the **Select a role** dropdown.

+1. In the **Add Assignment** dialog, click the **Assign** button.

+## Configure RevSpace SSO

+1. In a different web browser window, sign into RevSpace as an administrator.

+1. Click on user Profile icon, then select **Company settings**.

+ 

+1. Perform the following steps in **Settings** page.

+ 

+ a. Navigate to **Company > Single Sign-On**, then select the **Metadata Upload** tab.

+ b. Paste the **Federation Metadata XML** Value, which you've copied from the Azure portal into **XML Metadata** field.

+ c. Then click **Save**.

+### Create RevSpace test user

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

+## Test SSO

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

+#### SP initiated:

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

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

+#### IDP initiated:

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

+You can also use Microsoft My Apps to test the application in any mode. When you click the RevSpace tile in the My Apps, if configured in SP mode you would be redirected to the application sign-on page for initiating the login flow and if configured in IDP mode, you should be automatically signed in to the RevSpace for which you set up the SSO. For more information about the My Apps, see [Introduction to the My Apps](https://support.microsoft.com/account-billing/sign-in-and-start-apps-from-the-my-apps-portal-2f3b1bae-0e5a-4a86-a33e-876fbd2a4510).

+## Next steps

+Once you configure RevSpace 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 Defender for Cloud Apps](/cloud-app-security/proxy-deployment-any-app).

+In this article, you learn how to integrate Signiant Media Shuttle with Azure Active Directory (Azure AD). Media Shuttle is a solution for securely moving large files and data sets to, and from, cloud-based or on-premises storage. Transfers are accelerated and can be up to hundreds of times faster than FTP.

+When you integrate Signiant Media Shuttle with Azure AD, you can:

+You must configure and test Azure AD single sign-on for Signiant Media Shuttle in a test environment. Signiant Media Shuttle supports **SP** initiated single sign-on and **Just In Time** user provisioning.

+* A Signiant Media Shuttle subscription with a SAML Web SSO license, and access to the IT and Operations Administration Consoles.

+Add Signiant Media Shuttle from the Azure AD application gallery to configure single sign-on for Signiant Media Shuttle. 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).

+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).

+ | **Configuration Type** | **Identifier** |

+ | -- | -- |

+ | Account Level | `mediashuttle` |

+ | Portal Level | `https://<PORTALNAME>.mediashuttle.com` |

+ | **Configuration Type** | **Reply URL** |

+ | -- | -- |

+ | Account Level |`https://portals.mediashuttle.com.auth` |

+ | Portal Level | `https://<PORTALNAME>.mediashuttle.com/auth`|

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

+ | **Configuration Type** | **Sign on URL** |

+ | - | -- |

+ | Account Level | `https://portals.mediashuttle.com/auth` |

+ | Portal Level | `https://<PORTALNAME>.mediashuttle.com/auth` |

+Once you have the **App Federation Metadata Url**, sign in to the Media Shuttle IT Administration Console.

+To add Azure AD Metadata in Media Shuttle:

+1. Log into your IT Administration Console.

+2. On the Security page, in the Identity Provider Metadata field, paste the **App Federation Metadata Url** which you've copied from the Azure portal.

+3. Click **Save**.

+Once you have set up Azure AD for Media Shuttle, assigned users and groups can sign in to Media Shuttle portals through single sign-on using Azure AD authentication.

+If **Auto-add SAML authenticated members to this portal** is not enabled as part of the SAML configuration, you must add users through the **Portal Administration** console at `https://<PORTALNAME>.mediashuttle.com/admin`.

+| `verifiedCredentialsData`| array |Returns an array of verifiable credentials requested. For each verifiable credential, it provides: </li><li>The verifiable credential type(s).</li><li>The issuer's DID</li><li>The claims retrieved.</li><li>The verifiable credential issuer's domain. </li><li>The verifiable credential issuer's domain validation status. </li></ul> |

+* Recommendations summarized by category types (like reliability, performance) and impact types (high, medium, low)

+|nodeStageSecretRef.name | Specify secret name that stores one of the following:<br> `azurestorageaccountkey`<br>`azurestorageaccountsastoken`<br>`msisecret`<br>`azurestoragespnclientsecret`. | | No |Existing Kubernetes secret name |

+> Ensure you create a new resource group for your AKS cluster

+Create a file called **byok-azure-disk.yaml** that contains the following information. Replace *myAzureSubscriptionId*, *myResourceGroup*, and *myDiskEncrptionSetName* with your values, and apply the yaml. Make sure to use the resource group where your DiskEncryptionSet is deployed.

+```yaml

+* The *--service-cidr* is optional. This address is used to assign internal services in the AKS cluster an IP address. This IP address range should be an address space that isn't in use elsewhere in your network environment, including any on-premises network ranges if you connect, or plan to connect, your Azure virtual networks using Express Route or a Site-to-Site VPN connection. The default value is 10.0.0.0/16.

+* The *--dns-service-ip* is optional. The address should be the *.10* address of your service IP address range. The default value is 10.0.0.10.

+* The *--pod-cidr* is optional. This address should be a large address space that isn't in use elsewhere in your network environment. This range includes any on-premises network ranges if you connect, or plan to connect, your Azure virtual networks using Express Route or a Site-to-Site VPN connection. The default value is 10.244.0.0/16.

+* The *--docker-bridge-address* is optional. The address lets the AKS nodes communicate with the underlying management platform. This IP address must not be within the virtual network IP address range of your cluster, and shouldn't overlap with other address ranges in use on your network. The default value is 172.17.0.1/16.

+## Create an AKS cluster with a customized node configuration

+### Prerequisites for Windows kubelet custom configuration (Preview)

+* An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).

+First, install the aks-preview extension by running the following command:

+```azurecli

+az extension add --name aks-preview

+```

+Run the following command to update to the latest version of the extension released:

+```azurecli

+az extension update --name aks-preview

+```

+Then register the `WindowsCustomKubeletConfigPreview` feature flag by using the [`az feature register`][az-feature-register] command, as shown in the following example:

+```azurecli-interactive

+az feature register --namespace "Microsoft.ContainerService" --name "WindowsCustomKubeletConfigPreview"

+```

+It takes a few minutes for the status to show *Registered*. Verify the registration status by using the [`az feature show`][az-feature-show] command:

+```azurecli-interactive

+az feature show --namespace "Microsoft.ContainerService" --name "WindowsCustomKubeletConfigPreview"

+```

+When the status reflects *Registered*, refresh the registration of the *Microsoft.ContainerService* resource provider by using the [`az provider register`][az-provider-register] command:

+```azurecli-interactive

+az provider register --namespace Microsoft.ContainerService

+```

+### Create config files for kubelet configuration, OS configuration, or both

+Create a `linuxkubeletconfig.json` file with the following contents (for Linux node pools):

+> [!NOTE]

+> Windows kubelet custom configuration only supports the parameters `imageGcHighThreshold`, `imageGcLowThreshold`, `containerLogMaxSizeMB`, and `containerLogMaxFiles`. The json file contents above should be modified to remove any unsupported parameters.

+Create a `windowskubeletconfig.json` file with the following contents (for Windows node pools):

+```json

+{

+ "imageGcHighThreshold": 90,

+ "imageGcLowThreshold": 70,

+ "containerLogMaxSizeMB": 20,

+ "containerLogMaxFiles": 6

+}

+```

+Create a `linuxosconfig.json` file with the following contents (for Linux node pools only):

+### Create a new cluster using custom configuration files

+When creating a new cluster, you can use the customized configuration files created in the previous step to specify the kubelet configuration, OS configuration, or both. Since the first node pool created with az aks create is a linux node pool in all cases, you should use the `linuxkubeletconfig.json` and `linuxosconfig.json` files.

+> If you specify a configuration when creating a cluster, only the nodes in the initial node pool will have that configuration applied. Any settings not configured in the JSON file will retain the default value. CustomLinuxOsConfig isn't supported for OS type: Windows.

+az aks create --name myAKSCluster --resource-group myResourceGroup --kubelet-config ./linuxkubeletconfig.json --linux-os-config ./linuxosconfig.json

+### Add a node pool using custom configuration files

+When adding a node pool to a cluster, you can use the customized configuration file created in the previous step to specify the kubelet configuration. CustomKubeletConfig is supported for Linux and Windows node pools.

+> When you add a Linux node pool to an existing cluster, you can specify the kubelet configuration, OS configuration, or both. When you add a Windows node pool to an existing cluster, you can only specify the kubelet configuration. If you specify a configuration when adding a node pool, only the nodes in the new node pool will have that configuration applied. Any settings not configured in the JSON file will retain the default value.

+For Linux node pools

+```azurecli

+az aks nodepool add --name mynodepool1 --cluster-name myAKSCluster --resource-group myResourceGroup --kubelet-config ./linuxkubeletconfig.json

+```

+For Windows node pools (Preview)

+az aks nodepool add --name mynodepool1 --cluster-name myAKSCluster --resource-group myResourceGroup --os-type Windows --kubelet-config ./windowskubeletconfig.json

+### Other configurations

+These settings can be used to modify other operating system settings.

+#### Message of the Day

+Pass the ```--message-of-the-day``` flag with the location of the file to replace the Message of the Day on Linux nodes at cluster creation or node pool creation.

+##### Cluster creation

+##### Nodepool creation

+### Confirm settings have been applied

+## Custom node configuration supported parameters

+## Kubelet custom configuration

+Kubelet custom configuration is supported for Linux and Windows node pools. Supported parameters differ and are documented below.

+### Linux Kubelet custom configuration

+The supported Kubelet parameters and accepted values for Linux node pools are listed below.

+| Parameter | Allowed values/interval | Default | Description |

+| | -- | - | -- |

+| `cpuManagerPolicy` | none, static | none | The static policy allows containers in [Guaranteed pods](https://kubernetes.io/docs/tasks/configure-pod-container/quality-service-pod/) with integer CPU requests access to exclusive CPUs on the node. |

+| `cpuCfsQuota` | true, false | true | Enable/Disable CPU CFS quota enforcement for containers that specify CPU limits. |

+| `cpuCfsQuotaPeriod` | Interval in milliseconds (ms) | `100ms` | Sets CPU CFS quota period value. |

+| `imageGcHighThreshold` | 0-100 | 85 | The percent of disk usage after which image garbage collection is always run. Minimum disk usage that **will** trigger garbage collection. To disable image garbage collection, set to 100. |

+| `imageGcLowThreshold` | 0-100, no higher than `imageGcHighThreshold` | 80 | The percent of disk usage before which image garbage collection is never run. Minimum disk usage that **can** trigger garbage collection. |

+| `topologyManagerPolicy` | none, best-effort, restricted, single-numa-node | none | Optimize NUMA node alignment, see more [here](https://kubernetes.io/docs/tasks/administer-cluster/topology-manager/). |

+| `allowedUnsafeSysctls` | `kernel.shm*`, `kernel.msg*`, `kernel.sem`, `fs.mqueue.*`, `net.*` | None | Allowed list of unsafe sysctls or unsafe sysctl patterns. |

+| `containerLogMaxSizeMB` | Size in megabytes (MB) | 10 | The maximum size (for example, 10 MB) of a container log file before it's rotated. |

+| `containerLogMaxFiles` | ≥ 2 | 5 | The maximum number of container log files that can be present for a container. |

+| `podMaxPids` | -1 to kernel PID limit | -1 (∞)| The maximum amount of process IDs that can be running in a Pod |

+### Windows Kubelet custom configuration (Preview)

+The supported Kubelet parameters and accepted values for Windows node pools are listed below.

+| Parameter | Allowed values/interval | Default | Description |

+| | -- | - | -- |

+| `imageGcHighThreshold` | 0-100 | 85 | The percent of disk usage after which image garbage collection is always run. Minimum disk usage that **will** trigger garbage collection. To disable image garbage collection, set to 100. |

+| `imageGcLowThreshold` | 0-100, no higher than `imageGcHighThreshold` | 80 | The percent of disk usage before which image garbage collection is never run. Minimum disk usage that **can** trigger garbage collection. |

+| `containerLogMaxSizeMB` | Size in megabytes (MB) | 10 | The maximum size (for example, 10 MB) of a container log file before it's rotated. |

+| `containerLogMaxFiles` | ≥ 2 | 5 | The maximum number of container log files that can be present for a container. |

+## Linux OS custom configuration

+The supported OS settings and accepted values are listed below.

+### File handle limits

+When you're serving a lot of traffic, it's common that the traffic you're serving is coming from a large number of local files. You can tweak the below kernel settings and built-in limits to allow you to handle more, at the cost of some system memory.

+| Setting | Allowed values/interval | Default | Description |

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

+| `fs.file-max` | 8192 - 12000500 | 709620 | Maximum number of file-handles that the Linux kernel will allocate, by increasing this value you can increase the maximum number of open files permitted. |

+| `fs.inotify.max_user_watches` | 781250 - 2097152 | 1048576 | Maximum number of file watches allowed by the system. Each *watch* is roughly 90 bytes on a 32-bit kernel, and roughly 160 bytes on a 64-bit kernel. |

+| `fs.aio-max-nr` | 65536 - 6553500 | 65536 | The aio-nr shows the current system-wide number of asynchronous io requests. aio-max-nr allows you to change the maximum value aio-nr can grow to. |

+| `fs.nr_open` | 8192 - 20000500 | 1048576 | The maximum number of file-handles a process can allocate. |

+### Socket and network tuning

+For agent nodes, which are expected to handle very large numbers of concurrent sessions, you can use the subset of TCP and network options below that you can tweak per node pool.

+| Setting | Allowed values/interval | Default | Description |

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

+| `net.core.somaxconn` | 4096 - 3240000 | 16384 | Maximum number of connection requests that can be queued for any given listening socket. An upper limit for the value of the backlog parameter passed to the [listen(2)](http://man7.org/linux/man-pages/man2/listen.2.html) function. If the backlog argument is greater than the `somaxconn`, then it's silently truncated to this limit.

+| `net.core.netdev_max_backlog` | 1000 - 3240000 | 1000 | Maximum number of packets, queued on the INPUT side, when the interface receives packets faster than kernel can process them. |

+| `net.core.rmem_max` | 212992 - 134217728 | 212992 | The maximum receive socket buffer size in bytes. |

+| `net.core.wmem_max` | 212992 - 134217728 | 212992 | The maximum send socket buffer size in bytes. |

+| `net.core.optmem_max` | 20480 - 4194304 | 20480 | Maximum ancillary buffer size (option memory buffer) allowed per socket. Socket option memory is used in a few cases to store extra structures relating to usage of the socket. |

+| `net.ipv4.tcp_max_syn_backlog` | 128 - 3240000 | 16384 | The maximum number of queued connection requests that have still not received an acknowledgment from the connecting client. If this number is exceeded, the kernel will begin dropping requests. |

+| `net.ipv4.tcp_max_tw_buckets` | 8000 - 1440000 | 32768 | Maximal number of `timewait` sockets held by system simultaneously. If this number is exceeded, time-wait socket is immediately destroyed and warning is printed. |

+| `net.ipv4.tcp_fin_timeout` | 5 - 120 | 60 | The length of time an orphaned (no longer referenced by any application) connection will remain in the FIN_WAIT_2 state before it's aborted at the local end. |

+| `net.ipv4.tcp_keepalive_time` | 30 - 432000 | 7200 | How often TCP sends out `keepalive` messages when `keepalive` is enabled. |

+| `net.ipv4.tcp_keepalive_probes` | 1 - 15 | 9 | How many `keepalive` probes TCP sends out, until it decides that the connection is broken. |

+| `net.ipv4.tcp_keepalive_intvl` | 1 - 75 | 75 | How frequently the probes are sent out. Multiplied by `tcp_keepalive_probes` it makes up the time to kill a connection that isn't responding, after probes started. |

+| `net.ipv4.tcp_tw_reuse` | 0 or 1 | 0 | Allow to reuse `TIME-WAIT` sockets for new connections when it's safe from protocol viewpoint. |

+| `net.ipv4.ip_local_port_range` | First: 1024 - 60999 and Last: 32768 - 65000] | First: 32768 and Last: 60999 | The local port range that is used by TCP and UDP traffic to choose the local port. Comprised of two numbers: The first number is the first local port allowed for TCP and UDP traffic on the agent node, the second is the last local port number. |

+| `net.ipv4.neigh.default.gc_thresh1`| 128 - 80000 | 4096 | Minimum number of entries that may be in the ARP cache. Garbage collection won't be triggered if the number of entries is below this setting. |

+| `net.ipv4.neigh.default.gc_thresh2`| 512 - 90000 | 8192 | Soft maximum number of entries that may be in the ARP cache. This setting is arguably the most important, as ARP garbage collection will be triggered about 5 seconds after reaching this soft maximum. |

+| `net.ipv4.neigh.default.gc_thresh3`| 1024 - 100000 | 16384 | Hard maximum number of entries in the ARP cache. |

+| `net.netfilter.nf_conntrack_max` | 131072 - 1048576 | 131072 | `nf_conntrack` is a module that tracks connection entries for NAT within Linux. The `nf_conntrack` module uses a hash table to record the *established connection* record of the TCP protocol. `nf_conntrack_max` is the maximum number of nodes in the hash table, that is, the maximum number of connections supported by the `nf_conntrack` module or the size of connection tracking table. |

+| `net.netfilter.nf_conntrack_buckets` | 65536 - 147456 | 65536 | `nf_conntrack` is a module that tracks connection entries for NAT within Linux. The `nf_conntrack` module uses a hash table to record the *established connection* record of the TCP protocol. `nf_conntrack_buckets` is the size of hash table. |

+### Worker limits

+Like file descriptor limits, the number of workers or threads that a process can create are limited by both a kernel setting and user limits. The user limit on AKS is unlimited.

+| Setting | Allowed values/interval | Default | Description |

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

+| `kernel.threads-max` | 20 - 513785 | 55601 | Processes can spin up worker threads. The maximum number of all threads that can be created is set with the kernel setting `kernel.threads-max`. |

+### Virtual memory

+The settings below can be used to tune the operation of the virtual memory (VM) subsystem of the Linux kernel and the `writeout` of dirty data to disk.

+| Setting | Allowed values/interval | Default | Description |

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

+| `vm.max_map_count` | 65530 - 262144 | 65530 | This file contains the maximum number of memory map areas a process may have. Memory map areas are used as a side-effect of calling `malloc`, directly by `mmap`, `mprotect`, and `madvise`, and also when loading shared libraries. |

+| `vm.vfs_cache_pressure` | 1 - 500 | 100 | This percentage value controls the tendency of the kernel to reclaim the memory, which is used for caching of directory and inode objects. |

+| `vm.swappiness` | 0 - 100 | 60 | This control is used to define how aggressive the kernel will swap memory pages. Higher values will increase aggressiveness, lower values decrease the amount of swap. A value of 0 instructs the kernel not to initiate swap until the amount of free and file-backed pages is less than the high water mark in a zone. |

+| `swapFileSizeMB` | 1 MB - Size of the [temporary disk](../virtual-machines/managed-disks-overview.md#temporary-disk) (/dev/sdb) | None | SwapFileSizeMB specifies size in MB of a swap file will be created on the agent nodes from this node pool. |

+| `transparentHugePageEnabled` | `always`, `madvise`, `never` | `always` | [Transparent Hugepages](https://www.kernel.org/doc/html/latest/admin-guide/mm/transhuge.html#admin-guide-transhuge) is a Linux kernel feature intended to improve performance by making more efficient use of your processorΓÇÖs memory-mapping hardware. When enabled the kernel attempts to allocate `hugepages` whenever possible and any Linux process will receive 2-MB pages if the `mmap` region is 2 MB naturally aligned. In certain cases when `hugepages` are enabled system wide, applications may end up allocating more memory resources. An application may `mmap` a large region but only touch 1 byte of it, in that case a 2-MB page might be allocated instead of a 4k page for no good reason. This scenario is why it's possible to disable `hugepages` system-wide or to only have them inside `MADV_HUGEPAGE madvise` regions. |

+| `transparentHugePageDefrag` | `always`, `defer`, `defer+madvise`, `madvise`, `never` | `madvise` | This value controls whether the kernel should make aggressive use of memory compaction to make more `hugepages` available. |

+> [!IMPORTANT]

+> For ease of search and readability the OS settings are displayed in this document by their name but should be added to the configuration json file or AKS API using [camelCase capitalization convention](/dotnet/standard/design-guidelines/capitalization-conventions).

+[az-feature-show]: /cli/azure/feature#az-feature-show

+SOURCE_REGISTRY=registry.k8s.io

+$SourceRegistry = "registry.k8s.io"

+ --version=$CERT_MANAGER_TAG \

+The Kubernetes resource view from the Azure portal replaces the deprecated AKS dashboard add-on.

+To view Kubernetes resources in the Azure portal, you need an AKS cluster. Any cluster is supported, but if you're using Azure Active Directory (Azure AD) integration, your cluster must use [AKS-managed Azure AD integration][aks-managed-aad]. If your cluster uses legacy Azure AD, you can upgrade your cluster in the portal or with the [Azure CLI][cli-aad-upgrade]. You can also [use the Azure portal][aks-quickstart-portal] to create a new AKS cluster.

+1. From the **Services and ingresses** resource view, select **Create** > **Starter application**.

+2. Under **Create a basic web application**, select **Create**.

+3. On the **Application details** page, select **Next**.

+4. On the **Review YAML** page, select **Deploy**.

+Once the application is deployed, the resource view shows the two Kubernetes

+- **azure-vote-back**: The internal service.

+- **azure-vote-front**: The external service, which includes a linked external IP address so you can view the application in your browser.

+AKS clusters with [Container insights][enable-monitor] enabled can quickly view deployment and other insights. From the Kubernetes resources view, you can see the live status of individual deployments, including CPU and memory usage. You can also go to Azure Monitor for more in-depth information about specific nodes and containers.

+Here's an example of deployment insights from a sample AKS cluster:

+To edit a YAML file for one of your resources, see the following steps:

+1. Navigate to your resource in the Azure portal.

+2. Select **YAML** and make your desired edits.

+3. Select **Review + save** > **Confirm manifest changes** > **Save**.

+> We don't recommend performing direct production changes via UI or CLI. Instead, you should leverage [continuous integration (CI) and continuous deployment (CD) best practices](kubernetes-action.md). The Azure portal Kubernetes management capabilities, such as the YAML editor, are built for learning and flighting new deployments in a development and testing setting.

+> The Kubernetes resource view in the Azure portal is only supported by [managed-AAD enabled clusters](managed-aad.md) or non-AAD enabled clusters. If you're using a managed-AAD enabled cluster, your AAD user or identity needs to have the respective roles/role bindings to access the Kubernetes API and the permission to pull the [user `kubeconfig`](control-kubeconfig-access.md).

+> You can add the AKS feature for [**API server authorized IP ranges**](api-server-authorized-ip-ranges.md) to limit API server access to only the firewall's public endpoint. Another option is to update the `-ApiServerAccessAuthorizedIpRange` to include access for a local client computer or IP address range (from which portal is being browsed). To allow this access, you need the computer's public IPv4 address. You can find this address with the following command or you can search "what is my IP address" in your browser.

+> You can add the AKS feature for [**API server authorized IP ranges**](api-server-authorized-ip-ranges.md) to limit API server access to only the firewall's public endpoint. Another option is to update the `-ApiServerAccessAuthorizedIpRange` to include access for a local client computer or IP address range (from which portal is being browsed). To allow this access, you need the computer's public IPv4 address. You can find this address with the following command or you can search "what is my IP address" in your browser.

+This article showed you how to access Kubernetes resources from the Azure portal. For more information on cluster resources, see [Deployments and YAML manifests][deployments].

+

+

+1. In the Cloud Shell, open an editor and create a file named `azure-vote.yaml`.

+2. Paste in the following YAML definition:

+

+

+|username|Specifies the username of the Basic credential. Policy expressions are allowed. |Yes|N/A|

+|password|Specifies the password of the Basic credential. Policy expressions are allowed. |Yes|N/A|

+|thumbprint|The thumbprint for the client certificate. Policy expressions are allowed. |Either `thumbprint` or `certificate-id` can be present.|N/A|

+|certificate-id|The certificate resource name. Policy expressions are allowed.|Either `thumbprint` or `certificate-id` can be present.|N/A|

+|body|Client certificate as a byte array. Use if the certificate isn't retrieved from the built-in certificate store. Policy expressions are allowed.|No|N/A|

+|password|Password for the client certificate. Policy expressions are allowed.|Use if certificate specified in `body` is password protected.|N/A|

+|client-id|String. The client ID of the user-assigned identity in Azure Active Directory. Policy expressions aren't allowed. |No|system-assigned identity|

+|output-token-variable-name|String. Name of the context variable that will receive token value as an object of type `string`. Policy expressions aren't allowed. |No|N/A|

+|ignore-error|Boolean. If set to `true`, the policy pipeline continues to execute even if an access token isn't obtained.|No|`false`|

+| allow-private-response-caching | When set to `true`, allows caching of requests that contain an Authorization header. Policy expressions are allowed. | No | `false` |

+| caching-type | Choose between the following values of the attribute:<br />- `internal` to use the [built-in API Management cache](api-management-howto-cache.md),<br />- `external` to use the external cache as described in [Use an external Azure Cache for Redis in Azure API Management](api-management-howto-cache-external.md),<br />- `prefer-external` to use external cache if configured or internal cache otherwise.<br/><br/>Policy expressions aren't allowed. | No | `prefer-external` |

+| downstream-caching-type | This attribute must be set to one of the following values.<br /><br /> - none - downstream caching is not allowed.<br />- private - downstream private caching is allowed.<br />- public - private and shared downstream caching is allowed.<br/><br/>Policy expressions are allowed. | No | none |

+| must-revalidate | When downstream caching is enabled this attribute turns on or off the `must-revalidate` cache control directive in gateway responses. Policy expressions are allowed. | No | `true` |

+| vary-by-developer | Set to `true` to cache responses per developer account that owns [subscription key](./api-management-subscriptions.md) included in the request. Policy expressions are allowed. | Yes | `false` |

+| vary-by-developer-groups | Set to `true` to cache responses per [user group](./api-management-howto-create-groups.md). Policy expressions are allowed. | Yes | `false` |

+| caching-type | Choose between the following values of the attribute:<br />- `internal` to use the [built-in API Management cache](api-management-howto-cache.md),<br />- `external` to use the external cache as described in [Use an external Azure Cache for Redis in Azure API Management](api-management-howto-cache-external.md),<br />- `prefer-external` to use external cache if configured or internal cache otherwise.<br/><br/>Policy expressions aren't allowed. | No | `prefer-external` |

+| default-value | A value that will be assigned to the variable if the cache key lookup resulted in a miss. If this attribute is not specified, `null` is assigned. Policy expressions are allowed. | No | `null` |

+| key | Cache key value to use in the lookup. Policy expressions are allowed. | Yes | N/A |

+| variable-name | Name of the [context variable](api-management-policy-expressions.md#ContextVariables) the looked up value will be assigned to, if lookup is successful. If lookup results in a miss, the variable will not be set. Policy expressions aren't allowed. | Yes | N/A |

+| caching-type | Choose between the following values of the attribute:<br />- `internal` to use the [built-in API Management cache](api-management-howto-cache.md),<br />- `external` to use the external cache as described in [Use an external Azure Cache for Redis in Azure API Management](api-management-howto-cache-external.md),<br />- `prefer-external` to use external cache if configured or internal cache otherwise. <br/><br/>Policy expressions aren't allowed. | No | `prefer-external` |

+| key | The key of the previously cached value to be removed from the cache. Policy expressions are allowed. | Yes | N/A |

+| duration | Time-to-live of the cached entries, specified in seconds. Policy expressions are allowed. | Yes | N/A |

+| cache-response | Set to `true` to cache the current HTTP response. If the attribute is omitted or set to `false`, only HTTP responses with the status code `200 OK` are cached. Policy expressions are allowed. | No | `false` |

+| caching-type | Choose between the following values of the attribute:<br />- `internal` to use the [built-in API Management cache](api-management-howto-cache.md),<br />- `external` to use the external cache as described in [Use an external Azure Cache for Redis in Azure API Management](api-management-howto-cache-external.md),<br />- `prefer-external` to use external cache if configured or internal cache otherwise.<br/><br/>Policy expressions aren't allowed.| No | `prefer-external` |

+| duration | Value will be cached for the provided duration value, specified in seconds. Policy expressions are allowed. | Yes | N/A |

+| key | Cache key the value will be stored under. Policy expressions are allowed. | Yes | N/A |

+| value | The value to be cached. Policy expressions are allowed. | Yes | N/A |

+| name | The name of the HTTP header to check. Policy expressions are allowed. | Yes | N/A |

+| failed-check-httpcode | HTTP status code to return if the header doesn't exist or has an invalid value. Policy expressions are allowed. | Yes | N/A |

+| failed-check-error-message | Error message to return in the HTTP response body if the header doesn't exist or has an invalid value. This message must have any special characters properly escaped. Policy expressions are allowed. | Yes | N/A |

+| ignore-case | Boolean. If set to `true`, case is ignored when the header value is compared against the set of acceptable values. Policy expressions are allowed. | Yes | N/A |

+- **[Policy sections:](./api-management-howto-policies.md#sections)** inbound

+- **[Policy scopes:](./api-management-howto-policies.md#scopes)** global, product, API, operation

+|allow-credentials|The `Access-Control-Allow-Credentials` header in the preflight response will be set to the value of this attribute and affect the client's ability to submit credentials in cross-domain requests. Policy expressions are allowed.|No|`false`|

+|terminate-unmatched-request|Controls the processing of cross-origin requests that don't match the policy settings. Policy expressions are allowed.<br/><br/>When `OPTIONS` request is processed as a preflight request and `Origin` header doesn't match policy settings:<br/> - If the attribute is set to `true`, immediately terminate the request with an empty `200 OK` response<br/>- If the attribute is set to `false`, check inbound for other in-scope `cors` policies that are direct children of the inbound element and apply them. If no `cors` policies are found, terminate the request with an empty `200 OK` response. <br/><br/>When `GET` or `HEAD` request includes the `Origin` header (and therefore is processed as a simple cross-origin request), and doesn't match policy settings:<br/>- If the attribute is set to `true`, immediately terminate the request with an empty `200 OK` response.<br/> - If the attribute is set to `false`, allow the request to proceed normally and don't add CORS headers to the response.|No|`true`|

+### allowed-origins elements

+|Name|Description|Required|Default|

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

+|origin|The value can be either `*` to allow all origins, or a URI that specifies a single origin. The URI must include a scheme, host, and port.|Yes|If the port is omitted in a URI, port 80 is used for HTTP and port 443 is used for HTTPS.|

+|preflight-result-max-age|The `Access-Control-Max-Age` header in the preflight response will be set to the value of this attribute and affect the user agent's ability to cache the preflight response. Policy expressions are allowed.|No|0|

+### allowed-methods elements

+|Name|Description|Required|Default|

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

+|method|Specifies an HTTP verb. Policy expressions are allowed.|At least one `method` element is required if the `allowed-methods` section is present.|N/A|

+### allowed-headers elements

+|Name|Description|Required|Default|

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

+|header|Specifies a header name.|At least one `header` element is required in `allowed-headers` if that section is present.|N/A|

+### expose-headers elements

+|Name|Description|Required|Default|

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

+|header|Specifies a header name.|At least one `header` element is required in `expose-headers` if that section is present.|N/A|

+| name | A string. Name of custom metric. Policy expressions aren't allowed. | Yes | N/A |

+| namespace | A string. Namespace of custom metric. Policy expressions aren't allowed. | No | API Management |

+| value | Value of custom metric expressed as an integer. Policy expressions are allowed. | No | 1 |

+ Title: Enable CORS policies to test Azure API Management custom connector

+description: How to enable CORS policies in Azure API Management and Power Platform to test a custom connector from Power Platform applications.

+# Enable CORS policies to test custom connector from Power Platform

+Cross-origin resource sharing (CORS) is an HTTP-header based mechanism that allows a server to indicate any origins (domain, scheme, or port) other than its own from which a browser should permit loading resources. Customers can add a [CORS policy](cors-policy.md) to their web APIs in Azure API Management, which adds cross-origin resource sharing support to an operation or an API to allow cross-domain calls from browser-based clients.

+If you've exported an API from API Management as a [custom connector](export-api-power-platform.md) in the Power Platform and want to use the Power Apps or Power Automate test console to call the API, you need to configure your API to explicitly enable cross-origin requests from Power Platform applications. This article shows you how to configure the following two necessary policy settings:

+* Add a CORS policy to your API

+* Add a policy to your custom connector that sets an Origin header on HTTP requests

+## Prerequisites

+## Add CORS policy to API in API Management

+Follow these steps to configure the CORS policy in API Management.

+1. Sign into [Azure portal](https://portal.azure.com) and go to your API Management instance.

+1. In the left menu, select **APIs** and select the API that you exported as a custom connector. If you want to, select only an API operation to apply the policy to.

+1. In the **Policies** section, in the **Inbound processing** section, select **+ Add policy**.

+ 1. Select **Allow cross-origin resource sharing (CORS)**.

+ 1. Add the following **Allowed origin**: `https://make.powerapps.com`.

+ 1. Select **Save**.

+* For more information about configuring a policy, see [Set or edit policies](set-edit-policies.md).

+* For details about the CORS policy, see the [cors](cors-policy.md) policy reference.

+> [!NOTE]

+> If you already have an existing CORS policy at the service (all APIs) level to enable the test console of the developer portal, you can add the `https://make.powerapps.com` origin to that policy instead of configuring a separate policy for the API or operation.

+> [!NOTE]

+> Depending on how the custom connector gets used in Power Platform applications, you might need to configure additional origins in the CORS policy. If you experience CORS problems when running Power Platform applications, use developer tools in your browser, tracing in API Management, or Application Insights to investigate the issues.

+## Add policy to custom connector to set Origin header

+Add the following policy to your custom connector in your Power Platform environment. The policy sets an Origin header to match the CORS origin you allowed in API Management.

+For details about editing settings of a custom connector, see [Create a custom connector from scratch](/connectors/custom-connectors/define-blank).

+1. Sign in to Power Apps or Power Automate.

+1. On the left pane, select **Data** > **Custom Connectors**.

+1. Select your connector from the list of custom connectors.

+1. Select the pencil (Edit) icon to edit the custom connector.

+1. Select **3. Definition**.

+1. In **Policies**, select **+ New policy**. Select or enter the following policy details.

+

+ |Setting |Value |

+ |||

+ |Name | A name of your choice, such as **set-origin-header** |

+ |Template | **Set HTTP header** |

+ |Header name | **Origin** |

+ |Header value | `https://make.powerapps.com` (same URL that you configured in API Management) |

+ |Action if header exists | **override** |

+ |Run policy on | **Request** |

+ :::image type="content" source="media/enable-cors-power-platform/cors-policy-power-platform.png" alt-text="Screenshot of creating policy in Power Platform custom connector to set an Origin header in HTTP requests.":::

+1. Select **Update connector**.

+1. After setting the policy, go to the **5. Test** page to test the custom connector.

+## Next steps

+* [Learn more about the Power Platform](https://powerplatform.microsoft.com/)

+* [Learn more about creating and using custom connectors](/connectors/custom-connectors/)

+Once the connector is created, navigate to your [Power Apps](https://make.powerapps.com) or [Power Automate](https://make.powerautomate.com) environment. You'll see the API listed under **Data > Custom Connectors**.

+> [!IMPORTANT]

+> To call the API from the Power Apps test console, you need to configure a CORS policy in your API Management instance and create a policy in the custom connector to set an Origin header in HTTP requests. For more information, see [Enable CORS policies to test custom connector from Power Platform](enable-cors-power-platform.md).

+|from|The string to search for. Policy expressions are allowed. |Yes|N/A|

+|to|The replacement string. Specify a zero length replacement string to remove the search string. Policy expressions are allowed. |Yes|N/A|

+| timeout | The amount of time in seconds to wait for the HTTP response headers to be returned by the backend service before a timeout error is raised. Minimum value is 0 seconds. Values greater than 240 seconds may not be honored, because the underlying network infrastructure can drop idle connections after this time. Policy expressions are allowed. | No | 300 |

+| follow-redirects | Specifies whether redirects from the backend service are followed by the gateway or returned to the caller. Policy expressions are allowed. | No | `false` |

+| buffer-response | Affects processing of chunked responses. When set to `false`, each chunk received from the backend is immediately returned to the caller. When set to `true`, chunks are buffered (8 KB, unless end of stream is detected) and only then returned to the caller.<br/><br/>Set to `false` with backends such as those implementing [server-sent events (SSE)](how-to-server-sent-events.md) that require content to be returned or streamed immediately to the caller. Policy expressions aren't allowed. | No | `true` |

+| fail-on-error-status-code | When set to `true`, triggers [on-error](api-management-error-handling-policies.md) section for response codes in the range from 400 to 599 inclusive. Policy expressions aren't allowed. | No | `false` |

+| fragment-id | A string. Specifies the identifier (name) of a policy fragment created in the API Management instance. Policy expressions aren't allowed. | Yes | N/A |

+| name | Target binding name. Must match the name of the bindings [defined](https://github.com/dapr/docs/blob/master/daprdocs/content/en/reference/api/bindings_api.md#bindings-structure) in Dapr. Policy expressions are allowed. | Yes | N/A |

+| operation | Target operation name (binding specific). Maps to the [operation](https://github.com/dapr/docs/blob/master/daprdocs/content/en/reference/api/bindings_api.md#invoking-output-bindings) property in Dapr. Policy expressions aren't allowed. | No | None |

+| ignore-error | If set to `true` instructs the policy not to trigger ["on-error"](api-management-error-handling-policies.md) section upon receiving error from Dapr runtime. Policy expressions aren't allowed. | No | `false` |

+| response-variable-name | Name of the [Variables](api-management-policy-expressions.md#ContextVariables) collection entry to use for storing response from Dapr runtime. Policy expressions aren't allowed. | No | None |

+| timeout | Time (in seconds) to wait for Dapr runtime to respond. Can range from 1 to 240 seconds. Policy expressions are allowed.| No | 5 |

+| template | Templating engine to use for transforming the message content. "Liquid" is the only supported value. | No | None |

+## Elements

+| Element | Description | Required |

+||--|-|

+| metadata | Binding specific metadata in the form of key/value pairs. Maps to the [metadata](https://github.com/dapr/docs/blob/master/daprdocs/content/en/reference/api/bindings_api.md#invoking-output-bindings) property in Dapr. | No |

+| data | Content of the message. Maps to the [data](https://github.com/dapr/docs/blob/master/daprdocs/content/en/reference/api/bindings_api.md#invoking-output-bindings) property in Dapr. Policy expressions are allowed. | No |

+| action | Specifies whether calls should be allowed (`allow`) or not (`forbid`) for the specified IP addresses and ranges. Policy expressions are allowed. | Yes | N/A |

+| address | Add one or more of these elements to specify a single IP address on which to filter. Policy expressions are allowed. | At least one `address` or `address-range` element is required. |

+|apply|The attribute must be set to one of the following values.<br /><br /> - `always` - always apply conversion.<br />- `content-type-json` - convert only if response Content-Type header indicates presence of JSON.<br/><br/>Policy expressions are allowed.|Yes|N/A|

+|consider-accept-header|The attribute must be set to one of the following values.<br /><br /> - `true` - apply conversion if XML is requested in request Accept header.<br />- `false` - always apply conversion.<br/><br/>Policy expressions are allowed.|No|`true`|

+|parse-date|When set to `false` date values are simply copied during transformation. Policy expressions aren't allowed.|No|`true`|

+|namespace-separator|The character to use as a namespace separator. Policy expressions are allowed.|No|Underscore|

+|namespace-prefix|The string that identifies property as namespace attribute, usually "xmlns". Properties with names beginning with specified prefix will be added to current element as namespace declarations. Policy expressions are allowed.|No|N/A|

+|attribute-block-name|When set, properties inside the named object will be added to the element as attributes. Policy expressions are allowed.|No|Not set|

+|callback-parameter-name|The cross-domain JavaScript function call prefixed with the fully qualified domain name where the function resides. Policy expressions are allowed.|Yes|N/A|

+| key | A string. Specifies the concurrency scope. Can be shared by multiple policies. Policy expressions are allowed. | Yes | N/A |

+| max-count | An integer. Specifies a maximum number of requests that are allowed to enter the policy. Policy expressions aren't allowed. | Yes | N/A |

+| logger-id | The ID of the Logger registered with your API Management service. Policy expressions aren't allowed. | Yes | N/A |

+| partition-id | Specifies the index of the partition where messages are sent. Policy expressions aren't allowed. | Optional. Do not use if `partition-key` is used. | N/A |

+| partition-key | Specifies the value used for partition assignment when messages are sent. Policy expressions are allowed. | Optional. Do not use if `partition-id` is used. | N/A |

+The `mock-response` policy, as the name implies, is used to mock APIs and operations. It cancels normal pipeline execution and returns a mocked response to the caller. The policy always tries to return responses of highest fidelity. It prefers response content examples, when available. It generates sample responses from schemas, when schemas are provided and examples aren't. If neither examples or schemas are found, responses with no content are returned.

+| status-code | Specifies response status code and is used to select corresponding example or schema. Policy expressions aren't allowed. | No | 200 |

+| content-type | Specifies `Content-Type` response header value and is used to select corresponding example or schema. Policy expressions aren't allowed. | No | None |

+| url | Proxy URL in the form of `http://host:port`. Policy expressions are allowed. | Yes | N/A |

+| username | Username to be used for authentication with the proxy. Policy expressions are allowed. | No | N/A |

+| password | Password to be used for authentication with the proxy. Policy expressions are allowed. | No | N/A |

+| pubsub-name | The name of the target PubSub component. Maps to the [pubsubname](https://github.com/dapr/docs/blob/master/daprdocs/content/en/reference/api/pubsub_api.md) parameter in Dapr. If not present, the `topic` attribute value must be in the form of `pubsub-name/topic-name`. Policy expressions are allowed. | No | None |

+| topic | The name of the topic. Maps to the [topic](https://github.com/dapr/docs/blob/master/daprdocs/content/en/reference/api/pubsub_api.md) parameter in Dapr. Policy expressions are allowed. | Yes | N/A |

+| ignore-error | If set to `true`, instructs the policy not to trigger ["on-error"](api-management-error-handling-policies.md) section upon receiving error from Dapr runtime. Policy expressions aren't allowed. | No | `false` |

+| response-variable-name | Name of the [Variables](api-management-policy-expressions.md#ContextVariables) collection entry to use for storing response from Dapr runtime. Policy expressions aren't allowed. | No | None |

+| timeout | Time (in seconds) to wait for Dapr runtime to respond. Can range from 1 to 240 seconds. Policy expressions are allowed. | No | 5 |

+| bandwidth | The maximum total number of kilobytes allowed during the time interval specified in the `renewal-period`. Policy expressions aren't allowed.| Either `calls`, `bandwidth`, or both together must be specified. | N/A |

+| calls | The maximum total number of calls allowed during the time interval specified in the `renewal-period`. Policy expressions aren't allowed. | Either `calls`, `bandwidth`, or both together must be specified. | N/A |

+| counter-key | The key to use for the `quota policy`. For each key value, a single counter is used for all scopes at which the policy is configured. Policy expressions are allowed. | Yes | N/A |

+| increment-condition | The Boolean expression specifying if the request should be counted towards the quota (`true`). Policy expressions are allowed. | No | N/A |

+| renewal-period | The length in seconds of the fixed window after which the quota resets. The start of each period is calculated relative to `first-period-start`. When `renewal-period` is set to `0`, the period is set to infinite. Policy expressions aren't allowed. | Yes | N/A |

+| first-period-start | The starting date and time for quota renewal periods, in the following format: `yyyy-MM-ddTHH:mm:ssZ` as specified by the ISO 8601 standard. Policy expressions aren't allowed. | No | `0001-01-01T00:00:00Z` |

+| bandwidth | The maximum total number of kilobytes allowed during the time interval specified in the `renewal-period`. Policy expressions aren't allowed. | Either `calls`, `bandwidth`, or both together must be specified. | N/A |

+| calls | The maximum total number of calls allowed during the time interval specified in the `renewal-period`. Policy expressions aren't allowed. | Either `calls`, `bandwidth`, or both together must be specified. | N/A |

+| renewal-period | The length in seconds of the fixed window after which the quota resets. The start of each period is calculated relative to the start time of the subscription. When `renewal-period` is set to `0`, the period is set to infinite. Policy expressions aren't allowed.| Yes | N/A |

+| id | The ID of the API for which to apply the call quota limit. | Either `name` or `id` must be specified. | N/A |

+| bandwidth | The maximum total number of kilobytes allowed during the time interval specified in the `renewal-period`. Policy expressions aren't allowed. | Either `calls`, `bandwidth`, or both together must be specified. | N/A |

+| calls | The maximum total number of calls allowed during the time interval specified in the `renewal-period`. Policy expressions aren't allowed. | Either `calls`, `bandwidth`, or both together must be specified. | N/A |

+| renewal-period | The length in seconds of the fixed window after which the quota resets. The start of each period is calculated relative to the start time of the subscription. When `renewal-period` is set to `0`, the period is set to infinite. Policy expressions aren't allowed.| Yes | N/A |

+| name | The name of the operation for which to apply the call quota limit. | Either `name` or `id` must be specified. | N/A |

+| id | The ID of the operation for which to apply the call quota limit. | Either `name` or `id` must be specified. | N/A |

+| bandwidth | The maximum total number of kilobytes allowed during the time interval specified in the `renewal-period`. Policy expressions aren't allowed. | Either `calls`, `bandwidth`, or both together must be specified. | N/A |

+| calls | The maximum total number of calls allowed during the time interval specified in the `renewal-period`. Policy expressions aren't allowed. | Either `calls`, `bandwidth`, or both together must be specified. | N/A |

+| renewal-period | The length in seconds of the fixed window after which the quota resets. The start of each period is calculated relative to the start time of the subscription. When `renewal-period` is set to `0`, the period is set to infinite. Policy expressions aren't allowed.| Yes | N/A |

+| calls | The maximum total number of calls allowed during the time interval specified in the `renewal-period`. Policy expressions are allowed. | Yes | N/A |

+| counter-key | The key to use for the rate limit policy. For each key value, a single counter is used for all scopes at which the policy is configured. Policy expressions are allowed. | Yes | N/A |

+| increment-condition | The Boolean expression specifying if the request should be counted towards the rate (`true`). Policy expressions are allowed. | No | N/A |

+| increment-count | The number by which the counter is increased per request. Policy expressions are allowed. | No | 1 |

+| renewal-period | The length in seconds of the sliding window during which the number of allowed requests should not exceed the value specified in `calls`. Maximum allowed value: 300 seconds. Policy expressions are allowed. | Yes | N/A |

+| retry-after-header-name | The name of a custom response header whose value is the recommended retry interval in seconds after the specified call rate is exceeded. Policy expressions aren't allowed. | No | `Retry-After` |

+| retry-after-variable-name | The name of a policy expression variable that stores the recommended retry interval in seconds after the specified call rate is exceeded. Policy expressions aren't allowed. | No | N/A |

+| remaining-calls-header-name | The name of a response header whose value after each policy execution is the number of remaining calls allowed for the time interval specified in the `renewal-period`. Policy expressions aren't allowed. | No | N/A |

+| remaining-calls-variable-name | The name of a policy expression variable that after each policy execution stores the number of remaining calls allowed for the time interval specified in the `renewal-period`. Policy expressions aren't allowed. | No | N/A |

+| total-calls-header-name | The name of a response header whose value is the value specified in `calls`. Policy expressions aren't allowed. | No | N/A |

+| calls | The maximum total number of calls allowed during the time interval specified in `renewal-period`. Policy expressions aren't allowed.| Yes | N/A |

+| renewal-period | The length in seconds of the sliding window during which the number of allowed requests should not exceed the value specified in `calls`. Maximum allowed value: 300 seconds. Policy expressions aren't allowed. | Yes | N/A |

+| total-calls-header-name | The name of a response header whose value is the value specified in `calls`. Policy expressions aren't allowed. | No | N/A |

+| retry-after-header-name | The name of a custom response header whose value is the recommended retry interval in seconds after the specified call rate is exceeded. Policy expressions aren't allowed. | No | `Retry-After` |

+| retry-after-variable-name | The name of a variable that stores the recommended retry interval in seconds after the specified call rate is exceeded. Policy expressions aren't allowed. | No | N/A |

+| remaining-calls-header-name | The name of a response header whose value after each policy execution is the number of remaining calls allowed for the time interval specified in the `renewal-period`. Policy expressions aren't allowed.| No | N/A |

+| remaining-calls-variable-name | The name of a variable that after each policy execution stores the number of remaining calls allowed for the time interval specified in the `renewal-period`. Policy expressions aren't allowed.| No | N/A |

+| total-calls-header-name | The name of a response header whose value is the value specified in `calls`. Policy expressions aren't allowed.| No | N/A |

+| calls | The maximum total number of calls allowed during the time interval specified in `renewal-period`. Policy expressions aren't allowed.| Yes | N/A |

+| renewal-period | The length in seconds of the sliding window during which the number of allowed requests should not exceed the value specified in `calls`. Maximum allowed value: 300 seconds. Policy expressions aren't allowed. | Yes | N/A |

+| calls | The maximum total number of calls allowed during the time interval specified in `renewal-period`. Policy expressions aren't allowed.| Yes | N/A |

+| renewal-period | The length in seconds of the sliding window during which the number of allowed requests should not exceed the value specified in `calls`. Maximum allowed value: 300 seconds. Policy expressions aren't allowed. | Yes | N/A |

+| condition | Boolean. Specifies whether retries should be stopped (`false`) or continued (`true`). Policy expressions are allowed. | Yes | N/A |

+| count | A positive number specifying the maximum number of retries to attempt. Policy expressions are allowed. | Yes | N/A |

+| interval | A positive number in seconds specifying the wait interval between the retry attempts. Policy expressions are allowed. | Yes | N/A |

+| max-interval | A positive number in seconds specifying the maximum wait interval between the retry attempts. It is used to implement an exponential retry algorithm. Policy expressions are allowed. | No | N/A |

+| delta | A positive number in seconds specifying the wait interval increment. It is used to implement the linear and exponential retry algorithms. Policy expressions are allowed. | No | N/A |

+| first-fast-retry | Boolean. If set to `true`, the first retry attempt is performed immediately. Policy expressions are allowed. | No | `false` |

+| response-variable-name | The name of the context variable referenced from, for example, an upstream [send-request](send-request-policy.md) policy and containing a `Response` object. Policy expressions aren't allowed. | No | N/A |

+This policy can be used when a human and/or browser-friendly URL should be transformed into the URL format expected by the web service. This policy only needs to be applied when exposing an alternative URL format, such as clean URLs, RESTful URLs, user-friendly URLs or SEO-friendly URLs that are purely structural URLs that don't contain a query string and instead contain only the path of the resource (after the scheme and the authority). This is often done for aesthetic, usability, or search engine optimization (SEO) purposes.

+|template|The actual web service URL with any query string parameters. Policy expressions are allowed. When expressions are used, the whole value must be an expression. |Yes|N/A|

+|copy-unmatched-params|Specifies whether query parameters in the incoming request not present in the original URL template are added to the URL defined by the rewrite template. Policy expressions are allowed.|No|`true`|

+You can only add query string parameters using the policy. You can't add extra template path parameters in the rewrite URL.

+| mode | Determines whether this is a `new` request or a `copy` of the current request. In outbound mode, `mode=copy` does not initialize the request body. Policy expressions are allowed. | No | `new` |

+| timeout| The timeout interval in seconds before the call to the URL fails. Policy expressions are allowed. | No | 60 |

+| set-url | The URL of the request. Policy expressions are allowed. | No if `mode=copy`; otherwise yes. |

+| [set-method](set-method-policy.md) | Sets the method of the request. Policy expressions aren't allowed. | No if `mode=copy`; otherwise yes. |

+| [set-header](set-header-policy.md) | Sets a header in the request. Use multiple `set-header` elements for multiple request headers. | No |

+| [set-body](set-body-policy.md) | Sets the body of the request. | No |

+| mode | Determines whether this is a `new` request or a `copy` of the current request. In outbound mode, `mode=copy` does not initialize the request body. Policy expressions are allowed. | No | `new` |

+| response-variable-name | The name of context variable that will receive a response object. If the variable doesn't exist, it will be created upon successful execution of the policy and will become accessible via [`context.Variable`](api-management-policy-expressions.md#ContextVariables) collection. Policy expressions are allowed. | Yes | N/A |

+| timeout | The timeout interval in seconds before the call to the URL fails. Policy expressions are allowed. | No | 60 |

+| ignore-error | If `true` and the request results in an error, the error will be ignored, and the response variable will contain a null value. Policy expressions aren't allowed. | No | `false` |

+| set-url | The URL of the request. Policy expressions are allowed. | No if `mode=copy`; otherwise yes. |

+| [set-method](set-method-policy.md) | Sets the method of the request. Policy expressions aren't allowed. | No if `mode=copy`; otherwise yes. |

+| [set-header](set-header-policy.md) | Sets a header in the request. Use multiple `set-header` elements for multiple request headers. | No |

+| [set-body](set-body-policy.md) | Sets the body of the request. | No |

+| dapr-app-id | Name of the target microservice. Used to form the [appId](https://github.com/dapr/docs/blob/master/daprdocs/content/en/reference/api/service_invocation_api.md) parameter in Dapr. Policy expressions are allowed. | Yes | N/A |

+| dapr-method | Name of the method or a URL to invoke on the target microservice. Maps to the [method-name](https://github.com/dapr/docs/blob/master/daprdocs/content/en/reference/api/service_invocation_api.md) parameter in Dapr. Policy expressions are allowed. | Yes | N/A |

+| dapr-namespace | Name of the namespace the target microservice is residing in. Used to form the [appId](https://github.com/dapr/docs/blob/master/daprdocs/content/en/reference/api/service_invocation_api.md) parameter in Dapr. Policy expressions are allowed. | No | N/A |

+|base-url|New backend service base URL. Policy expressions are allowed.|One of `base-url` or `backend-id` must be present.|N/A|

+|backend-id|Identifier (name) of the backend to route primary or secondary replica of a partition. Policy expressions are allowed. |One of `base-url` or `backend-id` must be present.|N/A|

+|sf-resolve-condition|Only applicable when the backend is a Service Fabric service. Condition identifying if the call to Service Fabric backend has to be repeated with new resolution. Policy expressions are allowed.|No|N/A|

+|sf-service-instance-name|Only applicable when the backend is a Service Fabric service. Allows changing service instances at runtime. Policy expressions are allowed. |No|N/A|

+|sf-partition-key|Only applicable when the backend is a Service Fabric service. Specifies the partition key of a Service Fabric service. Policy expressions are allowed. |No|N/A|

+|sf-listener-name|Only applicable when the backend is a Service Fabric service and is specified using `backend-id`. Service Fabric Reliable Services allows you to create multiple listeners in a service. This attribute is used to select a specific listener when a backend Reliable Service has more than one listener. If this attribute isn't specified, API Management will attempt to use a listener without a name. A listener without a name is typical for Reliable Services that have only one listener. Policy expressions are allowed.|No|N/A|

+|template|Used to change the templating mode that the `set-body` policy runs in. Currently the only supported value is:<br /><br />- `liquid` - the `set-body` policy will use the liquid templating engine |No| N/A|

+|xsi-nil| Used to control how elements marked with `xsi:nil="true"` are represented in XML payloads. Set to one of the following values:<br /><br />- `blank` - `nil` is represented with an empty string.<br />- `null` - `nil` is represented with a null value.<br/></br>Policy expressions aren't allowed. |No | `blank` |

+ - If you're using the `set-body` policy to return a new or updated body, you don't need to set `preserveContent` to `true` because you're explicitly supplying the new body contents.

+ - Preserving the content of a response in the inbound pipeline doesn't make sense because there's no response yet.

+ - If this policy is used when there's no message body, for example in an inbound `GET`, an exception is thrown.

+We're preserving the original request body so that we can access it later in the pipeline.

+Since we're not reserving the original request body, accessing it later in the pipeline will result in an exception.

+The following example uses the `AsFormUrlEncodedContent()` expression to access the request body as URL-encoded form data (content type `application/x-www-form-urlencoded`), and then converts it to JSON. Since we're not reserving the original request body, accessing it later in the pipeline will result in an exception.

+The following example uses the `AsFormUrlEncodedContent()` expression to access the request body as URL-encoded form data (content type `application/x-www-form-urlencoded`), adds data to the payload, and returns URL-encoded form data. Since we're not reserving the original request body, accessing it later in the pipeline will result in an exception.

+|exists-action|Specifies action to take when the header is already specified. This attribute must have one of the following values.<br /><br /> - `override` - replaces the value of the existing header.<br />- `skip` - does not replace the existing header value.<br />- `append` - appends the value to the existing header value.<br />- `delete` - removes the header from the request.<br /><br /> When set to `override`, enlisting multiple entries with the same name results in the header being set according to all entries (which will be listed multiple times); only listed values will be set in the result. <br/><br/>Policy expressions are allowed.|No|`override`|

+|name|Specifies name of the header to be set. Policy expressions are allowed.|Yes|N/A|

+|value|Specifies the value of the header to be set. Policy expressions are allowed. For multiple headers with the same name, add additional `value` elements.|No|

+The value of the element specifies the HTTP method, such as `POST`, `GET`, and so on. Policy expressions are allowed.

+|exists-action|Specifies what action to take when the query parameter is already specified. This attribute must have one of the following values.<br /><br /> - `override` - replaces the value of the existing parameter.<br />- `skip` - does not replace the existing query parameter value.<br />- `append` - appends the value to the existing query parameter value.<br />- `delete` - removes the query parameter from the request.<br /><br /> When set to `override` enlisting multiple entries with the same name results in the query parameter being set according to all entries (which will be listed multiple times); only listed values will be set in the result.<br/><br/>Policy expressions are allowed. |No|`override`|

+|name|Specifies name of the query parameter to be set. Policy expressions are allowed. |Yes|N/A|

+|value|Specifies the value of the query parameter to be set. For multiple query parameters with the same name, add additional `value` elements. Policy expressions are allowed. |Yes|

+| code | Integer. The HTTP status code to return. Policy expressions are allowed. | Yes | N/A |

+| reason | String. A description of the reason for returning the status code. Policy expressions are allowed. | Yes | N/A |

+| name | The name of the variable. Policy expressions aren't allowed. | Yes |

+| value | The value of the variable. This can be an expression or a literal value. Policy expressions are allowed. | Yes |

+| source | String literal meaningful to the trace viewer and specifying the source of the message. Policy expressions aren't allowed. | Yes | N/A |

+| severity | Specifies the severity level of the trace. Allowed values are `verbose`, `information`, `error` (from lowest to highest). Policy expressions aren't allowed. | No | `verbose` |

+| message | A string or expression to be logged. Policy expressions are allowed. | Yes |

+| validate-revocationΓÇ» | Boolean. Specifies whether certificate is validated against online revocation list. Policy expressions aren't allowed.ΓÇ» | No | `true` |

+| validate-trustΓÇ»| Boolean. Specifies if validation should fail in case chain cannot be successfully built up to trusted CA. Policy expressions aren't allowed. | No | `true` |

+| validate-not-before | Boolean. Validates value against current time. Policy expressions aren't allowed.| NoΓÇ»| `true` |

+| validate-not-afterΓÇ» | Boolean. Validates value against current time. Policy expressions aren't allowed.| NoΓÇ»| `true`|

+| ignore-errorΓÇ» | Boolean. Specifies if policy should proceed to the next handler or jump to on-error upon failed validation. Policy expressions aren't allowed. | No | `false` |

+| unspecified-content-type-action | [Action](#actions) to perform for requests or responses with a content type that isnΓÇÖt specified in the API schema. Policy expressions are allowed. | Yes | N/A |

+| max-size | Maximum length of the body of the request or response in bytes, checked against the `Content-Length` header. If the request body or response body is compressed, this value is the decompressed length. Maximum allowed value: 102,400 bytes (100 KB). (Contact [support](https://azure.microsoft.com/support/options/) if you need to increase this limit.) Policy expressions are allowed. | Yes | N/A |

+| size-exceeded-action | [Action](#actions) to perform for requests or responses whose body exceeds the size specified in `max-size`. Policy expressions are allowed.| Yes | N/A |

+| errors-variable-name | Name of the variable in `context.Variables` to log validation errors to. Policy expressions aren't allowed. | No | N/A |

+| any-content-type-value | Content type used for validation of the body of a request or response, regardless of the incoming content type. Policy expressions aren't allowed. | No | N/A |

+| missing-content-type-value | Content type used for validation of the body of a request or response, when the incoming content type is missing or empty. Policy expressions aren't allowed. | No | N/A |

+| error-variable-name | Name of the variable in `context.Variables` to log validation errors to. Policy expressions are allowed. | No | N/A |

+| max-size | Maximum size of the request payload in bytes. Maximum allowed value: 102,400 bytes (100 KB). (Contact [support](https://azure.microsoft.com/support/options/) if you need to increase this limit.) Policy expressions are allowed. | Yes | N/A |

+| max-depth | An integer. Maximum query depth. Policy expressions are allowed. | No | 6 |

+| specified-header-action | [Action](#actions) to perform for response headers specified in the API schema. Policy expressions are allowed. | Yes | N/A |

+| unspecified-header-action | [Action](#actions) to perform for response headers that arenΓÇÖt specified in the API schema. Policy expressions are allowed. | Yes | N/A |

+| errors-variable-name | Name of the variable in `context.Variables` to log validation errors to. Policy expressions aren't allowed. | No | N/A |

+| header-name | The name of the HTTP header holding the token. Policy expressions are allowed. | One of `header-name`, `query-parameter-name` or `token-value` must be specified. | N/A |

+| query-parameter-name | The name of the query parameter holding the token. Policy expressions are allowed. | One of `header-name`, `query-parameter-name` or `token-value` must be specified. | N/A |

+| token-value | Expression returning a string containing the token. You must not return `Bearer ` as part of the token value. Policy expressions are allowed. | One of `header-name`, `query-parameter-name` or `token-value` must be specified. | N/A |

+| failed-validation-httpcode | HTTP Status code to return if the JWT doesn't pass validation. Policy expressions are allowed. | No | 401 |

+| failed-validation-error-message | Error message to return in the HTTP response body if the JWT doesn't pass validation. This message must have any special characters properly escaped. Policy expressions are allowed. | No | Default error message depends on validation issue, for example "JWT not present." |

+| require-expiration-time | Boolean. Specifies whether an expiration claim is required in the token. Policy expressions are allowed. | No | true |

+| require-scheme | The name of the token scheme, for example, "Bearer". When this attribute is set, the policy will ensure that specified scheme is present in the Authorization header value. Policy expressions are allowed. | No | N/A |

+| require-signed-tokens | Boolean. Specifies whether a token is required to be signed. Policy expressions are allowed. | No | true |

+| clock-skew | Timespan. Use to specify maximum expected time difference between the system clocks of the token issuer and the API Management instance. Policy expressions are allowed. | No | 0 seconds |

+| output-token-variable-name | String. Name of context variable that will receive token value as an object of type [`Jwt`](api-management-policy-expressions.md) upon successful token validation. Policy expressions aren't allowed. | No | N/A |

+| specified-parameter-action | [Action](#actions) to perform for request parameters specified in the API schema. <br/><br/> When provided in a `headers`, `query`, or `path` element, the value overrides the value of `specified-parameter-action` in the `validate-parameters` element. Policy expressions are allowed. | Yes | N/A |

+| unspecified-parameter-action | [Action](#actions) to perform for request parameters that arenΓÇÖt specified in the API schema. <br/><br/>When provided in a `headers`or `query` element, the value overrides the value of `unspecified-parameter-action` in the `validate-parameters` element. Policy expressions are allowed. | Yes | N/A |

+| errors-variable-name | Name of the variable in `context.Variables` to log validation errors to. Policy expressions aren't allowed. | No | N/A |

+| headers | Add this element and one or more `parameter` subelements to override default validation [actions](#actions) for certain named parameters in requests. If the parameter is specified in the API schema, this value overrides the higher-level `specified-parameter-action` configuration. If the parameter isnΓÇÖt specified in the API schema, this value overrides the higher-level `unspecified-parameter-action` configuration. | No |

+| query | Add this element and one or more `parameter` subelements to override default validation [actions](#actions) for certain named query parameters in requests. If the parameter is specified in the API schema, this value overrides the higher-level `specified-parameter-action` configuration. If the parameter isnΓÇÖt specified in the API schema, this value overrides the higher-level `unspecified-parameter-action` configuration. | No |

+| path | Add this element and one or more `parameter` subelements to override default validation [actions](#actions) for certain URL path parameters in requests. If the parameter is specified in the API schema, this value overrides the higher-level `specified-parameter-action` configuration. If the parameter isnΓÇÖt specified in the API schema, this value overrides the higher-level `unspecified-parameter-action` configuration. | No |

+| unspecified-status-code-action | [Action](#actions) to perform for HTTP status codes in responses that arenΓÇÖt specified in the API schema. Policy expressions are allowed. | Yes | N/A |

+| errors-variable-name | Name of the variable in `context.Variables` to log validation errors to. Policy expressions aren't allowed. | No | N/A |

+| for | Determines whether the `wait` policy waits for all immediate child policies to be completed or just one. Allowed values are:<br /><br /> - `all` - wait for all immediate child policies to complete<br />- `any` - wait for any immediate child policy to complete. Once the first immediate child policy has completed, the `wait` policy completes and execution of any other immediate child policies is terminated.<br/><br/>Policy expressions are allowed. | No | `all` |

+|kind|The attribute must be set to one of the following values.<br /><br /> - `javascript-friendly` - the converted JSON has a form friendly to JavaScript developers.<br />- `direct` - the converted JSON reflects the original XML document's structure.<br/><br/>Policy expressions are allowed.|Yes|N/A|

+|apply|The attribute must be set to one of the following values.<br /><br /> - `always` - convert always.<br />- `content-type-xml` - convert only if response Content-Type header indicates presence of XML.<br/><br/>Policy expressions are allowed.|Yes|N/A|

+|consider-accept-header|The attribute must be set to one of the following values.<br /><br /> - `true` - apply conversion if JSON is requested in request Accept header.<br />- `false` -always apply conversion.<br/><br/>Policy expressions are allowed.|No|`true`|

+|DNS fallback |Azure DNS |Azure DNS |[Ensure that you have a forwarder to a public DNS or include Azure DNS in the list of custom DNS servers](migrate.md#migration-feature-limitations) |

+ Title: Private Application Gateway deployment (preview)

+description: Learn how to restrict access to Application Gateway

+#Customer intent: As an administrator, I want to evaluate Azure Private Application Gateway

+# Private Application Gateway deployment (preview)

+## Introduction

+Historically, Application Gateway v2 SKUs, and to a certain extent v1, have required public IP addressing to enable management of the service. This requirement has imposed several limitations in using fine-grain controls in Network Security Groups and Route Tables. Specifically, the following challenges have been observed:

+1. All Application Gateways v2 deployments must contain public facing frontend IP configuration to enable communication to the **Gateway Manager** service tag.

+2. Network Security Group associations require rules to allow inbound access from GatewayManager and Outbound access to Internet.

+3. When introducing a default route (0.0.0.0/0) to forward traffic anywhere other than the Internet, metrics, monitoring, and updates of the gateway result in a failed status.

+Application Gateway v2 can now address each of these items to further eliminate risk of data exfiltration and control privacy of communication from within the virtual network. These changes include the following capabilities:

+1. Private IP address only frontend IP configuration

+ - No public IP address resource required

+2. Elimination of inbound traffic from GatewayManager service tag via Network Security Group

+3. Ability to define a **Deny All** outbound Network Security Group (NSG) rule to restrict egress traffic to the Internet

+4. Ability to override the default route to the Internet (0.0.0.0/0)

+5. DNS resolution via defined resolvers on the virtual network [Learn more](../virtual-network/manage-virtual-network.md#change-dns-servers), including private link private DNS zones.

+Each of these features can be configured independently. For example, a public IP address can be used to allow traffic inbound from the Internet and you can define a **_Deny All_** outbound rule in the network security group configuration to prevent data exfiltration.

+## Onboard to public preview

+The functionality of the new controls of private IP frontend configuration, control over NSG rules, and control over route tables, are currently in public preview. To join the public preview, you can opt in to the experience using the Azure portal, PowerShell, CLI, or REST API.

+When you join the preview, all new Application Gateways will provision with the ability to define any combination of the NSG, Route Table, or private IP configuration features. If you wish to opt out from the new functionality and return to the current generally available functionality of Application Gateway, you can do so by [unregistering from the preview](#unregister-from-the-preview).

+For more information about preview features, see [Set up preview features in Azure subscription](../azure-resource-manager/management/preview-features.md)

+## Register to the preview

+# [Azure Portal](#tab/portal)

+Use the following steps to enroll into the public preview for the enhanced Application Gateway network controls via the Azure portal:

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

+2. In the search box, enter _subscriptions_ and select **Subscriptions**.

+ :::image type="content" source="../azure-resource-manager/management/media/preview-features/search.png" alt-text="Azure portal search.":::

+3. Select the link for your subscription's name.

+ :::image type="content" source="../azure-resource-manager/management/media/preview-features/subscriptions.png" alt-text="Select Azure subscription.":::

+4. From the left menu, under **Settings** select **Preview features**.

+ :::image type="content" source="../azure-resource-manager/management/media/preview-features/preview-features-menu.png" alt-text="Azure preview features menu.":::

+5. You see a list of available preview features and your current registration status.

+ :::image type="content" source="../azure-resource-manager/management/media/preview-features/preview-features-list.png" alt-text="Azure portal list of preview features.":::

+6. From **Preview features** type into the filter box **EnableApplicationGatewayNetworkIsolation**, check the feature, and click **Register**.

+ :::image type="content" source="../azure-resource-manager/management/media/preview-features/filter.png" alt-text="Azure portal filter preview features.":::

+# [Azure PowerShell](#tab/powershell)

+To enroll into the public preview for the enhanced Application Gateway network controls via Azure PowerShell, the following commands can be referenced:

+```azurepowershell

+Register-AzProviderFeature -FeatureName "EnableApplicationGatewayNetworkIsolation" -ProviderNamespace "Microsoft.Network"

+```

+To view registration status of the feature, use the Get-AzProviderFeature cmdlet.

+```Output

+FeatureName ProviderName RegistrationState

+-- --

+EnableApplicationGatewayNetworkIsolation Microsoft.Network Registered

+```

+# [Azure CLI](#tab/cli)

+To enroll into the public preview for the enhanced Application Gateway network controls via Azure CLI, the following commands can be referenced:

+```azurecli

+az feature register --name EnableApplicationGatewayNetworkIsolation --namespace Microsoft.Network

+```

+To view registration status of the feature, use the Get-AzProviderFeature cmdlet.

+```Output

+Name RegistrationState

+- -

+Microsoft.Network/EnableApplicationGatewayNetworkIsolation Registered

+```

+A list of all Azure CLI references for Private Link Configuration on Application Gateway can be found here: [Azure CLI CLI - Private Link](/cli/azure/network/application-gateway/private-link)

+For more information about preview features, see [Set up preview features in Azure subscription](../azure-resource-manager/management/preview-features.md)

+## Unregister from the preview

+# [Azure Portal](#tab/portal)

+To opt out of the public preview for the enhanced Application Gateway network controls via Portal, use the following steps:

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

+2. In the search box, enter _subscriptions_ and select **Subscriptions**.

+ :::image type="content" source="../azure-resource-manager/management/media/preview-features/search.png" alt-text="Azure portal search.":::

+3. Select the link for your subscription's name.

+ :::image type="content" source="../azure-resource-manager/management/media/preview-features/subscriptions.png" alt-text="Select Azure subscription.":::

+4. From the left menu, under **Settings** select **Preview features**.

+ :::image type="content" source="../azure-resource-manager/management/media/preview-features/preview-features-menu.png" alt-text="Azure preview features menu.":::

+5. You see a list of available preview features and your current registration status.

+ :::image type="content" source="../azure-resource-manager/management/media/preview-features/preview-features-list.png" alt-text="Azure portal list of preview features.":::

+6. From **Preview features** type into the filter box **EnableApplicationGatewayNetworkIsolation**, check the feature, and click **Unregister**.

+ :::image type="content" source="../azure-resource-manager/management/media/preview-features/filter.png" alt-text="Azure portal filter preview features.":::

+# [Azure PowerShell](#tab/powershell)

+To opt out of the public preview for the enhanced Application Gateway network controls via Azure PowerShell, the following commands can be referenced:

+```azurepowershell

+Unregister-AzProviderFeature -FeatureName "EnableApplicationGatewayNetworkIsolation" -ProviderNamespace "Microsoft.Network"

+```

+To view registration status of the feature, use the Get-AzProviderFeature cmdlet.

+```Output

+FeatureName ProviderName RegistrationState

+-- --

+EnableApplicationGatewayNetworkIsolation Microsoft.Network Unregistered

+```

+# [Azure CLI](#tab/cli)

+To opt out of the public preview for the enhanced Application Gateway network controls via Azure CLI, the following commands can be referenced:

+```azurecli

+az feature unregister --name EnableApplicationGatewayNetworkIsolation --namespace Microsoft.Network

+```

+To view registration status of the feature, use the Get-AzProviderFeature cmdlet.

+```Output

+Name RegistrationState

+- -

+Microsoft.Network/EnableApplicationGatewayNetworkIsolation Unregistered

+```

+A list of all Azure CLI references for Private Link Configuration on Application Gateway can be found here: [Azure CLI CLI - Private Link](/cli/azure/network/application-gateway/private-link)

+## Regions and availability

+The Private Application Gateway preview is available to all public cloud regions [where Application Gateway v2 sku is supported](./overview-v2.md#unsupported-regions).

+## Configuration of network controls

+After registration into the public preview, configuration of NSG, Route Table, and private IP address frontend configuration can be performed using any methods. For example: REST API, ARM Template, Bicep deployment, Terraform, PowerShell, CLI, or Portal. No API or command changes are introduced with this public preview.

+## Resource Changes

+After your gateway is provisioned, isn't tag is automatically assigned with the name of **EnhancedNetworkControl** and value of **True**. See the following example:

+ 

+The resource tag is cosmetic, and serves to confirm that the gateway has been provisioned with the capabilities to configure any combination of the private only gateway features. Modification or deletion of the tag or value doesn't change any functional workings of the gateway.

+> [!TIP]

+> The **EnhancedNetworkControl** tag can be helpful when existing Application Gateways were deployed in the subscription prior to feature enablement and you would like to differentiate which gateway can utilize the new functionality.

+## Outbound Internet connectivity

+Application Gateway deployments that contain only a private frontend IP configuration (do not have a public IP frontend configuration) are not able to egress traffic destined to the Internet. This configuration affects communication to backend targets that are publicly accessible via the Internet.

+To enable outbound connectivity from your Application Gateway to an Internet facing backend target, you can utilize [Virtual Network NAT](../virtual-network/nat-gateway/nat-overview.md) or forward traffic to a virtual appliance that has access to the Internet.

+Virtual Network NAT offers control over what IP address or prefix should be used as well as configurable idle-timeout. To configure, create a new NAT Gateway with a public IP address or public prefix and associate it with the subnet containing Application Gateway.

+If a virtual appliance is required for Internet egress, see the [route table control](#route-table-control) section in this document.

+Common scenarios where public IP usage is required:

+- Communication to key vault without use of private endpoints or service endpoints

+ - Outbound communication isn't required for pfx files uploaded to Application Gateway directly

+- Communication to backend targets via Internet

+- Communication to Internet facing CRL or OCSP endpoints

+## Network Security Group Control

+Network security groups associated to an Application Gateway subnet no longer require inbound rules for GatewayManager, and they don't require outbound access to the Internet. The only required rule is **Allow inbound from AzureLoadBalancer** to ensure health probes can reach the gateway.

+The following configuration is an example of the most restrictive set of inbound rules, denying all traffic but Azure health probes. In addition to the defined rules, explicit rules are defined to allow client traffic to reach the listener of the gateway.

+ [  ](./media/application-gateway-private-deployment/inbound-rules.png#lightbox)

+> [!Note]

+> Application Gateway will display an alert asking to ensure the **Allow LoadBalanceRule** is specified if a **DenyAll** rule inadvertently restricts access to health probes.

+### Example scenario

+This example walks through creation of an NSG using the Azure portal with the following rules:

+- Allow inbound traffic to port 80 and 8080 to Application Gateway from client requests originating from the Internet

+- Deny all other inbound traffic

+- Allow outbound traffic to a backend target in another virtual network

+- Allow outbound traffic to a backend target that is Internet accessible

+- Deny all other outbound traffic

+First, [create a network security group](../virtual-network/tutorial-filter-network-traffic.md#create-a-network-security-group). This security group contains your inbound and outbound rules.

+#### Inbound rules

+Three inbound [default rules](../virtual-network/network-security-groups-overview.md#default-security-rules) are already provisioned in the security group. See the following example:

+ [  ](./media/application-gateway-private-deployment/default-rules.png#lightbox)

+Next, create the following four new inbound security rules:

+- Allow inbound port 80, tcp, from Internet (any)

+- Allow inbound port 8080, tcp, from Internet (any)

+- Allow inbound from AzureLoadBalancer

+- Deny Any Inbound

+To create these rules:

+- Select **Inbound security rules**

+- Select **Add**

+- Enter the following information for each rule into the **Add inbound security rule** pane.

+- When you've entered the information, select **Add** to create the rule.

+- Creation of each rule takes a moment.

+| Rule # | Source | Source service tag | Source port ranges | Destination | Service | Dest port ranges | Protocol | Action | Priority | Name |

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

+| 1 | Any | | * | Any | HTTP | 80 | TCP | Allow | 1028 | AllowWeb |

+| 2 | Any | | * | Any | Custom | 8080 | TCP | Allow | 1029 | AllowWeb8080 |

+| 3 | Service Tag | AzureLoadBalancer | * | Any | Custom | * | Any | Allow | 1045 | AllowLB |

+| 4 | Any | | * | Any | Custom | * | Any | Deny | 4095 | DenyAllInbound |

+Select **Refresh** to review all rules when provisioning is complete.

+ [  ](./media/application-gateway-private-deployment/inbound-example.png#lightbox)

+#### Outbound rules

+Three default outbound rules with priority 65000, 65001, and 65500 are already provisioned.

+Create the following three new outbound security rules:

+- Allow TCP 443 from 10.10.4.0/24 to backend target 20.62.8.49

+- Allow TCP 80 from source 10.10.4.0/24 to destination 10.13.0.4

+- DenyAll traffic rule

+These rules are assigned a priority of 400, 401, and 4096, respectively.

+> [!NOTE]

+> - 10.10.4.0/24 is the Application Gateway subnet address space.

+> - 10.13.0.4 is a virtual machine in a peered VNet.

+> - 20.63.8.49 is a backend target VM.

+To create these rules:

+- Select **Outbound security rules**

+- Select **Add**

+- Enter the following information for each rule into the **Add outbound security rule** pane.

+- When you've entered the information, select **Add** to create the rule.

+- Creation of each rule takes a moment.

+| Rule # | Source | Source IP addresses/CIDR ranges | Source port ranges | Destination | Destination IP addresses/CIDR ranges | Service | Dest port ranges | Protocol | Action | Priority | Name |

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

+| 1 | IP Addresses | 10.10.4.0/24 | * | IP Addresses | 20.63.8.49 | HTTPS | 443 | TCP | Allow | 400 | AllowToBackendTarget |

+| 2 | IP Addresses | 10.10.4.0/24 | * | IP Addresses | 10.13.0.4 | HTTP | 80 | TCP | Allow | 401 | AllowToPeeredVnetVM |

+| 3 | Any | | * | Any | | Custom | * | Any | Deny | 4096 | DenyAll |

+Select **Refresh** to review all rules when provisioning is complete.

+[  ](./media/application-gateway-private-deployment/outbound-example.png#lightbox)

+#### Associate NSG to the subnet

+The last step is to [associate the network security group to the subnet](../virtual-network/tutorial-filter-network-traffic.md#associate-network-security-group-to-subnet) that contains your Application Gateway.

+

+Result:

+[  ](./media/application-gateway-private-deployment/nsg-overview.png#lightbox)

+> [!IMPORTANT]

+> Be careful when you define **DenyAll** rules, as you might inadvertently deny inbound traffic from clients to which you intend to allow access. You might also inadvertently deny outbound traffic to the backend target, causing backend health to fail and produce 5XX responses.

+## Route Table Control

+In the current offering of Application Gateway, association of a route table with a rule (or creation of rule) defined as 0.0.0.0/0 with a next hop as virtual appliance is unsupported to ensure proper management of Application Gateway.

+After registration of the public preview feature, the ability to forward traffic to a virtual appliance is now possible via definition of a route table rule that defines 0.0.0.0/0 with a next hop to Virtual Appliance.

+Forced Tunneling or learning of 0.0.0.0/0 route through BGP advertising does not affect Application Gateway health, and is honored for traffic flow. This scenario can be applicable when using VPN, ExpressRoute, Route Server, or Virtual WAN.

+### Example scenario

+In the following example, we create a route table and associate it to the Application Gateway subnet to ensure outbound Internet access from the subnet will egress from a virtual appliance. At a high level, the following design is summarized in Figure 1:

+- The Application Gateway is in spoke virtual network

+- There is a network virtual appliance (a virtual machine) in the hub network

+- A route table with a default route (0.0.0.0/0) to the virtual appliance is associated to Application Gateway subnet

+

+**Figure 1**: Internet access egress through virtual appliance

+To create a route table and associate it to the Application Gateway subnet:

+1. [Create a route table](../virtual-network/manage-route-table.md#create-a-route-table):

+ 

+2. Select **Routes** and create the next hop rule for 0.0.0.0/0 and configure the destination to be the IP address of your VM:

+ [  ](./media/application-gateway-private-deployment/default-route-nva.png#lightbox)

+3. Select **Subnets** and associate the route table to the Application Gateway subnet:

+ [  ](./media/application-gateway-private-deployment/associate-route-to-subnet.png#lightbox)

+4. Validate that traffic is passing through the virtual appliance.

+## Limitations / Known Issues

+While in public preview, the following limitations are known.

+### Private link configuration (preview)

+[Private link configuration](private-link.md) support for tunneling traffic through private endpoints to Application Gateway is unsupported with private only gateway.

+### Private IP frontend configuration only with AGIC

+AGIC v1.7 must be used to introduce support for private frontend IP only.

+### Private Endpoint connectivity via Global VNet Peering

+If Application Gateway has a backend target or key vault reference to a private endpoint located in a VNet that is accessible via global VNet peering, traffic is dropped, resulting in an unhealthy status.

+### Coexisting v2 Application Gateways created prior to enablement of enhanced network control

+If a subnet shares Application Gateway v2 deployments that were created both prior to and after enablement of the enhanced network control functionality, Network Security Group (NSG) and Route Table functionality is limited to the prior gateway deployment. Application gateways provisioned prior to enablement of the new functionality must either be reprovisioned, or newly created gateways must use a different subnet to enable enhanced network security group and route table features.

+- If a gateway deployed prior to enablement of the new functionality exists in the subnet, you might see errors such as: `For routes associated to subnet containing Application Gateway V2, please ensure '0.0.0.0/0' uses Next Hop Type as 'Internet'` when adding route table entries.

+- When adding network security group rules to the subnet, you might see: `Failed to create security rule 'DenyAnyCustomAnyOutbound'. Error: Network security group \<NSG-name\> blocks outgoing Internet traffic on subnet \<AppGWSubnetId\>, associated with Application Gateway \<AppGWResourceId\>. This isn't permitted for Application Gateways that have fast update enabled or have V2 Sku.`

+### Unknown Backend Health status

+If backend health is _Unknown_, you may see the following error:

+ + The backend health status could not be retrieved. This happens when an NSG/UDR/Firewall on the application gateway subnet is blocking traffic on ports 65503-65534 in case of v1 SKU, and ports 65200-65535 in case of the v2 SKU or if the FQDN configured in the backend pool could not be resolved to an IP address. To learn more visit - https://aka.ms/UnknownBackendHealth.

+This error can be ignored and will be clarified in a future release.

+## Next steps

+- See [Azure security baseline for Application Gateway](/security/benchmark/azure/baselines/application-gateway-security-baseline.md) for more security best practices.

+The source IP address that Application Gateway uses for health probes depend on the backend pool:

+For example: You configure your application gateway to use backend servers A, B, and C to receive HTTP network traffic on port 80. The default health monitoring tests the three servers every 30 seconds for a healthy HTTP response with a 30-second-timeout for each request. A healthy HTTP response has a [status code](https://msdn.microsoft.com/library/aa287675.aspx) between 200 and 399. In this case, the HTTP GET request for the health probe looks like `http://127.0.0.1/`.

+| Protocol |Protocol used to send the probe. This has to match with the protocol defined in the backend HTTP settings it's associated to|

+| Host |Host name to send the probe with. In v1 SKU, this value is used only for the host header of the probe request. In v2 SKU, it is used both as host header and SNI |

+| Port |If defined, this is used as the destination port. Otherwise, it uses the same port as the HTTP settings that it's associated to. This property is only available in the v2 SKU

+Fine grain control over the Application Gateway subnet via NSG rules is possible in public preview. More details can be found [here](application-gateway-private-deployment.md#network-security-group-control).

+With current functionality there are some restrictions:

+Application Gateway V2 currently supports the following combinations:

+* [Private IP address only (preview)](application-gateway-private-deployment.md)

+A public IP address isn't required for an internal endpoint that's not exposed to the Internet. A private frontend configuration is useful for internal line-of-business applications that aren't exposed to the Internet. It's also useful for services and tiers in a multi-tier application within a security boundary that aren't exposed to the Internet but that require round-robin load distribution, session stickiness, or TLS termination.

+Network security groups (NSGs) are supported on Application Gateway.

+Fine grain control over the Application Gateway subnet via NSG rules is possible in public preview. More details can be found [here](application-gateway-private-deployment.md#network-security-group-control).

+With current functionality there are some restrictions:

+Fine grain control over the Application Gateway subnet via Route Table rules is possible in public preview. More details can be found [here](application-gateway-private-deployment.md#route-table-control).

+With current functionality there are some restrictions:

+- [Learn about private Application Gateway deployment](application-gateway-private-deployment.md).

+| Enhanced Network Control (NSG, Route Table, Private IP Frontend only) | | &#x2713; |

+|User-Defined Route (UDR) on Application Gateway subnet|For information about supported scenarios, see [Application Gateway configuration overview](configuration-infrastructure.md#supported-user-defined-routes).|

+|NSG for Inbound port range| - 65200 to 65535 for Standard_v2 SKU<br>- 65503 to 65534 for Standard SKU.<br>Not required for v2 SKUs in public preview [Learn more](application-gateway-private-deployment.md).<br>For more information, see the [FAQ](application-gateway-faq.yml#are-network-security-groups-supported-on-the-application-gateway-subnet).|

+|FIPS mode|Currently not supported.|

+|Private frontend configuration only mode|Currently in public preview [Learn more](application-gateway-private-deployment.md).|

+|Azure Network Watcher integration|Not supported.|

+In the Studio, prior to training with the classification model, run the [layout model](https://formrecognizer.appliedai.azure.com/studio/layout) on each document and upload it to the same location as the original document. Once the layout results are added, you can train the classifier model with your documents.

+Run the following commands on agent-based Linux Hybrid Worker:

+1. ```python

+ sudo bash

+ ```

+1. ```python

+ rm -r /home/nxautomation

+ ```

+1. Under **Process Automation**, select **Hybrid worker groups** and then your hybrid worker group to go to the **Hybrid Worker Group** page.

+1. Under **Hybrid worker group**, select **Hybrid Workers**.

+1. Select the checkbox next to the machine(s) you want to delete from the hybrid worker group.

+1. Select **Delete** to remove the agent-based Linux Hybrid Worker.

+ > [!NOTE]

+ > - This script doesn't remove the Log Analytics agent for Linux from the machine. It only removes the functionality and configuration of the Hybrid Runbook Worker role.

+ > - After you disable the Private Link in your Automation account, it might take up to 60 minutes to remove the Hybrid Runbook worker.

+ > - After you remove the Hybrid Worker, the Hybrid Worker authentication certificate on the machine is valid for 45 minutes.

+1. Open PowerShell session in Administrator mode and run the following command:

+ ```powershell-interactive

+ Remove-Item -Path "HKLM:\SOFTWARE\Microsoft\HybridRunbookWorker\<AutomationAccountID>\<HybridWorkerGroupName>" -Force -Verbose

+ ```

+1. Under **Process Automation**, select **Hybrid worker groups** and then your hybrid worker group to go to the **Hybrid Worker Group** page.

+1. Under **Hybrid worker group**, select **Hybrid Workers**.

+1. Select the checkbox next to the machine(s) you want to delete from the hybrid worker group.

+1. Select **Delete** to remove the agent-based Windows Hybrid Worker.

+ > [!NOTE]

+ > - After you disable the Private Link in your Automation account, it might take up to 60 minutes to remove the Hybrid Runbook worker.

+ > - After you remove the Hybrid Worker, the Hybrid Worker authentication certificate on the machine is valid for 45 minutes.

+1. Open PowerShell session in Administrator mode and run the following command:

+ ```powershell-interactive

+ Remove-Item -Path "HKLM:\SOFTWARE\Microsoft\HybridRunbookWorker\<AutomationAccountID>\<HybridWorkerGroupName>" -Force -Verbose

+ ```

+1. Under **Process Automation**, select **Hybrid worker groups** and then your hybrid worker group to go to the **Hybrid Worker Group** page.

+1. Under **Hybrid worker group**, select **Hybrid Workers**.

+1. Select the checkbox next to the machine(s) you want to delete from the hybrid worker group.

+1. Select **Delete** to remove the agent-based Windows Hybrid Worker.

+ > [!NOTE]

+ > - After you disable the Private Link in your Automation account, it might take up to 60 minutes to remove the Hybrid Runbook worker.

+ > - After you remove the Hybrid Worker, the Hybrid Worker authentication certificate on the machine is valid for 45 minutes.

+Run the following commands on agent-based Linux Hybrid Worker:

+1. ```python

+ sudo bash

+ ```

+1. ```python

+ rm -r /home/nxautomation

+ ```

+1. Under **Process Automation**, select **Hybrid worker groups** and then your hybrid worker group to go to the **Hybrid Worker Group** page.

+1. Under **Hybrid worker group**, select **Hybrid Workers**.

+1. Select the checkbox next to the machine(s) you want to delete from the hybrid worker group.

+1. Select **Delete** to remove the agent-based Linux Hybrid Worker.

+ > [!NOTE]

+ > - This script doesn't remove the Log Analytics agent for Linux from the machine. It only removes the functionality and configuration of the Hybrid Runbook Worker role. </br>

+ > - After you disable the Private Link in your Automation account, it might take up to 60 minutes to remove the Hybrid Runbook worker.

+ > - After you remove the Hybrid Worker, the Hybrid Worker authentication certificate on the machine is valid for 45 minutes.

+## Known limitations

+Currently, only one Azure Arc data controller per Kubernetes cluster is supported. However, you can create multiple Arc data services, such as Arc-enabled SQL managed instances and Arc-enabled PostgreSQL servers, that are managed by the same Azure Arc data controller.

+Developing modern cloud-native applications often includes building, deploying, configuring, and promoting workloads across a group of Kubernetes clusters. With the increasing diversity of Kubernetes cluster types, and the variety of applications and services, the process can become complex and unscalable. Enterprise organizations can be more successful in these efforts by having a well defined structure that organizes people and their activities, and by using automated tools.

+This article describes an organization that develops cloud-native applications. Any application needs a compute resource to work on. In the cloud-native world, this compute resource is a Kubernetes cluster. An organization may have a single cluster or, more commonly, multiple clusters. So the organization must decide which applications should work on which clusters. In other words, they must schedule the applications across clusters. The result of this decision, or scheduling, is a model of the desired state of the clusters in their environment. Having that in place, they need somehow to deliver applications to the assigned clusters so that they can turn the desired state into the reality, or, in other words, reconcile it.

+Depending on the application, there may be a great diversity of cluster types to which the application is deployed. The same application with different configurations could be hosted on a managed cluster in the cloud, on a connected cluster in an on-premises environment, on a group of clusters on semi-connected edge devices on factory lines or military drones, and on an air-gapped cluster on a starship. Another complexity is that clusters in early lifecycle stages such as Dev and QA are normally managed by the developer, while reconciliation to actual production clusters may be managed by the organization's customers. In the latter case, the developer may be responsible only for promoting and scheduling the application across different rings.

+- Promotion of the multi-cluster state through a chain of environments

+The platform team is responsible for managing the clusters that host applications produced by application teams.

+* Define cluster types and their distribution across environments.

+* Manage infrastructure configurations across the clusters.

+Typically, the application team has no knowledge of the clusters that they are deploying to. They aren't aware of the structure of the multi-cluster environment, global configurations, or tasks performed by other teams. The application team primarily understands the success of their application rollout as defined by the success of the pipeline stages.

+The platform team models the multi-cluster environment in the control plane. It's designed to be human-oriented and easy to understand, update, and review. The control plane operates with abstractions such as Cluster Types, Environments, Workloads, Scheduling Policies, Configs and Templates. These abstractions are handled by an automated process that assigns deployment targets and configuration values to the cluster types, then saves the result to the platform GitOps repository. Although there may be thousands of physical clusters, the platform repository operates at a higher level, grouping the clusters into cluster types.

+Platform services are workloads (such as Prometheus, NGINX, Fluentbit, and so on) maintained by the platform team. Just like any workloads, they have their source repositories and manifests storage. The source repositories may contain pointers to external Helm charts. CI/CD pipelines pull the charts with containers and perform necessary security scans before submitting them to the manifests storage, from where they're reconciled to the clusters.

+Deployment Observability Hub is a central storage that is easy to query with complex queries against a large amount of data. It contains deployment data with historical information on workload versions and their deployment state across clusters. Clusters register themselves in the storage and update their compliance status with the GitOps repositories. Clusters operate at the level of Git commits only. High-level information, such as application versions, environments, and cluster type data, is transferred to the central storage from the GitOps repositories. This high-level information gets correlated in the central storage with the commit compliance data sent from the clusters.

+* Walk through a sample implementation to explore [workload management in a multi-cluster environment with GitOps](workload-management.md).

+* Explore a [multi-cluster workload management sample repository](https://github.com/microsoft/kalypso).

+ Title: 'Explore workload management in a multi-cluster environment with GitOps'

+description: Explore typical use-cases that Platform and Application teams face on a daily basis working with Kubernetes workloads in a multi-cluster environment.

+keywords: "GitOps, Flux, Kubernetes, K8s, Azure, Arc, AKS, ci/cd, devops"

+# Explore workload management in a multi-cluster environment with GitOps

+Enterprise organizations, developing cloud native applications, face challenges to deploy, configure and promote a great variety of applications and services across multiple Kubernetes clusters at scale. This environment may include Azure Kubernetes Service (AKS) clusters, clusters running on other public cloud providers, or clusters in on-premises data centers that are connected to Azure through the Azure Arc. Refer to the [conceptual article](conceptual-workload-management.md) exploring the business process, challenges and solution architecture.

+This article walks you through an example scenario of the workload deployment and configuration in a multi-cluster Kubernetes environment. First, you deploy a sample infrastructure with a few GitHub repositories and AKS clusters. Next, you work through a set of use cases where you act as different personas working in the same environment: the Platform Team and the Application Team.

+## Prerequisites

+In order to successfully deploy the sample, you need:

+- An Azure subscription. If you don't already have one, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.

+- [Azure CLI](/cli/azure/install-azure-cli)

+- [GitHub CLI](https://cli.github.com)

+- [Helm](https://helm.sh/docs/helm/helm_install/)

+- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)

+- [jq](https://stedolan.github.io/jq/download/)

+- GitHub token with the following scopes: `repo`, `workflow`, `write:packages`, `delete:packages`, `read:org`, `delete_repo`.

+## 1 - Deploy the sample

+To deploy the sample, run the following script:

+```bash

+mkdir kalypso && cd kalypso

+curl -fsSL -o deploy.sh https://raw.githubusercontent.com/microsoft/kalypso/main/deploy/deploy.sh

+chmod 700 deploy.sh

+./deploy.sh -c -p <prefix. e.g. kalypso> -o <github org. e.g. eedorenko> -t <github token> -l <azure-location. e.g. westus2>

+```

+This script may take 10-15 minutes to complete. After it's done, it reports the execution result in the output like this:

+```output

+Deployment is complete!

+Created repositories:

+ - https://github.com/eedorenko/kalypso-control-plane

+ - https://github.com/eedorenko/kalypso-gitops

+ - https://github.com/eedorenko/kalypso-app-src

+ - https://github.com/eedorenko/kalypso-app-gitops

+Created AKS clusters in kalypso-rg resource group:

+ - control-plane

+ - drone (Flux based workload cluster)

+ - large (ArgoCD based workload cluster)

+

+```

+> [!NOTE]

+> If something goes wrong with the deployment, you can delete the created resources with the following command:

+>

+> ```bash

+> ./deploy.sh -d -p <preix. e.g. kalypso> -o <github org. e.g. eedorenko> -t <github token> -l <azure-location. e.g. westus2>

+> ```

+### Sample overview

+This deployment script created an infrastructure, shown in the following diagram:

+There are a few Platform Team repositories:

+- [Control Plane](https://github.com/microsoft/kalypso-control-plane): Contains a platform model defined with high level abstractions such as environments, cluster types, applications and services, mapping rules and configurations, and promotion workflows.

+- [Platform GitOps](https://github.com/microsoft/kalypso-gitops): Contains final manifests that represent the topology of the multi-cluster environment, such as which cluster types are available in each environment, what workloads are scheduled on them, and what platform configuration values are set.

+- [Services Source](https://github.com/microsoft/kalypso-svc-src): Contains high-level manifest templates of sample dial-tone platform services.

+- [Services GitOps](https://github.com/microsoft/kalypso-svc-gitops): Contains final manifests of sample dial-tone platform services to be deployed across the clusters.

+The infrastructure also includes a couple of the Application Team repositories:

+- [Application Source](https://github.com/microsoft/kalypso-app-src): Contains a sample application source code, including Docker files, manifest templates and CI/CD workflows.

+- [Application GitOps](https://github.com/microsoft/kalypso-app-gitops): Contains final sample application manifests to be deployed to the deployment targets.

+The script created the following Azure Kubernetes Service (AKS) clusters:

+- `control-plane` - This cluster is a management cluster that doesn't run any workloads. The `control-plane` cluster hosts [Kalypso Scheduler](https://github.com/microsoft/kalypso-scheduler) operator that transforms high level abstractions from the [Control Plane](https://github.com/microsoft/kalypso-control-plane) repository to the raw Kubernetes manifests in the [Platform GitOps](https://github.com/microsoft/kalypso-gitops) repository.

+- `drone` - A sample workload cluster. This cluster has the [GitOps extension](conceptual-gitops-flux2.md) installed and it uses `Flux` to reconcile manifests from the [Platform GitOps](https://github.com/microsoft/kalypso-gitops) repository. For this sample, the `drone` cluster can represent an Azure Arc-enabled cluster or an AKS cluster with the Flux/GitOps extension.

+- `large` - A sample workload cluster. This cluster has `ArgoCD` installed on it to reconcile manifests from the [Platform GitOps](https://github.com/microsoft/kalypso-gitops) repository.

+### Explore Control Plane

+The `control plane` repository contains three branches: `main`, `dev` and `stage`. The `dev` and `stage` branches contain configurations that are specific for `Dev` and `Stage` environments. On the other hand, the `main` branch doesn't represent any specific environment. The content of the `main` branch is common and used by all environments. Any change to the `main` branch is a subject to be promoted across environments. For example, a new application or a new template can be promoted to the `Stage` environment only after successful testing on the `Dev` environment.

+The `main` branch:

+|Folder|Description|

+||--|

+|.github/workflows| Contains GitHub workflows that implement the promotional flow.|

+|.environments| Contains a list of environments with pointers to the branches with the environment configurations.|

+|templates| Contains manifest templates for various reconcilers (for example, Flux and ArgoCD) and a template for the workload namespace.|

+|workloads| Contains a list of onboarded applications and services with pointers to the corresponding GitOps repositories.|

+The `dev` and `stage` branches:

+|Item|Description|

+|-|--|

+|cluster-types| Contains a list of available cluster types in the environment. The cluster types are grouped in custom subfolders. Each cluster type is marked with a set of labels. It specifies a reconciler type that it uses to fetch the manifests from GitOps repositories. The subfolders also contain a number of config maps with the platform configuration values available on the cluster types.|

+|configs/dev-config.yaml| Contains config maps with the platform configuration values applicable for all cluster types in the environment.|

+|scheduling| Contains scheduling policies that map workload deployment targets to the cluster types in the environment.|

+|base-repo.yaml| A pointer to the place in the `Control Plane` repository (`main`) from where the scheduler should take templates and workload registrations.|

+|gitops-repo.yaml| A pointer to the place in the `Platform GitOps` repository to where the scheduler should PR generated manifests.|

+> [!TIP]

+> The folder structure in the `Control Plane` repository doesn't really matter. This example provides one way of organizing files in the repository, but feel free to do it in your own preferred way. The scheduler is interested in the content of the files, rather than where the files are located.

+## 2 - Platform Team: Onboard a new application

+The Application Team runs their software development lifecycle. They build their application and promote it across environments. They're not aware of what cluster types are available and where their application will be deployed. But they do know that they want to deploy their application in `Dev` environment for functional and performance testing and in `Stage` environment for UAT testing.

+The Application Team describes this intention in the [workload](https://github.com/microsoft/kalypso-app-src/blob/main/workload/workload.yaml) file in the [Application Source](https://github.com/microsoft/kalypso-app-src) repository:

+```yaml

+apiVersion: scheduler.kalypso.io/v1alpha1

+kind: Workload

+metadata:

+ name: hello-world-app

+ labels:

+ type: application

+ family: force

+spec:

+ deploymentTargets:

+ - name: functional-test

+ labels:

+ purpose: functional-test

+ edge: "true"

+ environment: dev

+ manifests:

+ repo: https://github.com/microsoft/kalypso-app-gitops

+ branch: dev

+ path: ./functional-test

+ - name: performance-test

+ labels:

+ purpose: performance-test

+ edge: "false"

+ environment: dev

+ manifests:

+ repo: https://github.com/microsoft/kalypso-app-gitops

+ branch: dev

+ path: ./performance-test

+ - name: uat-test

+ labels:

+ purpose: uat-test

+ environment: stage

+ manifests:

+ repo: https://github.com/microsoft/kalypso-app-gitops

+ branch: stage

+ path: ./uat-test

+```

+This file contains a list of three deployment targets. These targets are marked with custom labels and point to the folders in [Application GitOps](https://github.com/microsoft/kalypso-app-gitops) repository where the Application Team generates application manifests for each deployment target.

+With this file, Application Team requests Kubernetes compute resources from the Platform Team. In response, the Platform Team must register the application in the [Control Plane](https://github.com/microsoft/kalypso-control-plane) repo.

+

+To register the application, open a terminal and use the following script:

+```bash

+export org=<github org>

+export prefix=<prefix>

+# clone the control-plane repo

+git clone https://github.com/$org/$prefix-control-plane control-plane

+cd control-plane

+# create workload registration file

+cat <<EOF >workloads/hello-world-app.yaml

+apiVersion: scheduler.kalypso.io/v1alpha1

+kind: WorkloadRegistration

+metadata:

+ name: hello-world-app

+ labels:

+ type: application

+spec:

+ workload:

+ repo: https://github.com/$org/$prefix-app-src

+ branch: main

+ path: workload/

+ workspace: kaizen-app-team

+EOF

+git add .

+git commit -m 'workload registration'

+git push

+```

+> [!NOTE]

+> For simplicity, this example pushes changes directly to `main`. In practice, you'd create a pull request to submit the changes.

+With that in place, the application is onboarded in the control plane. But the control plane still doesn't know how to map the application deployment targets to all of the cluster types.

+### Define application scheduling policy on Dev

+The Platform Team must define how the application deployment targets will be scheduled on cluster types in the `Dev` environment. To do this, submit scheduling policies for the `functional-test` and `performance-test` deployment targets with the following script:

+```bash

+# Switch to dev branch (representing Dev environemnt) in the control-plane folder

+git checkout dev

+mkdir -p scheduling/kaizen

+# Create a scheduling policy for the functional-test deployment target

+cat <<EOF >scheduling/kaizen/functional-test-policy.yaml

+apiVersion: scheduler.kalypso.io/v1alpha1

+kind: SchedulingPolicy

+metadata:

+ name: functional-test-policy

+spec:

+ deploymentTargetSelector:

+ workspace: kaizen-app-team

+ labelSelector:

+ matchLabels:

+ purpose: functional-test

+ edge: "true"

+ clusterTypeSelector:

+ labelSelector:

+ matchLabels:

+ restricted: "true"

+ edge: "true"

+EOF

+# Create a scheduling policy for the performance-test deployment target

+cat <<EOF >scheduling/kaizen/performance-test-policy.yaml

+apiVersion: scheduler.kalypso.io/v1alpha1

+kind: SchedulingPolicy

+metadata:

+ name: performance-test-policy

+spec:

+ deploymentTargetSelector:

+ workspace: kaizen-app-team

+ labelSelector:

+ matchLabels:

+ purpose: performance-test

+ edge: "false"

+ clusterTypeSelector:

+ labelSelector:

+ matchLabels:

+ size: large

+EOF

+git add .

+git commit -m 'application scheduling policies'

+git config pull.rebase false

+git pull --no-edit

+git push

+```

+The first policy states that all deployment targets from the `kaizen-app-team` workspace, marked with labels `purpose: functional-test` and `edge: "true"` should be scheduled on all environment cluster types that are marked with label `restricted: "true"`. You can treat a workspace as a group of applications produced by an application team.

+The second policy states that all deployment targets from the `kaizen-app-team` workspace, marked with labels `purpose: performance-test` and `edge: "false"` should be scheduled on all environment cluster types that are marked with label `size: "large"`.

+This push to the `dev` branch triggers the scheduling process and creates a PR to the `dev` branch in the `Platform GitOps` repository:

+Besides `Promoted_Commit_id`, which is just tracking information for the promotion CD flow, the PR contains assignment manifests. The `functional-test` deployment target is assigned to the `drone` cluster type, and the `performance-test` deployment target is assigned to the `large` cluster type. Those manifests will land in `drone` and `large` folders that contain all assignments to these cluster types in the `Dev` environment.

+

+The `Dev` environment also includes `command-center` and `small` cluster types:

+ :::image type="content" source="media/workload-management/dev-cluster-types.png" alt-text="Screenshot showing cluster types in the Dev environment.":::

+However, only the `drone` and `large` cluster types were selected by the scheduling policies that you defined.

+### Understand deployment target assignment manifests

+Before you continue, take a closer look at the generated assignment manifests for the `functional-test` deployment target. There are `namespace.yaml`, `config.yaml` and `reconciler.yaml` manifest files.

+`namespace.yaml` defines a namespace that will be created on any `drone` cluster where the `hello-world` application runs.

+

+```yaml

+apiVersion: v1

+kind: Namespace

+metadata:

+ labels:

+ deploymentTarget: hello-world-app-functional-test

+ environment: dev

+ someLabel: some-value

+ workload: hello-world-app

+ workspace: kaizen-app-team

+ name: dev-kaizen-app-team-hello-world-app-functional-test

+```

+`config.yaml` contains all platform configuration values available on any `drone` cluster that the application can use in the `Dev` environment.

+

+```yaml

+apiVersion: v1

+kind: ConfigMap

+metadata:

+ name: platform-config

+ namespace: dev-kaizen-app-team-hello-world-app-functional-test

+data:

+ CLUSTER_NAME: Drone

+ DATABASE_URL: mysql://restricted-host:3306/mysqlrty123

+ ENVIRONMENT: Dev

+ REGION: East US

+ SOME_COMMON_ENVIRONMENT_VARIABLE: "false"

+```

+`reconciler.yaml` contains Flux resources that a `drone` cluster uses to fetch application manifests, prepared by the Application Team for the `functional-test` deployment target.

+

+```yaml

+apiVersion: source.toolkit.fluxcd.io/v1beta2

+kind: GitRepository

+metadata:

+ name: hello-world-app-functional-test

+ namespace: flux-system

+spec:

+ interval: 30s

+ ref:

+ branch: dev

+ secretRef:

+ name: repo-secret

+ url: https://github.com/<github org>/<prefix>-app-gitops

+apiVersion: kustomize.toolkit.fluxcd.io/v1beta2

+kind: Kustomization

+metadata:

+ name: hello-world-app-functional-test

+ namespace: flux-system

+spec:

+ interval: 30s

+ path: ./functional-test

+ prune: true

+ sourceRef:

+ kind: GitRepository

+ name: hello-world-app-functional-test

+ targetNamespace: dev-kaizen-app-team-hello-world-app-functional-test

+```

+> [!NOTE]

+> The `control plane` defines that the `drone` cluster type uses `Flux` to reconcile manifests from the application GitOps repositories. The `large` cluster type, on the other hand, reconciles manifests with `ArgoCD`. Therefore `reconciler.yaml` for the `performance-test` deployment target will look differently and contain `ArgoCD` resources.

+### Promote application to Stage

+Once you approve and merge the PR to the `Platform GitOps` repository, the `drone` and `large` AKS clusters that represent corresponding cluster types start fetching the assignment manifests. The `drone` cluster has [GitOps extension](conceptual-gitops-flux2.md) installed, pointing to the `Platform GitOps` repository. It reports its `compliance` status to Azure Resource Graph:

+The PR merging event starts a GitHub workflow `checkpromote` in the `control plane` repository. This workflow waits until all clusters with the [GitOps extension](conceptual-gitops-flux2.md) installed that are looking at the `dev` branch in the `Platform GitOps` repository are compliant with the PR commit. In this example, the only such cluster is `drone`.

+Once the `checkpromote` is successful, it starts the `cd` workflow that promotes the change (application registration) to the `Stage` environment. For better visibility, it also updates the git commit status in the `control plane` repository:

+> [!NOTE]

+> If the `drone` cluster fails to reconcile the assignment manifests for any reason, the promotion flow will fail. The commit status will be marked as failed, and the application registration will not be promoted to the `Stage` environment.

+Next, configure a scheduling policy for the `uat-test` deployment target in the stage environment:

+```bash

+# Switch to stage branch (representing Stage environemnt) in the control-plane folder

+git checkout stage

+mkdir -p scheduling/kaizen

+# Create a scheduling policy for the uat-test deployment target

+cat <<EOF >scheduling/kaizen/uat-test-policy.yaml

+apiVersion: scheduler.kalypso.io/v1alpha1

+kind: SchedulingPolicy

+metadata:

+ name: uat-test-policy

+spec:

+ deploymentTargetSelector:

+ workspace: kaizen-app-team

+ labelSelector:

+ matchLabels:

+ purpose: uat-test

+ clusterTypeSelector:

+ labelSelector: {}

+EOF

+git add .

+git commit -m 'application scheduling policies'

+git config pull.rebase false

+git pull --no-edit

+git push

+```

+The policy states that all deployment targets from the `kaizen-app-team` workspace marked with labels `purpose: uat-test` should be scheduled on all cluster types defined in the environment.

+Pushing this policy to the `stage` branch triggers the scheduling process, which creates a PR with the assignment manifests to the `Platform GitOps` repository, similar to those for the `Dev` environment.

+As in the case with the `Dev` environment, after reviewing and merging the PR to the `Platform GitOps` repository, the `checkpromote` workflow in the `control plane` repository waits until clusters with the [GitOps extension](conceptual-gitops-flux2.md) (`drone`) reconcile the assignment manifests.

+ :::image type="content" source="media/workload-management/check-promote-to-stage.png" alt-text="Screenshot showing promotion to stage.":::

+On successful execution, the commit status is updated.

+## 3 - Application Dev Team: Build and deploy application

+The Application Team regularly submits pull requests to the `main` branch in the `Application Source` repository. Once a PR is merged to `main`, it starts a CI/CD workflow. Here, the workflow will be started manually.

+ Go to the `Application Source` repository in GitHub. On the `Actions` tab, select `Run workflow`.

+The workflow performs the following actions:

+- Builds the application Docker image and pushes it to the GitHub repository package.

+- Generates manifests for the `functional-test` and `performance-test` deployment targets. It uses configuration values from the `dev-configs` branch. The generated manifests are added to a pull request and auto-merged in the `dev` branch.

+- Generates manifests for the `uat-test` deployment target. It uses configuration values from the `stage-configs` branch.

+The generated manifests are added to a pull request to the `stage` branch waiting for approval:

+To test the application manually on the `Dev` environment before approving the PR to the `Stage` environment, first verify how the `functional-test` application instance works on the `drone` cluster:

+```bash

+kubectl port-forward svc/hello-world-service -n dev-kaizen-app-team-hello-world-app-functional-test 9090:9090 --context=drone

+# output:

+# Forwarding from 127.0.0.1:9090 -> 9090

+# Forwarding from [::1]:9090 -> 9090

+```

+While this command is running, open `localhost:9090` in your browser. You'll see the following greeting page:

+The next step is to check how the `performance-test` instance works on the `large` cluster:

+```bash

+kubectl port-forward svc/hello-world-service -n dev-kaizen-app-team-hello-world-app-performance-test 8080:8080 --context=large

+# output:

+# Forwarding from 127.0.0.1:8080 -> 8080

+# Forwarding from [::1]:8080 -> 8080

+```

+This time, use `8080` port and open `localhost:8080` in your browser.

+Once you're satisfied with the `Dev` environment, approve and merge the PR to the `Stage` environment. After that, test the `uat-test` application instance in the `Stage` environment on both clusters.

+Run the following command for the `drone` cluster and open `localhost:8001` in your browser:

+

+```bash

+kubectl port-forward svc/hello-world-service -n stage-kaizen-app-team-hello-world-app-uat-test 8001:8000 --context=drone

+```

+Run the following command for the `large` cluster and open `localhost:8002` in your browser:

+ ```bash

+kubectl port-forward svc/hello-world-service -n stage-kaizen-app-team-hello-world-app-uat-test 8002:8000 --context=large

+```

+> [!NOTE]

+> It may take up to three minutes to reconcile the changes from the application GitOps repository on the `large` cluster.

+The application instance on the `large` cluster shows the following greeting page:

+ :::image type="content" source="media/workload-management/stage-greeting-page.png" alt-text="Screenshot showing the greeting page on stage.":::

+## 4 - Platform Team: Provide platform configurations

+Applications in the clusters grab the data from the very same database in both `Dev` and `Stage` environments. Let's change it and configure `west-us` clusters to provide a different database url for the applications working in the `Stage` environment:

+```bash

+# Switch to stage branch (representing Stage environemnt) in the control-plane folder

+git checkout stage

+# Update a config map with the configurations for west-us clusters

+cat <<EOF >cluster-types/west-us/west-us-config.yaml

+apiVersion: v1

+kind: ConfigMap

+metadata:

+ name: west-us-config

+ labels:

+ platform-config: "true"

+ region: west-us

+data:

+ REGION: West US

+ DATABASE_URL: mysql://west-stage:8806/mysql2

+EOF

+git add .

+git commit -m 'database url configuration'

+git config pull.rebase false

+git pull --no-edit

+git push

+```

+The scheduler scans all config maps in the environment and collects values for each cluster type based on label matching. Then, it puts a `platform-config` config map in every deployment target folder in the `Platform GitOps` repository. The `platform-config` config map contains all of the platform configuration values that the workload can use on this cluster type in this environment.

+In a few seconds, a new PR to the `stage` branch in the `Platform GitOps` repository appears:

+Approve the PR and merge it.

+The `large` cluster is handled by ArgoCD, which, by default, is configured to reconcile every three minutes. This cluster doesn't report its compliance state to Azure like the clusters such as `drone` that have the [GitOps extension](conceptual-gitops-flux2.md). However, you can still monitor the reconciliation state on the cluster with ArgoCD UI.

+To access the ArgoCD UI on the `large` cluster, run the following command:

+```bash

+# Get ArgoCD username and password

+echo "ArgoCD username: admin, password: $(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" --context large| base64 -d)"

+# output:

+# ArgoCD username: admin, password: eCllTELZdIZfApPL

+kubectl port-forward svc/argocd-server 8080:80 -n argocd --context large

+```

+Next, open `localhost:8080` in your browser and provide the username and password printed by the script. You'll see a web page similar to this one:

+ :::image type="content" source="media/workload-management/argocd-ui.png" alt-text="Screenshot showing the Argo CD user interface web page." lightbox="media/workload-management/argocd-ui.png":::

+Select the `stage` tile to see more details on the reconciliation state from the `stage` branch to this cluster. You can select the `SYNC` buttons to force the reconciliation and speed up the process.

+Once the new configuration has arrived to the cluster, check the `uat-test` application instance at `localhost:8002` after

+running the following commands:

+```bash

+kubectl rollout restart deployment hello-world-deployment -n stage-kaizen-app-team-hello-world-app-uat-test --context=large

+kubectl port-forward svc/hello-world-service -n stage-kaizen-app-team-hello-world-app-uat-test 8002:8000 --context=large

+```

+You'll see the updated database url:

+## 5 - Platform Team: Add cluster type to environment

+Currently, only `drone` and `large` cluster types are included in the `Stage` environment. Let's include the `small` cluster type to `Stage` as well. Even though there's no physical cluster representing this cluster type, you can see how the scheduler reacts to this change.

+```bash

+# Switch to stage branch (representing Stage environemnt) in the control-plane folder

+git checkout stage

+# Add "small" cluster type in west-us region

+mkdir -p cluster-types/west-us/small

+cat <<EOF >cluster-types/west-us/small/small-cluster-type.yaml

+apiVersion: scheduler.kalypso.io/v1alpha1

+kind: ClusterType

+metadata:

+ name: small

+ labels:

+ region: west-us

+ size: small

+spec:

+ reconciler: argocd

+ namespaceService: default

+EOF

+git add .

+git commit -m 'add new cluster type'

+git config pull.rebase false

+git pull --no-edit

+git push

+```

+In a few seconds, the scheduler submits a PR to the `Platform GitOps` repository. According to the `uat-test-policy` that you created, it assigns the `uat-test` deployment target to the new cluster type, as it's supposed to work on all available cluster types in the environment.

+## Clean up resources

+When no longer needed, delete the resources that you created. To do so, run the following command:

+```bash

+# In kalypso folder

+./deploy.sh -d -p <preix. e.g. kalypso> -o <github org. e.g. eedorenko> -t <github token> -l <azure-location. e.g. westus2>

+```

+## Next steps

+You have performed tasks for a few common workload management scenarios in a multi-cluster Kubernetes environment. There are many other scenarios you may want to explore. Continue to use the sample and see how you can implement use cases that are most common in your daily activities.

+To understand the underlying concepts and mechanics deeper, refer to the following resources:

+> [!div class="nextstepaction"]

+> - [Concept: Workload Management in Multi-cluster environment with GitOps](conceptual-workload-management.md)

+> - [Sample implementation: Workload Management in Multi-cluster environment with GitOps](https://github.com/microsoft/kalypso)

+1. Open the `/etc/hosts` hosts file in a text editor.

+This article shows you how to perform tasks related to configuring your function app to connect to and run on a virtual network. For an in-depth tutorial on how to secure your storage account, refer to the [Connect to a Virtual Network tutorial](functions-create-vnet.md). To learn more about Azure Functions and networking, see [Azure Functions networking options](functions-networking-options.md).

+When you create a function app, you must create or link to a general-purpose Azure Storage account that supports Blob, Queue, and Table storage. You can secure a new storage account behind a virtual network during account creation. At this time, you can't secure an existing storage account being used by your function app in the same way.

+> [!NOTE]

+> Securing your storage account is supported for all tiers in both Dedicated (App Service) and Elastic Premium plans. Consumption plans currently don't support virtual networks.

+### During function app creation

+You can create a new function app along with a new storage account secured behind a virtual network. The following links show you how to create these resources by using either the Azure portal or by using deployment templates:

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

+Complete the following tutorial to create a new function app a secured storage account: [Use private endpoints to integrate Azure Functions with a virtual network](functions-create-vnet.md).

+# [Deployment templates](#tab/templates)

+Use Bicep or Azure Resource Manager (ARM) [quickstart templates](https://github.com/Azure/azure-quickstart-templates/tree/master/quickstarts/microsoft.web/function-app-storage-private-endpoints) to create secured function app and storage account resources.

+### Existing function app

+When you have an existing function app, you can't secure the storage account currently being used by the app. You must instead swap-out the existing storage account for a new, secured storage account.

+To secure the storage for an existing function app:

+1. Choose a function app with a storage account that doesn't have service endpoints or private endpoints enabled.

+1. [Enable virtual network integration](./functions-networking-options.md#enable-virtual-network-integration) for your function app.

+1. Create or configure a second storage account. This is going to be the secured storage account that your function app uses instead.

+1. [Create a file share](../storage/files/storage-how-to-create-file-share.md#create-a-file-share) in the new storage account.

+1. Secure the new storage account in one of the following ways:

+ * [Create a private endpoint](../storage/common/storage-private-endpoints.md#creating-a-private-endpoint). When using private endpoint connections, the storage account must have private endpoints for the `file` and `blob` subresources. For Durable Functions, you must also make `queue` and `table` subresources accessible through private endpoints.

+ * [Enable a service endpoint from the virtual network](../storage/common/storage-network-security.md#grant-access-from-a-virtual-network). When using service endpoints, enable the subnet dedicated to your function apps for storage accounts on the firewall.

+1. Copy the file and blob content from the current storage account used by the function app to the newly secured storage account and file share.

+zone_pivot_groups: programming-languages-set-functions-lang-workers

+Make sure to choose your Durable Functions development language at the top of the article.

+> [!IMPORTANT]

+> This article supports both Python v1 and Python v2 programming models for Durable Functions.

+> The Python v2 programming model is currently in preview.

+## Python v2 programming model

+Durable Functions provides preview support of the new [Python v2 programming model](../functions-reference-python.md?pivots=python-mode-decorators). To use the v2 model, you must install the Durable Functions SDK, which is the PyPI package `azure-functions-durable`, version `1.2.2` or a later version. During the preview, you can provide feedback and suggestions in the [Durable Functions SDK for Python repo](https://github.com/Azure/azure-functions-durable-python/issues).

+Using [Extension Bundles](../functions-bindings-register.md#extension-bundles) isn't currently supported for the v2 model with Durable Functions. You'll instead need to manage your extensions manually as follows:

+1. Remove the `extensionBundle` section of your `host.json` as described in [this Functions article](../functions-run-local.md#install-extensions).

+

+1. Run the `func extensions install --package Microsoft.Azure.WebJobs.Extensions.DurableTask --version 2.9.1` command on your terminal. This installs the Durable Functions extension for your app, which allows you to use the v2 model preview.

+When you author functions in .NET, the orchestration trigger is configured using the [OrchestrationTriggerAttribute](/dotnet/api/microsoft.azure.webjobs.extensions.durabletask.orchestrationtriggerattribute) .NET attribute.

+For Java, the `@DurableOrchestrationTrigger` annotation is used to configure the orchestration trigger.

+When you write orchestrator functions, the orchestration trigger is defined by the following JSON object in the `bindings` array of the *function.json* file:

+```json

+{

+ "name": "<Name of input parameter in function signature>",

+ "orchestration": "<Optional - name of the orchestration>",

+ "type": "orchestrationTrigger",

+ "direction": "in"

+}

+```

+* `orchestration` is the name of the orchestration that clients must use when they want to start new instances of this orchestrator function. This property is optional. If not specified, the name of the function is used.

+Azure Functions supports two programming models for Python. The way that you define an orchestration trigger depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define an orchestration trigger using the `orchestration_trigger` decorator directly in your Python function code.

+In the v2 model, the Durable Functions triggers and bindings are accessed from an instance of `DFApp`, which is a subclass of `FunctionApp` that additionally exports Durable Functions-specific decorators.

+# [v1](#tab/python-v1)

+When you write orchestrator functions in the Python v1 programming model, the orchestration trigger is defined by the following JSON object in the `bindings` array of the *function.json* file:

+> Orchestrator functions should never be declared `async`.

+The specific attribute used to define the trigger depends on whether you are running your C# functions [in-process](../functions-dotnet-class-library.md) or in an [isolated worker process](../dotnet-isolated-process-guide.md).

+# [In-process](#tab/in-process)

+# [Isolated process](#tab/isolated-process)

+# [v2](#tab/python-v2)

+```python

+import azure.functions as func

+import azure.durable_functions as df

+myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

+@myApp.orchestration_trigger(context_name="context")

+def my_orchestrator(context):

+ result = yield context.call_activity("Hello", "Tokyo")

+ return result

+```

+# [v1](#tab/python-v1)

+# [In-process](#tab/in-process)

+# [Isolated process](#tab/isolated-process)

+The activity trigger is configured using the [ActivityTriggerAttribute](/dotnet/api/microsoft.azure.webjobs.extensions.durabletask.activitytriggerattribute) .NET attribute.

+The activity trigger is configured using the `@DurableActivityTrigger` annotation.

+The activity trigger is defined by the following JSON object in the `bindings` array of *function.json*:

+```json

+{

+ "name": "<Name of input parameter in function signature>",

+ "activity": "<Optional - name of the activity>",

+ "type": "activityTrigger",

+ "direction": "in"

+}

+```

+* `activity` is the name of the activity. This value is the name that orchestrator functions use to invoke this activity function. This property is optional. If not specified, the name of the function is used.

+The way that you define an activity trigger depends on your chosen programming model.

+# [v2](#tab/python-v2)

+Using the `activity_trigger` decorator directly in your Python function code.

+# [v1](#tab/python-v1)

+The activity trigger is defined by the following JSON object in the `bindings` array of *function.json*:

+The following example code shows what a simple `SayHello` activity function might look like.

+# [In-process](#tab/in-process)

+# [Isolated process](#tab/isolated-process)

+# [v2](#tab/python-v2)

+```python

+import azure.functions as func

+import azure.durable_functions as df

+myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

+@myApp.activity_trigger(input_name="myInput")

+def my_activity(myInput: str):

+ return "Hello " + myInput

+```

+# [v1](#tab/python-v1)

+You can use regular input and output bindings in addition to the activity trigger binding.

+For example, you can take the input to your activity binding, and send a message to an EventHub using the EventHub output binding:

+You can bind to the orchestration client by using the [DurableClientAttribute](/dotnet/api/microsoft.azure.webjobs.extensions.durabletask.durableclientattribute) attribute ([OrchestrationClientAttribute](/dotnet/api/microsoft.azure.webjobs.orchestrationclientattribute?view=azure-dotnet-legacy&preserve-view=true) in Durable Functions v1.x).

+You can bind to the orchestration client by using the `@DurableClientInput` annotation.

+The durable client trigger is defined by the following JSON object in the `bindings` array of *function.json*:

+```json

+{

+ "name": "<Name of input parameter in function signature>",

+ "taskHub": "<Optional - name of the task hub>",

+ "connectionName": "<Optional - name of the connection string app setting>",

+ "type": "orchestrationClient",

+ "direction": "in"

+}

+```

+* `taskHub` - Used in scenarios where multiple function apps share the same storage account but need to be isolated from each other. If not specified, the default value from `host.json` is used. This value must match the value used by the target orchestrator functions.

+* `connectionName` - The name of an app setting that contains a storage account connection string. The storage account represented by this connection string must be the same one used by the target orchestrator functions. If not specified, the default storage account connection string for the function app is used.

+> [!NOTE]

+> In most cases, we recommend that you omit these properties and rely on the default behavior.

+The way that you define a durable client trigger depends on your chosen programming model.

+# [v2](#tab/python-v2)

+Using the `durable_client_input` decorator directly in your Python function code.

+# [v1](#tab/python-v1)

+The durable client trigger is defined by the following JSON object in the `bindings` array of *function.json*:

+You typically bind to [IDurableClient](/dotnet/api/microsoft.azure.webjobs.extensions.durabletask.idurableclient) ([DurableOrchestrationClient](/dotnet/api/microsoft.azure.webjobs.durableorchestrationclient?view=azure-dotnet-legacy&preserve-view=true) in Durable Functions v1.x), which gives you full access to all orchestration client APIs supported by Durable Functions.

+You typically bind to the `DurableClientContext` class.

+You must use the language-specific SDK to get access to a client object.

+# [In-process](#tab/in-process)

+# [Isolated process](#tab/isolated-process)

+**run.ps1**

+```powershell

+param([string] $input, $TriggerMetadata)

+$InstanceId = Start-DurableOrchestration -FunctionName $FunctionName -Input $input

+```

+# [v2](#tab/python-v2)

+```python

+import azure.functions as func

+import azure.durable_functions as df

+myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

+@myApp.route(route="orchestrators/{functionName}")

+@myApp.durable_client_input(client_name="client")

+async def durable_trigger(req: func.HttpRequest, client):

+ function_name = req.route_params.get('functionName')

+ instance_id = await client.start_new(function_name)

+ response = client.create_check_status_response(req, instance_id)

+ return response

+```

+# [v1](#tab/python-v1)

+The entity trigger is configured using the [EntityTriggerAttribute](/dotnet/api/microsoft.azure.webjobs.extensions.durabletask.entitytriggerattribute) .NET attribute.

+> [!NOTE]

+> Entity triggers aren't yet supported for isolated worker process apps.

+The entity trigger is defined by the following JSON object in the `bindings` array of *function.json*:

+By default, the name of an entity is the name of the function.

+> Entity triggers aren't yet supported for Java.

+The way that you define a entity trigger depends on your chosen programming model.

+# [v2](#tab/python-v2)

+Using the `entity_trigger` decorator directly in your Python function code.

+# [v1](#tab/python-v1)

+The entity trigger is defined by the following JSON object in the `bindings` array of *function.json*:

+```json

+{

+ "name": "<Name of input parameter in function signature>",

+ "entityName": "<Optional - name of the entity>",

+ "type": "entityTrigger",

+ "direction": "in"

+}

+```

+You can bind to the entity client by using the [DurableClientAttribute](/dotnet/api/microsoft.azure.webjobs.extensions.durabletask.durableclientattribute) .NET attribute in .NET class library functions.

+The entity client is defined by the following JSON object in the `bindings` array of *function.json*:

+* `taskHub` - Used in scenarios where multiple function apps share the same storage account but need to be isolated from each other. If not specified, the default value from `host.json` is used. This value must match the value used by the target entity functions.

+* `connectionName` - The name of an app setting that contains a storage account connection string. The storage account represented by this connection string must be the same one used by the target entity functions. If not specified, the default storage account connection string for the function app is used.

+> In most cases, we recommend that you omit the optional properties and rely on the default behavior.

+The way that you define a entity client depends on your chosen programming model.

+# [v2](#tab/python-v2)

+Using the `durable_client_input` decorator directly in your Python function code.

+# [v1](#tab/python-v1)

+The entity client is defined by the following JSON object in the `bindings` array of *function.json*:

+```json

+{

+ "name": "<Name of input parameter in function signature>",

+ "taskHub": "<Optional - name of the task hub>",

+ "connectionName": "<Optional - name of the connection string app setting>",

+ "type": "durableClient",

+ "direction": "in"

+}

+```

+> [!NOTE]

+> Entity clients aren't yet supported for Java.

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The examples depend on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+The following example shows an Azure Cosmos DB input binding. The function reads a single document and updates the document's text value.

+# [v2](#tab/python-v2)

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.queue_trigger(arg_name="msg",

+ queue_name="outqueue",

+ connection="AzureWebJobsStorage")

+@app.cosmos_db_input(arg_name="documents",

+ database_name="MyDatabase",

+ collection_name="MyCollection",

+ id="{msg.payload_property}",

+ partition_key="{msg.payload_property}",

+ connection_string_setting="MyAccount_COSMOSDB")

+@app.cosmos_db_output(arg_name="outputDocument",

+ database_name="MyDatabase",

+ collection_name="MyCollection",

+ connection_string_setting="MyAccount_COSMOSDB")

+def test_function(msg: func.QueueMessage,

+ inputDocument: func.DocumentList,

+ outputDocument: func.Out[func.Document]):

+ document = documents[id]

+ document["text"] = "This was updated!"

+ doc = inputDocument[0]

+ doc["text"] = "This was updated!"

+ outputDocument.set(doc)

+ print(f"Updated document.")

+```

+# [v1](#tab/python-v1)

+The following example shows a function that retrieves a single document. The function is triggered by an HTTP request that uses a query string to specify the ID and partition key value to look up. That ID and partition key value are used to retrieve a `ToDoItem` document from the specified database and collection.

+# [v2](#tab/python-v2)

+No equivalent sample for v2 at this time.

+# [v1](#tab/python-v1)

+The following example shows a function that retrieves a single document. The function is triggered by an HTTP request that uses route data to specify the ID and partition key value to look up. That ID and partition key value are used to retrieve a `ToDoItem` document from the specified database and collection.

+# [v2](#tab/python-v2)

+No equivalent sample for v2 at this time.

+# [v1](#tab/python-v1)

+The following example shows an Azure Cosmos DB input binding Python function that uses the binding. The function retrieves multiple documents specified by a SQL query, using a queue trigger to customize the query parameters.

+# [v2](#tab/python-v2)

+No equivalent sample for v2 at this time.

+# [v1](#tab/python-v1)

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using a decorator, the following properties on the `cosmos_db_input`:

+| Property | Description |

+|-|--|

+|`arg_name` | The variable name used in function code that represents the list of documents with changes. |

+|`database_name` | The name of the Azure Cosmos DB database with the collection being monitored. |

+|`collection_name` | The name of the Azure CosmosDB collection being monitored. |

+|`connection_string_setting` | The connection string of the Azure Cosmos DB being monitored. |

+|`partition_key` | The partition key of the Azure Cosmos DB being monitored. |

+|`id` | The ID of the document to retrieve. |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example shows how to write data to Azure Cosmos DB using an output binding. The binding is declared in the function's configuration file (_functions.json_), and takes data from a queue message and writes out to an Azure Cosmos DB document.

+The following example demonstrates how to write a document to an Azure Cosmos DB database as the output of a function. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.route()

+@app.cosmos_db_output(arg_name="documents",

+ database_name="DB_NAME",

+ collection_name="COLLECTION_NAME",

+ create_if_not_exists=True,

+ connection_string_setting="CONNECTION_SETTING")

+def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:

+ request_body = req.get_body()

+ documents.set(func.Document.from_json(request_body))

+ return 'OK'

+```

+# [v1](#tab/python-v1)

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using a decorator, the following properties on the `cosmos_db_output`:

+| Property | Description |

+|-|--|

+|`arg_name` | The variable name used in function code that represents the list of documents with changes. |

+|`database_name` | The name of the Azure Cosmos DB database with the collection being monitored. |

+|`collection_name` | The name of the Azure CosmosDB collection being monitored. |

+|`create_if_not_exists` | A Boolean value that indicates whether the database and collection should be created if they do not exist. |

+|`connection_string_setting` | The connection string of the Azure Cosmos DB being monitored. |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example shows an Azure Cosmos DB trigger binding. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.function_name(name="CosmosDBTrigger")

+@app.cosmos_db_trigger(arg_name="documents",

+ database_name="DB_NAME",

+ collection_name="COLLECTION_NAME",

+ connection_string_setting="CONNECTION_SETTING",

+ lease_collection_name="leases", create_lease_collection_if_not_exists="true")

+def test_function(documents: func.DocumentList) -> str:

+ if documents:

+ logging.info('Document id: %s', documents[0]['id'])

+```

+# [v1](#tab/python-v1)

+The function writes log messages when Azure Cosmos DB records are modified. Here's the binding data in the *function.json* file:

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using a decorator, the following properties on the `cosmos_db_trigger`:

+| Property | Description |

+|-|--|

+|`arg_name` | The variable name used in function code that represents the list of documents with changes. |

+|`database_name` | The name of the Azure Cosmos DB database with the collection being monitored. |

+|`collection_name` | The name of the Azure CosmosDB collection being monitored. |

+|`connection` | The connection string of the Azure Cosmos DB being monitored. |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example shows an event hub trigger binding and a Python function that uses the binding. The function writes a message to an event hub. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.function_name(name="eventhub_output")

+@app.route(route="eventhub_output")

+@app.event_hub_output(arg_name="event",

+ event_hub_name="<EVENT_HUB_NAME>",

+ connection="<CONNECTION_SETTING>")

+def eventhub_output(req: func.HttpRequest, event: func.Out[str]):

+ body = req.get_body()

+ if body is not None:

+ event.set(body.decode('utf-8'))

+ else:

+ logging.info('req body is none')

+ return 'ok'

+```

+# [v1](#tab/python-v1)

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using a decorator, the following properties on the `cosmos_db_trigger`:

+| Property | Description |

+|-|--|

+|`arg_name` | The variable name used in function code that represents the event. |

+|`event_hub_name` | he name of the event hub. When the event hub name is also present in the connection string, that value overrides this property at runtime. |

+|`connection` | The name of an app setting or setting collection that specifies how to connect to Event Hubs. To learn more, see [Connections](#connections). |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example shows a trigger binding and a Python function that uses the binding. The function looks for a `name` parameter either in the query string or the body of the HTTP request. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+```python

+import azure.functions as func

+import logging

+app = func.FunctionApp()

+@app.function_name(name="HttpTrigger1")

+@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)

+def test_function(req: func.HttpRequest) -> func.HttpResponse:

+ logging.info('Python HTTP trigger function processed a request.')

+ return func.HttpResponse(

+ "This HTTP triggered function executed successfully.",

+ status_code=200

+ )

+```

+# [v1](#tab/python-v1)

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using a decorator, the following properties for a trigger are defined in the `route` decorator, which adds HttpTrigger and HttpOutput binding:

+| Property | Description |

+|-|--|

+| `route` | Route for the http endpoint, if None, it will be set to function name if present or user defined python function name. |

+| `trigger_arg_name` | Argument name for HttpRequest, defaults to 'req'. |

+| `binding_arg_name` | Argument name for HttpResponse, defaults to '$return'. |

+| `methods` | A tuple of the HTTP methods to which the function responds. |

+| `auth_level` | Determines what keys, if any, need to be present on the request in order to invoke the function. |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+As an example, the following code defines a `route` property for an HTTP trigger with two parameters, `category` and `id`:

+# [v2](#tab/python-v2)

+```python

+@app.function_name(name="httpTrigger")

+@app.route(route="products/{category:alpha}/{id:int?}")

+```

+# [v1](#tab/python-v1)

+In the *function.json* file:

+```json

+{

+ "bindings": [

+ {

+ "type": "httpTrigger",

+ "name": "req",

+ "direction": "in",

+ "methods": [ "get" ],

+ "route": "products/{category:alpha}/{id:int?}"

+ },

+ {

+ "type": "http",

+ "name": "res",

+ "direction": "out"

+ }

+ ]

+}

+```

+# [v2](#tab/python-v2)

+```python

+@app.table_input(arg_name="product", table_name="products",

+ row_key="{id}", partition_key="products",

+ connection="AzureWebJobsStorage")

+```

+# [v1](#tab/python-v1)

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example demonstrates how to write out to a Service Bus queue in Python. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.route(route="put_message")

+@app.service_bus_topic_output(arg_name="message",

+ connection="<CONNECTION_SETTING>",

+ topic_name="<TOPIC_NAME>")

+def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:

+ input_msg = req.params.get('message')

+ message.set(input_msg)

+ return 'OK'

+```

+# [v1](#tab/python-v1)

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using a decorator, the following properties on the `service_bus_topic_output`:

+| Property | Description |

+|-|--|

+| `arg_name` | The name of the variable that represents the queue or topic message in function code. |

+| `queue_name` | Name of the queue. Set only if sending queue messages, not for a topic. |

+| `topic_name` | Name of the topic. Set only if sending topic messages, not for a queue. |

+| `connection` | The name of an app setting or setting collection that specifies how to connect to Service Bus. See [Connections](#connections). |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example demonstrates how to read a Service Bus queue message via a trigger. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.function_name(name="ServiceBusQueueTrigger1")

+@app.service_bus_queue_trigger(arg_name="msg",

+ queue_name="<QUEUE_NAME>",

+ connection="<CONNECTION_SETTING">)

+def test_function(msg: func.ServiceBusMessage):

+ logging.info('Python ServiceBus queue trigger processed message: %s',

+ msg.get_body().decode('utf-8'))

+```

+# [v1](#tab/python-v1)

+A Service Bus binding is defined in *function.json* where *type* is set to `serviceBusTrigger` and the queue is set by `queueName`.

+The following example demonstrates how to read a Service Bus queue topic via a trigger.

+# [v2](#tab/python-v2)

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.function_name(name="ServiceBusTopicTrigger1")

+@app.service_bus_topic_trigger(arg_name="message",

+ topic_name="TOPIC_NAME",

+ connection="CONNECTION_SETTING",

+ subscription_name="SUBSCRIPTION_NAME")

+def test_function(message: func.ServiceBusMessage):

+ message_body = message.get_body().decode("utf-8")

+ logging.info("Python ServiceBus topic trigger processed message.")

+ logging.info("Message Body: " + message_body)

+```

+# [v1](#tab/python-v1)

+A Service Bus binding is defined in *function.json* where *type* is set to `serviceBusTrigger` and the topic is set by `topicName`.

+```json

+{

+ "scriptFile": "__init__.py",

+ "bindings": [

+   {

+     "type": "serviceBusTrigger",

+     "direction": "in",

+     "name": "msg",

+     "topicName": "inputtopic",

+     "connection": "AzureServiceBusConnectionString"

+   }

+ ]

+}

+```

+The code in *_\_init_\_.py* declares a parameter as `func.ServiceBusMessage`, which allows you to read the topic in your function.

+```python

+import json

+import azure.functions as azf

+def main(msg: azf.ServiceBusMessage) -> str:

+ result = json.dumps({

+ 'message_id': msg.message_id,

+ 'body': msg.get_body().decode('utf-8'),

+ 'content_type': msg.content_type,

+ 'delivery_count': msg.delivery_count,

+ 'expiration_time': (msg.expiration_time.isoformat() if

+ msg.expiration_time else None),

+ 'label': msg.label,

+ 'partition_key': msg.partition_key,

+ 'reply_to': msg.reply_to,

+ 'reply_to_session_id': msg.reply_to_session_id,

+ 'scheduled_enqueue_time': (msg.scheduled_enqueue_time.isoformat() if

+ msg.scheduled_enqueue_time else None),

+ 'session_id': msg.session_id,

+ 'time_to_live': msg.time_to_live,

+ 'to': msg.to,

+ 'user_properties': msg.user_properties,

+ })

+ logging.info(result)

+```

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using a decorator, the following properties on the `service_bus_queue_trigger`:

+| Property | Description |

+|-|--|

+| `arg_name` | The name of the variable that represents the queue or topic message in function code. |

+| `queue_name` | Name of the queue to monitor. Set only if monitoring a queue, not for a topic. |

+| `connection` | The name of an app setting or setting collection that specifies how to connect to Service Bus. See [Connections](#connections). |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example shows blob input and output bindings. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+The code creates a copy of a blob.

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.function_name(name="BlobOutput1")

+@app.route(route="file")

+@app.blob_input(arg_name="inputblob",

+ path="sample-workitems/test.txt",

+ connection="<BLOB_CONNECTION_SETTING>")

+@app.blob_output(arg_name="outputblob",

+ path="newblob/test.txt",

+ connection="<BLOB_CONNECTION_SETTING>")

+def main(req: func.HttpRequest, inputblob: str, outputblob: func.Out[str]):

+ logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')

+ outputblob.set(inputblob)

+ return "ok"

+```

+# [v1](#tab/python-v1)

+The function makes a copy of a blob. The function is triggered by a queue message that contains the name of the blob to copy. The new blob is named *{originalblobname}-Copy*.

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using decorators, the following properties on the `blob_input` and `blob_output` decorators define the Blob Storage triggers:

+| Property | Description |

+|-|--|

+|`arg_name` | The name of the variable that represents the blob in function code. |

+|`path` | The path to the blob For the `blob_input` decorator, it's the blob read. For the `blob_output` decorator, it's the output or copy of the input blob. |

+|`connection` | The storage account connection string. |

+|`data_type` | For dynamically typed languages, specifies the underlying data type. Possible values are `string`, `binary`, or `stream`. For more detail, refer to the [triggers and bindings concepts](functions-triggers-bindings.md?tabs=python#trigger-and-binding-definitions). |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example shows blob input and output bindings. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+The code creates a copy of a blob.

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.function_name(name="BlobOutput1")

+@app.route(route="file")

+@app.blob_input(arg_name="inputblob",

+ path="sample-workitems/test.txt",

+ connection="<BLOB_CONNECTION_SETTING>")

+@app.blob_output(arg_name="outputblob",

+ path="newblob/test.txt",

+ connection="<BLOB_CONNECTION_SETTING>")

+def main(req: func.HttpRequest, inputblob: str, outputblob: func.Out[str]):

+ logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')

+ outputblob.set(inputblob)

+ return "ok"

+```

+# [v1](#tab/python-v1)

+The function makes a copy of a blob. The function is triggered by a queue message that contains the name of the blob to copy. The new blob is named *{originalblobname}-Copy*.

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using decorators, the following properties on the `blob_input` and `blob_output` decorators define the Blob Storage triggers:

+| Property | Description |

+|-|--|

+|`arg_name` | The name of the variable that represents the blob in function code. |

+|`path` | The path to the blob For the `blob_input` decorator, it's the blob read. For the `blob_output` decorator, it's the output or copy of the input blob. |

+|`connection` | The storage account connection string. |

+|`dataType` | For dynamically typed languages, specifies the underlying data type. Possible values are `string`, `binary`, or `stream`. For more detail, refer to the [triggers and bindings concepts](functions-triggers-bindings.md?tabs=python#trigger-and-binding-definitions). |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example shows a blob trigger binding. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.function_name(name="BlobTrigger1")

+@app.blob_trigger(arg_name="myblob",

+ path="PATH/TO/BLOB",

+ connection="CONNECTION_SETTING")

+def test_function(myblob: func.InputStream):

+ logging.info(f"Python blob trigger function processed blob \n"

+ f"Name: {myblob.name}\n"

+ f"Blob Size: {myblob.length} bytes")

+```

+# [v1](#tab/python-v1)

+The function writes a log when a blob is added or updated in the `samples-workitems` [container](../storage/blobs/storage-blobs-introduction.md#blob-storage-resources).

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using decorators, the following properties on the `blob_trigger` decorator define the Blob Storage trigger:

+| Property | Description |

+|-|--|

+|`arg_name` | Declares the parameter name in the function signature. When the function is triggered, this parameter's value has the contents of the queue message. |

+|`path` | The [container](../storage/blobs/storage-blobs-introduction.md#blob-storage-resources) to monitor. May be a [blob name pattern](#blob-name-patterns). |

+|`connection` | The storage account connection string. |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example demonstrates how to output single and multiple values to storage queues. The configuration needed for *function.json* is the same either way. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.function_name(name="QueueOutput1")

+@app.route(route="message")

+@app.queue_output(arg_name="msg",

+ queue_name="<QUEUE_NAME>",

+ connection="<CONNECTION_SETTING>")

+def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

+ input_msg = req.params.get('name')

+ logging.info(input_msg)

+

+ msg.set(input_msg)

+

+ logging.info(f'name: {name}')

+ return 'OK'

+```

+# [v1](#tab/python-v1)

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using a decorator, the following properties on the `queue_output`:

+| Property | Description |

+|-|--|

+| `arg_name` | The name of the variable that represents the queue in function code. |

+| `queue_name` | The name of the queue. |

+| `connection` | The name of an app setting or setting collection that specifies how to connect to Azure Queues. See [Connections](#connections). |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The [section below](#attributes) explains these properties.

+The following example demonstrates how to read a queue message passed to a function via a trigger. The example depends on whether you use the v1 or v2 Python programming model.

+# [v2](#tab/python-v2)

+```python

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.function_name(name="QueueFunc")

+@app.queue_trigger(arg_name="msg", queue_name="inputqueue",

+ connection="storageAccountConnectionString") # Queue trigger

+@app.write_queue(arg_name="outputQueueItem", queue_name="outqueue",

+ connection="storageAccountConnectionString") # Queue output binding

+def test_function(msg: func.QueueMessage,

+ outputQueueItem: func.Out[str]) -> None:

+ logging.info('Python queue trigger function processed a queue item: %s',

+ msg.get_body().decode('utf-8'))

+ outputQueueItem.set('hello')

+```

+# [v1](#tab/python-v1)

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using decorators, the following properties on the `queue_trigger` decorator define the Queue Storage trigger:

+| Property | Description |

+|-|--|

+|`arg_name` | Declares the parameter name in the function signature. When the function is triggered, this parameter's value has the contents of the queue message. |

+|`queue_name` | Declares the queue name in the storage account. |

+|`connection` | Points to the storage account connection string. |

+For Python functions defined by using function.json, see the Configuration section.

+_Applies only to the Python v1 programming model._

+Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

+# [v2](#tab/python-v2)

+The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-decorators#programming-model).

+# [v1](#tab/python-v1)

+The Python v1 programming model requires you to define bindings in a separate *function.json* file in the function folder. For more information, see the [Python developer guide](functions-reference-python.md?pivots=python-mode-configuration#programming-model).

+This article supports both programming models.

+> [!IMPORTANT]

+> The Python v2 programming model is currently in preview.

+The following example shows a timer trigger binding and function code that uses the binding, where an instance representing the timer is passed to the function. The function writes a log indicating whether this function invocation is due to a missed schedule occurrence. The example depends on whether you use the [v1 or v2 Python programming model](functions-reference-python.md).

+# [v2](#tab/python-v2)

+```python

+import datetime

+import logging

+import azure.functions as func

+app = func.FunctionApp()

+@app.function_name(name="mytimer")

+@app.schedule(schedule="0 */5 * * * *",

+ arg_name="mytimer",

+ run_on_startup=True)

+def test_function(mytimer: func.TimerRequest) -> None:

+ utc_timestamp = datetime.datetime.utcnow().replace(

+ tzinfo=datetime.timezone.utc).isoformat()

+ if mytimer.past_due:

+ logging.info('The timer is past due!')

+ logging.info('Python timer trigger function ran at %s', utc_timestamp)

+```

+# [v1](#tab/python-v1)

+## Decorators

+_Applies only to the Python v2 programming model._

+For Python v2 functions defined using a decorator, the following properties on the `schedule`:

+| Property | Description |

+|-|--|

+| `arg_name` | The name of the variable that represents the timer object in function code. |

+| `schedule` | A [CRON expression](#ncrontab-expressions) or a [TimeSpan](#timespan) value. A `TimeSpan` can be used only for a function app that runs on an App Service Plan. You can put the schedule expression in an app setting and set this property to the app setting name wrapped in **%** signs, as in this example: "%ScheduleAppSetting%". |

+| `run_on_startup` | If `true`, the function is invoked when the runtime starts. For example, the runtime starts when the function app wakes up after going idle due to inactivity. when the function app restarts due to function changes, and when the function app scales out. *Use with caution.* **runOnStartup** should rarely if ever be set to `true`, especially in production. |

+| `use_monitor` | Set to `true` or `false` to indicate whether the schedule should be monitored. Schedule monitoring persists schedule occurrences to aid in ensuring the schedule is maintained correctly even when function app instances restart. If not set explicitly, the default is `true` for schedules that have a recurrence interval greater than or equal to 1 minute. For schedules that trigger more than once per minute, the default is `false`. |

+For Python functions defined by using *function.json*, see the [Configuration](#configuration) section.

+_Applies only to the Python v1 programming model._

+This tutorial shows you how to use Azure Functions to connect to resources in an Azure virtual network by using private endpoints. You create a new function app using a new storage account that's locked behind a virtual network via the Azure portal. The virtual network uses a Service Bus queue trigger.

+> * Create a function app in the Elastic Premium plan with virtual network integration and private endpoints.

+> * Create Azure resources, such as the Service Bus

+You create a C# function app in an [Elastic Premium plan](./functions-premium-plan.md), which supports networking capabilities such as virtual network integration on create along with serverless scale. This tutorial uses C# and Windows. Other languages and Linux are also supported.

+ | **[Resource Group](../azure-resource-manager/management/overview.md)** | myResourceGroup | Name for the new resource group where you create your function app. |

+ |**Operating system**| Windows | This tutorial uses Windows but also works for Linux. |

+ | **[Plan](./functions-scale.md)** | Premium | Hosting plan that defines how resources are allocated to your function app. By default, when you select **Premium**, a new App Service plan is created. The default **Sku and size** is **EP1**, where *EP* stands for _elastic premium_. For more information, see the list of [Premium SKUs](./functions-premium-plan.md#available-instance-skus).<br/><br/>When you run JavaScript functions on a Premium plan, choose an instance that has fewer vCPUs. For more information, see [Choose single-core Premium plans](./functions-reference-node.md#considerations-for-javascript-functions). |

+ | **[Storage account](../storage/common/storage-account-create.md)** | Globally unique name | Create a storage account used by your function app. Storage account names must be between 3 and 24 characters long. They may contain numbers and lowercase letters only. You can also use an existing account that isn't restricted by firewall rules and meets the [storage account requirements](./storage-considerations.md#storage-account-requirements). When using Functions with a locked down storage account, a v2 storage account is needed. This is the default storage version created when creating a function app with networking capabilities through the create blade. |

+1. Select **Next: Networking**. On the **Networking** page, enter the following settings.

+ > [!NOTE]

+ > Some of these settings aren't visible until other options are selected.

+ | Setting | Suggested value | Description |

+ | | - | -- |

+ | **Enable network injection** | On | The ability to configure your application with VNet integration at creation appears in the portal window after this option is switched to **On**. |

+ | **Virtual Network** | Create New | Select the **Create New** field. In the pop-out screen, provide a name for your virtual network and select **Ok**. Options to restrict inbound and outbound access to your function app on create are displayed. You must explicitly enable VNet integration in the **Outbound access** portion of the window to restrict outbound access. |

+ Enter the following settings for the **Inbound access** section. This step creates a private endpoint on your function app.

+ > [!TIP]

+ > To continue interacting with your function app from portal, you'll need to add your local computer to the virtual network. If you don't wish to restrict inbound access, skip this step.

+

+ | Setting | Suggested value | Description |

+ | | - | -- |

+ | **Enable private endpoints** | On | The ability to configure your application with VNet integration at creation appears in the portal after this option is enabled. |

+ | **Private endpoint name** | myInboundPrivateEndpointName | Name that identifies your new function app private endpoint. |

+ | **Inbound subnet** | Create New | This option creates a new subnet for your inbound private endpoint. Multiple private endpoints may be added to a singular subnet. Provide a **Subnet Name**. The **Subnet Address Block** may be left at the default value. Select **Ok**. To learn more about subnet sizing, see [Subnets](functions-networking-options.md#subnets). |

+ | **DNS** | Azure Private DNS Zone | This value indicates which DNS server your private endpoint uses. In most cases if you're working within Azure, Azure Private DNS Zone is the DNS zone you should use as using **Manual** for custom DNS zones have increased complexity. |

+

+ Enter the following settings for the **Outbound access** section. This step integrates your function app with a virtual network on creation. It also exposes options to create private endpoints on your storage account and restrict your storage account from network access on create. When function app is vnet integrated, all outbound traffic by default goes [through the vnet.](../app-service/overview-vnet-integration.md#how-regional-virtual-network-integration-works).

+

+ | Setting | Suggested value | Description |

+ | | - | -- |

+ | **Enable VNet Integration** | On | This integrates your function app with a VNet on create and direct all outbound traffic through the VNet. |

+ | **Outbound subnet** | Create new | This creates a new subnet for your function app's VNet integration. A function app can only be VNet integrated with an empty subnet. Provide a **Subnet Name**. The **Subnet Address Block** may be left at the default value. If you wish to configure it, please learn more about Subnet sizing here. Select **Ok**. The option to create **Storage private endpoints** is displayed. To use your function app with virtual networks, you need to join it to a subnet. |

+

+ Enter the following settings for the **Storage private endpoint** section. This step creates private endpoints for the blob, queue, file, and table endpoints on your storage account on create. This effectively integrates your storage account with the VNet.

+

+ | Setting | Suggested value | Description |

+ | | - | -- |

+ | **Add storage private endpoint** | On | The ability to configure your application with VNet integration at creation is displayed in the portal after this option is enabled. |

+ | **Private endpoint name** | myInboundPrivateEndpointName | Name that identifies your storage account private endpoint. |

+ | **Private endpoint subnet** | Create New | This creates a new subnet for your inbound private endpoint on the storage account. Multiple private endpoints may be added to a singular subnet. Provide a **Subnet Name**. The **Subnet Address Block** may be left at the default value. If you wish to configure it, please learn more about Subnet sizing here. Select **Ok**. |

+ | **DNS** | Azure Private DNS Zone | This value indicates which DNS server your private endpoint uses. In most cases if you're working within Azure, Azure Private DNS Zone is the DNS zone you should use as using **Manual** for custom DNS zones will have increased complexity. |

+1. On the **Review + create** page, review your settings. Then select **Create** to create and deploy the function app.

+> [!NOTE]

+> Some deployments may occassionally fail to create the private endpoints in the storage account with the error 'StorageAccountOperationInProgress'. This failure occurs even though the function app itself gets created successfully. When you encounter such an error, delete the function app and retry the operation. You can instead create the private endpoints on the storage account manually.

+Next, you create a Service Bus instance that is used to test the functionality of your function app's network capabilities in this tutorial.

+ | **Subscription** | Your subscription | The subscription in which your resources are created. |

+ | **Namespace name** | myServiceBus| The name of the Service Bus instance for which the private endpoint is enabled. |

+ | **Subscription** | Your subscription | The subscription in which your resources are created. |

+ | **Name** | sb-endpoint | The name of the private endpoint for the service bus. |

+ | **Target subresource** | namespace | The private endpoint that is used for the namespace from the Service Bus. |

+1. On the **Virtual Network** tab, for the **Subnet** setting, choose **default**.

+1. After the private endpoint is created, return to the **Networking** section of your Service Bus namespace and check the **Public Access** tab.

+ | **Virtual networks** | myVirtualNet | The name of the virtual network to which your function app connects. |

+ | **Subnets** | functions | The name of the subnet to which your function app connects. |

+Create the queue where your Azure Functions Service Bus trigger gets events:

+1. Select **RootManageSharedAccessKey**. Copy and save the **Primary Connection String**. You need this connection string when you configure the app settings.

+1. To use your function app with virtual networks and service bus, update the app settings shown in the following table. To add or edit a setting, select **+ New application setting** or the **Edit** icon in the rightmost column of the app settings table. When you finish, select **Save**.

+1. Since you're using an Elastic Premium hosting plan, In the **Configuration** view, select the **Function runtime settings** tab. Set **Runtime Scale Monitoring** to **On**. Then select **Save**. Runtime-driven scaling allows you to connect non-HTTP trigger functions to services that run inside your virtual network.

+> [!NOTE]

+> Runtime scaling isn't needed for function apps hosted in a Dedicated App Service plan.

+> Enabling private endpoints on a function app also makes the Source Control Manager (SCM) site publicly inaccessible. The following instructions give deployment directions using the Deployment Center within the function app. Alternatively, use [zip deploy](functions-deployment-technologies.md#zip-deploy) or [self-hosted](/azure/devops/pipelines/agents/docker) agents that are deployed into a subnet on the virtual network.

+ | **Version** | .NET Core 3.1 | The runtime version. |

+You see that you can't monitor your app. Your browser doesn't have access to the virtual network, so it can't directly access resources within the virtual network.

+- [How to configure Azure Functions with a virtual network](./configure-networking-how-to.md)

+You can host function apps in several ways:

+## Quickstart resources

+ * [Private HTTP triggered function app](https://github.com/Azure-Samples/function-app-with-private-http-endpoint)

+ * [Private Event Hubs triggered function app](https://github.com/Azure-Samples/function-app-with-private-eventhub)

+ * [Function app with Azure Storage private endpoints](https://github.com/Azure/azure-quickstart-templates/tree/master/quickstarts/microsoft.web/function-app-storage-private-endpoints).

+ * [Azure function app with Virtual Network Integration](https://github.com/Azure-Samples/function-app-arm-templates/tree/main/function-app-vnet-integration).

+ * [Integrate Azure Functions with an Azure virtual network by using private endpoints](functions-create-vnet.md)

+Using service endpoints, you can restrict many Azure services to selected virtual network subnets to provide a higher level of security. Regional virtual network integration enables your function app to reach Azure services that are secured with service endpoints. This configuration is supported on all [plans](functions-scale.md#networking-features) that support virtual network integration. To access a service endpoint-secured service, you must do the following:

+If service endpoints aren't already enabled with Microsoft.Web for the subnet that you selected, they are automatically enabled unless you select the **Ignore missing Microsoft.Web service endpoints** check box. The scenario where you might want to enable service endpoints on the app but not the subnet depends mainly on whether you have the permissions to enable them on the subnet.

+If you need someone else to enable service endpoints on the subnet, select the **Ignore missing Microsoft.Web service endpoints** check box. Your app is configured for service endpoints in anticipation of having them enabled later on the subnet.

+1. In your function app in the [Azure portal](https://portal.azure.com), select **Networking**, then under **VNet Integration** select **Click here to configure**.

+ * To select a virtual network in another region, you must have a virtual network gateway provisioned with point to site enabled. Virtual network integration across regions is only supported for Dedicated plans, but global peerings work with regional virtual network integration.

+During the integration, your app is restarted. When integration is finished, you see details on the virtual network you're integrated with. By default, Route All is enabled, and all traffic is routed into your virtual network.

+When you scale up or down in size, the required address space is doubled for a short period of time. This affects the real, available supported instances for a given subnet size. The following table shows both the maximum available addresses per CIDR block and the effect this has on horizontal scale:

+<sup>*</sup>Assumes that you need to scale up or down in either size or SKU at some point.

+> To quickly deploy a function app with private endpoints enabled on the storage account, please refer to the following template: [Function app with Azure Storage private endpoints](https://github.com/Azure/azure-quickstart-templates/tree/master/quickstarts/microsoft.web/function-app-storage-private-endpoints).

+[privateendpoints]: ../app-service/networking/private-endpoint.md

+| Elevation service ([deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023)) | 50 | 50 | Not Available |

+| Render service - Contour tiles, Digital Elevation Model (DEM) tiles ([deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023)) and Customer tiles | 50 | 50 | Not Available |

+For a guide on how to prepare your drawing package, see [Drawing Package Guide].

+For a guide on how to prepare your drawing package, see the drawing package guide.

+The Azure Maps Java SDK can be integrated with Java applications and libraries to build maps-related and location-aware applications. The Azure Maps Java SDK contains APIs for Search, Route, Render, Geolocation, Traffic, Timezone, and Weather. These APIs support operations such as searching for an address, routing between different coordinates, obtaining the geo-location of a specific IP address etc.

+| [Elevation][java elevation readme] ([deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023))| [azure-maps-elevation][java elevation package] | [elevation samples][java elevation sample] |

+> [!IMPORTANT]

+> The Azure Maps Elevation services and Render V2 DEM tiles have been retired and will no longer be available or supported after May 5, 2023. No other Azure Maps API, services or tilesets are affected. For more information, see [Elevation Services Retirement](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023).

+Both Azure and Bing Maps provide access to spatial APIs through REST web services. The API interfaces for these platforms perform similar functionalities but use different naming conventions and response objects. This tutorial demonstrates how to:

+| Bing Maps service API | Azure Maps service API |

+||-|

+| Autosuggest | [Search] |

+| Directions (including truck) | [Route directions] |

+| Distance Matrix | [Route Matrix] |

+| Imagery ΓÇô Static Map | [Render] |

+| Isochrones | [Route Range] |

+| Local Insights | [Search] + [Route Range] |

+| Local Search | [Search] |

+| Location Recognition (POIs) | [Search] |

+| Locations (forward/reverse geocoding) | [Search] |

+| Snap to Road | [POST Route directions] |

+| Spatial Data Services (SDS) | [Search] + [Route] + other Azure Services |

+| Time Zone | [Time Zone] |

+| Traffic Incidents | [Traffic Incident Details] |

+| Elevations | <sup>1</sup> |

+<sup>1</sup> Azure Maps [Elevation services](/rest/api/maps/elevation) have been [deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023). For more information how to include this functionality in your Azure Maps, see [Create elevation data & services](elevation-data-services.md).

+The following service APIs aren't currently available in Azure Maps:

+* Azure Maps [Elevation services](/rest/api/maps/elevation) have been [deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023). For more information how to include this functionality in your Azure Maps, see [Create elevation data & services](elevation-data-services.md)

+Azure Maps also has these REST web

+* [Azure Maps Creator] ΓÇô Create a custom private digital twin of buildings and spaces.

+* [Spatial operations] ΓÇô Offload complex spatial calculations and operations, such as geofencing, to a service.

+* [Map Tiles] ΓÇô Access road and imagery tiles from Azure Maps as raster and vector tiles.

+* [Batch routing] ΓÇô Allows up to 1,000 route requests to be made in a single batch over a period of time. Routes are calculated in parallel on the server for faster processing.

+* [Traffic] Flow ΓÇô Access real-time traffic flow data as both raster and vector tiles.

+* [Geolocation API] ΓÇô Get the location of an IP address.

+* [Weather services] ΓÇô Gain access to real-time and forecast weather data.

+* [Best practices for Azure Maps Search service]

+* [Best practices for Azure Maps Route service]

+If you don't have an Azure subscription, create a [free account] before you begin.

+> For more information on authentication in Azure Maps, see [manage authentication in Azure Maps].

+Azure Maps provides several methods for geocoding addresses:

+* [Free-form address geocoding]: Specify a single address string (like `"1 Microsoft way, Redmond, WA"`) and process the request immediately. This service is recommended if you need to geocode individual addresses quickly.

+* [Structured address geocoding]: Specify the parts of a single address, such as the street name, city, country, and postal code and process the request immediately. This service is recommended if you need to geocode individual addresses quickly and the data is already parsed into its individual address parts.

+* [Batch address geocoding]: Create a request containing up to 10,000 addresses and have them processed over a period of time. All the addresses are geocoded in parallel on the server and when completed the full result set can be downloaded. This service is recommended for geocoding large data sets.

+* [Fuzzy search]: This API combines address geocoding with point of interest search. This API takes in a free-form string that can be an address, place, landmark, point of interest, or point of interest category and process the request immediately. This API is recommended for applications where users can search for addresses or points of interest from the same textbox.

+* [Fuzzy batch search]: Create a request containing up to 10,000 addresses, places, landmarks, or point of interests and have them processed over a period of time. All the data is processed in parallel on the server and when completed the full result set can be downloaded.

+| Bing Maps API parameter | Comparable Azure Maps API parameter |

+|-|--|

+| `addressLine` | `streetNumber`, `streetName` or `crossStreet` |

+| `adminDistrict` | `countrySubdivision` |

+| `countryRegion` | `country` and `countryCode` |

+| `locality` | `municipality` or `municipalitySubdivision` |

+| `postalCode` | `postalCode` |

+| `maxResults` (`maxRes`) | `limit` |

+| `key` | `subscription-key` ΓÇô For more information, see [Authentication with Azure Maps]. |

+| `culture` (`c`) | `language` ΓÇô For more information, see [Localization support in Azure Maps]. |

+| `userRegion` (`ur`) | `view` ΓÇô For more information, see [Azure Maps supported views]. |

+Azure Maps also supports:

+* `countryTertiarySubdivision` - Named areas, boroughs, cantons, communes

+| Bing Maps API parameter | Comparable Azure Maps API parameter |

+|-||

+| `query` | `query` |

+| `maxResults` (`maxRes`) | `limit` |

+| `key` | `subscription-key` ΓÇô For more information, see [Authentication with Azure Maps]. |

+| `culture` (`c`) | `language` ΓÇô For more information, see [Localization support in Azure Maps]. |

+| `userRegion` (`ur`) | `view` ΓÇô For more information, see [Azure Maps supported views]. |

+Azure Maps also supports:

+* `typeahead` - Specifies if the query is interpreted as a partial input and the search enters predictive mode (autosuggest/autocomplete).

+For more information on using the search service, see [Search for a location using Azure Maps Search services] and [Best practices for Azure Maps Search service].

+Azure Maps provides several reverse geocoding methods:

+* [Address reverse geocoder]: Specify a single geographic coordinate to get its approximate address and process the request immediately.

+* [Cross street reverse geocoder]: Specify a single geographic coordinate to get nearby cross street information (for example, 1st & main) and process the request immediately.

+* [Batch address reverse geocoder]: Create a request containing up to 10,000 coordinates and have them processed over a period of time. All the data is processed in parallel on the server and when completed the full result set can be downloaded.

+| Bing Maps API parameter | Comparable Azure Maps API parameter |

+|--|-|

+| `point` | `query` |

+| `includeEntityTypes` | `entityType` ΓÇô See entity type comparison table below.|

+| `includeNeighborhood` (`inclnb`) | N/A ΓÇô Always returned by Azure Maps if available. |

+| `include` (`incl`) | N/A ΓÇô Country ISO2 Code always returned by Azure Maps.|

+| `key` | `subscription-key` ΓÇô For more information, see [Authentication with Azure Maps]. |

+| `culture` (`c`) | `language` ΓÇô For more information, see [Localization support in Azure Maps]. |

+| `userRegion` (`ur`) | `view` ΓÇô For more information, see [Azure Maps supported views]. |

+For more information on searching in Azure Maps, see [Best practices for Azure Maps Search service].

+The Azure Maps reverse geocoding API has features not available in Bing Maps that might be useful to integrate when migrating your app:

+* Retrieve road use information, local road, arterial, limited access, ramp, etc.

+| Bing Maps Entity Type | Comparable Azure Maps Entity type | Description |

+|--||-|

+| `Address` | | *Address* |

+| `Neighborhood` | `Neighbourhood` | *Neighborhood* |

+| `PopulatedPlace` | `Municipality` or `MunicipalitySubdivision` | *City*, *Town or Sub*, or *Super City* |

+| `Postcode1` | `PostalCodeArea` | *Postal Code* or *Zip Code* |

+| `AdminDivision1` | `CountrySubdivision` | *State* or *Province* |

+| `AdminDivision2` | `CountrySecondarySubdivison` | *County* or *districts* |

+| `CountryRegion` | `Country` | *Country name* |

+| | `CountryTertiarySubdivision` | *Boroughs*, *Cantons*, *Communes* |

+Several of the Azure Maps search APIΓÇÖs support predictive mode that can be used for autosuggest scenarios. The Azure Maps [fuzzy search] API is the most like the Bing Maps Autosuggest API. The following APIs also support predictive mode, add `&typeahead=true` to the query:

+* [Free-form address geocoding]: Specify a single address string (like `"1 Microsoft way, Redmond, WA"`) and process the request immediately. This service is recommended if you need to geocode individual addresses quickly.

+* [Fuzzy search]: This API combines address geocoding with point of interest search. This API takes in a free-form string that can be an address, place, landmark, point of interest, or point of interest category and process the request immediately. This API is recommended for applications where users can search for addresses or points of interest from the same textbox.

+* [POI search]: Search for points of interests by name. For example, `"starbucks"`.

+* [POI category search]: Search for points of interests by category. For example, "restaurant".

+Azure Maps can be used to calculate routes and directions. Azure Maps has many of the same functionalities as the Bing Maps routing service, such as:

+* different modes of transportation, driving, walking, truck

+The Azure Maps routing service provides the following APIs for calculating routes:

+* [Calculate route]: Calculate a route and have the request processed immediately. This API supports both `GET` and `POST` requests. `POST` requests are recommended when specifying a large number of waypoints or when using lots of the route options to ensure that the URL request doesnΓÇÖt become too long and cause issues.

+* [Batch route]: Create a request containing up to 1,000 route request and have them processed over a period of time. All the data is processed in parallel on the server and when completed the full result set can be downloaded.

+| Bing Maps API parameter | Comparable Azure Maps API parameter |

+|-||

+| `avoid` | `avoid` |

+| `dateTime` (`dt`) | `departAt` or `arriveAt` |

+| `distanceBeforeFirstTurn` (`dbft`) | N/A |

+| `distanceUnit` (`du`) | N/A ΓÇô Azure Maps only uses the metric system. |

+| `heading` (`hd`) | `vehicleHeading` |

+| `maxSolutions` (`maxSolns`) | `maxAlternatives`, `alternativeType`, `minDeviationDistance`, and `minDeviationTime` |

+| `optimize` (`optwz`) | `routeType` and `traffic` |

+| `optimizeWaypoints` (`optWp`) | `computeBestOrder` |

+| `routeAttributes` (`ra`) | `instructionsType` |

+| `routePathOutput` (`rpo`) | `routeRepresentation` |

+| `timeType` (`tt`) | `departAt` or `arriveAt` |

+| `tolerances` (`tl`) | N/A |

+| `travelMode` | `travelMode` |

+| `waypoint.n` (`wp.n`) or `viaWaypoint.n` (`vwp.n`) | `query` – coordinates in the format `lat0,lon0:lat1,lon1….` |

+| `key` | `subscription-key` ΓÇô For more information, see [Authentication with Azure Maps]. |

+| `culture` (`c`) | `language` ΓÇô For more information, see [Localization support in Azure Maps]. |

+| `userRegion` (`ur`) | `view` ΓÇô For more information, see [Azure Maps supported views]. |

+For more information on the Azure Maps route API, see [Best practices for Azure Maps Route service].

+The Azure Maps routing API has features not available in Bing Maps that might be useful to integrate when migrating your app:

+* Support for more travel modes: bicycle, bus, motorcycle, taxi, truck, and van.

+* Compute multiple travel times in a single request, historic traffic, live traffic, no traffic.

+Azure Maps can snap coordinates to roads by using the [route directions] API. This service can be used to reconstruct a logical route between a set of coordinates and is comparable to the Bing Maps Snap to Road API.

+* If there are 150 coordinates or less, they can be passed as waypoints in the `GET` route directions API. Using this approach two different types of snapped data can be retrieved; route instructions contain the individual snapped waypoints, while the route path has an interpolated set of coordinates that fill the full path between the coordinates.

+* If there are more than 150 coordinates, the `POST` route directions API can be used. The coordinates start and end coordinates have to be passed into the query parameter, but all coordinates can be passed into the `supportingPoints` parameter in the body of the `POST` request and formatted a GeoJSON geometry collection of points. The only snapped data available using this approach is the route path that is an interpolated set of coordinates that fill the full path between the coordinates. To see an example of this approach using the services module in the Azure Maps Web SDK, see the [Snap points to logical route path] sample in the Azure Maps samples.

+| `points` | `supportingPoints` ΓÇô pass these points into the body of the `POST` request |

+| `key` | `subscription-key` ΓÇô For more information, see [Authentication with Azure Maps]. |

+| `culture` (`c`) | `language` ΓÇô For more information, see [Localization support in Azure Maps]. |

+| `userRegion` (`ur`) | `view` ΓÇô For more information, see [Azure Maps supported views]. |

+The Azure Maps route directions API doesn't currently return speed limit data, however that can be retrieved using the Azure Maps reverse geocoding API.

+The Azure Maps Web SDK uses vector tiles to render the maps. These vector tiles contain the raw road geometry information and can be used to calculate the nearest road to a coordinate for simple snapping of individual coordinates. This is useful when you want the coordinates to visually appear over roads and you're already using the Azure Maps Web SDK to visualize the data.

+This approach however will only snap to the road segments that are loaded within the map view. When zoomed out at country level there may be no road data, so snapping canΓÇÖt be done, however at that zoom level a single pixel can represent the area of several city blocks so snapping isnΓÇÖt needed. To address this, the snapping logic can be applied every time the map has finished moving. To see a fully functional example of this snapping logic, see the [Basic snap to road logic] sample in the Azure Maps samples.

+The Azure Maps vector tiles contain the raw road geometry data that can be used to calculate the nearest point on a road to a coordinate to do basic snapping of individual coordinates. All road segments appear in the sectors at zoom level 15, so you want to retrieve tiles from there. You can then use the [quadtree tile pyramid math] to determine that tiles are needed and convert the tiles to geometries. From there a spatial math library, such as [turf js] or [NetTopologySuite] can be used to calculate the closest line segments.

+Azure Maps provides an API for rendering the static map images with data overlaid. The Azure Maps [Map image render] API is comparable to the static map API in Bing Maps.

+> Azure Maps requires the center, all pushpins and path locations to be coordinates in `longitude,latitude` format whereas Bing Maps uses the `latitude,longitude` format. Addresses will need to be geocoded first.

+| `imagerySet` | `layer` and `style` ΓÇô For more information, see [Supported map styles].|

+| `key` | `subscription-key` ΓÇô For more information, see [Authentication with Azure Maps]. |

+| `culture` (`c`) | `language` ΓÇô For more information, see [Localization support in Azure Maps]. |

+| `userRegion` (`ur`) | `view` ΓÇô For more information, see [Azure Maps supported views]. |

+For more information, see [Render custom data on a raster map].

+In addition to being able to generate a static map image, the Azure Maps render service also enables direct access to map tiles in raster (PNG) and vector format:

+* [Map tiles] ΓÇô Retrieve raster (PNG) and vector tiles for the base maps (roads, boundaries, background).

+* [Map imagery tile] ΓÇô Retrieve aerial and satellite imagery tiles.

+Pushpins can be added by adding more `pushpin` parameters to the URL with a different set of values. Pushpin icon styles are limited to one of the predefined styles available in the Bing Maps API.

+Additional styles can be used by adding more `pins` parameters to the URL with a different style and set of locations.

+Regarding pin locations, Azure Maps requires the coordinates to be in `longitude latitude` format whereas Bing Maps uses `latitude,longitude` format. Also note that **there is a space, not a comma** separating longitude and latitude in Azure Maps.

+* `none` ΓÇô No icon is displayed, only labels are rendered.

+Pin styles in Azure Maps are added with the format `optionNameValue`, with multiple styles separated by pipe (`|`) characters like this `iconType|optionName1Value1|optionName2Value2`. Note the option names and values aren't separated. The following style option names can be used to style pushpins in Azure Maps:

+More styles can be used by adding additional `drawCurve` parameters to the URL with a different style and set of locations.

+When it comes to path locations, Azure Maps requires the coordinates to be in `longitude latitude` format whereas Bing Maps uses `latitude,longitude` format. Also note that **there is a space, not a comma separating** longitude and latitude in Azure Maps. Azure Maps doesn't support encoded paths currently. Larger data sets can be uploaded as a GeoJSON fills into the Azure Maps Data Storage API. For more information, see [Upload pins and path data](./how-to-render-custom-data.md#upload-pins-and-path-data).

+Path styles in Azure Maps are added with the format `optionNameValue`, with multiple styles separated by pipe (`|`) characters like this `optionName1Value1|optionName2Value2`. Note the option names and values aren't separated. The following style option names can be used to style paths in Azure Maps:

+Azure Maps provides an API for calculating the travel times and distances between a set of locations as a distance matrix. The Azure Maps distance matrix API is comparable to the distance matrix API in Bing Maps:

+* [Route matrix]: Asynchronously calculates travel times and distances for a set of origins and destinations. Up to 700 cells per request is supported (the number of origins multiplied by the number of destinations). With that constraint in mind, examples of possible matrix dimensions are: `700x1`, `50x10`, `10x10`, `28x25`, `10x70`.

+> A request to the distance matrix API can only be made using a `POST` request with the origin and destination information in the body of the request. Additionally, Azure Maps requires all origins and destinations to be coordinates. Addresses will need to be geocoded first.

+| `origins` | `origins` ΓÇô specify in the `POST` request body as GeoJSON. |

+| `destinations` | `destination` ΓÇô specify in the `POST` request body as GeoJSON.|

+| `key` | `subscription-key` ΓÇô For more information, see [Authentication with Azure Maps]. |

+| `culture` (`c`) | `language` ΓÇô For more information, see [Localization support in Azure Maps]. |

+| `userRegion` (`ur`) | `view` ΓÇô For more information, see [Azure Maps supported views]. |

+Azure Maps provides an API for calculating an isochrone, a polygon covering an area that can be traveled to in any direction from an origin point within a specified amount of time or amount of fuel/charge. The Azure Maps route range API is comparable to the isochrone API in Bing Maps.

+* [Route] Range: Calculate a polygon covering an area that can be traveled to in any direction from an origin point within a specified amount of time, distance, or amount of fuel/charge available.

+| `key` | `subscription-key` ΓÇô For more information, see [Authentication with Azure Maps]. |

+| `culture` (`c`) | `language` ΓÇô For more information, see [Localization support in Azure Maps]. |

+| `userRegion` (`ur`) | `view` ΓÇô For more information, see [Azure Maps supported views]. |

+* **Local search**: Searches for points of interest that are nearby (radial search), by name, or by entity type (category). The Azure Maps [POI search] and [POI category search] APIs are most like this API.

+* **Location recognition**: Searches for points of interests that are within a certain distance of a location. The Azure Maps [nearby search] API is most like this API.

+* **Local insights**: Searches for points of interests that are within a specified maximum driving time or distance from a specific coordinate. This is achievable with Azure Maps by first calculating an isochrone and then passing it into the [Search within geometry] API.

+* [POI search]: Search for points of interests by name. For example, `"starbucks"`.

+* [POI category search]: Search for points of interests by category. For example, "restaurant".

+* [Search within geometry]: Searches for points of interests that are within a certain distance of a location.

+* [Fuzzy search]: This API combines address geocoding with point of interest search. This API takes in a free-form string that can be an address, place, landmark, point of interest, or point of interest category and process the request immediately. This API is recommended for applications where users can search for addresses or points of interest from the same textbox.

+* [Search within geometry]: Search for points of interests that are within a specified geometry (polygon).

+* [Search along route]: Search for points of interests that are along a specified route path.

+* [Fuzzy batch search]: Create a request containing up to 10,000 addresses, places, landmarks, or point of interests and have them processed over a period of time. All the data is processed in parallel on the server and when completed the full result set can be downloaded.

+For more information on searching in Azure Maps, see [Best practices for Azure Maps Search service].

+Azure Maps provides several APIs for retrieving traffic data. There are two types of traffic data available:

+Traffic data is also integrated into the Azure Maps interactive map controls. Azure maps also provides the following traffic services APIs:

+* [Traffic flow segments]: Provides information about the speeds and travel times of the road fragment closest to the given coordinates.

+* [Traffic flow tiles]: Provides raster and vector tiles containing traffic flow data. These

+* [Traffic incident details]: Provides traffic incident details that are within a bounding box, zoom level, and traffic model.

+* [Traffic incident tiles]: Provides raster and vector tiles containing traffic incident data.

+* [Traffic incident viewport]: Retrieves the legal and technical information for the viewport described in the request, such as the traffic model ID.

+| `key` | `subscription-key` ΓÇô For more information, see [Authentication with Azure Maps]. |

+| `culture` (`c`) | `language` ΓÇô For more information, see [Localization support in Azure Maps]. |

+| `userRegion` (`ur`) | `view` ΓÇô For more information, see [Azure Maps supported views]. |

+Azure Maps provides an API for retrieving the time zone a coordinate is in. The Azure Maps time zone API is comparable to the time zone API in Bing Maps.

+* [Time zone by coordinate]: Specify a coordinate and get the details for the time zone it falls in.

+| `key` | `subscription-key` ΓÇô For more information, see [Authentication with Azure Maps]. |

+| `culture` (`c`) | `language` ΓÇô For more information, see [Localization support in Azure Maps]. |

+| `userRegion` (`ur`) | `view` ΓÇô For more information, see [Azure Maps supported views]. |

+In addition to this the Azure Maps platform also provides many other time zone APIs to help with conversions with time zone names and IDs:

+* [Time zone by ID]: Returns current, historical, and future time zone information for the specified IANA time zone ID.

+* [Time zone Enum IANA]: Returns a full list of IANA time zone IDs. Updates to the IANA service are reflected in the system within one day.

+* [Time zone Enum Windows]: Returns a full list of Windows Time Zone IDs.

+* [Time zone IANA version]: Returns the current IANA version number used by Azure Maps.

+* [Time zone Windows to IANA]: Returns a corresponding IANA ID, given a valid Windows Time Zone ID. Multiple IANA IDs may be returned for a single Windows ID.

+Azure Maps has a batch geocoding service, however it allows up to 10,000 addresses to be passed in a single request and is processed over seconds to a few minutes depending on the size of the data set and the load on the service. Each address in the request generated a transaction. In Azure Maps, the batch geocoding service is only available the Gen 2 or S1 pricing tier. For more information on pricing tiers, see [Choose the right pricing tier in Azure Maps].

+Another option for geocoding a large number addresses with Azure Maps is to make parallel requests to the standard search APIs. These services only accept a single address per request but can be used with the S0 tier that also provides free usage limits. The S0 tier allows up to 50 requests per second to the Azure Maps platform from a single account. So if you process limit these to stay within that limit, it's possible to geocode upwards of 180,000 address an hour. The Gen 2 or S1 pricing tier doesnΓÇÖt have a documented limit on the number of queries per second that can be made from an account, so a lot more data can be processed faster when using that pricing tier, however using the batch geocoding service helps reduce the total amount of data transferred, reducing network traffic.

+* [Free-form address geocoding]: Specify a single address string (like `"1 Microsoft way, Redmond, WA"`) and process the request immediately. This service is recommended if you need to geocode individual addresses quickly.

+* [Structured address geocoding]: Specify the parts of a single address, such as the street name, city, country, and postal code and process the request immediately. This service is recommended if you need to geocode individual addresses quickly and the data is already parsed into its individual address parts.

+* [Batch address geocoding]: Create a request containing up to 10,000 addresses and have them processed over a period of time. All the addresses are geocoded in parallel on the server and when completed the full result set can be downloaded. This service is recommended for geocoding large data sets.

+* [Fuzzy search]: This API combines address geocoding with point of interest search. This API takes in a free-form string that can be an address, place, landmark, point of interest, or point of interest category and process the request immediately. This API is recommended for applications where users can search for addresses or points of interest from the same textbox.

+* **[Fuzzy batch search]**: Create a request containing up to 10,000 addresses, places, landmarks, or point of interests and have them processed over a period of time. All the data is processed in parallel on the server and when completed the full result set can be downloaded.

+In Bing Maps, administrative boundaries for countries, states, counties, cities, and postal codes are made available via the Geodata API. This API takes in either a coordinate or query to geocode. If a query is passed in, it's geocoded and the coordinates from the first result is used. This API takes the coordinates and retrieves the boundary of the specified entity type that intersects the coordinate. This API didn't necessarily return the boundary for the query that was passed in. If a query for `"Seattle, WA"` is passed in, but the entity type value is set to country region, the boundary for the USA would be returned.

+Azure Maps also provides access to administrative boundaries (countries, states, counties, cities, and postal codes). To retrieve a boundary, you must query one of the search APIs for the boundary you want (such as `Seattle, WA`). If the search result has an associated boundary, a geometry ID is provided in the result response. The search polygon API can then be used to retrieve the exact boundaries for one or more geometry IDs. This is a bit different than Bing Maps as Azure Maps returns the boundary for what was searched for, whereas Bing Maps returns a boundary for a specified entity type at a specified coordinate. Additionally, the boundary data returned by Azure Maps is in GeoJSON format.

+ * [Free-form address geocoding]

+ * [Structured address geocoding]

+ * [Batch address geocoding]

+ * [Fuzzy search]

+ * [Fuzzy batch search]

+1. If the desired result(s) has a geometry ID(s), pass it into the [Search Polygon API].

+The spatial data services in Bing Maps provide simple spatial data storage solution for hosting business data and exposing it as a spatial REST service. This service provides four main queries; find by property, find nearby, find in bounding box, and find with 1 mile of a route. Many companies who use this service, often already have their business data already stored in a database somewhere and have been uploading a small subset of it into this service to power applications like store locators. Since key-based authentication provides basic security, it has been recommended that this service be used only with public facing data.

+Most business location data starts off in a database. As such it's recommended to use existing Azure storage solutions such as Azure SQL or Azure PostgreSQL (with the PostGIS plugin). Both of these storage solutions support spatial data and provide a rich set of spatial querying capabilities. Once your data is in a suitable storage solution, it can then be integrated into your application by creating a custom web service, or by using a framework such as ASP.NET or Entity Framework. Using this approach is more secure and provides more querying capabilities.

+* [Azure SQL Spatial Data Types overview]

+* [Azure SQL Spatial ΓÇô Query nearest neighbor]

+* [Azure Cosmos DB geospatial capabilities overview]

+Azure Maps provides client libraries for the following programming languages:

+Open-source client libraries for other programming languages:

+[Search]: /rest/api/maps/search

+[Route directions]: /rest/api/maps/route/getroutedirections

+[Route Matrix]: /rest/api/maps/route/postroutematrixpreview

+[Render]: /rest/api/maps/render/getmapimage

+[Route Range]: /rest/api/maps/route/getrouterange

+[POST Route directions]: /rest/api/maps/route/postroutedirections

+[Route]: /rest/api/maps/route

+[Time Zone]: /rest/api/maps/timezone

+[Elevation]: /rest/api/maps/elevation

+[Azure Maps Creator]: creator-indoor-maps.md

+[Spatial operations]: /rest/api/maps/spatial

+[Map Tiles]: /rest/api/maps/render/getmaptile

+[Map imagery tile]: /rest/api/maps/render/getmapimagerytile

+[Batch routing]: /rest/api/maps/route/postroutedirectionsbatchpreview

+[Traffic]: /rest/api/maps/traffic

+[Geolocation API]: /rest/api/maps/geolocation/get-ip-to-location

+[Weather services]: /rest/api/maps/weather

+[Best practices for Azure Maps Search service]: how-to-use-best-practices-for-search.md

+[Best practices for Azure Maps Route service]: how-to-use-best-practices-for-routing.md

+[free account]: https://azure.microsoft.com/free/?azure-portal=true

+[manage authentication in Azure Maps]: how-to-manage-authentication.md

+[Free-form address geocoding]: /rest/api/maps/search/getsearchaddress

+[Structured address geocoding]: /rest/api/maps/search/getsearchaddressstructured

+[Batch address geocoding]: /rest/api/maps/search/postsearchaddressbatchpreview

+[Fuzzy search]: /rest/api/maps/search/getsearchfuzzy

+[Fuzzy batch search]: /rest/api/maps/search/postsearchfuzzybatchpreview

+[Authentication with Azure Maps]: azure-maps-authentication.md

+[Localization support in Azure Maps]: supported-languages.md

+[Azure Maps supported views]: supported-languages.md#azure-maps-supported-views

+[Address reverse geocoder]: /rest/api/maps/search/getsearchaddressreverse

+[Cross street reverse geocoder]: /rest/api/maps/search/getsearchaddressreversecrossstreet

+[Batch address reverse geocoder]: /rest/api/maps/search/postsearchaddressreversebatchpreview

+[POI search]: /rest/api/maps/search/get-search-poi

+[POI category search]: /rest/api/maps/search/get-search-poi-category

+[Calculate route]: /rest/api/maps/route/getroutedirections

+[Batch route]: /rest/api/maps/route/postroutedirectionsbatchpreview

+[Snap points to logical route path]: https://samples.azuremaps.com/?sample=snap-points-to-logical-route-path?azure-portal=true

+[Basic snap to road logic]: https://samples.azuremaps.com/?sample=basic-snap-to-road-logic?azure-portal=true

+[quadtree tile pyramid math]: zoom-levels-and-tile-grid.md

+[turf js]: https://turfjs.org?azure-portal=true

+[NetTopologySuite]: https://github.com/NetTopologySuite/NetTopologySuite?azure-portal=true

+[Map image render]: /rest/api/maps/render/getmapimagerytile

+[Supported map styles]: supported-map-styles.md

+[Render custom data on a raster map]: how-to-render-custom-data.md

+[Search along route]: /rest/api/maps/search/postsearchalongroute

+[Search within geometry]: /rest/api/maps/search/postsearchinsidegeometry

+[nearby search]: /rest/api/maps/search/getsearchnearby

+[Search Polygon API]: /rest/api/maps/search/getsearchpolygon

+[Search for a location using Azure Maps Search services]: how-to-search-for-address.md

+[Traffic flow segments]: /rest/api/maps/traffic/gettrafficflowsegment

+[Traffic flow tiles]: /rest/api/maps/traffic/gettrafficflowtile

+[Traffic incident details]: /rest/api/maps/traffic/gettrafficincidentdetail

+[Traffic incident tiles]: /rest/api/maps/traffic/gettrafficincidenttile

+[Traffic incident viewport]: /rest/api/maps/traffic/gettrafficincidentviewport

+[Time zone by ID]: /rest/api/maps/timezone/gettimezonebyid

+[Time zone Windows to IANA]: /rest/api/maps/timezone/gettimezonewindowstoiana

+[Time zone Enum IANA]: /rest/api/maps/timezone/gettimezoneenumiana

+[Time zone Enum Windows]: /rest/api/maps/timezone/gettimezoneenumwindows

+[Time zone IANA version]: /rest/api/maps/timezone/gettimezoneianaversion

+[Time zone by coordinate]: /rest/api/maps/timezone/gettimezonebycoordinates

+[Choose the right pricing tier in Azure Maps]: choose-pricing-tier.md

+[Azure SQL Spatial Data Types overview]: /sql/relational-databases/spatial/spatial-data-types-overview

+[Azure SQL Spatial ΓÇô Query nearest neighbor]: /sql/relational-databases/spatial/query-spatial-data-for-nearest-neighbor

+[Azure Cosmos DB geospatial capabilities overview]: ../cosmos-db/sql-query-geospatial-intro.md

+| Elevations | <sup>1</sup> |

+<sup>1</sup> Azure Maps [Elevation services](/rest/api/maps/elevation) have been [deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023). For more information how to include this functionality in your Azure Maps, see [Create elevation data & services](elevation-data-services.md).

+| Elevation service | <sup>1</sup> |

+<sup>1</sup> Azure Maps [Elevation services](/rest/api/maps/elevation) have been [deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023). For more information how to include this functionality in your Azure Maps, see [Create elevation data & services](elevation-data-services.md).

+| Google Maps service API | Azure Maps service API |

+|-|--|

+| Directions | [Route](/rest/api/maps/route) |

+| Distance Matrix | [Route Matrix](/rest/api/maps/route/postroutematrixpreview) |

+| Geocoding | [Search](/rest/api/maps/search) |

+| Places Search | [Search](/rest/api/maps/search) |

+| Place Autocomplete | [Search](/rest/api/maps/search) |

+| Snap to Road | See [Calculate routes and directions](#calculate-routes-and-directions) section. |

+| Speed Limits | See [Reverse geocode a coordinate](#reverse-geocode-a-coordinate) section. |

+| Static Map | [Render](/rest/api/maps/render/getmapimage) |

+| Time Zone | [Time Zone](/rest/api/maps/timezone) |

+| Elevation | [Elevation](/rest/api/maps/elevation)<sup>1</sup> |

+<sup>1</sup> Azure Maps [Elevation services](/rest/api/maps/elevation) have been [deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023). For more information how to include this functionality in your Azure Maps, see [Create elevation data & services](elevation-data-services.md).

+| Elevation | <sup>1</sup> |

+<sup>1</sup> Azure Maps [Elevation services](/rest/api/maps/elevation) have been [deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023). For more information how to include this functionality in your Azure Maps, see [Create elevation data & services](elevation-data-services.md).

+| [Elevation][java elevation readme] ([deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023)) | [azure-maps-elevation][java elevation package] | [elevation samples][java elevation sample] |

+| [Elevation (DEM)](/rest/api/maps/elevation)([deprecated](https://azure.microsoft.com/updates/azure-maps-elevation-apis-and-render-v2-dem-tiles-will-be-retired-on-5-may-2023))| Yes| One request = 2 transactions<br> <ul><li>If requesting elevation for a single point then one request = 1 transaction| <ul><li>Location Insights Elevation (Gen2 pricing)</li><li>Standard S1 Elevation Service Transactions (Gen1 S1 pricing)</li></ul>|

+| [Change Tracking and Inventory Management](../../automation/change-tracking/overview.md) | Public preview | Change Tracking extension | [Change Tracking and Inventory using Azure Monitor Agent](../../automation/change-tracking/overview-monitoring-agent.md) |

+| [Automation Hybrid Runbook Worker overview](../../automation/automation-hybrid-runbook-worker.md) (available without Azure Monitor Agent) | Migrate to Azure Automation Hybrid Worker Extension - Generally available | None | [Migrate an existing Agent based to Extension based Hybrid Workers](../../automation/extension-based-hybrid-runbook-worker-install.md#migrate-an-existing-agent-based-to-extension-based-hybrid-workers) |

+> The Log Analytics agent will be [retired on **August 31, 2024**](https://azure.microsoft.com/updates/were-retiring-the-log-analytics-agent-in-azure-monitor-on-31-august-2024/). If you're currently using the Log Analytics agent with Azure Monitor or [other supported features and services](./agents-overview.md#supported-services-and-features), you should start planning your migration to Azure Monitor Agent by using the information in this article and the availability of other solutions/services.

+ 2. Once data starts flowing via Azure Monitor agent, **compare it with legacy agent data** to ensure there are no gaps. You can do this by joining with the `Category` column in the [Heartbeat](/azure/azure-monitor/reference/tables/heartbeat) table which indicates 'Azure Monitor Agent' for the new data collection.

+3. **Validate** that Azure Monitor Agent is collecting data as expected and all **downstream dependencies**, such as dashboards, alerts, and workbooks, function properly. You can do this by joining with/looking at the `Category` column in the [Heartbeat](/azure/azure-monitor/reference/tables/heartbeat) table which indicates 'Azure Monitor Agent' vs 'Direct Agent' (for legacy).

+> [!NOTE]

+> This article provides specific guidance for installing the Azure Monitor agent on Windows client devices, subject to [limitations below](#limitations). For standard installation and management guidance for the agent, refer [the agent extension management guidance here](./azure-monitor-agent-manage.md)

+## Limitations

+1. The Windows client installer supports latest Windows machines only that are **Azure AD joined** or hybrid Azure AD joined. More information under [prerequisites](#prerequisites) below

+2. The Data Collection rules need can only target the Azure AD tenant scope, i.e. all DCRs associated to the tenant (via Monitored Object) will apply to all Windows client machines within that tenant with the agent installed using this client installer. **Granular targeting using DCRs is not supported** for Windows client devices yet

+3. No support for Windows machines connected via **Azure private links**

+4. The agent installed using the Windows client installer is designed mainly for Windows desktops or workstations that are **always connected**. While the agent can be installed via this method on laptops, it is not optimized for battery consumption and network limitations on a laptop.

+> The agent installed with the client installer currently doesn't support updating local agent settings once it is installed. Uninstall and reinstall AMA to update above settings.

+You need to create a 'Monitored Object' (MO) that creates a representation for the Azure AD tenant within Azure Resource Manager (ARM). This ARM entity is what Data Collection Rules are then associated with. **This Monitored Object needs to be created only once for any number of machines in a single AAD tenant**.

+ - Do store files on the local drive of the machine on which Azure Monitor Agent is running and in the directory that is being monitored.

+ - Do Not rename a file and open a new file with the same name to log to.

+ - Do Not rename or copy large log files in to the monitored directory. If you must, do not exceed 50MB per minute

+description: This article describes the Application Insights telemetry data model including request, dependency, exception, trace, event, metric, PageView, and context.

+[Application Insights](./app-insights-overview.md) sends telemetry from your web application to the Azure portal so that you can analyze the performance and usage of your application. The telemetry model is standardized, so it's possible to create platform- and language-independent monitoring.

+The following types of telemetry are used to monitor the execution of your app. The Application Insights SDK from the web application framework automatically collects these three types:

+You can group requests by logical `name` and define the `source` of this request. Code execution can result in `success` or `fail` and has a certain `duration`. You can further group success and failure executions by using `resultCode`. Start time for the request telemetry is defined on the envelope level.

+This field is the name of the request and it represents the code path taken to process the request. A low cardinality value allows for better grouping of requests. For HTTP requests, it represents the HTTP method and URL path template like `GET /values/{id}` without the actual `id` value.

+**Maximum length:** 1,024 characters

+**Maximum length:** 128 characters

+**Maximum length:** 2,048 characters

+**Maximum length:** 1,024 characters

+**Maximum length:** 1,024 characters

+Success indicates whether a call was successful or unsuccessful. This field is required. When a request isn't set explicitly to `false`, it's considered to be successful. If an exception or returned error result code interrupted the operation, set this value to `false`.

+Partially accepted content `206` might indicate a failure of an overall request. For instance, an Application Insights endpoint might receive a batch of telemetry items as a single request. It returns `206` when some items in the batch weren't processed successfully. An increasing rate of `206` indicates a problem that needs to be investigated. Similar logic applies to `207` Multi-Status, where the success might be the worst of separate response codes.

+Dependency telemetry (in [Application Insights](./app-insights-overview.md)) represents an interaction of the monitored component with a remote component such as SQL or an HTTP endpoint.

+This field is the name of the command initiated with this dependency call. It has a low cardinality value. Examples are stored procedure name and URL path template.

+ID is the identifier of a dependency call instance. It's used for correlation with the request telemetry item that corresponds to this dependency call. For more information, see [Telemetry correlation in Application Insights](./correlation.md).

+This field is the command initiated by this dependency call. Examples are SQL statement and HTTP URL with all query parameters.

+This field is the dependency type name. It has a low cardinality value for logical grouping of dependencies and interpretation of other fields like `commandName` and `resultCode`. Examples are SQL, Azure table, and HTTP.

+This field is the target site of a dependency call. Examples are server name and host address. For more information, see [Telemetry correlation in Application Insights](./correlation.md).

+The request duration is in the format `DD.HH:MM:SS.MMMMMM`. It must be less than `1000` days.

+This field is the result code of a dependency call. Examples are SQL error code and HTTP status code.

+This field is the indication of a successful or unsuccessful call.

+In [Application Insights](./app-insights-overview.md), an instance of exception represents a handled or unhandled exception that occurred during execution of the monitored application.

+### Problem ID

+The problem ID identifies where the exception was thrown in code. It's used for exceptions grouping. Typically, it's a combination of an exception type and a function from the call stack.

+**Maximum length:** 1,024 characters

+This field is the trace severity level. The value can be `Verbose`, `Information`, `Warning`, `Error`, or `Critical`.

+**Maximum length:** 32,768 characters

+**Values:** `Verbose`, `Information`, `Warning`, `Error`, and `Critical`

+You can create event telemetry items (in [Application Insights](./app-insights-overview.md)) to represent an event that occurred in your application. Typically, it's a user interaction such as a button click or an order checkout. It can also be an application lifecycle event like initialization or a configuration update.

+Semantically, events might or might not be correlated to requests. If used properly, event telemetry is more important than requests or traces. Events represent business telemetry and should be subject to separate, less aggressive [sampling](./api-filtering-sampling.md).

+**Event name:** To allow proper grouping and useful metrics, restrict your application so that it generates a few separate event names. For example, don't use a separate name for each generated instance of an event.

+[Application Insights](./app-insights-overview.md) supports two types of metric telemetry: single measurement and preaggregated metric. Single measurement is just a name and value. Preaggregated metric specifies the minimum and maximum value of the metric in the aggregation interval and the standard deviation of it.

+Preaggregated metric telemetry assumes that the aggregation period was one minute.

+Application Insights supports several well-known metric names. These metrics are placed into the `performanceCounters` table.

+The following table shows the metrics that represent system and process counters.

+| .NET name | Platform-agnostic name | Description

+| - | -- | -

+| `\Processor(_Total)\% Processor Time` | Work in progress... | Total machine CPU.

+| `\Memory\Available Bytes` | Work in progress... | Shows the amount of physical memory, in bytes, available to processes running on the computer. It's calculated by summing the amount of space on the zeroed, free, and standby memory lists. Free memory is ready for use. Zeroed memory consists of pages of memory filled with zeros to prevent later processes from seeing data used by a previous process. Standby memory is memory that's been removed from a process's working set (its physical memory) en route to disk but is still available to be recalled. See [Memory Object](/previous-versions/ms804008(v=msdn.10)).

+| `\Process(??APP_WIN32_PROC??)\% Processor Time` | Work in progress... | CPU of the process hosting the application.

+| `\Process(??APP_WIN32_PROC??)\Private Bytes` | Work in progress... | Memory used by the process hosting the application.

+| `\Process(??APP_WIN32_PROC??)\IO Data Bytes/sec` | Work in progress... | Rate of I/O operations run by the process hosting the application.

+| `\ASP.NET Applications(??APP_W3SVC_PROC??)\Requests/Sec` | Work in progress... | Rate of requests processed by an application.

+| `\.NET CLR Exceptions(??APP_CLR_PROC??)\# of Exceps Thrown / sec` | Work in progress... | Rate of exceptions thrown by an application.

+| `\ASP.NET Applications(??APP_W3SVC_PROC??)\Request Execution Time` | Work in progress... | Average request execution time.

+| `\ASP.NET Applications(??APP_W3SVC_PROC??)\Requests In Application Queue` | Work in progress... | Number of requests waiting for the processing in a queue.