+- `2023-12-01-preview` [Swagger spec](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-12-01-preview/inference.json)

+You can make requests using [Azure AI Search](./concepts/use-your-data.md?tabs=ai-search#ingesting-your-data), [Azure Cosmos DB for MongoDB vCore](./concepts/use-your-data.md?tabs=mongo-db#ingesting-your-data), [Azure Machine learning](/azure/machine-learning/overview-what-is-azure-machine-learning), [Pinecone](https://www.pinecone.io/), and [Elasticsearch](https://www.elastic.co/).

+##### Elasticsearch

+```console

+curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \

+-H "Content-Type: application/json" \

+-H "api-key: YOUR_API_KEY" \

+-d \

+{

+ "messages": [

+ {

+ "role": "system",

+ "content": "you are a helpful assistant that talks like a pirate"

+ },

+ {

+ "role": "user",

+ "content": "can you tell me how to care for a parrot?"

+ }

+ ],

+ "dataSources": [

+ {

+ "type": "Elasticsearch",

+ "parameters": {

+ "endpoint": "{search endpoint}",

+ "indexName": "{index name}",

+ "authentication": {

+ "type": "KeyAndKeyId",

+ "key": "{key}",

+ "keyId": "{key id}"

+ }

+ }

+ }

+ ]

+}

+```

+##### Azure Machine Learning

+```console

+curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \

+-H "Content-Type: application/json" \

+-H "api-key: YOUR_API_KEY" \

+-d \

+'

+{

+ "messages": [

+ {

+ "role": "system",

+ "content": "you are a helpful assistant that talks like a pirate"

+ },

+ {

+ "role": "user",

+ "content": "can you tell me how to care for a parrot?"

+ }

+ ],

+ "dataSources": [

+ {

+ "type": "AzureMLIndex",

+ "parameters": {

+ "projectResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.MachineLearningServices/workspaces/{workspace-id}",

+ "name": "my-project",

+ "version": "5"

+ }

+ }

+ ]

+}

+'

+```

+##### Pinecone

+```console

+curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \

+-H "Content-Type: application/json" \

+-H "api-key: YOUR_API_KEY" \

+-d \

+'

+{

+ "messages": [

+ {

+ "role": "system",

+ "content": "you are a helpful assistant that talks like a pirate"

+ },

+ {

+ "role": "user",

+ "content": "can you tell me how to care for a parrot?"

+ }

+ ],

+ "dataSources": [

+ {

+ "type": "Pinecone",

+ "parameters": {

+ "authentication": {

+ "type": "APIKey",

+ "apiKey": "{api key}"

+ },

+ "environment": "{environment name}",

+ "indexName": "{index name}",

+ "embeddingDependency": {

+ "type": "DeploymentName",

+ "deploymentName": "{embedding deployment name}"

+ },

+ "fieldsMapping": {

+ "titleField": "title",

+ "urlField": "url",

+ "filepathField": "filepath",

+ "contentFields": [

+ "content"

+ ],

+ "contentFieldsSeparator": "\n"

+ }

+ }

+ }

+ ]

+}

+'

+```

+| `type` | string | Required | null | The data source to be used for the Azure OpenAI on your data feature. For Azure AI Search the value is `AzureCognitiveSearch`. For Azure Cosmos DB for MongoDB vCore, the value is `AzureCosmosDB`. For Elasticsearch the value is `Elasticsearch`. For Azure Machine Learning, the value is `AzureMLIndex`. For Pinecone, the value is `Pinecone`. |

+### Azure AI Search parameters

+The following parameters are used for Azure AI Search.

+The following parameters are used inside of the `authentication` field, which enables you to use Azure OpenAI [without public network access](./how-to/use-your-data-securely.md).

+| Parameters | Type | Required? | Default | Description |

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

+| `type` | string | Required | null | The authentication type. |

+| `managedIdentityResourceId` | string | Required | null | The resource ID of the user-assigned managed identity to use for authentication. |

+```json

+"authentication": {

+ "type": "UserAssignedManagedIdentity",

+ "managedIdentityResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{resource-name}"

+},

+```

+| `contentFieldsSeparator` | string | Optional | null | The separator for the content fields. Use `\n` by default. |

+The following parameters are used inside of the optional `embeddingDependency` parameter, which contains details of a vectorization source that is based on an internal embeddings model deployment name in the same Azure OpenAI resource.

+| Parameters | Type | Required? | Default | Description |

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

+| `deploymentName` | string | Optional | null | The type of vectorization source to use. |

+| `type` | string | Optional | null | The embedding model deployment name, located within the same Azure OpenAI resource. This enables you to use vector search without an Azure OpenAI API key and without Azure OpenAI public network access. |

+```json

+"embeddingDependency": {

+ "type": "DeploymentName",

+ "deploymentName": "{embedding deployment name}"

+},

+```

+### Azure CosmosDB for MongoDB vCore parameters

+The following parameters are used for Azure Cosmos DB for MongoDB vCore.

+| `fieldsMapping` | dictionary | Required for Azure Cosmos DB for MongoDB vCore. | null | Index data column mapping. When you use Azure Cosmos DB for MongoDB vCore, the value `vectorFields` is required, which indicates the fields that store vectors. |

+The following parameters are used inside of the optional `embeddingDependency` parameter, which contains details of a vectorization source that is based on an internal embeddings model deployment name in the same Azure OpenAI resource.

+| Parameters | Type | Required? | Default | Description |

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

+| `deploymentName` | string | Optional | null | The type of vectorization source to use. |

+| `type` | string | Optional | null | The embedding model deployment name, located within the same Azure OpenAI resource. This enables you to use vector search without an Azure OpenAI API key and without Azure OpenAI public network access. |

+```json

+"embeddingDependency": {

+ "type": "DeploymentName",

+ "deploymentName": "{embedding deployment name}"

+},

+```

+### Elasticsearch parameters

+The following parameters are used for Elasticsearch.

+| Parameters | Type | Required? | Default | Description |

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

+| `endpoint` | string | Required | null | The endpoint for connecting to Elasticsearch. |

+| `indexName` | string | Required | null | The name of the Elasticsearch index. |

+| `type` (found inside of `authentication`) | string | Required | null | The authentication to be used. For Elasticsearch, the value is `KeyAndKeyId`. |

+| `key` (found inside of `authentication`) | string | Required | null | The key used to connect to Elasticsearch. |

+| `keyId` (found inside of `authentication`) | string | Required | null | The key ID to be used. For Elasticsearch. |

+The following parameters are used inside of the `fieldsMapping` field.

+| Parameters | Type | Required? | Default | Description |

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

+| `titleField` | string | Optional | null | The field in your index that contains the original title of each document. |

+| `urlField` | string | Optional | null | The field in your index that contains the original URL of each document. |

+| `filepathField` | string | Optional | null | The field in your index that contains the original file name of each document. |

+| `contentFields` | dictionary | Optional | null | The fields in your index that contain the main text content of each document. |

+| `contentFieldsSeparator` | string | Optional | null | The separator for the content fields. Use `\n` by default. |

+| `vectorFields` | dictionary | Optional | null | The names of fields that represent vector data |

+```json

+"fieldsMapping": {

+ "titleField": "myTitleField",

+ "urlField": "myUrlField",

+ "filepathField": "myFilePathField",

+ "contentFields": [

+ "myContentField"

+ ],

+ "contentFieldsSeparator": "\n",

+ "vectorFields": [

+ "myVectorField"

+ ]

+}

+```

+The following parameters are used inside of the optional `embeddingDependency` parameter, which contains details of a vectorization source that is based on an internal embeddings model deployment name in the same Azure OpenAI resource.

+| Parameters | Type | Required? | Default | Description |

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

+| `deploymentName` | string | Optional | null | The type of vectorization source to use. |

+| `type` | string | Optional | null | The embedding model deployment name, located within the same Azure OpenAI resource. This enables you to use vector search without an Azure OpenAI API key and without Azure OpenAI public network access. |

+```json

+"embeddingDependency": {

+ "type": "DeploymentName",

+ "deploymentName": "{embedding deployment name}"

+},

+```

+### Azure Machine Learning parameters

+The following parameters are used for Azure Machine Learning.

+| Parameters | Type | Required? | Default | Description |

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

+| `projectResourceId` | string | Required | null | The project resource ID. |

+| `name` | string | Required | null | The name of the Azure Machine Learning project name. |

+| `version` (found inside of `authentication`) | string | Required | null | The version of the Azure Machine Learning vector index. |

+The following parameters are used inside of the optional `embeddingDependency` parameter, which contains details of a vectorization source that is based on an internal embeddings model deployment name in the same Azure OpenAI resource.

+| Parameters | Type | Required? | Default | Description |

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

+| `deploymentName` | string | Optional | null | The type of vectorization source to use. |

+| `type` | string | Optional | null | The embedding model deployment name, located within the same Azure OpenAI resource. This enables you to use vector search without an Azure OpenAI API key and without Azure OpenAI public network access. |

+```json

+"embeddingDependency": {

+ "type": "DeploymentName",

+ "deploymentName": "{embedding deployment name}"

+},

+```

+### Pinecone parameters

+The following parameters are used for Pinecone.

+| Parameters | Type | Required? | Default | Description |

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

+| `type` (found inside of `authentication`) | string | Required | null | The authentication to be used. For Pinecone, the value is `APIKey`. |

+| `apiKey` (found inside of `authentication`) | string | Required | null | The API key for Pinecone. |

+| `environment` | string | Required | null | The name of the Pinecone environment. |

+| `indexName` | string | Required | null | The name of the Pinecone index. |

+| `embeddingDependency` | string | Required | null | The embedding dependency for vector search. |

+| `type` (found inside of `embeddingDependency`) | string | Required | null | The type of dependency. For Pinecone the value is `DeploymentName`. |

+| `deploymentName` (found inside of `embeddingDependency`) | string | Required | null | The name of the deployment. |

+| `titleField` (found inside of `fieldsMapping`) | string | Required | null | The name of the index field to use as a title. |

+| `urlField` (found inside of `fieldsMapping`) | string | Required | null | The name of the index field to use as a URL. |

+| `filepathField` (found inside of `fieldsMapping`) | string | Required | null | The name of the index field to use as a file path. |

+| `contentFields` (found inside of `fieldsMapping`) | string | Required | null | The name of the index fields that should be treated as content. |

+| `vectorFields` | dictionary | Optional | null | The names of fields that represent vector data |

+| `contentFieldsSeparator` (found inside of `fieldsMapping`) | string | Required | null | The separator for the your content fields. Use `\n` by default. |

+The following parameters are used inside of the optional `embeddingDependency` parameter, which contains details of a vectorization source that is based on an internal embeddings model deployment name in the same Azure OpenAI resource.

+| Parameters | Type | Required? | Default | Description |

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

+| `deploymentName` | string | Optional | null | The type of vectorization source to use. |

+| `type` | string | Optional | null | The embedding model deployment name, located within the same Azure OpenAI resource. This enables you to use vector search without an Azure OpenAI API key and without Azure OpenAI public network access. |

+```json

+"embeddingDependency": {

+ "type": "DeploymentName",

+ "deploymentName": "{embedding deployment name}"

+},

+```

+To add user consent to the personal voice project, you provide the prerecorded consent audio file [from a publicly accessible URL](#add-consent-from-a-url) (`Consents_Create`) or [upload the audio file](#add-consent-from-a-file) (`Consents_Post`).

+## Add consent from a file

+In this scenario, the audio files must be available locally.

+To add consent to a personal voice project from a local audio file, use the `Consents_Post` operation of the custom voice API. Construct the request body according to the following instructions:

+- Set the required `projectId` property. See [create a project](./personal-voice-create-project.md).

+- Set the required `voiceTalentName` property. The voice talent name can't be changed later.

+- Set the required `companyName` property. The company name can't be changed later.

+- Set the required `audiodata` property with the consent audio file.

+- Set the required `locale` property. This should be the locale of the consent. The locale can't be changed later. You can find the text to speech locale list [here](/azure/ai-services/speech-service/language-support?tabs=tts).

+Make an HTTP POST request using the URI as shown in the following `Consents_Post` example.

+- Replace `YourResourceKey` with your Speech resource key.

+- Replace `YourResourceRegion` with your Speech resource region.

+- Replace `JessicaConsentId` with a consent ID of your choice. The case sensitive ID will be used in the consent's URI and can't be changed later.

+```azurecli-interactive

+curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourResourceKey" -F 'description="Consent for Jessica voice"' -F 'projectId="ProjectId"' -F 'voiceTalentName="Jessica Smith"' -F 'companyName="Contoso"' -F 'audiodata=@"D:\PersonalVoiceTest\jessica-consent.wav"' -F 'locale="en-US"' "https://YourResourceRegion.api.cognitive.microsoft.com/customvoice/consents/JessicaConsentId?api-version=2023-12-01-preview"

+```

+You should receive a response body in the following format:

+```json

+{

+ "id": "JessicaConsentId",

+ "description": "Consent for Jessica voice",

+ "projectId": "ProjectId",

+ "voiceTalentName": "Jessica Smith",

+ "companyName": "Contoso",

+ "locale": "en-US",

+ "status": "NotStarted",

+ "createdDateTime": "2023-04-01T05:30:00.000Z",

+ "lastActionDateTime": "2023-04-02T10:15:30.000Z"

+}

+```

+The response header contains the `Operation-Location` property. Use this URI to get details about the `Consents_Post` operation. Here's an example of the response header:

+```HTTP 201

+Operation-Location: https://eastus.api.cognitive.microsoft.com/customvoice/operations/070f7986-ef17-41d0-ba2b-907f0f28e314?api-version=2023-12-01-preview

+Operation-Id: 070f7986-ef17-41d0-ba2b-907f0f28e314

+```

+In this scenario, the audio files must already be stored in an Azure Blob Storage container.

+> [!NOTE]

+> The personal voice ID and speaker profile ID aren't same. You can choose the personal voice ID, but the speaker profile ID is generated by the service. The personal voice ID is used to manage the personal voice. The speaker profile ID is used for text to speech.

+You provide the audio files [from a publicly accessible URL](#create-personal-voice-from-a-url) (`PersonalVoices_Create`) or [upload the audio files](#create-personal-voice-from-a-file) (`PersonalVoices_Post`).

+## Create personal voice from a file

+In this scenario, the audio files must be available locally.

+To create a personal voice and get the speaker profile ID, use the `PersonalVoices_Post` operation of the custom voice API. Construct the request body according to the following instructions:

+- Set the required `projectId` property. See [create a project](./personal-voice-create-project.md).

+- Set the required `consentId` property. See [add user consent](./personal-voice-create-consent.md).

+- Set the required `audiodata` property. You can specify one or more audio files in the same request.

+Make an HTTP POST request using the URI as shown in the following `PersonalVoices_Post` example.

+- Replace `YourResourceKey` with your Speech resource key.

+- Replace `YourResourceRegion` with your Speech resource region.

+- Replace `JessicaPersonalVoiceId` with a personal voice ID of your choice. The case sensitive ID will be used in the personal voice's URI and can't be changed later.

+```azurecli-interactive

+curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourResourceKey" -F 'projectId="ProjectId"' -F 'consentId="JessicaConsentId"' -F 'audiodata=@"D:\PersonalVoiceTest\CNVSample001.wav"' -F 'audiodata=@"D:\PersonalVoiceTest\CNVSample002.wav"' "

+https://YourResourceRegion.api.cognitive.microsoft.com/customvoice/personalvoices/JessicaPersonalVoiceId?api-version=2023-12-01-preview"

+```

+You should receive a response body in the following format:

+```json

+{

+ "id": "JessicaPersonalVoiceId",

+ "speakerProfileId": "3059912f-a3dc-49e3-bdd0-02e449df1fe3",

+ "projectId": "ProjectId",

+ "consentId": "JessicaConsentId",

+ "status": "NotStarted",

+ "createdDateTime": "2023-04-01T05:30:00.000Z",

+ "lastActionDateTime": "2023-04-02T10:15:30.000Z"

+}

+```

+Use the `speakerProfileId` property to integrate personal voice in your text to speech application. For more information, see [use personal voice in your application](./personal-voice-how-to-use.md).

+The response header contains the `Operation-Location` property. Use this URI to get details about the `PersonalVoices_Post` operation. Here's an example of the response header:

+```HTTP 201

+Operation-Location: https://eastus.api.cognitive.microsoft.com/customvoice/operations/1321a2c0-9be4-471d-83bb-bc3be4f96a6f?api-version=2023-12-01-preview

+Operation-Id: 1321a2c0-9be4-471d-83bb-bc3be4f96a6f

+```

+## Create personal voice from a URL

+In this scenario, the audio files must already be stored in an Azure Blob Storage container.

+To create a personal voice and get the speaker profile ID, use the `PersonalVoices_Create` operation of the custom voice API. Construct the request body according to the following instructions:

+VS Code (web) in Azure AI Studio creates and runs the development container on a compute instance. To get started with this approach, follow the instructions in [Work with Azure AI projects in VS Code](develop-in-vscode.md).

+If you launched VS Code from the AI Studio, you are in an Azure-connected custom container experience, and you can work directly with flows stored in the `shared` folder. These flow files are the same underlying files prompt flow references in the Studio, so they should already be configured with your project connections and deployments. To learn more about the folder structure in the VS Code container experience, see [Work with Azure AI projects in VS Code](develop-in-vscode.md)

+- [Try the Azure AI CLI from Azure AI Studio in a browser](develop-in-vscode.md)

+ > The compute can't be idle if you have [prompt flow runtime](./create-manage-runtime.md) in **Running** status on the compute. You need to delete any active runtime before the compute instance can be eligible for idle shutdown. You also can't have any active [VS Code (Web)](./develop-in-vscode.md) sessions hosted on the compute instance.

+> The compute can't be idle if you have [prompt flow runtime](./create-manage-runtime.md) in **Running** status on the compute. You need to delete any active runtime before the compute instance can be eligible for idle shutdown. You also can't have any active [VS Code (Web)](./develop-in-vscode.md) sessions hosted on the compute instance.

+ Title: Work with Azure AI projects in VS Code

+description: This article provides instructions on how to get started with Azure AI projects in VS Code.

+ - ignite-2023

+# Get started with Azure AI projects in VS Code

+Azure AI Studio supports developing in VS Code - Web and Desktop. In each scenario, your VS Code instance is remotely connected to a prebuilt custom container running on a virtual machine, also known as a compute instance. To work in your local environment instead, or to learn more, follow the steps in [Install the Azure AI SDK](sdk-install.md) and [Install the Azure AI CLI](cli-install.md).

+## Launch VS Code from Azure AI Studio

+1. Go to [Azure AI Studio](https://ai.azure.com).

+1. Go to **Build** > **Projects** and select or create the project you want to work with.

+1. At the top-right of any page in the **Build** tab, select **Open project in VS Code (Web)** if you want to work in the browser. If you want to work in your local VS Code instance instead, select the dropdown arrow and choose **Open project in VS Code (Desktop)**.

+1. Within the dialog that opened following the previous step, select or create the compute instance that you want to use.

+1. Once the compute is running, select **Set up** which configures the container on your compute for you. The compute setup might take a few minutes to complete. Once you set up the compute the first time, you can directly launch subsequent times. You might need to authenticate your compute when prompted.

+ > [!WARNING]

+ > Even if you [enable and configure idle shutdown on your compute instance](./create-manage-compute.md#configure-idle-shutdown), any computes that host this custom container for VS Code won't idle shutdown. This is to ensure the compute doesn't shut down unexpectedly while you're working within a container.

+1. Once the container is ready, select **Launch**. This launches your previously selected VS Code experience, remotely connected to a custom development environment running on your compute instance.

+ If you selected VS Code (Web), a new browser tab connected to *vscode.dev* opens. If you selected VS Code (Desktop), a new local instance of VS Code opens on your local machine.

+## The custom container folder structure

+Our prebuilt development environments are based on a docker container that has the Azure AI SDK generative packages, the Azure AI CLI, the Prompt flow SDK, and other tools. The environment is configured to run VS Code remotely inside of the container. The container is defined in a similar way to [this Dockerfile](https://github.com/Azure/aistudio-copilot-sample/blob/main/.devcontainer/Dockerfile), and is based on [Microsoft's Python 3.10 Development Container Image](https://mcr.microsoft.com/product/devcontainers/python/about).

+Your file explorer is opened to the specific project directory you launched from in AI Studio.

+The container is configured with the Azure AI folder hierarchy (`afh` directory), which is designed to orient you within your current development context, and help you work with your code, data and shared files most efficiently. This `afh` directory houses your Azure AI projects, and each project has a dedicated project directory that includes `code`, `data` and `shared` folders.

+This table summarizes the folder structure:

+| Folder | Description |

+| | |

+| `code` | Use for working with git repositories or local code files.<br/><br/>The `code` folder is a storage location directly on your compute instance and performant for large repositories. It's an ideal location to clone your git repositories, or otherwise bring in or create your code files. |

+| `data` | Use for storing local data files. We recommend you use the `data` folder to store and reference local data in a consistent way.|

+| `shared` | Use for working with a project's shared files and assets such as prompt flows.<br/><br/>For example, `shared\Users\{user-name}\promptflow` is where you find the project's prompt flows. |

+> [!IMPORTANT]

+> It's recommended that you work within this project directory. Files, folders, and repos you include in your project directory persist on your host machine (your compute instance). Files stored in the code and data folders will persist even when the compute instance is stopped or restarted, but will be lost if the compute is deleted. However, the shared files are saved in your Azure AI resource's storage account, and therefore aren't lost if the compute instance is deleted.

+### The Azure AI SDK

+To get started with the AI SDK, we recommend the [aistudio-copilot-sample repo](https://github.com/azure/aistudio-copilot-sample) as a comprehensive starter repository that includes a few different copilot implementations. For the full list of samples, check out the [Azure AI Samples repository](https://github.com/azure-samples/azureai-samples).

+1. Open a terminal

+1. Clone a sample repo into your project's `code` folder. You might be prompted to authenticate to GitHub

+ ```bash

+ cd code

+ git clone https://github.com/azure/aistudio-copilot-sample

+ ```

+1. If you have existing notebooks or code files, you can import `import azure.ai.generative` and use intellisense to browse capabilities included in that package

+### The Azure AI CLI

+If you prefer to work interactively, the Azure AI CLI has everything you need to build generative AI solutions.

+1. Open a terminal to get started

+1. `ai help` guides you through CLI capabilities

+1. `ai init` configures your resources in your development environment

+### Working with prompt flows

+You can use the Azure AI SDK and Azure AI CLI to create, reference and work with prompt flows.

+Prompt flows already created in the Azure AI Studio can be found at `shared\Users\{user-name}\promptflow`. You can also create new flows in your `code` or `shared` folder using the Azure AI CLI and SDK.

+- To reference an existing flow using the AI CLI, use `ai flow invoke`.

+- To create a new flow using the AI CLI, use `ai flow new`.

+Prompt flow will automatically use the Azure AI connections your project has access to when you use the AI CLI or SDK.

+You can also work with the prompt flow extension in VS Code, which is preinstalled in this environment. Within this extension, you can set the connection provider to your Azure AI project. See [consume connections from Azure AI](https://microsoft.github.io/promptflow/cloud/azureai/consume-connections-from-azure-ai.html).

+For prompt flow specific capabilities that aren't present in the AI SDK and CLI, you can work directly with the prompt flow CLI or SDK. For more information, see [prompt flow capabilities](https://microsoft.github.io/promptflow/reference/https://docsupdatetracker.net/index.html).

+## Remarks

+If you plan to work across multiple code and data directories, or multiple repositories, you can use the split root file explorer feature in VS Code. To try this feature, follow these steps:

+1. Enter *Ctrl+Shift+p* to open the command palette. Search for and select **Workspaces: Add Folder to Workspace**.

+1. Select the repository folder that you want to load. You should see a new section in your file explorer for the folder you opened. If it was a repository, you can now work with source control in VS Code.

+1. If you want to save this configuration for future development sessions, again enter *Ctrl+Shift+p* and select **Workspaces: Save Workspace As**. This action saves a config file to your current folder.

+For cross-language compatibility and seamless integration of Azure AI capabilities, explore the Azure AI Hub at [https://aka.ms/azai](https://aka.ms/azai). Discover app templates and SDK samples in your preferred programming language.

+## Next steps

+- [Get started with the Azure AI CLI](cli-install.md)

+- [Quickstart: Generate product name ideas in the Azure AI Studio playground](../quickstarts/playground-completions.md)

+VS Code (web) in Azure AI Studio creates and runs the development container on a compute instance. To get started with this approach, follow the instructions in [Work with Azure AI projects in VS Code](develop-in-vscode.md).

+- [Try the Azure AI CLI from Azure AI Studio in a browser](develop-in-vscode.md)

+>

+> Shrinking persistent volumes is currently not supported.

+az aks update --name myAKSCluster --resource-group myResourceGroup --disable-cost-analysis

+If you don't plan on going through the [AKS tutorial][aks-tutorial], clean up unnecessary resources to avoid Azure charges.

+If you don't plan on going through the [AKS tutorial][aks-tutorial], clean up unnecessary resources to avoid Azure charges.

+This quickstart assumes a basic understanding of Kubernetes concepts. For more information, see [Kubernetes core concepts for Azure Kubernetes Service (AKS)][kubernetes-concepts].

+- [!INCLUDE [quickstarts-free-trial-note](../../../includes/quickstarts-free-trial-note.md)]

+- This article requires version 2.0.64 or later of the Azure CLI. If you are using Azure Cloud Shell, then the latest version is already installed.

+- Make sure that the identity you're using to create your cluster has the appropriate minimum permissions. For more details on access and identity for AKS, see [Access and identity options for Azure Kubernetes Service (AKS)](../concepts-identity.md).

+- If you have multiple Azure subscriptions, select the appropriate subscription ID in which the resources should be billed using the [az account](/cli/azure/account) command.

+To create an AKS cluster, use the [`az aks create`][az-aks-create] command. The following example creates a cluster named *myAKSCluster* with one node and enables a system-assigned managed identity.

+To manage a Kubernetes cluster, use the Kubernetes command-line client, [kubectl][kubectl]. `kubectl` is already installed if you use Azure Cloud Shell. To install `kubectl` locally, use the [`az aks install-cli`][az-aks-install-cli] command.

+ NAME STATUS ROLES AGE VERSION

+ aks-nodepool1-11853318-vmss000000 Ready agent 2m26s v1.27.7

+ If you create and save the YAML file locally, then you can upload the manifest file to your default directory in CloudShell by selecting the **Upload/Download files** button and selecting the file from your local file system.

+1. Deploy the application using the [`kubectl apply`][kubectl-apply] command and specify the name of your YAML manifest.

+1. Check the status of the deployed pods using the [`kubectl get pods`][kubectl-get] command. Make sure all pods are `Running` before proceeding.

+ :::image type="content" source="media/quick-kubernetes-deploy-cli/aks-store-application.png" alt-text="Screenshot of AKS Store sample application." lightbox="media/quick-kubernetes-deploy-cli/aks-store-application.png":::

+If you don't plan on going through the [AKS tutorial][aks-tutorial], clean up unnecessary resources to avoid Azure charges.

+If you don't plan on going through the [AKS tutorial][aks-tutorial], clean up unnecessary resources to avoid Azure charges.

+- Deploy an AKS cluster using Azure PowerShell.

+- Run a sample multi-container application with a group of microservices and web front ends simulating a retail scenario.

+This article assumes a basic understanding of Kubernetes concepts. For more information, see [Kubernetes core concepts for Azure Kubernetes Service (AKS)](../concepts-clusters-workloads.md).

+- [!INCLUDE [quickstarts-free-trial-note](../../../includes/quickstarts-free-trial-note.md)]

+- For ease of use, try the PowerShell environment in [Azure Cloud Shell](/azure/cloud-shell/overview). For more information, see [Quickstart for Azure Cloud Shell](/azure/cloud-shell/quickstart).

+ If you want to use PowerShell locally, then install the [Az PowerShell](/powershell/azure/new-azureps-module-az) module and connect to your Azure account using the [Connect-AzAccount](/powershell/module/az.accounts/Connect-AzAccount) cmdlet. Make sure that you run the commands with administrative privileges. For more information, see [Install Azure PowerShell][install-azure-powershell].

+- Make sure that the identity you're using to create your cluster has the appropriate minimum permissions. For more details on access and identity for AKS, see [Access and identity options for Azure Kubernetes Service (AKS)](../concepts-identity.md).

+- If you have more than one Azure subscription, set the subscription that you wish to use for the quickstart by calling the [Set-AzContext](/powershell/module/az.accounts/set-azcontext) cmdlet.

+- Create a resource group using the [`New-AzResourceGroup`][new-azresourcegroup] cmdlet.

+ ```azurepowershell

+To create an AKS cluster, use the [`New-AzAksCluster`][new-azakscluster] cmdlet. The following example creates a cluster named *myAKSCluster* with one node and enables a system-assigned managed identity.

+```azurepowershell

+New-AzAksCluster -ResourceGroupName myResourceGroup `

+ -Name myAKSCluster `

+ -NodeCount 1 `

+ -EnableManagedIdentity `

+ -GenerateSshKey

+```

+After a few minutes, the command completes and returns information about the cluster.

+> [!NOTE]

+> When you create an AKS cluster, a second resource group is automatically created to store the AKS resources. For more information, see [Why are two resource groups created with AKS?](../faq.md#why-are-two-resource-groups-created-with-aks)

+To manage a Kubernetes cluster, use the Kubernetes command-line client, [kubectl][kubectl]. `kubectl` is already installed if you use Azure Cloud Shell. To install `kubectl` locally, use the `Install-AzAksCliTool` cmdlet.

+1. Configure `kubectl` to connect to your Kubernetes cluster using the [`Import-AzAksCredential`][import-azakscredential] cmdlet. This command downloads credentials and configures the Kubernetes CLI to use them.

+ ```azurepowershell

+1. Verify the connection to your cluster using the [`kubectl get`][kubectl-get] command. This command returns a list of the cluster nodes.

+ ```azurepowershell

+ NAME STATUS ROLES AGE VERSION

+ aks-nodepool1-11853318-vmss000000 Ready agent 2m26s v1.27.7

+- **Store front**: Web application for customers to view products and place orders.

+- **Product service**: Shows product information.

+- **Order service**: Places orders.

+- **Rabbit MQ**: Message queue for an order queue.

+ If you create and save the YAML file locally, then you can upload the manifest file to your default directory in CloudShell by selecting the **Upload/Download files** button and selecting the file from your local file system.

+1. Check for a public IP address for the store-front application. Monitor progress using the [`kubectl get service`][kubectl-get] command with the `--watch` argument.

+1. Once the **EXTERNAL-IP** address changes from *pending* to an actual public IP address, use `CTRL-C` to stop the `kubectl` watch process.

+1. Open a web browser to the external IP address of your service to see the Azure Store app in action.

+If you don't plan on going through the [AKS tutorial][aks-tutorial], clean up unnecessary resources to avoid Azure charges. Remove the resource group, container service, and all related resources using the [`Remove-AzResourceGroup`][remove-azresourcegroup] cmdlet.

+```azurepowershell

+Remove-AzResourceGroup -Name myResourceGroup

+```

+> [!NOTE]

+> The AKS cluster was created with system-assigned managed identity (default identity option used in this quickstart), the identity is managed by the platform and doesn't require removal.

+If you don't plan on going through the [AKS tutorial][aks-tutorial], clean up unnecessary resources to avoid Azure charges.

+1. Check the status of the deployed pods using the [`kubectl get pods`][kubectl-get] command. Make all pods are `Running` before proceeding.

+If you don't plan on going through the [AKS tutorial][aks-tutorial], you should delete your cluster to avoid incurring Azure charges.

+ NAME STATUS ROLES AGE VERSION

+ aks-agentpool-41946322-vmss000001 Ready agent 28h v1.27.7

+ aks-agentpool-41946322-vmss000002 Ready agent 28h v1.27.7

+ aks-npwin-41946322-vmss000000 Ready agent 28h v1.27.7

+ aks-userpool-41946322-vmss000001 Ready agent 28h v1.27.7

+ aks-userpool-41946322-vmss000002 Ready agent 28h v1.27.7

+ NAME STATUS ROLES AGE VERSION

+ aks-agentpool-41946322-vmss000001 Ready agent 28h v1.27.7

+ aks-agentpool-41946322-vmss000002 Ready agent 28h v1.27.7

+ aks-npwin-41946322-vmss000000 Ready agent 28h v1.27.7

+ aks-userpool-41946322-vmss000001 Ready agent 28h v1.27.7

+ aks-userpool-41946322-vmss000002 Ready agent 28h v1.27.7

+1. Check the status of the deployed pods using the [`kubectl get pods`][kubectl-get] command. Make all pods are `Running` before proceeding.

+If you don't plan on going through the [AKS tutorial][aks-tutorial], you should delete your cluster to avoid incurring Azure charges.

+ If you want to use PowerShell locally, then install the [Az PowerShell](/powershell/azure/new-azureps-module-az) module and connect to your Azure account using the [Connect-AzAccount](/powershell/module/az.accounts/Connect-AzAccount) cmdlet. Make sure that you run the commands with administrative privileges. For more information, see [Install Azure PowerShell][install-azure-powershell].

+1. Check the status of the deployed pods using the [`kubectl get pods`][kubectl-get] command. Make all pods are `Running` before proceeding.

+1. See the sample app in action by opening a web browser to the external IP address of your service.

+If you don't plan on going through the [AKS tutorial][aks-tutorial], then delete your cluster to avoid incurring Azure charges. Call the [Remove-AzResourceGroup](/powershell/module/az.resources/remove-azresourcegroup) cmdlet to remove the resource group, container service, and all related resources.

+* If no zone is specified when creating a managed NAT gateway, then NAT gateway is deployed to "no zone" by default. When NAT gateway is placed in **no zone**, Azure places the resource in a zone for you. For more information on non-zonal deployment model, see [non-zonal NAT gateway](/azure/nat-gateway/nat-availability-zones#non-zonal).

+ ```azurecli-interactive

+ > A single NAT gateway resource can't be used across multiple availability zones. To ensure zone-resiliency, it is recommended to deploy a NAT gateway resource to each availability zone and assign to subnets containing AKS clusters in each zone. For more information on this deployment model, see [NAT gateway for each zone](/azure/nat-gateway/nat-availability-zones#zonal-nat-gateway-resource-for-each-zone-in-a-region-to-create-zone-resiliency).

+Finally, you'll place the driver JARs in the Tomcat classpath and restart your App Service. Ensure that the JDBC driver files are available to the Tomcat classloader by placing them in the */home/site/lib* directory. In the [Cloud Shell](https://shell.azure.com), run `az webapp deploy --type=lib` for each driver JAR:

+```azurecli-interactive

+az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --target-path <jar-name>.jar

+```

+1. Ensure that the JDBC driver files are available to the Tomcat classloader by placing them in the */home/site/lib* directory. In the [Cloud Shell](https://shell.azure.com), run `az webapp deploy --type=lib` for each driver JAR:

+```azurecli-interactive

+az webapp deploy --resource-group <group-name> --name <app-name> --src-path <jar-name>.jar --type=lib --path <jar-name>.jar

+```

+If you created a server-level data source, restart the App Service Linux application. Tomcat will reset `CATALINA_BASE` to `/home/tomcat` and use the updated configuration.

+| `type` | `war`\|`jar`\|`ear`\|`lib`\|`startup`\|`static`\|`zip` | The type of the artifact being deployed, this sets the default target path and informs the web app how the deployment should be handled. <br/> - `type=zip`: Deploy a ZIP package by unzipping the content to `/home/site/wwwroot`. `target-path` parameter is optional. <br/> - `type=war`: Deploy a WAR package. By default, the WAR package is deployed to `/home/site/wwwroot/app.war`. The target path can be specified with `target-path`. <br/> - `type=jar`: Deploy a JAR package to `/home/site/wwwroot/app.jar`. The `target-path` parameter is ignored <br/> - `type=ear`: Deploy an EAR package to `/home/site/wwwroot/app.ear`. The `target-path` parameter is ignored <br/> - `type=lib`: Deploy a JAR library file. By default, the file is deployed to `/home/site/libs`. The target path can be specified with `target-path`. <br/> - `type=static`: Deploy a static file (e.g. a script). By default, the file is deployed to `/home/site/wwwroot`. <br/> - `type=startup`: Deploy a script that App Service automatically uses as the startup script for your app. By default, the script is deployed to `D:\home\site\scripts\<name-of-source>` for Windows and `home/site/wwwroot/startup.sh` for Linux. The target path can be specified with `target-path`. | Yes | String |

+| `target-path` | `"<absolute-path>"` | The absolute path to deploy the artifact to. For example, `"/home/site/deployments/tools/driver.jar"`, `"/home/site/scripts/helper.sh"`. | No | String |

+|dnsMaxCacheTimeout|30|0|0-60|DNS results will be cached according to the individual records TTL, but no longer than the defined max cache timeout. Setting cache to zero means you've disabled caching.|

+token=<Replace with an Azure DevOps Services (formerly Visual Studio Team Services, or VSTS) personal access token>

+> Logs are available only for resources deployed in the Azure Resource Manager deployment model. You can't use logs for resources in the classic deployment model. For a better understanding of the two models, see the [Understanding Resource Manager deployment and classic deployment](../azure-resource-manager/management/deployment-models.md) article.

+|originalHost| This field contains the original request host name|

+|error_info|The reason for the 4xx and 5xx error. Displays an error code for a failed request. More details in [Error code information.](./application-gateway-diagnostics.md#error-code-information) |

+|contentType|The type of content or data that is being processed or delivered by the application gateway

+ "host": "20.110.30.194",

+ "error_info":"ERRORINFO_NO_ERROR",

+ "contentType":"application/json"

+|host| The hostname for which the request has been sent to the backend server. If backend hostname is being overridden, this name reflects that.|

+|originalHost| The hostname for which the request was received by the Application Gateway from the client.|

+### Error code Information

+If the application gateway can't complete the request, it stores one of the following reason codes in the error_info field of the access log.

+|4XX Errors |The 4xx error codes indicate that there was an issue with the client's request, and the server can't fulfill it |

+|||

+| ERRORINFO_INVALID_METHOD| The client has sent a request which is non-RFC compliant. Possible reasons: client using HTTP method not supported by server, misspelled method, incompatible HTTP protocol version etc.|

+ | ERRORINFO_INVALID_REQUEST | The server can't fulfill the request because of incorrect syntax.|

+ | ERRORINFO_INVALID_VERSION| The application gateway received a request with an invalid or unsupported HTTP version.|

+ | ERRORINFO_INVALID_09_METHOD| The client sent request with HTTP Protocol version 0.9.|

+ | ERRORINFO_INVALID_HOST |The value provided in the "Host" header is either missing, improperly formatted, or doesn't match the expected host value (when there is no Basic listener, and none of the hostnames of Multisite listeners match with the host).|

+ | ERRORINFO_INVALID_CONTENT_LENGTH | The length of the content specified by the client in the content-Length header doesn't match the actual length of the content in the request.|

+ | ERRORINFO_INVALID_METHOD_TRACE | The client sent HTTP TRACE method which is not supported by the application gateway.|

+ | ERRORINFO_CLIENT_CLOSED_REQUEST | The client closed the connection with the application gateway before the idle timeout period elapsed.Check whether the client timeout period is greater than the [idle timeout period](./application-gateway-faq.yml#what-are-the-settings-for-keep-alive-timeout-and-tcp-idle-timeout) for the application gateway.|

+ | ERRORINFO_REQUEST_URI_INVALID |Indicates issue with the Uniform Resource Identifier (URI) provided in the client's request. |

+ | ERRORINFO_HTTP_NO_HOST_HEADER | Client sent a request without Host header. |

+ | ERRORINFO_HTTP_TO_HTTPS_PORT |The client sent a plain HTTP request to an HTTPS port. |

+ | ERRORINFO_HTTPS_NO_CERT | Indicates client is not sending a valid and properly configured TLS certificate during Mutual TLS authentication. |

+|5XX Errors |Description |

+|||

+ | ERRORINFO_UPSTREAM_NO_LIVE | The application gateway is unable to find any active or reachable backend servers to handle incoming requests |

+ | ERRORINFO_UPSTREAM_CLOSED_CONNECTION | The backend server closed the connection unexpectedly or before the request was fully processed. This could happen due to backend server reaching its limits, crashing etc.|

+ | ERRORINFO_UPSTREAM_TIMED_OUT | The established TCP connection with the server was closed as the connection took longer than the configured timeout value. |

+description: Deploy the Open Service Mesh (OSM) extension on Azure Arc-enabled Kubernetes cluster

+All components of Azure Arc-enabled OSM are deployed on availability zones, making them zone redundant.

+> To pin a specific version of OSM, add the `--version x.y.z` flag to the `create` command. Note that this will set the value for `auto-upgrade-minor-version` to false.

+```azurecli-interactive

+export SETTINGS_FILE=<json-file-path>

+```

+Run the `az k8s-extension create` command to create the OSM extension, passing in the settings file using the `--configuration-settings-file` flag:

+```azurecli-interactive

+az k8s-extension create --cluster-name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --cluster-type connectedClusters --extension-type Microsoft.openservicemesh --scope cluster --name osm --configuration-settings-file $SETTINGS_FILE

+```

+After connecting your cluster to Azure Arc, create a JSON file with the following format, making sure to update the `<cluster-name>` and `<osm-arc-version>` values:

+Run this command to install the OSM extension:

+A built-in policy is available on Azure portal under the **Kubernetes** category: **Azure Arc-enabled Kubernetes clusters should have the Open Service Mesh extension installed**. This policy can be assigned at the scope of a subscription or a resource group.

+The default action of this policy is **Deploy if not exists**. However, you can choose to audit the clusters for extension installations by changing the parameters during assignment. You're also prompted to specify the version you wish to install (v1.0.0-1 or higher) as a parameter.

+For more commands that you can use to validate and troubleshoot the deployment of the Open Service Mesh (OSM) extension components on your cluster, see [our troubleshooting guide](extensions-troubleshooting.md#azure-arc-enabled-open-service-mesh)

+OSM deploys a MeshConfig resource `osm-mesh-config` as a part of its control plane in `arc-osm-system` namespace. The purpose of this MeshConfig is to provide the mesh owner/operator the ability to update some of the mesh configurations based on their needs. To view the default values, use the following command.

+The output shows the default values:

+To start using OSM capabilities, you need to first onboard the application namespaces to the service mesh. Download the OSM CLI from the [OSM GitHub releases page](https://github.com/openservicemesh/osm/releases/). Once the namespaces are added to the mesh, you can configure the SMI policies to achieve the desired OSM capability.

+For more information about onboarding services, see the [Open Service Mesh documentation](https://docs.openservicemesh.io/docs/guides/app_onboarding/#onboard-services).

+> If you use sample applications, ensure that their versions match the version of the OSM extension installed on your cluster. For example, if you are using v1.0.0 of the OSM extension, use the bookstore manifest from release-v1.0 branch of OSM upstream repository.

+2. Go to Azure Monitor and navigate to the **Reports** tab to access the OSM workbook.

+The **Requests** tab shows a summary of all the http requests sent via service to service in OSM.

+The **Connections** tab shows a summary of all the connections between your services in Open Service Mesh.

+- Just want to try things out? Get started quickly with an [Azure Arc Jumpstart](https://aka.ms/arc-jumpstart-osm) scenario using Cluster API.

+- Get [troubleshooting help for Azure Arc-enabled OSM](extensions-troubleshooting.md#azure-arc-enabled-open-service-mesh).

+To upgrade a resource bridge on Azure Stack HCI, please transition to 23H2 and use the built-in upgrade management tool. More info available [here](/azure-stack/hci/update/whats-the-lifecycle-manager-23h2).

+| At scale | [Install the Arc agent on VMware VMs at scale using Arc enabled VMware vSphere](../vmware-vsphere/enable-guest-management-at-scale.md). Arc enabled VMware vSphere allows you to [connect your VMware vCenter server to Azure](../vmware-vsphere/quick-start-connect-vcenter-to-arc-using-script.md), automatically discover your VMware VMs, and install the Arc agent on them. Requires VMware tools on VMs.|

+| At scale | [Install the Arc agent on SCVMM VMs at scale using Arc-enabled System Center Virtual Machine Manager](../system-center-virtual-machine-manager/enable-guest-management-at-scale.md). Arc-enabled System Center Virtual Machine Manager allows you to [connect your SCVMM management server to Azure](../system-center-virtual-machine-manager/quickstart-connect-system-center-virtual-machine-manager-to-arc.md), automatically discover your SCVMM VMs, and install the Arc agent on them. |

+description: Learn how to use a .NET isolated worker process to run your C# functions in Azure, which lets you run your functions on currently supported versions of .NET and .NET Framework.

+This article is an introduction to working with Azure Functions in .NET, using the isolated worker model. This model allows your project to target versions of .NET independently of other runtime components. For information about specific .NET versions supported, see [supported version](#supported-versions).

+Use the following links to get started right away building .NET isolated worker model functions.

+To learn just about deploying an isolated worker model project to Azure, see [Deploy to Azure Functions](#deploy-to-azure-functions).

+## Benefits of the isolated worker model

+There are two modes in which you can run your .NET class library functions: either [in the same process](functions-dotnet-class-library.md) as the Functions host runtime (_in-process_) or in an isolated worker process. When your .NET functions run in an isolated worker process, you can take advantage of the following benefits:

+

+If you have an existing C# function app that runs in-process, you need to migrate your app to take advantage of these benefits. For more information, see [Migrate .NET apps from the in-process model to the isolated worker model][migrate].

+For a comprehensive comparison between the two modes, see [Differences between in-process and isolate worker process .NET Azure Functions](./dotnet-isolated-in-process-differences.md).

+## Project structure

+You find these extension packages under [Microsoft.Azure.Functions.Worker.Extensions](https://www.nuget.org/packages?q=Microsoft.Azure.Functions.Worker.Extensions).

+- Call either `ConfigureFunctionsWebApplication()` if using [ASP.NET Core integration](#aspnet-core-integration) or `ConfigureFunctionsWorkerDefaults()` otherwise. See [HTTP trigger](#http-trigger) for details on these options.

+ If you're writing your application using F#, some trigger and binding extensions require extra configuration. See the setup documentation for the [Blobs extension][fsharp-blobs], the [Tables extension][fsharp-tables], and the [Cosmos DB extension][fsharp-cosmos] when you plan to use these extensions in an F# app.

+- Configure any services or app configuration your project requires. See [Configuration](#configuration) for details.

+ If you're planning to use Application Insights, you need to call `AddApplicationInsightsTelemetryWorkerService()` and `ConfigureFunctionsApplicationInsights()` in the `ConfigureServices()` delegate. See [Application Insights](#application-insights) for details.

+These configurations apply to your function app running in a separate process. To make changes to the functions host or trigger and binding configuration, you still need to use the [host.json file](functions-host-json.md).

+Dependency injection is simplified when compared to .NET in-process functions, which requires you to create a startup class to register services.

+For a .NET isolated process app, you use the .NET standard way of call [ConfigureServices] on the host builder and use the extension methods on [IServiceCollection] to inject specific services.

+The [`ILogger<T>`][ILogger&lt;T&gt;] in this example was also obtained through dependency injection, so it's registered automatically. To learn more about configuration options for logging, see [Logging](#logging).

+| **`BindInputAsync`** | Binds an input binding item for the requested `BindingMetadata` instance. For example, you can use this method when you have a function with a `BlobInput` input binding that needs to be used by your middleware. |

+This is an example of a middleware implementation that reads the `HttpRequestData` instance and updates the `HttpResponseData` instance during function execution:

+This middleware checks for the presence of a specific request header(x-correlationId), and when present uses the header value to stamp a response header. Otherwise, it generates a new GUID value and uses that for stamping the response header. For a more complete example of using custom middleware in your function app, see the [custom middleware reference sample](https://github.com/Azure/azure-functions-dotnet-worker/blob/main/samples/CustomMiddleware).

+## Methods recognized as functions

+A function method is a public method of a public class with a `Function` attribute applied to the method and a trigger attribute applied to an input parameter, as shown in the following example:

+The trigger attribute specifies the trigger type and binds input data to a method parameter. The previous example function is triggered by a queue message, and the queue message is passed to the method in the `myQueueItem` parameter.

+The `Function` attribute marks the method as a function entry point. The name must be unique within a project, start with a letter and only contain letters, numbers, `_`, and `-`, up to 127 characters in length. Project templates often create a method named `Run`, but the method name can be any valid C# method name. The method must be a public member of a public class. It should generally be an instance method so that services can be passed in via [dependency injection](#dependency-injection).

+## Function parameters

+Here are some of the parameters that you can include as part of a function method signature:

+- [Bindings](#bindings), which are marked as such by decorating the parameters as attributes. The function must contain exactly one trigger parameter.

+- An [execution context object](#execution-context), which provides information about the current invocation.

+- A [cancellation token](#cancellation-tokens), used for graceful shutdown.

+### Execution context

+.NET isolated passes a [FunctionContext] object to your function methods. This object lets you get an [`ILogger`][ILogger] instance to write to the logs by calling the [GetLogger] method and supplying a `categoryName` string. You can use this context to obtain an [`ILogger`][ILogger] without having to use dependency injection. To learn more, see [Logging](#logging).

+### Cancellation tokens

+A function can accept a [CancellationToken](/dotnet/api/system.threading.cancellationtoken) parameter, which enables the operating system to notify your code when the function is about to be terminated. You can use this notification to make sure the function doesn't terminate unexpectedly in a way that leaves data in an inconsistent state.

+Cancellation tokens are supported in .NET functions when running in an isolated worker process. The following example raises an exception when a cancellation request is received:

+

+The following example performs clean-up actions when a cancellation request is received:

+Bindings are defined by using attributes on methods, parameters, and return types. Bindings can provide data as strings, arrays, and serializable types, such as plain old class objects (POCOs). For some binding extensions, you can also [bind to service-specific types](#sdk-types) defined in service SDKs.

+For HTTP triggers, see the [HTTP trigger](#http-trigger) section.

+For a complete set of reference samples using triggers and bindings with isolated worker process functions, see the [binding extensions reference sample](https://github.com/Azure/azure-functions-dotnet-worker/blob/main/samples/Extensions).

+For some service-specific binding types, binding data can be provided using types from service SDKs and frameworks. These provide more capability beyond what a serialized string or plain-old CLR object (POCO) can offer. To use the newer types, your project needs to be updated to use newer versions of core dependencies.

+When testing SDK types locally on your machine, you also need to use [Azure Functions Core Tools](./functions-run-local.md), version 4.0.5000 or later. You can check your current version using the `func version` command.

+Each trigger and binding extension also has its own minimum version requirement, which is described in the extension reference articles. The following service-specific bindings provide SDK types:

+| [Azure Queues][queue-sdk-types] | **Generally Available** | _Input binding doesn't exist_ | _SDK types not recommended.<sup>1</sup>_ |

+| [Azure Service Bus][servicebus-sdk-types] | **Generally Available** | _Input binding doesn't exist_ | _SDK types not recommended.<sup>1</sup>_ |

+| [Azure Event Hubs][eventhub-sdk-types] | **Generally Available** | _Input binding doesn't exist_ | _SDK types not recommended.<sup>1</sup>_ |

+| [Azure Tables][tables-sdk-types] | _Trigger doesn't exist_ | **Generally Available** | _SDK types not recommended.<sup>1</sup>_ |

+| [Azure Event Grid][eventgrid-sdk-types] | **Generally Available** | _Input binding doesn't exist_ | _SDK types not recommended.<sup>1</sup>_ |

+<sup>1</sup> For output scenarios in which you would use an SDK type, you should create and work with SDK clients directly instead of using an output binding. See [Register Azure clients](#register-azure-clients) for a dependency injection example.

+## HTTP trigger

+- A [built-in model](#built-in-http-model), which doesn't require extra dependencies and uses custom types for HTTP requests and responses. This approach is maintained for backward compatibility with previous .NET isolated worker apps.

+### ASP.NET Core integration

+This section shows how to work with the underlying HTTP request and response objects using types from ASP.NET Core including [HttpRequest], [HttpResponse], and [IActionResult]. This model isn't available to [apps targeting .NET Framework][supported-versions], which should instead use the [built-in model](#built-in-http-model).

+> Not all features of ASP.NET Core are exposed by this model. Specifically, the ASP.NET Core middleware pipeline and routing capabilities are not available. ASP.NET Core integration requires you to use updated packages.

+To enable ASP.NET Core integration for HTTP:

+1. Add a reference in your project to the [Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore/) package, version 1.0.0 or later.

+1. Update your project to use these specific package versions:

+ + [Microsoft.Azure.Functions.Worker.Sdk](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Sdk/), version 1.11.0. or later

+ + [Microsoft.Azure.Functions.Worker](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker/), version 1.16.0 or later.

+1. In your `Program.cs` file, update the host builder configuration to use `ConfigureFunctionsWebApplication()` instead of `ConfigureFunctionsWorkerDefaults()`. The following example shows a minimal setup without other customizations:

+1. Update any existing HTTP-triggered functions to use the ASP.NET Core types. This example shows the standard `HttpRequest` and an `IActionResult` used for a simple "hello, world" function:

+### Built-in HTTP model

+In the built-in model, the system translates the incoming HTTP request message into an [HttpRequestData] object that is passed to the function. This object provides data from the request, including `Headers`, `Cookies`, `Identities`, `URL`, and optionally a message `Body`. This object is a representation of the HTTP request but isn't directly connected to the underlying HTTP listener or the received message.

+You can configure your isolated process application to emit logs directly [Application Insights](../azure-monitor/app/app-insights-overview.md?tabs=net). This behavior replaces the default behavior of [relaying logs through the host](./configure-monitoring.md#custom-application-logs), and is recommended because it gives you control over how those logs are emitted.

+#### Install packages

+To write logs directly to Application Insights from your code, add references to these packages in your project:

+You can run the following commands to add these references to your project:

+#### Configure startup

+With the packages installed, you must call `AddApplicationInsightsTelemetryWorkerService()` and `ConfigureFunctionsApplicationInsights()` during service configuration in your `Program.cs` file, as in this example:

+The call to `ConfigureFunctionsApplicationInsights()` adds an `ITelemetryModule`, which listens to a Functions-defined `ActivitySource`. This creates the dependency telemetry required to support distributed tracing. To learn more about `AddApplicationInsightsTelemetryWorkerService()` and how to use it, see [Application Insights for Worker Service applications](../azure-monitor/app/worker-service.md).

+#### Managing log levels

+## Performance optimizations

+This section outlines options you can enable that improve performance around [cold start](./event-driven-scaling.md#cold-start).

+In general, your app should use the latest versions of its core dependencies. At a minimum, you should update your project as follows:

+1. Upgrade [Microsoft.Azure.Functions.Worker] to version 1.19.0 or later.

+1. Upgrade [Microsoft.Azure.Functions.Worker.Sdk] to version 1.16.4 or later.

+1. Add a framework reference to `Microsoft.AspNetCore.App`, unless your app targets .NET Framework.

+The following snippet shows this configuration in the context of a project file:

+```xml

+ <ItemGroup>

+ <FrameworkReference Include="Microsoft.AspNetCore.App" />

+ <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.19.0" />

+ <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />

+ </ItemGroup>

+```

+### Placeholders

+Placeholders are a platform capability that improves cold start for apps targeting .NET 6 or later. To use this optimization, you must explicitly enable placeholders using these steps:

+1. Update your project configuration to use the latest dependency versions, as detailed in the previous section.

+1. Set the [`WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED`](./functions-app-settings.md#website_use_placeholder_dotnetisolated) application setting to `1`, which you can do by using this [az functionapp config appsettings set](/cli/azure/functionapp/config/appsettings#az-functionapp-config-appsettings-set) command:

+ ```azurecli

+ az functionapp config appsettings set -g <groupName> -n <appName> --settings 'WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED=1'

+ ```

+ In this example, replace `<groupName>` with the name of the resource group, and replace `<appName>` with the name of your function app.

+

+1. Make sure that the [`netFrameworkVersion`](./functions-app-settings.md#netframeworkversion) property of the function app matches your project's target framework, which must be .NET 6 or later. You can do this by using this [az functionapp config set](/cli/azure/functionapp/config#az-functionapp-config-set) command:

+ ```azurecli

+ az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

+ ```

+ In this example, also replace `<framework>` with the appropriate version string, such as `v8.0`, `v7.0`, or `v6.0`, according to your target .NET version.

+

+1. Make sure that your function app is configured to use a 64-bit process, which you can do by using this [az functionapp config set](/cli/azure/functionapp/config#az-functionapp-config-set) command:

+ ```azurecli

+ az functionapp config set -g <groupName> -n <appName> --use-32bit-worker-process false

+ ```

+> [!IMPORTANT]

+> When setting the [`WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED`](./functions-app-settings.md#website_use_placeholder_dotnetisolated) to `1`, all other function app configurations must be set correctly. Otherwise, your function app might fail to start.

+### Optimized executor

+The function executor is a component of the platform that causes invocations to run. An optimized version of this component is enabled by default starting with version 1.16.2 of the SDK. No other configuration is required.

+### ReadyToRun

+You can compile your function app as [ReadyToRun binaries](/dotnet/core/deploying/ready-to-run). ReadyToRun is a form of ahead-of-time compilation that can improve startup performance to help reduce the effect of cold starts when running in a [Consumption plan](consumption-plan.md). ReadyToRun is available in .NET 6 and later versions and requires [version 4.0 or later](functions-versions.md) of the Azure Functions runtime.

+ReadyToRun requires you to build the project against the runtime architecture of the hosting app. **If these are not aligned, your app will encounter an error at startup.** Select your runtime identifier from this table:

+|Operating System | App is 32-bit¹ | Runtime identifier |

+|-|-|-|

+| Windows | True | `win-x86` |

+| Windows | False | `win-x64` |

+| Linux | True | N/A (not supported) |

+| Linux | False | `linux-x64` |

+¹ Only 64-bit apps are eligible for some other performance optimizations.

+To check if your Windows app is 32-bit or 64-bit, you can run the following CLI command, substituting `<group_name>` with the name of your resource group and `<app_name>` with the name of your application. An output of "true" indicates that the app is 32-bit, and "false" indicates 64-bit.

+```azurecli

+ az functionapp config show -g <group_name> -n <app_name> --query "use32BitWorkerProcess"

+```

+You can change your application to 64-bit with the following command, using the same substitutions:

+```azurecli

+az functionapp config set -g <group_name> -n <app_name> --use-32bit-worker-process false`

+```

+To compile your project as ReadyToRun, update your project file by adding the `<PublishReadyToRun>` and `<RuntimeIdentifier>` elements. The following example shows a configuration for publishing to a Windows 64-bit function app.

+```xml

+<PropertyGroup>

+ <TargetFramework>net8.0</TargetFramework>

+ <AzureFunctionsVersion>v4</AzureFunctionsVersion>

+ <RuntimeIdentifier>win-x64</RuntimeIdentifier>

+ <PublishReadyToRun>true</PublishReadyToRun>

+</PropertyGroup>

+```

+If you don't want to set the `<RuntimeIdentifier>` as part of the project file, you can also configure this as part of the publishing gesture itself. For example, with a Windows 64-bit function app, the .NET CLI command would be:

+```dotnetcli

+dotnet publish --runtime win-x64

+```

+In Visual Studio, the **Target Runtime** option in the publish profile should be set to the correct runtime identifier. When set to the default value of **Portable**, ReadyToRun isn't used.

+## Deploy to Azure Functions

+When running in Azure, your function code project must run in either a function app or in a Linux container. The function app and other required Azure resources must exist before you deploy your code.

+You can also deploy your function app in a Linux container. For more information, see [Working with containers and Azure Functions](functions-how-to-custom-container.md).

+### Create Azure resources

+You can create your function app and other required resources in Azure using one of these methods:

+### Publish code project

+After creating your function app and other required resources in Azure, you can deploy the code project to Azure using one of these methods:

+For more information, see [Deployment technologies in Azure Functions](functions-deployment-technologies.md).

+### Deployment requirements

+There are a few requirements for running .NET functions in the isolated worker model in Azure, depending on the operating system:

+### [Windows](#tab/windows)

+### [Linux](#tab/linux)

+When you create your function app in Azure using the methods in the previous section, these required settings are added for you. When you create these resources [by using ARM templates or Bicep files for automation](functions-infrastructure-as-code.md), you must make sure to set them in the template.

+## Debugging

+When running locally using Visual Studio or Visual Studio Code, you're able to debug your .NET isolated worker project as normal. However, there are two debugging scenarios that don't work as expected.

+### Remote Debugging using Visual Studio

+Because your isolated worker process app runs outside the Functions runtime, you need to attach the remote debugger to a separate process. To learn more about debugging using Visual Studio, see [Remote Debugging](functions-develop-vs.md?tabs=isolated-process#remote-debugging).

+### Debugging when targeting .NET Framework

+Your app should start with a call to `FunctionsDebugger.Enable();` as its first operation. This occurs in the `Main()` method before initializing a HostBuilder. Your `Program.cs` file should look similar to this:

+This starts your worker, and the process stops with the following message:

+Before a generally available release, a .NET version might be released in a _Preview_ or _Go-live_ state. See the [.NET Official Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) for details on these states.

+While it might be possible to target a given release from a local Functions project, function apps hosted in Azure might not have that release available. Azure Functions can only be used with Preview or Go-live releases noted in this section.

+Azure Functions doesn't currently work with any "Preview" or "Go-live" .NET releases. See [Supported versions][supported-versions] for a list of generally available releases that you can use.

+When deploying to a function app in Azure, you also need to ensure that the framework is made available to the app. To do so on Windows, you can use the following CLI command. Replace `<groupName>` with the name of the resource group, and replace `<appName>` with the name of your function app. Replace `<framework>` with the appropriate version string, such as `v8.0`.

+ 1. Navigate to **Tools** > **Options**, choose **Azure Functions** under **Projects and Solutions**.

+ 1. Select **Check for updates** and install updates as prompted.

+ 1. Run the `dotnet --list-sdks` command and note the preview version you're currently using during local development.

+ 1. Run the `dotnet new globaljson --sdk-version <SDK_VERSION> --force` command, where `<SDK_VERSION>` is the version you're using locally. For example, `dotnet new globaljson --sdk-version dotnet-sdk-8.0.100-preview.7.23376.3 --force` causes the system to use the .NET 8 Preview 7 SDK when building your project.

+> [!NOTE]

+> Because of the just-in-time loading of preview frameworks, function apps running on Windows can experience increased cold start times when compared against earlier GA versions.

+Using this model lets you get all the great benefits that come with the Azure Functions .NET isolated worker process. For more information, see [Benefits of the isolated worker model](../dotnet-isolated-process-guide.md#benefits-of-the-isolated-worker-model). Additionally, this new SDK includes some new [features](#feature-improvements-over-in-process-durable-functions).

+## WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED

+Indicates whether to use a specific [cold start](event-driven-scaling.md#cold-start) optimization when running .NET isolated worker process functions on the [Consumption plan](consumption-plan.md). Set to `0` to disable the cold-start optimization on the Consumption plan.

+|Key|Sample value|

+|||

+|WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED|`1`|

+1. choose the Azure icon in the Activity bar, then in the **Workspace (local)** area, select the **+** button, choose **Create Function** in the dropdown. When prompted, choose **Create new project**.

+An HttpExample.cs class library file, the contents of which vary depending on whether your project runs in an [isolated worker process](dotnet-isolated-process-guide.md#project-structure) or [in-process](functions-dotnet-class-library.md#functions-class-library-project) with the Functions host.

+You can add a new function to an existing project baswed on one of the predefined Functions trigger templates. To add a new function trigger, select F1 to open the command palette, and then search for and run the command **Azure Functions: Create Function**. Follow the prompts to choose your trigger type and define the required attributes of the trigger. If your trigger requires an access key or connection string to connect to a service, get it ready before you create the function trigger.

+### Run functions in Azure

+To debug your functions, select F5. If [Core Tools][Azure Functions Core Tools] isn't available, you're prompted to install it. When Core Tools is installed and running, output is shown in the Terminal. This step is the same as running the `func start` Core Tools command from the Terminal, but with extra build tasks and an attached debugger.

+> As of December 13, 2022, function apps running on versions 2.x and 3.x of the Azure Functions runtime have reached the end of extended support. For more information, see [Retired versions](#retired-versions).

+These versions of the Functions runtime reached the end of extended support on December 13, 2022.

+| 3.x | Out-of-support | GA |

+> As of December 13, 2022, function apps running on versions 2.x and 3.x of the Azure Functions runtime have reached the end of extended support. For more information, see [Retired versions](functions-versions.md#retired-versions).

+A function app runs on a specific [version of the Azure Functions runtime](functions-versions.md). By default, function apps are created in version 4.x of the runtime. This article explains how to configure a function app in Azure to run on the version you choose. For information about how to configure a local development environment for a specific version, see [Code and test Azure Functions locally](functions-run-local.md).

+| Major version² | `FUNCTIONS_EXTENSION_VERSION` value | Additional configuration |

+¹ If using a later version with the .NET Isolated worker model, instead enable that version.

+²Reached the end of extended support on December 13, 2022. For a detailed support statement about end-of-support versions, see [this migration article](migrate-version-3-version-4.md).

+³[Support for version 1.x of the Azure Functions runtime ends on September 14, 2026](https://aka.ms/azure-functions-retirements/hostv1). Before that date, [migrate your version 1.x apps to version 4.x](./migrate-version-1-version-4.md) to maintain full support.

+description: Learn which languages are supported for developing your Functions in Azure, the support level of the various language versions, and potential end-of-support dates.

+### [3.1.0] (January 12, 2024)

+#### New features (3.1.0)

+- Added a new control, `atlas.control.ScaleControl`, to display a scale bar on the map.

+- Introduced functions for accessing, updating, and deleting a feature state.

+#### Bug fixes (3.1.0)

+- Addressed the issue of layer ordering after a style update, when a user layer is inserted before another user layer.

+- **\[BREAKING\]** Aligned the polygon fill pattern behavior with Maplibre. Now, the `fillPattern` option consistently disables the `fillColor` option. When configuring `fillColor` for polygon layers, ensure that `fillPattern` is set to `undefined`.

+### [2.3.6] (January 12, 2024)

+#### New features (2.3.6)

+- Added a new control, `atlas.control.ScaleControl`, to display a scale bar on the map.

+- Introduced functions for accessing, updating, and deleting a feature state.

+#### Bug fixes (2.3.6)

+- Addressed the issue of layer ordering after a style update, when a user layer is inserted before another user layer.

+[3.1.0]: https://www.npmjs.com/package/azure-maps-control/v/3.1.0

+[2.3.6]: https://www.npmjs.com/package/azure-maps-control/v/2.3.6

+## [0.1.7]

+#### New features (0.1.7)

+- Introduced a new customization option, `bubbleRadiusFactor`, to enable users to adjust the default multiplier for the bubble radius in a SimpleDataLayer.

+[0.1.7]: https://www.npmjs.com/package/azure-maps-spatial-io/v/0.1.7

+| December 2023 |**Windows** <ul><li>Support new settings that control agent disk size</li><li>Prevent CPU spikes by not using bookmark when resetting an Event Log subscription</li><li>Added missing fluentbit exe to AMA client setup for Custom Log support</li><li>Updated to latest AzureCredentialsManagementService and DsmsCredentialsManagement package</li><li>Update ME to v2.2023.1027.1417</li></ul>**Linux**<ul><li>Support for TLS V1.3</li><li>Support for nopri in Syslog</li><li>Ability to set disk quota from DCR Agent Settings</li><li>Add ARM64 Ubuntu 22 support</li><li>**Fixes**<ul><li>SysLog</li><ul><li>Parse syslog Palo Alto CEF with multiple space characters following the hostname</li><li>Fix an issue with incorrectly parsing messages containing two '\n' chars in a row</li><li>Improved support for non-RFC compliant devices</li><li>Support infoblox device messages containing both hostname and IP headers</li></ul><li>Fix AMA crash in RHEL 7.2</li><li>Remove dependency on "which" command</li><li>Fix port conflicts due to AMA using 13000 </li><li>Reliability and Performance improvements</li></ul></li></ul>| 1.22.0 | 1.29.4|

+# MMA Discovery and Removal Tool (Preview)

+- Data export will gradually support more tables, but is currently limited to tables specified in the [supported tables](#supported-tables) section. You can include tables that aren't yet supported in rules, but no data will be exported for them until the tables are supported.

+A data export rule defines the destination and tables for which data is exported. The rule provisioning takes about 30 minutes before the export operation initiated. Data export rules considerations:

+- The Storage Account must be unique across rules in the workspace.

+- Multiple rules can use the same Event Hubs namespace when you're sending to separate Event Hubs.

+- Export to a Storage Account: A separate container is created in the Storage Account for each table.

+- Export to Event Hubs: If an Event Hub name isn't provided, a separate Event Hub is created for each table. The [number of supported Event Hubs in Basic and Standard namespace tiers is 10](../../event-hubs/event-hubs-quotas.md#common-limits-for-all-tiers). When you're exporting more than 10 tables to these tiers, either split the tables between several export rules to different Event Hubs namespaces or provide an Event Hub name in the rule to export all tables to it.

+Azure NetApp Files is an Azure native, first-party, enterprise-class, high-performance file storage service. It provides _Volumes as a service_ for which you can create NetApp accounts, capacity pools, volumes, select service and performance levels, and manage data protection. It allows you to create and manage high-performance, highly available, and scalable file shares, using the same protocols and tools that you're familiar with and enterprise applications rely on on-premises.

+Azure NetApp FilesΓÇÖ key attributes are:

+- Performance, cost optimization and scale

+- Simplicity and availability

+- Data management and security

+Azure NetApp Files supports SMB, NFS and dual protocols volumes and can be used for various use cases such as:

+- file sharing

+- home directories

+- databases

+- high-performance computing and more

+For more information about workload solutions leveraging Azure NetApp Files, see [Solution architectures using Azure NetApp Files](azure-netapp-files-solution-architectures.md).

+## Performance, cost optimization, and scale

+Azure NetApp Files is designed to provide high-performance file storage for enterprise workloads and provide functionality to provide cost optimization and scale. Key features that contribute to these include:

+| Functionality | Description | Benefit |

+| - | - | - |

+| In-Azure bare-metal flash performance | Fast and reliable all-flash performance with submillisecond latency | Run performance-intensive workloads in the cloud with on-premises infrastructure-level performance

+| Multi-protocol support | Supports multiple protocols including NFSv3, NFSv4.1, SMB 3.0, SMB 3.1.1 and simultaneous dual-protocol | Seamlessly integrate with existing infrastructure and workflows without compatibility issues or complex configurations. |

+| Three flexible performance tiers (standard, premium, ultra) | Three performance tiers with dynamic service level change capability based on workload needs, including cool access for cold data | Choose the right performance level for workloads and dynamically adjust performance without overspending on resources.

+| Small-to-large volumes | Easily resize file volumes from 100 GiB up to 100 TiB without downtime | Scale storage as business needs grow without over-provisioning, avoiding upfront cost.

+| 1-TiB minimum capacity pool size | 1-TiB capacity pool is a reduced size storage pool compared to the initial 4 TiB minimum | Save money by starting with a smaller storage footprint and lower entry point, without sacrificing performance or availability. Scale storage based on growth without high upfront costs.

+| 1000-TiB maximum capacity pool | 1000-TiB capacity pool is an increased storage pool compared to the initial 500 TiB maximum | Reduce waste by creating larger, pooled capacity and performance budget and share/distribute across volumes.

+| 100-500 TiB large volumes | Store large volumes of data up to 500 TiB in a single volume | Manage large data sets and high-performance workloads with ease.

+| User and group quotas | Set quotas on storage usage for individual users and groups | Control storage usage and optimize resource allocation.

+| Virtual machine (VM) networked storage performance | Higher VM network throughput compared to disk IO limits enable more-demanding workloads on smaller Azure VMs | Improve application performance at a smaller virtual machine footprint, improving overall efficiency and lowering application license cost.

+| Deep workload readiness | Seamless deployment and migration of any-size workload with well-documented deployment guides | Easily migrate any workload of any size to the platform. Enjoy a seamless, cost-effective deployment and migration experience.

+| Datastores for Azure VMware Solution | Use Azure NetApp Files as a storage solution for VMware workloads in Azure, reducing the need for superfluous compute nodes normally included with Azure VMware Solution expansions | Save money by eliminating the need for unnecessary compute nodes when expanding storage, resulting in significant cost savings.

+| Standard storage with cool access | Use the cool access option of Azure NetApp Files Standard service level to move inactive data transparently from Azure NetApp Files Standard service-level storage (the hot tier) to an Azure storage account (the cool tier) | Save money by transitioning data that resides within Azure NetApp Files volumes (the hot tier) by moving blocks to the lower cost storage (the cool tier). |

+These features work together to provide a high-performance file storage solution for the demands of enterprise workloads. They help to ensure that your workloads experience optimal (low) storage latency, cost and scale.

+## Simplicity and availability

+Azure NetApp Files is designed to provide simplicity and high availability for your file storage needs. Key features include:

+| Functionality | Description | Benefit |

+| - | - | - |

+| Volumes as a Service | Provision and manage volumes in minutes with a few clicks like any other Azure service | Enables businesses to quickly and easily provision and manage volumes without the need for dedicated hardware or complex configurations.

+| Native Azure Integration | Integration with the Azure portal, REST, CLI, billing, monitoring, and security | Simplifies management and ensures consistency with other Azure services, while providing a familiar interface and integration with existing tools and workflows.

+| High availability | Azure NetApp Files provides a [high availability SLA](https://azure.microsoft.com/support/legal/sla/netapp/) with automatic failover | Ensures that data is always available and accessible, avoiding downtime and disruption to business operations.

+| Application migration | Migrate applications to Azure without refactoring | Enables businesses to move their workloads to Azure quickly and easily without the need for costly and time-consuming application refactoring or redesign.

+| Cross-region and cross-zone replication | Replicate data between regions or zones | Provide disaster recovery capabilities and ensure data availability and redundancy across different Azure regions or availability zones.

+| Application volume groups | Application volume groups enable you to deploy all application volumes according to best practices in a single one-step and optimized workflow | Simplified multi-volume deployment for applications, ensuring volumes and mount points are optimized and adhere to best practices in a single step, saving time and effort.

+| Programmatic deployment | Automate deployment and management with APIs and SDKs | Enables businesses to integrate Azure NetApp Files with their existing automation and management tools, reducing the need for manual intervention and improving efficiency.

+| Fault-tolerant bare metal | Built on a fault-tolerant bare metal fleet powered by ONTAP | Ensures high performance and reliability by leveraging a robust, fault-tolerant storage platform and powerful data management capabilities provided by ONTAP.

+| Azure native billing | Integrates natively with Azure billing, providing a seamless and easy-to-use billing experience, based on hourly usage | Easily and accurately manage and track the cost of using the service, allowing for seamless budgeting and cost control. Easily track usage and expenses directly from the Azure portal, providing a unified experience for billing and management. |

+These features work together to provide a simple-to-use and highly available file storage solution to ensure that your data is easy to manage and always available, recoverable, and accessible to your applications even in an outage.

+## Data management and security

+Azure NetApp Files provides built-in data management and security capabilities to help ensure the secure storage, availability, and manageability of your data. Key features include:

+| Functionality | Description | Benefit |

+| - | - | - |

+| Efficient snapshots and backup | Advanced data protection and faster recovery of data by leveraging block-efficient, incremental snapshots and vaulting | Quickly and easily backup data and restore to a previous point in time, minimizing downtime and reducing the risk of data loss.

+| Snapshot restore to a new volume | Instantly restore data from a previously taken snapshot quickly and accurately | Reduce downtime and save time and resources that would otherwise be spent on restoring data from backups.

+| Snapshot revert | Revert volume to the state it was in when a previous snapshot was taken | Easily and quickly recover data (in-place) to a known good state, ensuring business continuity and maintaining productivity.

+| Application-aware snapshots and backup | Ensure application-consistent snapshots with guaranteed recoverability | Automate snapshot creation and deletion processes, reducing manual efforts and potential errors while increasing productivity by allowing teams to focus on other critical tasks.

+| Efficient cloning | Create and access clones in seconds | Save time and reduce costs for test, development, system refresh and analytics.

+| Data-in-transit encryption | Secure data transfers with protocol encryption | Ensure the confidentiality and integrity of data being transmitted, with peace of mind that information is safe and secure.

+| Data-at-rest encryption | Data-at-rest encryption with platform- or customer-managed keys | Prevent unrestrained access to stored data, meet compliance requirements and enhance data security.

+| Azure platform integration and compliance certifications | Compliance with regulatory requirements and Azure platform integration | Adhere to Azure standards and regulatory compliance, ensure audit and governance completion.

+| Azure Identity and Access Management (IAM) | Azure role-based access control (RBAC) service allows you to manage permissions for resources at any level | Simplify access management and improve compliance with Azure-native RBAC, empowering you to easily control user access to configuration management.

+| AD/LDAP authentication, export policies & access control lists (ACLs) | Authenticate and authorize access to data using existing AD/LDAP credentials and allow for the creation of export policies and ACLs to govern data access and usage | Prevent data breaches and ensure compliance with data security regulations, with enhanced granular control over access to data volumes, directories and files. |

+These features work together to provide a comprehensive data management solution that helps to ensure that your data is always available, recoverable, and secure.

+* [Understand NAS concepts in Azure NetApp Files](network-attached-storage-concept.md)

+* [Register for NetApp Resource Provider](azure-netapp-files-register.md)

+* [Solution architectures using Azure NetApp Files](azure-netapp-files-solution-architectures.md)

+* Automatic Managed System Identity (MSI) certificate renewal isn't currently supported. It's recommended you create an Azure monitor alert to notify you when the MSI certificate is set to expire.

+Before creating your first customer-managed key volume, you must set up:

+* You must register the feature before you can use customer-managed keys.

+## Register the feature

+You must register customer-managed keys before using it for the first time.

+1. Register the feature:

+ ```azurepowershell-interactive

+ Register-AzProviderFeature -ProviderNamespace Microsoft.NetApp -FeatureName ANFAzureKeyVaultEncryption

+ ```

+2. Check the status of the feature registration:

+ > [!NOTE]

+ > The **RegistrationState** may be in the `Registering` state for up to 60 minutes before changing to `Registered`. Wait until the status is **Registered** before continuing.

+ ```azurepowershell-interactive

+ Get-AzProviderFeature -ProviderNamespace Microsoft.NetApp -FeatureName ANFAzureKeyVaultEncryption

+ ```

+You can also use [Azure CLI commands](/cli/azure/feature) `az feature register` and `az feature show` to register the feature and display the registration status.

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

+1. Select **Save** then observe the notification communicating the status of the operation. If the operation was not successful, an error message displays. Refer to [error messages and troubleshooting](#error-messages-and-troubleshooting) for assistance in resolving the error.

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

+The process to configure a NetApp account with customer-managed keys in the Azure CLI depends on whether you are using a [system-assigned identity](#use-a-system-assigned-identity) or an [user-assigned identity](#use-a-new-user-assigned-identity).

+#### Use a system-assigned identity

+1. Update your NetApp account to use a system-assigned identity.

+ ```azurecli

+ az netappfiles account update \

+ --name <account_name> \

+ --resource-group <resource_group> \

+ --identity-type SystemAssigned

+ ```

+1. To use an access policy, create a variable that includes the principal ID of the account identity, then run `az keyvault set-policy` and assign permissions of "Get", "Encrypt", and "Decrypt".

+ ```azurecli

+ netapp_account_principal=$(az netappfiles account show \

+ --name <account_name> \

+ --resource-group <resource_group> \

+ --query identity.principalId \

+ --output tsv)

+

+ az keyvault set-policy \

+ --name <key_vault_name> \

+ --resource-group <resource-group> \

+ --object-id $netapp_account_principal \

+ --key-permissions get encrypt decrypt

+ ```

+1. Update the NetApp account with your key vault.

+ ```azurecli

+ key_vault_uri=$(az keyvault show \

+ --name <key-vault> \

+ --resource-group <resource_group> \

+ --query properties.vaultUri \

+ --output tsv)

+ az netappfiles account update --name <account_name> \

+ --resource-group <resource_group> \

+ --key-source Microsoft.Keyvault \

+ --key-vault-uri $key_vault_uri \

+ --key-name <key>

+ ```

+#### Use a new user-assigned identity

+1. Create a new user-assigned identity.

+

+ ```azurecli

+ az identity create \

+ --name <identity_name> \

+ --resource-group <resource_group>

+ ```

+1. Set an access policy for the key vault.

+ ```azurecli

+ user_assigned_identity_principal=$(az identity show \

+ --name <identity_name> \

+ --resource-group <resource_group> \

+ --query properties.principalId \

+ -output tsv)

+ az keyvault set-policy \

+ --name <key_vault_name> \

+ --resource-group <resource-group> \

+ --object-id $user_assigned_identity_principal \

+ --key-permissions get encrypt decrypt

+ ```

+

+ >[!NOTE]

+ >You can alternately [use role-based access control to grant access to the key vault](#use-role-based-access-control).

+1. Assign the user-assigned identity to the NetApp account and update the key vault encryption.

+ ```azurecli

+ key_vault_uri=$(az keyvault show \

+ --name <key-vault> \

+ --resource-group <resource_group> \

+ --query properties.vaultUri \

+ --output tsv)

+ user_assigned_identity=$(az identity show \

+ --name <identity_name> \

+ --resource-group <resource_group> \

+ --query id \

+ -output tsv)

+ az netappfiles account update --name <account_name> \

+ --resource-group <resource_group> \

+ --identity-type UserAssigned \

+ --key-source Microsoft.Keyvault \

+ --key-vault-uri $key_vault_uri \

+ --key-name <key> \

+ --keyvault-resource-id <key-vault> \

+ --user-assigned-identity $user_assigned_identity

+ ```

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

+The process to configure a NetApp account with customer-managed keys in the Azure CLI depends on whether you are using a [system-assigned identity](#enable-access-for-system-assigned-identity) or an [user-assigned identity](#enable-access-for-user-assigned-identity).

+#### Enable access for system-assigned identity

+1. Update your NetApp account to use system-assigned identity.

+ ```azurepowershell

+ $netappAccount = Update-AzNetAppFilesAccount -ResourceGroupName <resource_group> -Name <account_name> -AssignIdentity

+ ```

+1. To use an access policy, run `Set-AzKeyVaultAccessPolicy` with the key vault name, the principal ID of the account identity, and the permissions "Get", "Encrypt", and "Decrypt".

+ ```azurepowershell

+ Set-AzKeyVaultAccessPolicy -VaultName <key_vault_name> -ResourceGroupname <resource_group> -ObjectId $netappAccount.Identity.PrincipalId -PermissionsToKeys get,encrypt,decrypt

+ ```

+1. Update your NetApp account with the key vault information.

+ ```azurepowershell

+ Update-AzNetAppFilesAccount -ResourceGroupName $netappAccount.ResourceGroupName -AccountName $netappAccount.ResourceGroupName -KeyVaultEncryption -KeyVaultUri <keyVaultUri> -KeyName <keyName>

+ ```

+#### Enable access for user-assigned identity

+1. Create a new user-assigned identity.

+ ```azurepowershell

+ $userId = New-AzUserAssignedIdentity -ResourceGroupName <resourceGroupName> -Name $userIdName

+ ```

+1. Assign the access policy to the key vault.

+ ```azurepowershell

+ Set-AzKeyVaultAccessPolicy -VaultName <key_vault_name> `

+ -ResourceGroupname <resource_group> `

+ -ObjectId $userId.PrincipalId `

+ -PermissionsToKeys get,encrypt,decrypt `

+ -BypassObjectIdValidation

+ ```

+

+ >[!NOTE]

+ >You can alternately [use role-based access control to grant access to the key vault](#use-role-based-access-control).

+1. Assign the user-assigned identity to the NetApp account and update the key vault encryption.

+ ```azurepowershell

+ $netappAccount = Update-AzNetAppFilesAccount -ResourceGroupName <resource_group> `

+ -Name <account_name> `

+ -IdentityType UserAssigned `

+ -UserAssignedIdentityId $userId.Id `

+ -KeyVaultEncryption `

+ -KeyVaultUri <keyVaultUri> `

+ -KeyName <keyName> `

+ -EncryptionUserAssignedIdentity $userId.Id

+ ```

+ > The **RegistrationState** may be in the `Registering` state for up to 60 minutes before changing to `Registered`. Wait until the status is **Registered** before continuing.

+## January 2024

+* [Customer-managed keys](configure-customer-managed-keys.md) is now generally available (GA).

+ You still must register the feature before using it for the first time.

+Bicep supports an optional configuration file named `bicepconfig.json`. Within this file, you can add values that customize your Bicep development experience.

+To customize configuration, create this file in the same directory, or a parent directory of your Bicep files. If multiple parent directories contain `bicepconfig.json` files, Bicep uses configuration from the nearest one. If a configuration file is not found, Bicep uses default values.

+You can enable experimental features by adding the following section to your `bicepconfig.json` file.

+Here is an example of enabling features 'compileTimeImports' and 'userDefinedFunctions`.

+ "compileTimeImports": true,

+ "userDefinedFunctions": true

+For information on the current set of experimental features, see [Experimental Features](https://aka.ms/bicep/experimental-features).

+* User-defined functions are not supported at the moment. However, an experimental feature is currently accessible. For more information, see [User-defined functions in Bicep](./user-defined-functions.md).

+using 'main.bicep'

+In addition to be used in the `type` statement, type expressions can also be used in these places for creating user-defined data types:

+The existing cluster vSAN storage capacity can be expanded by connecting Azure storage resources including Azure NetApp Files or Azure Elastic SAN. Virtual machines can be migrated between vSAN datastores and other datastores non-disruptively using storage vMotion. Expanding datastore capacity using Azure storage resources allows increased datastore capacity without scaling the clusters.

+### Azure NetApp Files

+Azure NetApp Files is an enterprise-class, high-performance, metered file storage service. The service supports the demanding enterprise file-workloads in the cloud: databases, SAP, and high-performance computing applications, with no code changes.

+You can create Network File System (NFS) datastores with Azure NetApp Files volumes and attach them to clusters of your choice. By using NFS datastores backed by Azure NetApp Files, you can expand your storage instead of scaling the clusters. Azure NetApp Files is available in [Ultra, Premium and Standard performance tiers](../azure-netapp-files/azure-netapp-files-service-levels.md) to allow for adjusting performance and cost to the requirements of the workloads.

+For more information, see [Attach Azure NetApp Files datastores to Azure VMware Solution hosts](attach-azure-netapp-files-to-azure-vmware-solution-hosts.md).

+### Azure Elastic SAN

+Azure Elastic storage area network (SAN) is MicrosoftΓÇÖs answer to the problem of workload optimization and integration between your large-scale databases and performance-intensive mission-critical applications.

+Azure VMware Solution supports attaching iSCSI datastores as a persistent storage option. You can create Virtual Machine File System (VMFS) datastores with Azure Elastic SAN volumes and attach them to clusters of your choice. By using VMFS datastores backed by Azure Elastic SAN, you can expand your storage instead of scaling the clusters.

+For more information, see [Use Azure VMware Solution with Azure Elastic SAN](configure-azure-elastic-san.md).

+You can use Azure storage services in workloads running in your private cloud. The Azure storage services include Storage Accounts, Table Storage, Blob Storage, and file storage (Azure Files and Azure NetApp Files). The connection of workloads to Azure storage services doesn't traverse the internet. This connectivity provides more security and enables you to use SLA-based Azure storage services in your private cloud workloads.

+## Storage

+Azure VMware Solution supports the expansion of datastore capacity beyond what is included with vSAN using Azure storage services, enabling you to expand datastore capacity without scaling the clusters. For more information, see [Datastore capacity expansion options](concepts-storage.md#datastore-capacity-expansion-options).

+# [JavaScript Model v4](#tab/javascript-v4)

+- [Node.js](https://nodejs.org/en/download/), version 18.x or above.

+ > [!NOTE]

+ > For more information about the supported versions of Node.js, see [Azure Functions runtime versions documentation](../azure-functions/functions-versions.md#languages).

+- [Azure Functions Core Tools](https://github.com/Azure/azure-functions-core-tools#installing) (v4 or higher preferred) to run Azure Function apps locally and deploy to Azure.

+- The [Azure CLI](/cli/azure) to manage Azure resources.

+# [JavaScript Model v3](#tab/javascript-v3)

+- A code editor, such as [Visual Studio Code](https://code.visualstudio.com/)

+- [Node.js](https://nodejs.org/en/download/), version 18.x or above.

+ # [JavaScript Model v4](#tab/javascript-v4)

+ ```bash

+ func init --worker-runtime javascript --model V4

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ func init --worker-runtime javascript --model V3

+ # [JavaScript Model v4](#tab/javascript-v4)

+ Confirm and update `host.json`'s extensionBundle to version _4.*_ or later to get Web PubSub support.

+ ```json

+ {

+ "extensionBundle": {

+ "id": "Microsoft.Azure.Functions.ExtensionBundle",

+ "version": "[4.*, 5.0.0)"

+ }

+ }

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ Confirm and update `host.json`'s extensionBundle to version _3.3.0_ or later to get Web PubSub support.

+ # [JavaScript Model v4](#tab/javascript-v4)

+ - Update `src/functions/index.js` and copy following codes.

+ ```js

+ const { app } = require('@azure/functions');

+ const { readFile } = require('fs/promises');

+

+ app.http('index', {

+ methods: ['GET', 'POST'],

+ authLevel: 'anonymous',

+ handler: async (context) => {

+ const content = await readFile('https://docsupdatetracker.net/index.html', 'utf8', (err, data) => {

+ if (err) {

+ context.err(err)

+ return

+ }

+ });

+

+ return {

+ status: 200,

+ headers: {

+ 'Content-Type': 'text/html'

+ },

+ body: content,

+ };

+ }

+ });

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ # [JavaScript Model v4](#tab/javascript-v4)

+ - Update `src/functions/negotiate` and copy following codes.

+ ```js

+ const { app, input } = require('@azure/functions');

+

+ const connection = input.generic({

+ type: 'webPubSubConnection',

+ name: 'connection',

+ userId: '{headers.x-ms-client-principal-name}',

+ hub: 'simplechat'

+ });

+

+ app.http('negotiate', {

+ methods: ['GET', 'POST'],

+ authLevel: 'anonymous',

+ extraInputs: [connection],

+ handler: async (request, context) => {

+ return { body: JSON.stringify(context.extraInputs.get('connection')) };

+ },

+ });

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ # [JavaScript Model v4](#tab/javascript-v4)

+ - Update `src/functions/message.js` and copy following codes.

+ ```js

+ const { app, output, trigger } = require('@azure/functions');

+

+ const wpsMsg = output.generic({

+ type: 'webPubSub',

+ name: 'actions',

+ hub: 'simplechat',

+ });

+

+ const wpsTrigger = trigger.generic({

+ type: 'webPubSubTrigger',

+ name: 'request',

+ hub: 'simplechat',

+ eventName: 'message',

+ eventType: 'user'

+ });

+

+ app.generic('message', {

+ trigger: wpsTrigger,

+ extraOutputs: [wpsMsg],

+ handler: async (request, context) => {

+ context.extraOutputs.set(wpsMsg, [{

+ "actionName": "sendToAll",

+ "data": `[${context.triggerMetadata.connectionContext.userId}] ${request.data}`,

+ "dataType": request.dataType

+ }]);

+

+ return {

+ data: "[SYSTEM] ack.",

+ dataType: "text",

+ };

+ }

+ });

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ # [JavaScript Model v4](#tab/javascript-v4)

+ # [JavaScript Model v3](#tab/javascript-v3)

+ # [JavaScript Model v4](#tab/javascript-v4)

+ ```azurecli

+ az functionapp create --resource-group WebPubSubFunction --consumption-plan-location <REGION> --runtime node --runtime-version 18 --functions-version 4 --name <FUNCIONAPP_NAME> --storage-account <STORAGE_NAME>

+ ```

+ > [!NOTE]

+ > Check [Azure Functions runtime versions documentation](../azure-functions/functions-versions.md#languages) to set `--runtime-version` parameter to supported value.

+ # [JavaScript Model v3](#tab/javascript-v3)

+ az functionapp create --resource-group WebPubSubFunction --consumption-plan-location <REGION> --runtime node --runtime-version 18 --functions-version 4 --name <FUNCIONAPP_NAME> --storage-account <STORAGE_NAME>

+# [JavaScript Model v4](#tab/javascript-v4)

+The following example shows a Web PubSub trigger [JavaScript function](../azure-functions/functions-reference-node.md).

+```js

+const { app, trigger } = require('@azure/functions');

+const wpsTrigger = trigger.generic({

+ type: 'webPubSubTrigger',

+ name: 'request',

+ hub: '<hub>',

+ eventName: 'message',

+ eventType: 'user'

+});

+app.generic('message', {

+ trigger: wpsTrigger,

+ handler: async (request, context) => {

+ context.log('Request from: ', request.connectionContext.userId);

+ context.log('Request message data: ', request.data);

+ context.log('Request message dataType: ', request.dataType);

+ }

+});

+```

+`WebPubSubTrigger` binding also supports return value in synchronize scenarios, for example, system `Connect` and user event, when server can check and deny the client request, or send message to the request client directly. In JavaScript weakly typed language, it's deserialized regarding the object keys. And `EventErrorResponse` has the highest priority compare to rest objects, that if `code` is in the return, then it's parsed to `EventErrorResponse` and client connection is dropped.

+```js

+app.generic('message', {

+ trigger: wpsTrigger,

+ handler: async (request, context) => {

+ return {

+ "data": "ack",

+ "dataType" : "text"

+ };

+ }

+});

+```

+# [JavaScript Model v3](#tab/javascript-v3)

+# [JavaScript Model v4](#tab/javascript-v4)

+```js

+const { app, input } = require('@azure/functions');

+const connection = input.generic({

+ type: 'webPubSubConnection',

+ name: 'connection',

+ userId: '{query.userId}',

+ hub: '<hub>'

+});

+app.http('negotiate', {

+ methods: ['GET', 'POST'],

+ authLevel: 'anonymous',

+ extraInputs: [connection],

+ handler: async (request, context) => {

+ return { body: JSON.stringify(context.extraInputs.get('connection')) };

+ },

+});

+```

+# [JavaScript Model v3](#tab/javascript-v3)

+> Limited to the binding parameter types don't support a way to pass list nor array, the `WebPubSubConnection` is not fully supported with all the parameters server SDK has, especially `roles`, and also includes `groups` and `expiresAfter`. In the case customer needs to add roles or delay build the access token in the function, it's suggested to work with [server SDK for C#](/dotnet/api/overview/azure/messaging.webpubsub-readme).

+# [JavaScript Model v4](#tab/javascript-v4)

+> [!NOTE]

+> Limited to the binding parameter types don't support a way to pass list nor array, the `WebPubSubConnection` is not fully supported with all the parameters server SDK has, especially `roles`, and also includes `groups` and `expiresAfter`. In the case customer needs to add roles or delay build the access token in the function, it's suggested to work with [server SDK for JavaScript](/javascript/api/overview/azure/web-pubsub).

+> ```js

+> const { app } = require('@azure/functions');

+> const { WebPubSubServiceClient } = require('@azure/web-pubsub');

+> app.http('negotiate', {

+> methods: ['GET', 'POST'],

+> authLevel: 'anonymous',

+> handler: async (request, context) => {

+> const serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, "<hub>");

+> let token = await serviceClient.getAuthenticationToken({ userId: req.query.userid, roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });

+> return { body: token.url };

+> },

+> });

+> ```

+# [JavaScript Model v3](#tab/javascript-v3)

+> Limited to the binding parameter types don't support a way to pass list nor array, the `WebPubSubConnection` is not fully supported with all the parameters server SDK has, especially `roles`, and also includes `groups` and `expiresAfter`. In the case customer needs to add roles or delay build the access token in the function, it's suggested to work with [server SDK for JavaScript](/javascript/api/overview/azure/web-pubsub).

+> let token = await serviceClient.getAuthenticationToken({ userId: req.query.userid, roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });

+# [JavaScript Model v4](#tab/javascript-v4)

+```js

+const { app, input } = require('@azure/functions');

+const wpsContext = input.generic({

+ type: 'webPubSubContext',

+ name: 'wpsContext'

+});

+app.http('connect', {

+ methods: ['GET', 'POST'],

+ authLevel: 'anonymous',

+ extraInputs: [wpsContext],

+ handler: async (request, context) => {

+ var wpsRequest = context.extraInputs.get('wpsContext');

+ return { "userId": wpsRequest.request.connectionContext.userId };

+ }

+});

+```

+# [JavaScript Model v3](#tab/javascript-v3)

+# [JavaScript Model v4](#tab/javascript-v4)

+`WebPubSubConnection` provides below properties.

+| Binding Name | Description |

+|||

+| baseUrl | Web PubSub client connection uri. |

+| url | Absolute Uri of the Web PubSub connection, contains `AccessToken` generated base on the request. |

+| accessToken | Generated `AccessToken` based on request UserId and service information. |

+# [JavaScript Model v3](#tab/javascript-v3)

+# [JavaScript Model v4](#tab/javascript-v4)

+```js

+const { app, output } = require('@azure/functions');

+const wpsMsg = output.generic({

+ type: 'webPubSub',

+ name: 'actions',

+ hub: '<hub>',

+});

+app.http('message', {

+ methods: ['GET', 'POST'],

+ authLevel: 'anonymous',

+ extraOutputs: [wpsMsg],

+ handler: async (request, context) => {

+ context.extraOutputs.set(wpsMsg, [{

+ "actionName": "sendToAll",

+ "data": `Hello world`,

+ "dataType": `text`

+ }]);

+ }

+});

+```

+# [JavaScript Model v3](#tab/javascript-v3)

+# [JavaScript Model v4](#tab/javascript-v4)

+In weakly typed language like `javascript`, **`actionName`** is the key parameter to resolve the type, available actions are listed as below.

+| ActionName | Properties |

+| -- | -- |

+| `sendToAll`|Data, DataType, Excluded |

+| `sendToGroup`|Group, Data, DataType, Excluded |

+| `sendToUser`|UserId, Data, DataType |

+| `sendToConnection`|ConnectionId, Data, DataType |

+| `addUserToGroup`|UserId, Group |

+| `removeUserFromGroup`|UserId, Group |

+| `removeUserFromAllGroups`|UserId |

+| `addConnectionToGroup`|ConnectionId, Group |

+| `removeConnectionFromGroup`|ConnectionId, Group |

+| `closeAllConnections`|Excluded, Reason |

+| `closeClientConnection`|ConnectionId, Reason |

+| `closeGroupConnections`|Group, Excluded, Reason |

+| `grantPermission`|ConnectionId, Permission, TargetName |

+| `revokePermission`|ConnectionId, Permission, TargetName |

+> [!IMPORTANT]

+> The message data property in the send message related actions must be `string` if data type is set to `json` or `text` to avoid data conversion ambiguity. Please use `JSON.stringify()` to convert the json object in need. This is applied to any place using message property, for example, `UserEventResponse.Data` working with `WebPubSubTrigger`.

+>

+> When data type is set to `binary`, it's allowed to leverage binding naturally supported `dataType` as `binary` configured in the `function.json`, see [Trigger and binding definitions](../azure-functions/functions-triggers-bindings.md?tabs=csharp#trigger-and-binding-definitions) for details.

+# [JavaScript Model v3](#tab/javascript-v3)

+| `sendToAll`|Data, DataType, Excluded |

+| `sendToGroup`|Group, Data, DataType, Excluded |

+| `sendToUser`|UserId, Data, DataType |

+| `sendToConnection`|ConnectionId, Data, DataType |

+| `addUserToGroup`|UserId, Group |

+| `removeUserFromGroup`|UserId, Group |

+| `removeUserFromAllGroups`|UserId |

+| `addConnectionToGroup`|ConnectionId, Group |

+| `removeConnectionFromGroup`|ConnectionId, Group |

+| `closeAllConnections`|Excluded, Reason |

+| `closeClientConnection`|ConnectionId, Reason |

+| `closeGroupConnections`|Group, Excluded, Reason |

+| `grantPermission`|ConnectionId, Permission, TargetName |

+| `revokePermission`|ConnectionId, Permission, TargetName |

+ Title: Integrate - How to use Web PubSub for Socket.IO with Azure API Management

+description: A how-to guide about how to use Web PubSub for Socket.IO with Azure API Management

+keywords: Socket.IO, Socket.IO on Azure, webapp Socket.IO, Socket.IO integration, APIM

+# How-to: Use Web PubSub for Socket.IO with Azure API Management

+Azure API Management service provides a hybrid, multicloud management platform for APIs across all environments. This article shows you how to add real-time capability to your application with Azure API Management and Web PubSub for Socket.IO.

+## Limitations

+Socket.IO clients support WebSocket and Long Polling and by default, the client connects to the service with Long Polling and then upgrade to WebSocket. However, as for now, API Management doesn't yet support different types of APIs (WebSocket or Http) with the same path. You must set either `websocket` or `polling` in client settings.

+## Create resources

+

+In order to follow the step-by-step guide, you need

+- Follow [Create a Web PubSub for Socket.IO resource](./socketio-quickstart.md#create-a-web-pubsub-for-socketio-resource) to create a Web PubSub for Socket.IO instance.

+- Follow [Quickstart: Use an ARM template to deploy Azure API Management](../api-management/quickstart-arm-template.md) and create an API Management instance.

+## Set up API Management

+### Configure APIs when client connects with `websocket` transport

+This section describes the steps to configure API Management when the Socket.IO clients connect with `websocket` transport.

+1. Go to **APIs** tab in the portal for API Management instance, select **Add API** and choose **WebSocket**, **Create** with the following parameters:

+ - Display name: `Web PubSub for Socket.IO`

+ - Web service URL: `wss://<your-webpubsubforsocketio-service-url>/clients/socketio/hubs/eio_hub`

+ - API URL suffix: `clients/socketio/hubs/eio_hub`

+ The hub name can be changed to meet your application.

+1. Press **Create** to create the API and after created, switch to **Settings** tab and uncheck **Subscription required** for quick demo purpose

+### Configure APIs when client connects with `polling` transport

+This section describes the steps to configure API Management when the Socket.IO clients connect with `websocket` transport.

+1. Go to **APIs** tab in the portal for API Management instance, select **Add API** and choose **WebSocket**, **Create** with the following parameters:

+ - Display name: `Web PubSub for Socket.IO`

+ - Web service URL: `https://<your-webpubsubforsocketio-service-url>/clients/socketio/hubs/eio_hub`

+ - API URL suffix: `clients/socketio/hubs/eio_hub`

+ The hub name can be changed to meet your application.

+1. Switch to **Settings** tab and uncheck Subscription required for quick demo purpose

+1. Switch to **Design** tab and select **Add operation**, and Save with the following parameters:

+ Add operation for post data

+ - Display name: connect

+ - URL: POST /

+ Add operation for get data

+ - Display name: connect get

+ - GET /

+## Try Sample

+Now, the traffic can reach Web PubSub for Socket.IO through API Management. There are some configurations in application. LetΓÇÖs use a chat application as an example.

+Clone GitHub repo https://github.com/Azure/azure-webpubsub and investigate to `sdk/webpubsub-socketio-extension/examples/chat` folder

+Then make some changes to let the sample work with API Management

+1. Open `public/main.js` and it's the Socket.IO client side codes

+ Edit the constructor of Socket.IO. You have to select either `websocket` or `polling` as the transport:

+ ```javascript

+ const webPubSubEndpoint = "https://<api-management-url>";

+ var socket = io(webPubSubEndpoint, {

+ transports: ["websocket"], // Depends on your transport choice. If you use WebSocket in API Management, set it to "websocket". If choosing Long Polling, set it to "polling"

+ path: "/clients/socketio/hubs/eio_hub", // The path also need to match the settings in API Management

+ });

+ ```

+2. On the **Keys** tab of Web PubSub for Socket.IO. Copy the **Connection String** and use the following command to run the server:

+ ```bash

+ npm install

+ npm run start -- <connection-string>

+ ```

+3. According to the output, use browser to visit the endpoint

+ ```

+ Visit http://localhost:3000

+ ```

+4. In the sample, you can chat with other users.

+## Next steps

+> [!div class="nextstepaction"]

+> [Check out more Socket.IO samples](https://aka.ms/awps/sio/sample)

+* [Node.js](https://nodejs.org/en/download/), version 18.x or above.

+ # [JavaScript Model v4](#tab/javascript-v4)

+ func init --worker-runtime javascript --model V4

+ # [JavaScript Model v3](#tab/javascript-v3)

+ ```bash

+ func init --worker-runtime javascript --model V3

+ ```

+

+2. Create an `index` function to read and host a static web page for clients.

+

+ # [JavaScript Model v4](#tab/javascript-v4)

+ Update `src/functions/index.js` with following code, which serves the HTML content as a static site.

+ ```js

+ const { app } = require('@azure/functions');

+ const { readFile } = require('fs/promises');

+

+ app.http('index', {

+ methods: ['GET', 'POST'],

+ authLevel: 'anonymous',

+ handler: async (context) => {

+ const content = await readFile('https://docsupdatetracker.net/index.html', 'utf8', (err, data) => {

+ if (err) {

+ context.err(err)

+ return

+ }

+ });

+

+ return {

+ status: 200,

+ headers: {

+ 'Content-Type': 'text/html'

+ },

+ body: content,

+ };

+ }

+ });

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ Update `index/index.js` with following code, which serves the HTML content as a static site.

+ ```js

+ var fs = require("fs");

+ var path = require("path");

+ module.exports = function (context, req) {

+ let index = path.join(

+ context.executionContext.functionDirectory,

+ "/../https://docsupdatetracker.net/index.html"

+ );

+ fs.readFile(index, "utf8", function (err, data) {

+ if (err) {

+ console.log(err);

+ context.done(err);

+ return;

+ }

+ context.res = {

+ status: 200,

+ headers: {

+ "Content-Type": "text/html",

+ },

+ body: data,

+ };

+ context.done();

+ });

+ };

+ ```

+

+4. Create an `https://docsupdatetracker.net/index.html` file under the root folder.

+

+ # [JavaScript Model v4](#tab/javascript-v4)

+ Update `src/functions/negotiate.js` to use [`WebPubSubConnection`](reference-functions-bindings.md#input-binding) that contains the generated token.

+ ```js

+ const { app, input } = require('@azure/functions');

+

+ const connection = input.generic({

+ type: 'webPubSubConnection',

+ name: 'connection',

+ hub: '%hubName%'

+ });

+

+ app.http('negotiate', {

+ methods: ['GET', 'POST'],

+ authLevel: 'anonymous',

+ extraInputs: [connection],

+ handler: async (request, context) => {

+ return { body: JSON.stringify(context.extraInputs.get('connection')) };

+ },

+ });

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ - Update `negotiate/function.json` to include an input binding [`WebPubSubConnection`](reference-functions-bindings.md#input-binding), with the following json code.

+ - Update `negotiate/index.js` to return the `connection` binding that contains the generated token.

+

+ func new --template "Azure Event Hub trigger" --name messagehandler

+ # [JavaScript Model v4](#tab/javascript-v4)

+ - Update `src/functions/messagehandler.js` to add [Web PubSub output binding](reference-functions-bindings.md#output-binding) with the following json code. We use variable `%hubName%` as the hub name for both IoT eventHubName and Web PubSub hub.

+ ```js

+ const { app, output } = require('@azure/functions');

+

+ const wpsAction = output.generic({

+ type: 'webPubSub',

+ name: 'action',

+ hub: '%hubName%'

+ });

+

+ app.eventHub('messagehandler', {

+ connection: 'IOTHUBConnectionString',

+ eventHubName: '%hubName%',

+ cardinality: 'many',

+ extraOutputs: [wpsAction],

+ handler: (messages, context) => {

+ var actions = [];

+ if (Array.isArray(messages)) {

+ context.log(`Event hub function processed ${messages.length} messages`);

+ for (const message of messages) {

+ context.log('Event hub message:', message);

+ actions.push({

+ actionName: "sendToAll",

+ data: JSON.stringify({

+ IotData: message,

+ MessageDate: message.date || new Date().toISOString(),

+ DeviceId: message.deviceId,

+ })});

+ }

+ } else {

+ context.log('Event hub function processed message:', messages);

+ actions.push({

+ actionName: "sendToAll",

+ data: JSON.stringify({

+ IotData: message,

+ MessageDate: message.date || new Date().toISOString(),

+ DeviceId: message.deviceId,

+ })});

+ }

+ context.extraOutputs.set(wpsAction, actions);

+ }

+ });

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ - Update _messagehandler/function.json_ to add [Web PubSub output binding](reference-functions-bindings.md#output-binding) with the following json code. We use variable `%hubName%` as the hub name for both IoT eventHubName and Web PubSub hub.

+ - Update `messagehandler/index.js` with the following code. It sends every message from IoT hub to every client connected to Web PubSub service using the Web PubSub output bindings.

+

+ > The `Azure Event Hub trigger` function trigger used in the sample has dependency on Azure Storage, but you can use a local storage emulator when the function is running locally. If you get an error such as `There was an error performing a read operation on the Blob Storage Secret Repository. Please ensure the 'AzureWebJobsStorage' connection string is valid.`, you'll need to download and enable [Storage Emulator](../storage/common/storage-use-emulator.md).

+# [JavaScript Model v4](#tab/javascript-v4)

+* [Node.js](https://nodejs.org/en/download/), version 18.x or above.

+ > [!NOTE]

+ > For more information about the supported versions of Node.js, see [Azure Functions runtime versions documentation](../azure-functions/functions-versions.md#languages).

+* [Azure Functions Core Tools](https://github.com/Azure/azure-functions-core-tools#installing) (V4 or higher preferred) to run Azure Function apps locally and deploy to Azure.

+* The [Azure CLI](/cli/azure) to manage Azure resources.

+# [JavaScript Model v3](#tab/javascript-v3)

+* A code editor, such as [Visual Studio Code](https://code.visualstudio.com/)

+* [Node.js](https://nodejs.org/en/download/), version 18.x or above.

+ # [JavaScript Model v4](#tab/javascript-v4)

+ ```bash

+ func init --worker-runtime javascript --model V4

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ func init --worker-runtime javascript --model V3

+ # [JavaScript Model v4](#tab/javascript-v4)

+ Confirm or update `host.json`'s extensionBundle to version _4.*_ or later to get Web PubSub support. For updating the `host.json`, open the file in editor, and then replace the existing version extensionBundle to version _4.*_ or later.

+ ```json

+ {

+ "extensionBundle": {

+ "id": "Microsoft.Azure.Functions.ExtensionBundle",

+ "version": "[4.*, 5.0.0)"

+ }

+ }

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ Confirm or update `host.json`'s extensionBundle to version _3.3.0_ or later to get Web PubSub support. For updating the `host.json`, open the file in editor, and then replace the existing version extensionBundle to version _3.3.0_ or later.

+ # [JavaScript Model v4](#tab/javascript-v4)

+ - Update `src/functions/index.js` and copy following codes.

+ ```js

+ const { app } = require('@azure/functions');

+ const { readFile } = require('fs/promises');

+

+ app.http('index', {

+ methods: ['GET', 'POST'],

+ authLevel: 'anonymous',

+ handler: async (context) => {

+ const content = await readFile('https://docsupdatetracker.net/index.html', 'utf8', (err, data) => {

+ if (err) {

+ context.err(err)

+ return

+ }

+ });

+

+ return {

+ status: 200,

+ headers: {

+ 'Content-Type': 'text/html'

+ },

+ body: content,

+ };

+ }

+ });

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ - Update `index/function.json` and copy following json codes.

+ - Update `index/index.js` and copy following codes.

+ # [JavaScript Model v4](#tab/javascript-v4)

+ - Update `src/functions/negotiate.js` and copy following codes.

+ ```js

+ const { app, input } = require('@azure/functions');

+

+ const connection = input.generic({

+ type: 'webPubSubConnection',

+ name: 'connection',

+ hub: 'notification'

+ });

+

+ app.http('negotiate', {

+ methods: ['GET', 'POST'],

+ authLevel: 'anonymous',

+ extraInputs: [connection],

+ handler: async (request, context) => {

+ return { body: JSON.stringify(context.extraInputs.get('connection')) };

+ },

+ });

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ - Update `negotiate/function.json` and copy following json codes.

+ - Create a folder negotiate and update `negotiate/index.js` and copy following codes.

+ # [JavaScript Model v4](#tab/javascript-v4)

+ - Update `src/functions/notification.js` and copy following codes.

+ ```js

+ const { app, output } = require('@azure/functions');

+

+ const wpsAction = output.generic({

+ type: 'webPubSub',

+ name: 'action',

+ hub: 'notification'

+ });

+

+ app.timer('notification', {

+ schedule: "*/10 * * * * *",

+ extraOutputs: [wpsAction],

+ handler: (myTimer, context) => {

+ context.extraOutputs.set(wpsAction, {

+ actionName: 'sendToAll',

+ data: `[DateTime: ${new Date()}] Temperature: ${getValue(22, 1)}\xB0C, Humidity: ${getValue(40, 2)}%`,

+ dataType: 'text',

+ });

+ },

+ });

+

+ function getValue(baseNum, floatNum) {

+ return (baseNum + 2 * floatNum * (Math.random() - 0.5)).toFixed(3);

+ }

+ ```

+ # [JavaScript Model v3](#tab/javascript-v3)

+ - Update `notification/function.json` and copy following json codes.

+ - Update `notification/index.js` and copy following codes.

+ # [JavaScript Model v4](#tab/javascript-v4)

+ # [JavaScript Model v3](#tab/javascript-v3)

+ # [JavaScript Model v4](#tab/javascript-v4)

+ ```azurecli

+ az functionapp create --resource-group WebPubSubFunction --consumption-plan-location <REGION> --runtime node --runtime-version 18 --functions-version 4 --name <FUNCIONAPP_NAME> --storage-account <STORAGE_NAME>

+ ```

+ > [!NOTE]

+ > Check [Azure Functions runtime versions documentation](../azure-functions/functions-versions.md#languages) to set `--runtime-version` parameter to supported value.

+ # [JavaScript Model v3](#tab/javascript-v3)

+ az functionapp create --resource-group WebPubSubFunction --consumption-plan-location <REGION> --runtime node --runtime-version 18 --functions-version 4 --name <FUNCIONAPP_NAME> --storage-account <STORAGE_NAME>

+## What's new in MABS V3 UR2 Hotfix?

+This update contains the following enhancement to improve the backup time. For more information on the enhancements and the installation, see the [KB article](https://help.microsoft.com/support/5031799).

+**Removed File Catalog dependency for online backup of file/folder workloads**: This update removes the dependency of MABS V3 on File Catalog (list of files in a recovery point maintained in the cloud) which was needed to restore individual files and folders from the online recovery points. This Hotfix allows MABS V3 UR2 to use a modern *iSCSI mount* method to provide individual file restoration.

+**Advantages**:

+- Reduces the backup time by up to *15%* because file catalog metadata (list of files in a recovery point) isn't generated during the backup operation.

+>[!Note]

+>We recommend that you update your MABS V3 installation to Hotfix for Update Rollup 2 to benefit from the enhancement. Ensure that you also update your MARS Agent to the latest version (2.0.9262.0 or higher).

+Because the Developer SKU bastion resource isn't dedicated, the features for the Developer SKU are limited. See the Bastion configuration settings [SKU](configuration-settings.md) section for features by SKU. You can always upgrade the Developer SKU to a higher SKU if you need more features. See [Upgrade a SKU](upgrade-sku.md).

+ * If you have a virtual network, make sure you have the rights to write to it.

+If just-in-time (JIT) is enabled, you might need to add additional role assignments to connect to Bastion. Add the following permissions to the user, and then try reconnecting to Bastion. For more information, see [Enable just-in-time access on VMs](../defender-for-cloud/just-in-time-access-usage.md).

+| Setting | Description|

+|||

+|Microsoft.Security/locations/jitNetworkAccessPolicies/read|Gets the just-in-time network access policies|

+Microsoft.Security/locations/jitNetworkAccessPolicies/write | Creates a new just-in-time network access policy or updates an existing one |

+**A:** This happens when there's either a network connectivity issue between your web browser and Azure Bastion (your client Internet firewall might be blocking WebSockets traffic or similar), or between the Azure Bastion and your target VM. Most cases include an NSG applied either to AzureBastionSubnet, or on your target VM subnet that is blocking the RDP/SSH traffic in your virtual network. Allow WebSockets traffic on your client internet firewall, and check the NSGs on your target VM subnet. See [Unable to connect to virtual machine](#connectivity) to learn how to use **Connection Troubleshoot** to troubleshoot your connectivity issues.

+> [Download latest version (``2.14.12``)](https://aka.ms/cosmosdb-emulator)

+## Latest version ``2.14.12``

+> *Released March 20, 2023*

+- This release fixes an issue impacting Gremlin and Table endpoint API types. Prior to this fix a client application fails with a 500 status code when trying to connect to the public emulator's endpoint.

+For **shared throughput databases**, start the merge by using `az cosmosdb sql database merge`.

+```azurecli

+az cosmosdb sql database merge \

+ --account-name '<cosmos-account-name>'

+ --name '<cosmos-database-name>'

+ --resource-group '<resource-group-name>'

+```

+```http

+POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/sqlDatabases/{databaseName}/partitionMerge?api-version=2023-11-15-preview

+```

+For **shared-throughput databases**, start the merge by using [`az cosmosdb mongodb database merge`](/cli/azure/cosmosdb/mongodb/database?view=azure-cli-latest).

+```azurecli

+az cosmosdb mongodb database merge \

+ --account-name '<cosmos-account-name>'

+ --name '<cosmos-database-name>'

+ --resource-group '<resource-group-name>'

+```

+```http

+POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/mongodbDatabases/{databaseName}/partitionMerge?api-version=2023-11-15-preview

+```

+For **provisioned containers**, start the merge by using [`az cosmosdb mongodb collection merge`](/cli/azure/cosmosdb/mongodb/collection#az-cosmosdb-mongodb-collection-merge).

+>[!NOTE]

+>The confirmation process can take up to 24 hours.

+> [!NOTE]

+> You can only monitor SSIS operation with Azure Monitor in Azure Data Factory, not in Azure Synapse Pipelines.

+Cross-tenant management enables you to view and manage the security posture of multiple tenants in Defender for Cloud by using [Azure Lighthouse](../lighthouse/overview.md). Manage multiple tenants efficiently, from a single view, without having to sign in to each tenant's directory.

+## How cross-tenant management works in Defender for Cloud

+You're able to review and manage subscriptions across multiple tenants in the same way that you manage multiple subscriptions in a single tenant.

+From the top menu bar, select the filter icon, and select the subscriptions, from each tenant's directory, you'd like to view.

+This article explains how cross-tenant management works in Defender for Cloud. To discover how Azure Lighthouse can simplify cross-tenant management within an enterprise that uses multiple Microsoft Entra tenants, see [Azure Lighthouse in enterprise scenarios](../lighthouse/concepts/enterprise.md).

+The **Networking** features of Defender for Cloud include:

+The network map can show you your Azure resources in a **Topology** view and a **Traffic** view.

+- The lines connecting the resources in the map let you know which resources are associated with each other, and how your Azure network is structured.

+- You can select any of the resources to drill down into them and view the details of that resource and its recommendations directly, and in the context of the Network map.

+ - **Security health**: You can filter the map based on Severity (High, Medium, Low) of your Azure resources.

+1. You can select **Reset** in top left corner at any time to return the map to its default state.

+1. When you select a specific resource on the map, the right pane opens and gives you general information about the resource, connected security solutions if there are any, and the recommendations relevant to the resource. It's the same type of behavior for each type of resource you select.

+3. Use the link to zoom into the tool tip and refocus the map on that specific node.

+The strength of this view is in its ability to show you these allowed connections together with the vulnerabilities that exist, so you can use this cross-section of data to perform the necessary hardening on your resources.

+1. When you select a specific resource on the map, the right pane opens and gives you general information about the resource, connected security solutions if there are any, and the recommendations relevant to the resource. It's the same type of behavior for each type of resource you select.

+2. Select **Traffic** to see the list of possible outbound and inbound traffic on the resource - this is a comprehensive list of who can communicate with the resource and who it can communicate with, and through which protocols and ports. For example, when you select a VM, all the VMs it can communicate with are shown, and when you select a subnet, all the subnets which it can communicate with are shown.

+**This data is based on analysis of the Network Security Groups as well as advanced machine learning algorithms that analyze multiple rules to understand their crossovers and interactions.**

+ > [!NOTE]

+ > If you're using a sensor version earlier than 23.2.0, use the [*cyberx_host*](roles-on-premises.md#legacy-users) user instead. Skip the next step for running `system shell` and jump directly to creating a directory for your backup files.

+description: Learn how to manage network connections for a dev center in Microsoft Dev Box. Connect to a virtual network or enable connecting to on-premises resources.

+## Prerequisites

+- Sufficient permissions to enable creating and configuring network connections.

+- At least one virtual network and subnet available for your dev boxes.

+When you're planning network connectivity for your dev boxes, consider the following points:

+### Verify your permissions

+To manage a network connection, confirm that you have the following permissions:

+| Action | Role | Permissions required |

+||||

+| _Create and configure a virtual network and subnet_ | **Network Contributor** (**Owner** or **Contributor**) | Permissions on an existing virtual network or permission to create a new virtual network and subnet |

+| _Create or delete a network connection_ | **Owner** or **Contributor** | Permissions on an Azure subscription or on a specific resource group, which includes permission to create a resource group |

+| _Add or remove a network connection_ | **Contributor** | Permission to perform **Write** actions on the dev center |

+ |||

+ | **Resource group** | Select an existing resource group, or create a new one by selecting **Create new**, entering a name, and then selecting **OK**. |

+ | **Name** | Enter a name for the virtual network. |

+ :::image type="content" source="./media/how-to-manage-network-connection/example-basics-tab.png" alt-text="Screenshot of the Basics tab on the pane for creating a virtual network in the Azure portal." lightbox="./media/how-to-manage-network-connection/example-basics-tab.png":::

+ > [!IMPORTANT]

+ > The region you select for the virtual network is the where Azure deploys the dev boxes.

+### Review types of Active Directory join

+Microsoft Dev Box requires a configured and working Active Directory join, which defines how dev boxes join your domain and access resources. There are two choices: Microsoft Entra join and Microsoft Entra hybrid join.

+- **Microsoft Entra join**. If your organization uses Microsoft Entra ID, you can use a Microsoft Entra join (sometimes called a _native_ Microsoft Entra join). Dev box users sign in to Microsoft Entra joined dev boxes by using their Microsoft Entra account. They access resources based on the permissions assigned to that account. Microsoft Entra join enables access to cloud-based and on-premises apps and resources. For more information, see [Plan your Microsoft Entra join deployment](../active-directory/devices/device-join-plan.md).

+- **Microsoft Entra hybrid join**. If your organization has an on-premises Active Directory implementation, you can still benefit from some of the functionality in Microsoft Entra ID by using Microsoft Entra hybrid joined dev boxes. These dev boxes are joined to your on-premises Active Directory instance and registered with Microsoft Entra ID. Microsoft Entra hybrid joined dev boxes require network line of sight to your on-premises domain controllers periodically. Without this connection, devices become unusable. For more information, see [Plan your Microsoft Entra hybrid join deployment](../active-directory/devices/hybrid-join-plan.md).

+# [**Microsoft Entra join**](#tab/AzureADJoin/)

+1. In the search box, enter **network connections**. In the list of results, select **Network Connections**.

+ :::image type="content" source="./media/how-to-manage-network-connection/network-connections-empty.png" alt-text="Screenshot that shows the Create button on the page for network connections." lightbox="./media/how-to-manage-network-connection/network-connections-empty.png":::

+ | Setting | Value |

+ |||

+ | **Domain join type** | Select **Microsoft Entra join**. |

+ | **Subscription** | Select the subscription in which you want to create the network connection. |

+ | **Resource group** | Select an existing resource group, or select **Create new** and then enter a name for the new resource group. |

+ | **Name** | Enter a descriptive name for the network connection. |

+ | **Virtual network** | Select the virtual network that you want the network connection to use. |

+ | **Subnet** | Select the subnet that you want the network connection to use. |

+ :::image type="content" source="./media/how-to-manage-network-connection/create-native-network-connection-full-blank.png" alt-text="Screenshot that shows the Basics tab on the pane for creating a network connection, with the option for Microsoft Entra join selected." lightbox="./media/how-to-manage-network-connection/create-native-network-connection-full-blank.png":::

+1. When the deployment completes, select **Go to resource**. Confirm the connection appears on the **Network Connections** page.

+# [**Microsoft Entra hybrid join**](#tab/HybridAzureADJoin/)

+1. In the search box, enter **network connections**. In the list of results, select **Network Connections**.

+ :::image type="content" source="./media/how-to-manage-network-connection/network-connections-empty.png" alt-text="Screenshot that shows the Create button on the page that lists network connections." lightbox="./media/how-to-manage-network-connection/network-connections-empty.png":::

+ | Setting | Value |

+ |||

+ | **Domain join type** | Select **Microsoft Entra hybrid join**. |

+ | **Subscription** | Select the subscription in which you want to create the network connection. |

+ | **ResourceGroup** | Select an existing resource group, or select **Create new** and then enter a name for the new resource group. |

+ | **Name** | Enter a descriptive name for the network connection. |

+ | **Virtual network** | Select the virtual network that you want the network connection to use. |

+ | **Subnet** | Select the subnet that you want the network connection to use. |

+ | **AD DNS domain name**| Enter the DNS name of the Active Directory domain that you want to use for connecting and provisioning Cloud PCs. For example: `corp.contoso.com`. |

+ | **Organizational unit** | Enter the organizational unit (OU). An OU is a container within an Active Directory domain that can hold users, groups, and computers. |

+ | **AD username UPN** | Enter the username, in user principal name (UPN) format, that you want to use for connecting Cloud PCs to your Active Directory domain. For example: `svcDomainJoin@corp.contoso.com`. This service account must have permission to join computers to the domain and the target OU (if one is set). |

+ | **AD domain password** | Enter the password for the user. |

+ :::image type="content" source="./media/how-to-manage-network-connection/create-hybrid-network-connection-full-blank.png" alt-text="Screenshot that shows the Basics tab on the pane for creating a network connection, with the option for Microsoft Entra hybrid join selected." lightbox="./media/how-to-manage-network-connection/create-hybrid-network-connection-full-blank.png":::

+1. When the deployment completes, select **Go to resource**. Confirm the connection appears on the **Network connections** page.

+> [!NOTE]

+ :::image type="content" source="./media/how-to-manage-network-connection/add-network-connection.png" alt-text="Screenshot that shows the pane for adding a network connection." lightbox="./media/how-to-manage-network-connection/add-network-connection.png":::

+You can add network connections that pass all health checks to a dev center and use them to create dev box pools. Dev boxes within dev box pools are created and domain joined in the location of the virtual network assigned to the network connection.

+1. Review the warning message, and then select **OK**.

+description: Learn how to configure an auto-stop schedule to automatically shut down dev boxes in a pool at a specified time and save on costs.

+To save on costs, you can enable an auto-stop schedule on a dev box pool. Microsoft Dev Box attempts to shut down all dev boxes in the pool at the time specified in the schedule. You can configure one stop time in one timezone for each pool.

+| Action | Permission required |

+|||

+| _Configure a schedule_ | Owner, Contributor, or DevCenter Project Admin. |

+You can enable, modify, and disable auto-stop schedules by using the Azure portal.

+You can create an auto-stop schedule while configuring a new dev box pool, or by modifying an already existing dev box pool. The following steps show you how to use the Azure portal to create and configure an auto-stop schedule.

+1. In the search box, enter **projects**. In the list of results, select **Projects**.

+ :::image type="content" source="./media/how-to-manage-stop-schedule/discover-projects.png" alt-text="Screenshot showing a search for projects from the Azure portal search box." lightbox="./media/how-to-manage-stop-schedule/discover-projects.png":::

+1. Open the project associated with the pool that you want to edit, and then select **Dev box pools**.

+ :::image type="content" source="./media/how-to-manage-stop-schedule/dev-box-pool-grid-populated.png" alt-text="Screenshot of the list of existing dev box pools for the project." lightbox="./media/how-to-manage-stop-schedule/dev-box-pool-grid-populated.png":::

+1. Determine the pool that you want to modify and scroll right. Open the more options (**...**) menu for the pool and select **Edit**.

+ :::image type="content" source="./media/how-to-manage-stop-schedule/dev-box-edit-pool.png" alt-text="Screenshot of the more options menu for a dev box pool and the Edit option selected." lightbox="./media/how-to-manage-stop-schedule/dev-box-edit-pool.png":::

+1. In the **Edit dev box pool** pane, configure the following settings in the **Auto-stop** section:

+ | Setting | Value |

+ |||

+ | **Enable Auto-stop** | Select **Yes** to enable an auto-stop schedule after the pool is created. |

+ | **Stop time** | Select a time to shutdown all the dev boxes in the pool. All dev boxes in this pool shutdown at this time every day. |

+ | **Time zone** | Select the time zone that the stop time is in. |

+ :::image type="content" source="./media/how-to-manage-stop-schedule/dev-box-enable-stop.png" alt-text="Screenshot of the edit dev box pool page showing the Auto-stop options and Yes selected." lightbox="./media/how-to-manage-stop-schedule/dev-box-enable-stop.png":::

+### Add an auto-stop schedule when you create a pool

+1. In the search box, enter **projects**. In the list of results, select **Projects**.

+1. Open the project for which you want to create a pool, select **Dev box pools**, and then select **Create**.

+ :::image type="content" source="./media/how-to-manage-stop-schedule/dev-box-pool-grid-empty.png" alt-text="Screenshot of the list of dev box pools within a project. The list is empty. The Create option is selected." lightbox="./media/how-to-manage-stop-schedule/dev-box-pool-grid-empty.png":::

+1. On the **Create a dev box pool** pane, enter the following values:

+ | Setting | Value |

+ |||

+ | **Name** | Enter a name for the pool. The pool name is visible to developers to select when they're creating dev boxes. The name must be unique within a project. |

+ | **Dev box definition** | Select an existing dev box definition. The definition determines the base image and size for the dev boxes that are created in this pool. |

+ | **Network connection** | 1. Select **Deploy to a Microsoft hosted network**. </br>2. Select your desired deployment region for the dev boxes. Choose a region close to your expected dev box users for the optimal user experience. |

+ | **Dev box Creator Privileges** | Select **Local Administrator** or **Standard User**. |

+ | **Enable Auto-stop** | **Yes** is the default. Select **No** to disable an auto-stop schedule. You can configure an auto-stop schedule after the pool is created. |

+ | **Stop time** | Select a time to shut down all the dev boxes in the pool. All dev boxes in this pool shut down at this time every day. |

+ | **Time zone** | Select the time zone for the stop time. |

+ | **Licensing** | Select this checkbox to confirm that your organization has Azure Hybrid Benefit licenses that you want to apply to the dev boxes in this pool. |

+ :::image type="content" source="./media/how-to-manage-stop-schedule/dev-box-pool-create.png" alt-text="Screenshot of the Create dev box pool dialog." lightbox="./media/how-to-manage-stop-schedule/dev-box-pool-create.png":::

+1. Select **Create**.

+1. Verify that the new dev box pool appears in the list. You might need to refresh the screen.

+Follow these steps to delete an auto-stop schedule for your pool:

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

+1. In the search box, enter **projects**. In the list of results, select **Projects**.

+1. Open the project associated with the pool that you want to modify, and then select **Dev box pools**.

+1. Determine the pool that you want to modify and scroll right. Open the more options (**...**) menu for the pool and select **Edit**.

+1. In the **Edit dev box pool** pane, in the **Auto-stop** section, toggle the **Enable Auto-stop** setting to **No**.

+ :::image type="content" source="./media/how-to-manage-stop-schedule/dev-box-disable-stop.png" alt-text="Screenshot of the edit dev box pool page showing the Auto-stop options and No selected." lightbox="./media/how-to-manage-stop-schedule/dev-box-disable-stop.png":::

+1. Select **Save**.

+After you change the setting, dev boxes in this pool don't automatically shut down.

+## Manage an auto-stop schedule with the Azure CLI

+You can also manage auto-stop schedules by using the Azure CLI.

+The following Azure CLI command creates an auto-stop schedule:

+```azurecli

+az devcenter admin schedule create --pool-name {poolName} --project {projectName} --resource-group {resourceGroupName} --time {hh:mm} --time-zone {"timeZone"} --state Enabled

+```

+| Parameter | Value |

+|||

+| `pool-name` | Name of your dev box pool. |

+| `project` | Name of your dev box project. |

+| `resource-group` | Name of the resource group for your dev box pool. |

+| `time` | Local time when dev boxes should be shut down, such as `23:15` for 11:15 PM. |

+| `time-zone` | Standard timezone string to determine the local time, such as `"America/Los_Angeles"`. |

+| `state` | Indicates whether the schedule is in use. The options include `Enabled` or `Disabled`. |

+Enter the following command in the Azure CLI to delete an auto-stop schedule:

+```azurecli

+az devcenter admin schedule delete --pool-name {poolName} --project-name {projectName}

+```

+| Parameter | Value |

+|||

+| `pool-name` | Name of your dev box pool. |

+| `project-name` | Name of your dev box project. |

+## Related content

+- [Manage a dev box by using the developer portal](./how-to-create-dev-boxes-developer-portal.md)

+To ensure that resources are available for customers, Microsoft Dev Box has a limit on the number of each type of resource that can be used in a subscription. This limit is called a _quota_.

+Keeping track of how your quota of virtual machine cores is being used across your subscriptions can be difficult. You might want to know what your current usage is, how much is remaining, and in what regions you have capacity. To help you understand where and how you're using your quota, Azure provides the **Usage + Quotas** page in the Azure portal.

+1. Sign in to the [Azure portal](https://portal.azure.com), and go to the subscription you want to examine.

+1. On the **Subscription** page, under **Settings**, select **Usage + quotas**.

+1. To view usage and quota information about Microsoft Dev Box, select the **Provider** filter, and then select **Dev Box** in the dropdown list.

+ :::image type="content" source="media/how-to-determine-your-quota-usage/select-dev-box.png" alt-text="Screenshot showing the Usage and quotas page, with Dev Box highlighted in the Provider filter dropdown list." lightbox="media/how-to-determine-your-quota-usage/select-dev-box.png":::

+1. Notice that Azure groups the usage by level: **Regular**, **Low**, and **No usage**:

+ :::image type="content" source="media/how-to-determine-your-quota-usage/example-subscription-groups.png" alt-text="Screenshot showing the Usage and quotas page, with virtual machine size groups highlighted." lightbox="media/how-to-determine-your-quota-usage/example-subscription-groups.png" :::

+ :::image type="content" source="media/how-to-determine-your-quota-usage/select-regions.png" alt-text="Screenshot showing the Usage and quotas page, with the Regions dropdown list highlighted." lightbox="media/how-to-determine-your-quota-usage/select-regions.png":::

+ :::image type="content" source="media/how-to-determine-your-quota-usage/select-items-with-usage.png" alt-text="Screenshot showing the Usage and quotas page, with the Usage dropdown list and Only show items with usage option highlighted." lightbox="media/how-to-determine-your-quota-usage/select-items-with-usage.png" :::

+ :::image type="content" source="media/how-to-determine-your-quota-usage/select-custom-usage-before.png" alt-text="Screenshot showing the Usage and quotas page, with the Usage dropdown list and Select custom usage option highlighted." lightbox="media/how-to-determine-your-quota-usage/select-custom-usage-before.png" :::

+ :::image type="content" source="media/how-to-determine-your-quota-usage/select-custom-usage.png" alt-text="Screenshot showing the Usage and quotas page, with Select custom usage option and configuration settings highlighted." lightbox="media/how-to-determine-your-quota-usage/select-custom-usage.png":::

+Each subscription has its own **Usage + quotas** page that covers all the various services in the subscription and not just Microsoft Dev Box.

+- Check the default quota for each resource type by subscription type with [Microsoft Dev Box limits](../azure-resource-manager/management/azure-subscription-service-limits.md#microsoft-dev-box-limits)

+- Learn how to [request a quota limit increase](./how-to-request-quota-increase.md)

+| Action | Permission required |

+|||

+| _Create or delete dev box project_ | Owner, Contributor, or Write permissions on the dev center in which you want to create the project. |

+| _Update a dev box project_ | Owner, Contributor, or Write permissions on the project. |

+| _Create, delete, and update dev box pools in the project_ | Owner, Contributor, or DevCenter Project Admin. |

+| _Manage a dev box within the project_ | Owner, Contributor, or DevCenter Project Admin. |

+| _Add a dev box user to the project_ | Owner permissions on the project. |

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

+1. In the search box, enter **projects**. In the list of results, select **Projects**.

+1. On the **Projects** page, select **Create**.

+1. On the **Create a project** pane, on the **Basics** tab, enter the following values:

+ | Setting | Value |

+ |||

+ | **Subscription** | Select the subscription in which you want to create the project. |

+ | **Resource group** | Select an existing resource group, or select **Create new** and then enter a name for the new resource group. |

+ | **Dev center** | Select the dev center that you want to associate with this project. All the settings at the dev center level apply to the project. |

+ | **Name** | Enter a name for the project. |

+ | **Description** | Enter a brief description of the project. |

+ :::image type="content" source="./media/how-to-manage-dev-box-projects/dev-box-project-create.png" alt-text="Screenshot of the Create a dev box project Basics tab." lightbox="./media/how-to-manage-dev-box-projects/dev-box-project-create.png":::

+1. On the **Dev box management** tab, ensure **No** is selected.

+ You can select **Yes** to limit the number of dev boxes per developer, and specify the maximum number of dev boxes a developer can create. The default, **No**, means developers can create an unlimited number of dev boxes.

+ To learn more about dev box limits, see [Tutorial: Control costs by setting dev box limits on a project](./tutorial-dev-box-limits.md).

+1. (Optional) On the **Tags** tab, enter a name/value pair that you want to assign.

+1. Verify that the project appears on the **Projects** page.

+

+As you create a project, you might see this informational message about catalogs:

+Because you're not configuring Deployment Environments, you can safely ignore this message.

+1. In the search box, enter **projects**. In the list of results, select **Projects**.

+1. Open the dev box project that you want to delete.

+1. Select **Delete**.

+ :::image type="content" source="./media/how-to-manage-dev-box-projects/delete-project.png" alt-text="Screenshot of the overview page for a dev box project and the Delete option highlighted." lightbox="./media/how-to-manage-dev-box-projects/delete-project.png":::

+1. In the confirmation message, select **OK**.

+ :::image type="content" source="./media/how-to-manage-dev-box-projects/confirm-delete-project.png" alt-text="Screenshot of the Delete dev box pool confirmation message.":::

+Before users can create dev boxes based on the dev box pools in a project, you must provide access for them through a role assignment. The Dev Box User role enables dev box users to create, manage, and delete their own dev boxes. You must have sufficient permissions to a project before you can add users to it.

+1. In the search box, enter **projects**. In the list of results, select **Projects**.

+1. Open the dev box project that you want to provide your team members access to.

+1. On the left menu, select **Access Control (IAM)**, and then select **Add** > **Add role assignment**.

+ :::image type="content" source="./media/how-to-manage-dev-box-projects/project-permissions.png" alt-text="Screenshot that shows the page for project access control." lightbox="./media/how-to-manage-dev-box-projects/project-permissions.png":::

+ | Setting | Value |

+ |||

+ | **Role** | Select **DevCenter Dev Box User**. |

+ | **Assign access to** | Select **User, group, or service principal**. |

+ | **Members** | Select the users or groups you want to have access to the project. |

+ :::image type="content" source="media/how-to-manage-dev-box-projects/add-role-assignment-user.png" alt-text="Screenshot that shows the Add role assignment pane." lightbox="media/how-to-manage-dev-box-projects/add-role-assignment-user.png":::

+## Related content

+- [Create a dev box definition](quickstart-configure-dev-box-service.md#create-a-dev-box-definition)

+- [Configure Azure Compute Gallery](./how-to-configure-azure-compute-gallery.md)

+description: Learn how to delay the scheduled shutdown of your dev box, or skip the shutdown entirely, to manage your work and resources more effectively.

+## Change scheduled shutdown from the dev box

+1. In the pop-up notification, select a time to delay the shutdown for, such as **Delay 1 Hour**.

+ :::image type="content" source="media/how-to-skip-delay-stop/dev-box-toast-time.png" alt-text="Screenshot showing the shutdown notification and delay options in the dropdown list." lightbox="media/how-to-skip-delay-stop/dev-box-toast-time.png" :::

+1. Select **Delay**.

+ :::image type="content" source="media/how-to-skip-delay-stop/dev-box-toast-delay.png" alt-text="Screenshot showing the shutdown notification and the Delay button highlighted." lightbox="media/how-to-skip-delay-stop/dev-box-toast-delay.png" :::

+You can also choose to skip the next scheduled shutdown altogether. In the pop-up notification, select **Skip**.

+The dev box doesn't shut down until the next scheduled shutdown time.

+## Change scheduled shutdown from the developer portal

+In the developer portal, you can see the scheduled shutdown time on the dev box tile. You can delay or skip the shutdown from the more options (**...**) menu.

+1. On the more options (**...**) menu, select **Delay scheduled shutdown**.

+ :::image type="content" source="media/how-to-skip-delay-stop/dev-portal-menu.png" alt-text="Screenshot showing the dev box tile and the more options menu with the Delay scheduled shutdown option highlighted." lightbox="media/how-to-skip-delay-stop/dev-portal-menu.png":::

+1. In the **Delay shutdown until** dropdown list, select the time that you want to delay the shutdown until. You can delay the shutdown by up to 8 hours from the scheduled time.

+ :::image type="content" source="media/how-to-skip-delay-stop/delay-options.png" alt-text="Screenshot showing how to delay the scheduled shutdown until 7 30 p m." lightbox="media/how-to-skip-delay-stop/delay-options.png":::

+1. Select **Delay**.

+1. On the more options (**...**) menu, select **Delay scheduled shutdown**.

+1. In the **Delay shutdown until** dropdown list, select the last available option, which specifies the time 8 hours after the scheduled shutdown time. In this example, the last option is **6:30 pm tomorrow (skip)**.

+ :::image type="content" source="media/how-to-skip-delay-stop/skip-shutdown.png" alt-text="Screenshot showing the final shutdown option that skips shutdown until the next scheduled time." lightbox="media/how-to-skip-delay-stop/skip-shutdown.png":::

+1. Select **Delay**.

+## Related content

+- [Manage a dev box by using the developer portal](./how-to-create-dev-boxes-developer-portal.md)

+- [Auto-stop your dev boxes on schedule](how-to-configure-stop-schedule.md)

+ Title: Troubleshoot and repair Dev Box RDP connectivity issues

+In this article, you learn how to troubleshoot and resolve remote desktop connectivity (RDC) issues with your dev box. Because RDC issues to your dev box can be time consuming to resolve manually, use the **Troubleshoot & repair** tool in the developer portal to diagnose and repair some common dev box connectivity issues.

+When you run the **Troubleshoot & repair** tool, your dev box and its back-end services in the Azure infrastructure are scanned for issues. If an issue is detected, the troubleshoot and repair process fixes the issue so you can connect to your dev box.

+- Access to the Microsoft developer portal.

+- The dev box that you want to troubleshoot must be running.

+## Run Troubleshoot & repair

+If you're unable to connect to your dev box by using an RDP client, use the **Troubleshoot & repair** tool.

+The troubleshoot and repair process completes on average in 20 minutes, but can take up to 40 minutes. During this time, you can't use your dev box. The tool scans a list of critical components that relate to RDP connectivity, including but not limited to:

+- Virtual machine power status check

+- Virtual machine extension check

+> Running the troubleshoot and repair process might effectively restart your dev box. Any unsaved data on your dev box will be lost.

+To run the **Troubleshoot & repair** tool on your dev box, follow these steps:

+ :::image type="content" source="media/how-to-troubleshoot-repair-dev-box/dev-box-running-tile.png" alt-text="Screenshot showing the dev box tile with the status Running." lightbox="media/how-to-troubleshoot-repair-dev-box/dev-box-running-tile.png":::

+1. If your dev box is running and you still can't connect to it with RDP, on the more actions (**...**) menu, select **Troubleshoot & repair**.

+ :::image type="content" source="media/how-to-troubleshoot-repair-dev-box/dev-box-actions-troubleshoot-repair.png" alt-text="Screenshot showing the Troubleshoot and repair option for a dev box on the more actions menu." lightbox="media/how-to-troubleshoot-repair-dev-box/dev-box-actions-troubleshoot-repair.png" :::

+1. In the **Troubleshoot & repair** connectivity message box, select **Yes, I want to troubleshoot this dev box**, and then select **Troubleshoot**.

+ :::image type="content" source="media/how-to-troubleshoot-repair-dev-box/dev-box-troubleshoot-confirm.png" alt-text="Screenshot showing the Troubleshoot and repair connectivity confirmation message with the Yes option highlighted." lightbox="media/how-to-troubleshoot-repair-dev-box/dev-box-troubleshoot-confirm.png" :::

+ While you wait for the process to complete, you can leave your developer portal session open, or close it and reopen it later. The troubleshoot and repair process continues in the background.

+## View Troubleshoot & repair results

+When the troubleshoot and repair process finishes, the tool lists the results of the completed checks:

+| Check result | Description |

+|||

+| **An issue was resolved.** | An issue was detected and fixed. You can try to connect to the dev box again. |

+| **No issue detected.** | None of the checks discovered an issue with the dev box. |

+| **An issue was detected but could not be fixed automatically.** | There's an issue with the dev box that the Troubleshoot & repair process couldn't resolve. You can select **View details** for the issue and explore options to fix the issue manually. |

+- [Tutorial: Use a Remote Desktop client to connect to a dev box](tutorial-connect-to-dev-box-with-remote-desktop-app.md)

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+* The `clientRequestId` key isn't included.

+ | [Microsoft.Storage.BlobInventoryPolicyCompleted](#microsoftstorageblobinventorypolicycompleted-event) |Triggered when the inventory run completes for a rule that is defined an inventory policy. This event also occurs if the inventory run fails with a user error before it starts to run. For example, an invalid policy, or an error that occurs when a destination container isn't present will trigger the event. |

+description: Describes how to validate an HTTP endpoint, then receive and deserialize Events from Azure Event Grid.

+> We recommend that you use an [Event Grid Trigger](../azure-functions/functions-bindings-event-grid.md) when triggering an Azure Function with Event Grid. It provides an easier and quicker integration between Event Grid and Azure Functions. However, note that Azure Functions' Event Grid trigger does not support the scenario where the hosted code needs to control the HTTP status code returned to Event Grid. Given this limitation, your code running on an Azure Function would not be able to return a 5XX error to initiate an event delivery retry by Event Grid, for example.

+In C#, the `ParseMany()` method is used to deserialize a `BinaryData` instance containing one or more events into an array of `EventGridEvent`. If you knew ahead of time that you are deserializing only a single event, you could use the `Parse` method instead.

+You can also test by creating a Blob storage account or General Purpose V2 Storage account, [adding an event subscription](../storage/blobs/storage-blob-event-quickstart.md), and setting the endpoint to the function URL:

+- [Apache Flink on HDInsight on AKS](/azure/hdinsight-aks/flink/flink-overview)

+the page, [Differences between Windows PowerShell 5.1 and PowerShell 7.x][https://learn.microsoft.com/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.4].

+- The user used to connect to the database should have **SELECT, CREATE TABLE, INSERT, UPDATE, DELETE, ALTER ON SCHEMA and REFERENCES ON SCHEMA** permissions on the database.

+```sql

+GRANT CREATE TABLE TO newuser;

+GRANT INSERT TO newuser;

+GRANT SELECT TO newuser;

+GRANT UPDATE TO newuser;

+GRANT DELETE TO newuser;

+GRANT ALTER ON SCHEMA::dbo TO newuser;

+GRANT REFERENCES ON SCHEMA::dbo TO newuser;

+```

+The set of root keys will change over time as it is proper to periodically rotate signing keys for security purposes. As a result, the Device Update agent software will need to be updated with the latest set of root keys at intervals specified by the Device Update team. **The next planned root key rotation will occur in May 2025**.

+ Title: Connect Azure Arc-enabled servers from an isolated network

+description: Connect a node host to Azure Arc-enabled servers from an isolated network

+#CustomerIntent: As an operator, I want to configure Layered Network Management so that I have secure isolated devices.

+# Connect Azure Arc-enabled servers from an isolated network

+This walkthrough is an example of connecting your host machine to Azure Arc as an [Arc-enabled server](/azure/azure-arc/servers) from an isolated network environment. For example, level 3 of the *Purdue Network*. You connect the host machine to Azure IoT Layered Network Management at the parent level as a proxy to reach Azure endpoints for the service. You can integrate these steps into your procedure to set up your cluster for Azure IoT Operations. Don't use this guidance independently. For more information, see [Configure Layered Network Management service to enable Azure IoT Operations in an isolated network](howto-configure-aks-edge-essentials-layered-network.md).

+> [!IMPORTANT]

+> **Arc-enabled servers** aren't a requirement for the Azure IoT Operations experiences. You should evaluate your own design and only enable this service if it suits your needs. Before proceeding with these steps, you should also get familiar with the **Arc-enabled servers** by trying this service with a machine that has direct internet access.

+> [!NOTE]

+> Layered Network Management for Arc-enabled servers does not support Azure VMs.

+## Configuration for Layered Network Management

+To support the Arc-enabled servers, the level 4 Layered Network Management instance needs to include the following endpoints in the allowlist when applying the custom resource:

+```

+ - destinationUrl: "gbl.his.arc.azure.com"

+ destinationType: external

+ - destinationUrl: "gbl.his.arc.azure.us"

+ destinationType: external

+ - destinationUrl: "gbl.his.arc.azure.cn"

+ destinationType: external

+ - destinationUrl: "packages.microsoft.com"

+ destinationType: external

+ - destinationUrl: "aka.ms"

+ destinationType: external

+ - destinationUrl: "ppa.launchpadcontent.net"

+ destinationType: external

+ - destinationUrl: "mirror.enzu.com"

+ destinationType: external

+ - destinationUrl: "*.guestconfiguration.azure.com"

+ destinationType: external

+ - destinationUrl: "agentserviceapi.guestconfiguration.azure.com"

+ destinationType: external

+ - destinationUrl: "pas.windows.net"

+ destinationType: external

+ - destinationUrl: "download.microsoft.com"

+ destinationType: external

+```

+> [!NOTE]

+> If you plan to onboard an Ubuntu machine, you also need to add the domain name of the *software and update* repository of your choice to the allowlist. For more information selecting the repository, see [Configuration Ubuntu host machine](#configure-ubuntu-host-machine).

+If you want to enable optional features, add the appropriate endpoint from the following table. For more information, see [Connected Machine agent network requirements](/azure/azure-arc/servers/network-requirements).

+| Endpoint | Optional feature |

+|||

+| *.waconazure.com | Windows Admin Center connectivity |

+| san-af-[REGION]-prod.azurewebsites.net | SQL Server enabled by Azure Arc. The Azure extension for SQL Server uploads inventory and billing information to the data processing service. |

+| telemetry.[REGION].arcdataservices.com | For Arc SQL Server. Sends service telemetry and performance monitoring to Azure. |

+## Configure Windows host machine

+If you prepared your host machine and cluster to be Arc-enabled by following the [Configure level 3 cluster](howto-configure-l3-cluster-layered-network.md) article, you can proceed to onboard your Arc-enabled server. Otherwise at a minimum, point the host machine to your custom DNS. For more information, see [Configure the DNS server](howto-configure-layered-network.md#configure-the-dns-server).

+After properly setting up the parent level Layered Network Management instance and custom DNS, see [Quickstart: Connect hybrid machines with Azure Arc-enabled servers](/azure/azure-arc/servers/learn/quick-enable-hybrid-vm).

+- After downloading the `OnboardingScript.ps1`, open it with a text editor. find the following section and add the parameter `--use-device-code` at the end of the command.

+ ```

+ # Run connect command

+ & "$env:ProgramW6432\AzureConnectedMachineAgent\azcmagent.exe" connect --resource-group "$env:RESOURCE_GROUP" --tenant-id "$env:TENANT_ID" --location "$env:LOCATION" --subscription-id "$env:SUBSCRIPTION_ID" --cloud "$env:CLOUD" --correlation-id "$env:CORRELATION_ID";

+ ```

+- Proceed with the steps in [Quickstart: Connect hybrid machines with Azure Arc-enabled servers](/azure/azure-arc/servers/learn/quick-enable-hybrid-vm) to complete the onboarding.

+## Configure Ubuntu host machine

+If you prepared your host machine and cluster to be Arc-enabled by following the [Configure level 3 cluster](howto-configure-l3-cluster-layered-network.md) article, you can proceed to onboard your Arc-enabled server. Otherwise at a minimum, point the host machine to your custom DNS. For more information, see [Configure the DNS server](howto-configure-layered-network.md#configure-the-dns-server).

+Before starting the onboarding process, you need to assign an *https* address for the Ubuntu OS *software and update* repository.

+1. Visit https://launchpad.net/ubuntu/+archivemirrors and identify a repository that is close to your location and supports the *https* protocol.

+1. Modify `/etc/apt/sources.list` to replace the address with the URL from the previous step.

+1. Add the domain name of this repository to the Layered Network Management allowlist.

+1. Run `apt update` to confirm the update is pulling packages from the new repository with *https* protocol.

+See [Quickstart: Connect hybrid machines with Azure Arc-enabled servers](/azure/azure-arc/servers/learn/quick-enable-hybrid-vm) to complete the Arc-enabled Servers onboarding.

+## Troubleshoot Layered Network Management

+The troubleshooting guidance in this section is specific to Azure IoT Operations when using an IoT Layered Network Management. For more information, see [How does Azure IoT Operations work in layered network?](../manage-layered-network/concept-iot-operations-in-layered-network.md).

+### Can't install Layered Network Management on the parent level

+Layered Network Management operator install fails or you can't apply the custom resource for a Layered Network Management instance.

+1. Verify the regions are supported for public preview. Public preview supports eight regions. For more information, see [Quickstart: Deploy Azure IoT Operations](../get-started/quickstart-deploy.md#connect-a-kubernetes-cluster-to-azure-arc).

+1. If there are any other errors in installing Layered Network Management Arc extensions, follow the guidance included with the error. Try uninstalling and installing the extension.

+1. Verify the Layered Network Management operator is in the *Running and Ready* state.

+1. If applying the custom resource `kubectl apply -f cr.yaml` fails, the output of this command lists the reason for error. For example, CRD version mismatch or wrong entry in CRD.

+### Can't Arc-enable the cluster through the parent level Layered Network Management

+If you repeatedly remove and onboard a cluster with the same machine, you might get an error while Arc-enabling the cluster on nested layers. For example, the error message might look like:

+```Output

+Error: We found an issue with outbound network connectivity from the cluster to the endpoints required for onboarding.

+Please ensure to meet the following network requirements 'https://docs.microsoft.com/en-us/azure/azure-arc/kubernetes/quickstart-connect-cluster?tabs=azure-cli#meet-network-requirements'

+If your cluster is behind an outbound proxy server, please ensure that you have passed proxy parameters during the onboarding of your cluster.

+```

+1. Run the following command:

+ ```bash

+ sudo systemctl restart systemd-networkd

+ ```

+1. Reboot the host machine.

+#### Other types of Arc-enablement failures

+1. Add the `--debug` parameter when running the `connectedk8s` command.

+1. Capture and investigate a network packet trace. For more information, see [capture Layered Network Management packet trace](#capture-layered-network-management-packet-trace).

+### Can't install IoT Operations on the isolated cluster

+You can't install IoT Operations components on nested layers. For example, Layered Network Management on level 4 is running but can't install IoT Operations on level 3.

+1. Verify the nodes can access the Layered Network Management service running on parent level. For example, run `ping <IP-ADDRESS-L4-LNM>` from the node.

+1. Verify the DNS queries are being resolved to the Layered Network Management service running on the parent level using the following commands:

+ ```bash

+ nslookup management.azure.com

+ ```

+ DNS should respond with the IP address of the Layered Network Management service.

+1. If the domain is being resolved correctly, verify the domain is added to the allowlist. For more information, see [Check the allowlist of Layered Network Management](#check-the-allowlist-of-layered-network-management).

+1. Capture and investigate a network packet trace. For more information, see [capture Layered Network Management packet trace](#capture-layered-network-management-packet-trace).

+### A pod fails when installing IoT Operations on an isolated cluster

+When installing the IoT Operations components to a cluster, the installation starts and proceeds. However, initialization of one or few of the components (pods) fails.

+1. Identify the failed pod

+ ```bash

+ kubectl get pods -n azure-iot-operations

+ ```

+1. Get details about the pod:

+ ```bash

+ kubectl describe pod [POD NAME] -n azure-iot-operations

+ ```

+1. Check the container image related information. If the image download fails, check if the domain name of download path is on the allowlist. For example:

+ ```output

+ Warning Failed 3m14s kubelet Failed to pull image "…

+ ```

+### Check the allowlist of Layered Network Management

+Layered Network Management blocks traffic if the destination domain isn't on the allowlist.

+1. Run the following command to list the config maps.

+ ```bash

+ kubectl get cm -n azure-iot-operations

+ ```

+1. The output should look like the following example:

+ ```

+ NAME DATA AGE

+ aio-lnm-level4-config 1 50s

+ aio-lnm-level4-client-config 1 50s

+ ```

+1. The *xxx-client-config* contains the allowlist. Run:

+ ```bash

+ kubectl get cm aio-lnm-level4-client-config -o yaml

+ ```

+1. All the allowed domains are listed in the output.

+### Capture Layered Network Management packet trace

+In some cases, you might suspect that Layered Network Management instance at the parent level isn't forwarding network traffic to a particular endpoint. Connection to a required endpoint is causing an issue for the service running on your node. It's possible that the service you enabled is trying to connect to a new endpoint after an update. Or you're trying to install a new Arc extension or service that requires connection to endpoints that aren't on the default allowlist. Usually there would be information in the error message to notify the connection failure. However, if there's no clear information about the missing endpoint, you can capture the network traffic on the child node for detailed debugging.

+#### Windows host

+1. Install Wireshark network traffic analyzer on the host.

+1. Run Wireshark and start capturing.

+1. Reproduce the installation or connection failure.

+1. Stop capturing.

+#### Linux host

+1. Run the following command to start capturing:

+ ```bash

+ sudo tcpdump -W 5 -C 10 -i any -w AIO-deploy -Z root

+ ```

+1. Reproduce the installation or connection failure.

+1. Stop capturing.

+#### Analyze the packet trace

+Use Wireshark to open the trace file. Look for connection failures or nonresponded connections.

+1. Filter the packets with the *ip.addr == [IP address]* parameter. Input the IP address of your custom DNS service address.

+1. Review the DNS query and response, check if there's a domain name that isn't on the allowlist of Layered Network Management.

+The **AS2** connector has different versions, based on [logic app type and host environment](logic-apps-overview.md#resource-environment-differences).

+| **Consumption** | multitenant Azure Logic Apps | **AS2 (v2)** and **AS2** managed connectors (Standard class). The **AS2 (v2)** connector provides only actions, but you can use any trigger that works for your scenario. For more information, review the following documentation: <br><br>- [AS2 managed connector reference](/connectors/as2/) <br>- [AS2 (v2) managed connector operations](#as2-v2-operations) <br>- [AS2 message limits](logic-apps-limits-and-config.md#b2b-protocol-limits) |

+| **Consumption** | Integration service environment (ISE) | **AS2 (v2)** and **AS2** managed connectors (Standard class) and **AS2** ISE version, which has different message limits than the Standard class. The **AS2 (v2)** connector provides only actions, but you can use any trigger that works for your scenario. For more information, review the following documentation: <br><br>- [AS2 managed connector reference](/connectors/as2/) <br>- [AS2 (v2) managed connector operations](#as2-v2-operations) <br>- [AS2 message limits](logic-apps-limits-and-config.md#b2b-protocol-limits) |

+| **Standard** | Single-tenant Azure Logic Apps and App Service Environment v3 (Windows plans only) | **AS2 (v2)** built-in connector and **AS2** managed connector. The built-in version differs in the following ways: <br><br>- The built-in version provides only actions, but you can use any trigger that works for your scenario. <br><br>- The built-in version can directly access Azure virtual networks. You don't need an on-premises data gateway.<br><br>For more information, review the following documentation: <br><br>- [AS2 managed connector reference](/connectors/as2/) <br>- [AS2 (v2) built-in connector operations](#as2-v2-operations) <br>- [AS2 message limits](logic-apps-limits-and-config.md#b2b-protocol-limits) |

+| [**AS2 Encode** action](#encode) | Provides encryption, digital signing, and acknowledgments through Message Disposition Notifications (MDN), which help support nonrepudiation. For example, this action applies AS2/HTTP headers and performs the following tasks when configured: <br><br>- Sign outgoing messages. <br>- Encrypt outgoing messages. <br>- Compress the message. <br>- Transmit the file name in the MIME header. |

+| [**AS2 Decode** action](#decode) | Provide decryption, digital signing, and acknowledgments through Message Disposition Notifications (MDN). For example, this action performs the following tasks when configured: <br><br>- Process AS2/HTTP headers. <br>- Reconcile received MDNs with the original outbound messages. <br>- Update and correlate records in the nonrepudiation database. <br>- Write records for AS2 status reporting. <br>- Output payload contents as base64-encoded. <br>- Determine whether MDNs are required. Based on the AS2 agreement, determine whether MDNs should be synchronous or asynchronous. <br>- Generate synchronous or asynchronous MDNs based on the AS2 agreement. <br>- Set the correlation tokens and properties on MDNs. <br>- Verify the signature. <br>- Decrypt the messages. <br>- Decompress the message. <br>- Check and disallow message ID duplicates. |

+* An [integration account resource](./enterprise-integration/create-integration-account.md) to define and store artifacts for use in enterprise integration and B2B workflows.

+ | Consumption | - **AS2 (v2)** connector: Connection required, but no link required <br>- **AS2** connector: [Link required](./enterprise-integration/create-integration-account.md?tabs=consumption#link-account), but no connection required |

+ | Standard | - **AS2 (v2)** connector: [Link required](./enterprise-integration/create-integration-account.md?tabs=standard#link-account), but no connection required <br>- **AS2** connector: Connection required, but no link required |

+This guide shows how to add the EDIFACT encoding and decoding actions to an existing logic app workflow. When no **EDIFACT** trigger is available, you can any trigger to start your workflow. The examples in this guide use the [Request trigger](../connectors/connectors-native-reqres.md).

+The **EDIFACT** connector has different versions, based on [logic app type and host environment](logic-apps-overview.md#resource-environment-differences).

+| Logic app | Environment | Connector version |

+|--|-|-|

+| **Consumption** | multitenant Azure Logic Apps | **EDIFACT** managed connector (Standard class). The **EDIFACT** connector provides only actions, but you can use any trigger that works for your scenario. For more information, see the following documentation: <br><br>- [EDIFACT managed connector reference](/connectors/edifact/) <br>- [EDIFACT message limits](logic-apps-limits-and-config.md#b2b-protocol-limits) |

+| **Consumption** | Integration service environment (ISE) | **EDIFACT** managed connector (Standard class) and **EDIFACT** ISE version, which has different message limits than the Standard class. The **EDIFACT** connector provides only actions, but you can use any trigger that works for your scenario. For more information, see the following documentation: <br><br>- [EDIFACT managed connector reference](/connectors/edifact/) <br>- [EDIFACT message limits](logic-apps-limits-and-config.md#b2b-protocol-limits) |

+| **Standard** | Single-tenant Azure Logic Apps and App Service Environment v3 (Windows plans only) | **EDIFACT** built-in connector (preview) and **EDIFACT** managed connector. The built-in version differs in the following ways: <br><br>- The built-in version provides only actions, but you can use any trigger that works for your scenario. <br><br>- The built-in version can directly access Azure virtual networks. You don't need an on-premises data gateway.<br><br>For more information, see the following documentation: <br><br>- [EDIFACT managed connector reference](/connectors/edifact/) <br>- [EDIFACT built-in connector operations](#edifact-built-in-operations) <br>- [EDIFACT message limits](logic-apps-limits-and-config.md#b2b-protocol-limits) |

+<a name="edifact-built-in-operations"></a>

+### EDIFACT built-in operations (Standard workflows only - Preview)

+The preview **EDIFACT** built-in connector has the following actions, which are similar to their counterpart **EDIFACT** managed connector actions, except where noted in [Limitations and known issues](#limitations-known-issues).

+* [**EDIFACT Encode** action](#encode)

+* [**EDIFACT Decode** action](#decode)

+<a name="limitations-known-issues"></a>

+### Limitations and known issues

+* Preview **EDIFACT** built-in connector

+ * This capability is in preview and is subject to the [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

+ * This connector's actions currently support payloads up to at least 100 MB.

+ * The preview **EDIFACT Decode** action currently doesn't include the following capabilities:

+ * Check for duplicate interchange, group, and transaction set control numbers, if configured.

+ * Preserve the entire interchange.

+ Otherwise, the preview **EDIFACT Encode** and **EDIFACT decode** built-in connector actions have capabilities similar to their counterpart **EDIFACT** managed connector actions.

+ * This connector's actions currently don't support interchanges with multiple transactions or batched messages.

+ * This connector's actions don't currently emit EDI-specific tracking.

+* An [integration account resource](./enterprise-integration/create-integration-account.md) where you define and store artifacts, such as trading partners, agreements, certificates, and so on, for use in your enterprise integration and B2B workflows. This resource has to meet the following requirements:

+ * [Create an example Consumption logic app workflow in multitenant Azure Logic Apps](quickstart-create-example-consumption-workflow.md)

+The **EDIFACT** managed connector action named **Encode to EDIFACT message** action and the **EDIFACT** built-in connector action named **EDIFACT Encode** performs the following tasks, except where noted in [Limitations and known issues](#limitations-known-issues):

+* Resolve the agreement by matching the sender qualifier & identifier and receiver qualifier and identifier.

+* Serialize the Electronic Data Interchange (EDI), which converts XML-encoded messages into EDI transaction sets in the interchange.

+* Apply transaction set header and trailer segments.

+* Generate an interchange control number, a group control number, and a transaction set control number for each outgoing interchange.

+* Replace separators in the payload data.

+* Validate EDI and partner-specific properties, such as the schema for transaction-set data elements against the message schema, transaction-set data elements, and extended validation on transaction-set data elements.

+* Generate an XML document for each transaction set.

+* Request a technical acknowledgment, functional acknowledgment, or both, if configured.

+ * As a technical acknowledgment, the CONTRL message indicates the receipt for an interchange.

+ * As a functional acknowledgment, the CONTRL message indicates the acceptance or rejection for the received interchange, group, or message, including a list of errors or unsupported functionality.

+1. Provide the following connection information for your integration account:

+ 

+1. In the EDIFACT action, provide the following property values:

+ | Other parameters | No | This operation includes the following other parameters: <br><br>- **Data element separator** <br>- **Release indicator** <br>- **Component separator** <br>- **Repetition separator** <br>- **Segment terminator** <br>- **Segment terminator suffix** <br>- **Decimal indicator** <br><br>For more information, see [EDIFACT message settings](logic-apps-enterprise-integration-edifact-message-settings.md). |

+ For example, the XML message payload to encode can be the **Body** content output from the Request trigger:

+ 

+1. Save your workflow.

+#### EDIFACT built-in connector (preview)

+1. In the [Azure portal](https://portal.azure.com), open your logic app resource and workflow in the designer.

+1. In the designer, [follow these general steps to add the **EDIFACT** action named **EDIFACT Encode** to your workflow](create-workflow-with-trigger-or-action.md?tabs=standard#add-action).

+1. In the EDIFACT action pane, provide the required property values:

+ | Property | Required | Description |

+ |-|-|-|

+ | **Message To Encode** | Yes | The XML message content that you want to encode. Specifically, the business identifier for the message sender as specified by your EDIFACT agreement. |

+ | **Advanced parameters** | No | From the list, add any other properties that you want to use. This operation includes the following other parameters: <br><br>- **Sender Identity Receiver Qualifier** <br>- **Sender Identity Receiver Identifier** <br>- **Receiver Identity Receiver Qualifier** <br>- **Receiver Identity Receiver Identifier** <br>- **Name of EDIFACT agreement** |

+ For example, the XML message payload to encode can be the **Body** content output from the Request trigger:

+ 

+1. Save your workflow.

+#### EDIFACT managed connector

+1. Provide the following connection information for your integration account:

+ | **Integration Account ID** | Yes | The resource ID for your integration account, which has the following format: <br><br>**`/subscriptions/<Azure-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Logic/integrationAccounts/<integration-account-name>`** <br><br>For example: <br>`/subscriptions/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/resourceGroups/integrationAccount-RG/providers/Microsoft.Logic/integrationAccounts/myIntegrationAccount` <br><br>To find this resource ID, follow these steps: <br>1. In the Azure portal, open your integration account. <br>2. On the integration account menu, select **Overview**. <br>3. On the **Overview** page, select **JSON View**. <br>4. From the **Resource ID** property, copy the value. |

+ | **Integration Account SAS URL** | Yes | The request endpoint URL that uses shared access signature (SAS) authentication to provide access to your integration account. This callback URL has the following format: <br><br>**`https://<request-endpoint-URI>sp=<permissions>sv=<SAS-version>sig=<signature>`** <br><br>For example: <br>`https://prod-04.west-us.logic-azure.com:443/integrationAccounts/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX?api-version=2015-08-1-preview&sp=XXXXXXXXX&sv=1.0&sig=ZZZZZZZZZZZZZZZZZZZZZZZZZZZ` <br><br>To find this URL, follow these steps: <br>1. In the Azure portal, open your integration account. <br>2. On the integration account menu, under **Settings**, select **Callback URL**. <br>3. From the **Generated Callback URL** property, copy the value. |

+ | **Size of Control Number Block** | No | The block size of control numbers to reserve from an agreement for high throughput scenarios |

+ 

+1. In the EDIFACT action pane, provide the following property values:

+ | Other parameters | No | This operation includes the following other parameters: <br><br>- **Data element separator** <br>- **Release indicator** <br>- **Component separator** <br>- **Repetition separator** <br>- **Segment terminator** <br>- **Segment terminator suffix** <br>- **Decimal indicator** <br><br>For more information, see [EDIFACT message settings](logic-apps-enterprise-integration-edifact-message-settings.md). |

+ For example, the XML message payload to encode can be the **Body** content output from the Request trigger:

+ 

+1. Save your workflow.

+The **EDIFACT** managed connector action named **Decode EDIFACT message** action and the **EDIFACT** built-in connector action named **EDIFACT Decode** performs the following tasks, except where noted in [Limitations and known issues](#limitations-known-issues):

+* Validate the envelope against the trading partner agreement.

+* Resolve the agreement by matching the sender qualifier and identifier along with the receiver qualifier and identifier.

+* Split an interchange into multiple transaction sets when the interchange has more than one transaction, based on the agreement's **Receive Settings**.

+* Disassemble the interchange.

+* Validate Electronic Data Interchange (EDI) and partner-specific properties, such as the interchange envelope structure, the envelope schema against the control schema, the schema for the transaction-set data elements against the message schema, and extended validation on transaction-set data elements.

+* Verify that the interchange, group, and transaction set control numbers aren't duplicates (managed connector only), if configured, for example:

+ * Check the interchange control number against previously received interchanges.

+ * Check the group control number against other group control numbers in the interchange.

+ * Check the transaction set control number against other transaction set control numbers in that group.

+* Split the interchange into transaction sets, or preserve the entire interchange (managed connector only), for example:

+ * Split Interchange as transaction sets - suspend transaction sets on error.

+ The decoding action splits the interchange into transaction sets and parses each transaction set. The action outputs only those transaction sets that fail validation to `badMessages`, and outputs the remaining transactions sets to `goodMessages`.

+ * Split Interchange as transaction sets - suspend interchange on error.

+ The decoding action splits the interchange into transaction sets and parses each transaction set. If one or more transaction sets in the interchange fail validation, the action outputs all the transaction sets in that interchange to `badMessages`.

+ * Preserve Interchange - suspend transaction sets on error.

+ The decoding action preserves the interchange and processes the entire batched interchange. The action outputs only those transaction sets that fail validation to `badMessages`, and outputs the remaining transactions sets to `goodMessages`.

+ * Preserve Interchange - suspend interchange on error.

+ The decoding action preserves the interchange and processes the entire batched interchange. If one or more transaction sets in the interchange fail validation, the action outputs all the transaction sets in that interchange to `badMessages`.

+* Generate a technical acknowledgment, functional acknowledgment, or both, if configured.

+ * A technical acknowledgment or the CONTRL ACK, which reports the results from a syntactical check on the complete received interchange.

+ * A functional acknowledgment that acknowledges the acceptance or rejection for the received interchange or group.

+1. Provide the following connection information for your integration account:

+ 

+1. In the EDIFACT action, provide the following property values:

+ | Other parameters | No | This operation includes the following other parameters: <br><br>- **Component separator** <br>- **Data element separator** <br>- **Release indicator** <br>- **Repetition separator** <br>- **Segment terminator** <br>- **Segment terminator suffix** <br>- **Decimal indicator** <br>- **Payload character set** <br>- **Segment terminator suffix** <br>- **Preserve Interchange** <br>- **Suspend Interchange On Error** <br><br>For more information, see [EDIFACT message settings](logic-apps-enterprise-integration-edifact-message-settings.md). |

+ 

+#### EDIFACT built-in connector (preview)

+1. In the [Azure portal](https://portal.azure.com), open your logic app resource and workflow in the designer.

+1. In the designer, [follow these general steps to add the **EDIFACT** action named **EDIFACT Decode** to your workflow](create-workflow-with-trigger-or-action.md?tabs=standard#add-action).

+1. In the EDIFACT action, provide the following property values:

+ | Property | Required | Description |

+ |-|-|-|

+ | **Message To Decode** | Yes | The XML flat file message to decode. |

+ | Other parameters | No | This operation includes the following other parameters: <br><br>- **Component Separator** <br>- **Data Element Separator** <br>- **Release Indicator** <br>- **Repetition Separator** <br>- **Segment Terminator** <br>- **Segment Terminator Suffix** <br>- **Decimal Indicator** <br>- **Payload Character Set** <br>- **Segment Terminator Suffix** <br>- **Preserve Interchange** <br>- **Suspend Interchange On Error** <br><br>For more information, see [EDIFACT message settings](logic-apps-enterprise-integration-edifact-message-settings.md). |

+ For example, the XML message payload to decode can be the **Body** content output from the Request trigger:

+ 

+1. Save your workflow.

+#### EDIFACT managed connector

+1. Provide the following connection information for your integration account:

+ 

+1. In the EDIFACT action pane, provide the following property values:

+ | Other parameters | No | This operation includes the following other parameters: <br><br>- **Data element separator** <br>- **Release indicator** <br>- **Component separator** <br>- **Repetition separator** <br>- **Segment terminator** <br>- **Segment terminator suffix** <br>- **Decimal indicator** <br><br>For more information, see [EDIFACT message settings](logic-apps-enterprise-integration-edifact-message-settings.md). |

+ For example, the XML message payload to decode can be the **Body** content output from the Request trigger:

+| UAE Central | 20.45.75.193, 20.45.64.29, 20.45.64.87, 20.45.71.213, 40.126.212.77, 40.126.209.97 |

+| UAE Central | 20.45.75.200, 20.45.72.72, 20.45.75.236, 20.45.79.239, 20.45.67.170, 20.45.72.54, 20.45.67.134, 20.45.67.135, 40.126.210.93, 40.126.209.151, 40.126.208.156, 40.126.214.92 |

+In general, the user identity and endpoint identity would have separate permission requirements. For more information on managing identities and permissions, see [How to authenticate clients for online endpoints](how-to-authenticate-online-endpoint.md). For more information on the special case of automatically adding extra permission for secrets, see [Additional permissions for user identity](#additional-permissions-for-user-identity-when-enforcing-access-to-default-secret-stores).

+#### Additional permissions for user identity when enforcing access to default secret stores

+If you intend to use the [secret injection](concept-secret-injection.md) feature, and while creating your endpoints, you set the flag to enforce access to the default secret stores, your _user identity_ needs to have the permission to read secrets from workspace connections.

+When the endpoint is created with a system-assigned identity (SAI) _and_ the flag is set to enforce access to the default secret stores, your user identity needs to have permissions to read secrets from workspace connections when creating the endpoint and creating the deployment(s) under the endpoint. This restriction ensures that only a _user identity_ with the permission to read secrets can grant the endpoint identity the permission to read secrets.

+- If a user identity doesn't have the permissions to read secrets from workspace connections, but it tries to create the _endpoint_ with an SAI and the endpoint's flag set to enforce access to the default secret stores, the endpoint creation is rejected.

+- Similarly, if a user identity doesn't have the permissions to read secrets from workspace connections, but tries to create a _deployment_ under the endpoint with an SAI and the endpoint's flag set to enforce access to the default secret stores, the deployment creation is rejected.

+When (1) the endpoint is created with a UAI, _or_ (2) the flag is _not_ set to enforce access to the default secret stores even if the endpoint uses an SAI, your user identity doesn't need to have permissions to read secrets from workspace connections. In this case, the endpoint identity won't be automatically granted the permission to read secrets, but you can still manually grant the endpoint identity this permission by assigning proper roles if needed. Regardless of whether the role assignment was done automatically or manually, the secret retrieval and injection will still be triggered if you mapped the environment variables with secret references in the deployment definition, and it will use the endpoint identity to do so.

+For more information on managing authorization to an Azure Machine Learning workspace, see [Manage access to Azure Machine Learning](how-to-assign-roles.md).

+For more information on secret injection, see [Secret injection in online endpoints](concept-secret-injection.md).

+If the endpoint identity is a system-assigned identity, some roles are assigned to the endpoint identity for convenience.

+Role | Description | Condition for the automatic role assignment

+-- | -- | --

+`AcrPull` | Allows the endpoint identity to pull images from the Azure Container Registry (ACR) associated with the workspace. | The endpoint identity is a system-assigned identity (SAI).

+`Storage Blob Data Reader` | Allows the endpoint identity to read blobs from the default datastore of the workspace. | The endpoint identity is a system-assigned identity (SAI).

+`AzureML Metrics Writer (preview)` | Allows the endpoint identity to write metrics to the workspace. | The endpoint identity is a system-assigned identity (SAI).

+`Azure Machine Learning Workspace Connection Secrets Reader` ¹ | Allows the endpoint identity to read secrets from workspace connections. | The endpoint identity is a system-assigned identity (SAI). The endpoint is created with a flag to enforce access to the default secret stores. The _user identity_ that creates the endpoint has the same permission to read secrets from workspace connections. ²

+¹ For more information on the `Azure Machine Learning Workspace Connection Secrets Reader` role, see [Assign permissions to the identity](how-to-authenticate-online-endpoint.md#assign-permissions-to-the-identity).

+² Even if the endpoint identity is SAI, if the enforce flag is not set or the user identity doesn't have the permission, there's no automatic role assignment for this role. For more information, see [How to deploy online endpoint with secret injection](how-to-deploy-online-endpoint-with-secret-injection.md#create-an-endpoint).

+If the endpoint identity is a user-assigned identity, there's no automatic role assignment. In this case, you need to manually assign roles to the endpoint identity as needed.

+#Customer intent: As an ML pro, I want to understand what an online endpoint is and why I need it.

+### Secret injection in online deployments (preview)

+Secret injection in the context of an online deployment is a process of retrieving secrets (such as API keys) from secret stores, and injecting them into your user container that runs inside an online deployment. Secrets will eventually be accessible via environment variables, thereby providing a secure way for them to be consumed by the inference server that runs your scoring script or by the inferencing stack that you bring with a BYOC (bring your own container) deployment approach.

+There are two ways to inject secrets. You can inject secrets yourself, using managed identities, or you can use the secret injection feature. To learn more about the ways to inject secrets, see [Secret injection in online endpoints (preview)](concept-secret-injection.md).

+ Title: What is secret injection in online endpoints (preview)?

+description: Learn about secret injection as it applies to online endpoints in Azure Machine Learning.

+reviewer: msakande

+#CustomerIntent: As an ML Pro, I want to retrieve and inject secrets into the deployment environment easily so that deployments I create can consume the secrets in a secured manner.

+# Secret injection in online endpoints (preview)

+Secret injection in the context of an online endpoint is a process of retrieving secrets (such as API keys) from secret stores, and injecting them into your user container that runs inside an online deployment. Secrets are eventually accessed securely via environment variables, which are used by the inference server that runs your scoring script or by the inferencing stack that you bring with a BYOC (bring your own container) deployment approach.

+## Problem statement

+When you create an online deployment, you might want to use secrets from within the deployment to access external services. Some of these external services include Microsoft Azure OpenAI service, Azure AI Services, and Azure AI Content Safety.

+To use the secrets, you have to find a way to securely pass them to your user container that runs inside the deployment. We don't recommend that you include secrets as part of the deployment definition, since this practice would expose the secrets in the deployment definition.

+A better approach is to store the secrets in secret stores and then retrieve them securely from within the deployment. However, this approach poses its own challenge: how the deployment should authenticate itself to the secret stores to retrieve secrets. Because the online deployment runs your user container using the _endpoint identity_, which is a [managed identity](/entr) to control the endpoint identity's permissions and allow the endpoint to retrieve secrets from the secret stores.

+Using this approach requires you to do the following tasks:

+- Assign the right roles to the endpoint identity so that it can read secrets from the secret stores.

+- Implement the scoring logic for the deployment so that it uses the endpoint's managed identity to retrieve the secrets from the secret stores.

+While this approach of using a managed identity is a secure way to retrieve and inject secrets, [secret injection via the secret injection feature](#secret-injection-via-the-secret-injection-feature) further simplifies the process of retrieving secrets for [workspace connections](prompt-flow/concept-connections.md) and [key vaults](../key-vault/general/overview.md).

+## Managed identity associated with the endpoint

+An online deployment runs your user container with the managed identity associated with the endpoint. This managed identity, called the _endpoint identity_, is a [Microsoft Entra ID](/entr). Therefore, you can assign Azure roles to the identity to control permissions that are required to perform operations. The endpoint identity can be either a system-assigned identity (SAI) or a user-assigned identity (UAI). You can decide which of these kinds of identities to use when you create the endpoint.

+- For a _system-assigned identity_, the identity is created automatically when you create the endpoint, and roles with fundamental permissions (such as the Azure Container Registry pull permission and the storage blob data reader) are automatically assigned.

+- For a _user-assigned identity_, you need to create the identity first, and then associate it with the endpoint when you create the endpoint. You're also responsible for assigning proper roles to the UAI as needed.

+For more information on using managed identities of an endpoint, see [How to access resources from endpoints with managed identities](how-to-access-resources-from-endpoints-managed-identities.md), and the example for [using managed identities to interact with external services](https://github.com/Azure/azureml-examples/tree/main/cli/endpoints/online/managed/managed-identities).

+## Role assignment to the endpoint identity

+The following roles are required by the secret stores:

+- For __secrets stored in workspace connections under your workspace__: `Workspace Connections` provides a [List Secrets API (preview)](/rest/api/azureml/2023-08-01-preview/workspace-connections/list-secrets) that requires the identity that calls the API to have `Azure Machine Learning Workspace Connection Secrets Reader` role (or equivalent) assigned to the identity.

+- For __secrets stored in an external Microsoft Azure Key Vault__: Key Vault provides a [Get Secret Versions API](/rest/api/keyvault/secrets/get-secret-versions/get-secret-versions) that requires the identity that calls the API to have `Key Vault Secrets User` role (or equivalent) assigned to the identity.

+## Implementation of secret injection

+Once secrets (such as API keys) are retrieved from secret stores, there are two ways to inject them into a user container that runs inside the online deployment:

+- Inject secrets yourself, using managed identities.

+- Inject secrets, using the secret injection feature.

+Both of these approaches involve two steps:

+1. First, retrieve secrets from the secret stores, using the endpoint identity.

+1. Second, inject the secrets into your user container.

+### Secret injection via the use of managed identities

+In your deployment definition, you need to use the endpoint identity to call the APIs from secret stores. You can implement this logic either in your scoring script or in shell scripts that you run in your BYOC container. To implement secret injection via the use of managed identities, see the [example for using managed identities to interact with external services](https://github.com/Azure/azureml-examples/tree/main/cli/endpoints/online/managed/managed-identities).

+### Secret injection via the secret injection feature

+To use the secret injection feature, in your deployment definition, map the secrets (that you want to refer to) from workspace connections or the Key Vault onto the environment variables. This approach doesn't require you to write any code in your scoring script or in shell scripts that you run in your BYOC container. To map the secrets from workspace connections or the Key Vault onto the environment variables, the following conditions must be met:

+- During endpoint creation, if an online endpoint was defined to enforce access to default secret stores (workspace connections under the current workspace), your user identity that creates the deployment under the endpoint should have the permissions to read secrets from workspace connections.

+- The endpoint identity that the deployment uses should have permissions to read secrets from either workspace connections or the Key Vault, as referenced in the deployment definition.

+> [!NOTE]

+> - If the endpoint was successfully created with an SAI and the flag set to enforce access to default secret stores, then the endpoint would automatically have the permission for workspace connections.

+> - In the case where the endpoint used a UAI, or the flag to enforce access to default secret stores wasn't set, then the endpoint identity might not have the permission for workspace connections. In such a situation, you need to manually assign the role for the workspace connections to the endpoint identity.

+> - The endpoint identity won't automatically receive permission for the external Key Vault. If you're using the Key Vault as a secret store, you'll need to manually assign the role for the Key Vault to the endpoint identity.

+For more information on using secret injection, see [Deploy machine learning models to online endpoints with secret injection (preview)](how-to-deploy-online-endpoint-with-secret-injection.md).

+## Related content

+- [Deploy machine learning models to online endpoints with secret injection (preview)](how-to-deploy-online-endpoint-with-secret-injection.md)

+- [Authentication for managed online endpoints](concept-endpoints-online-auth.md)

+- [Online endpoints](concept-endpoints-online.md)

+The `AzureML Data Scientist` [built-in role](../role-based-access-control/built-in-roles.md#azureml-data-scientist) can be used to manage and use endpoints and deployments and it uses wildcards to include the following _control plane_ RBAC actions:

+Optionally, the `Azure Machine Learning Workspace Connection Secrets Reader` built-in role can be used to access secrets from workspace connections and it include the following _control plane_ RBAC actions:

+- `Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action`

+- `Microsoft.MachineLearningServices/workspaces/metadata/secrets/read`

+If you use these built-in roles, there's no action needed at this step.

+1. Optionally, if you're using the `Azure Machine Learning Workspace Connection Secrets Reader` built-in role, use the following code to assign the role to your user identity.

+ ```bash

+ az role assignment create --assignee <identityId> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

+ ```

+ Title: Access secrets from online deployment using secret injection (preview)

+description: Learn to use secret injection with online endpoint and deployment to access secrets like API keys.

+reviewer: msakande

+# Access secrets from online deployment using secret injection (preview)

+In this article, you learn to use secret injection with an online endpoint and deployment to access secrets from a secret store.

+You'll learn to:

+> [!div class="checklist"]

+> * Set up your user identity and its permissions

+> * Create workspace connections and/or key vaults to use as secret stores

+> * Create the endpoint and deployment by using the secret injection feature

+## Prerequisites

+- To use Azure Machine Learning, you must have an Azure subscription. If you don't have an Azure subscription, create a free account before you begin. Try the [free or paid version of Azure Machine Learning](https://azure.microsoft.com/free/) today.

+- Install and configure the [Azure Machine Learning CLI (v2) extension](how-to-configure-cli.md) or the [Azure Machine Learning Python SDK (v2)](https://aka.ms/sdk-v2-install).

+- An Azure Resource group, in which you (or the service principal you use) need to have `User Access Administrator` and `Contributor` access. You'll have such a resource group if you configured your Azure Machine Learning extension as stated previously.

+- An Azure Machine Learning workspace. You'll have a workspace if you configured your Azure Machine Learning extension as stated previously.

+- Any trained machine learning model ready for scoring and deployment.

+## Choose a secret store

+You can choose to store your secrets (such as API keys) using either:

+- __Workspace connections under the workspace__: If you use this kind of secret store, you can later grant permission to the endpoint identity (at endpoint creation time) to read secrets from workspace connections automatically, provided certain conditions are met. For more information, see the system-assigned identity tab from the [Create an endpoint](#create-an-endpoint) section.

+- __Key vaults__ that aren't necessarily under the workspace: If you use this kind of secret store, the endpoint identity won't be granted permission to read secrets from the key vaults automatically. Therefore, if you want to use a managed key vault service such as Microsoft Azure Key Vault as a secret store, you must assign a proper role later.

+#### Use workspace connection as a secret store

+You can create workspace connections to use in your deployment. For example, you can create a connection to Microsoft Azure OpenAI Service by using [Workspace Connections - Create REST API](/rest/api/azureml/2023-08-01-preview/workspace-connections/create).

+Alternatively, you can create a custom connection by using Azure Machine Learning studio (see [How to create a custom connection for prompt flow](./prompt-flow/tools-reference/python-tool.md#create-a-custom-connection)) or Azure AI Studio (see [How to create a custom connection in AI Studio](../ai-studio/how-to/connections-add.md?tabs=custom#create-a-new-connection)).

+1. Create an Azure OpenAI connection:

+ ```REST

+ PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview

+ Authorization: Bearer {{token}}

+ Content-Type: application/json

+

+ {

+ "properties": {

+ "authType": "ApiKey",

+ "category": "AzureOpenAI",

+ "credentials": {

+ "key": "<key>",

+ "endpoint": "https://<name>.openai.azure.com/",

+ },

+ "expiryTime": null,

+ "target": "https://<name>.openai.azure.com/",

+ "isSharedToAll": false,

+ "sharedUserList": [],

+ "metadata": {

+ "ApiType": "Azure"

+ }

+ }

+ }

+ ```

+1. Alternatively, you can create a custom connection:

+ ```REST

+ PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview

+ Authorization: Bearer {{token}}

+ Content-Type: application/json

+

+ {

+ "properties": {

+ "authType": "CustomKeys",

+ "category": "CustomKeys",

+ "credentials": {

+ "keys": {

+ "OPENAI_API_KEY": "<key>",

+ "SPEECH_API_KEY": "<key>"

+ }

+ },

+ "expiryTime": null,

+ "target": "_",

+ "isSharedToAll": false,

+ "sharedUserList": [],

+ "metadata": {

+ "OPENAI_API_BASE": "<oai endpoint>",

+ "OPENAI_API_VERSION": "<oai version>",

+ "OPENAI_API_TYPE": "azure",

+ "SPEECH_REGION": "eastus",

+ }

+ }

+ }

+ ```

+1. Verify that the user identity can read the secrets from the workspace connection, by using [Workspace Connections - List Secrets REST API (preview)](/rest/api/azureml/2023-08-01-preview/workspace-connections/list-secrets).

+ ```REST

+ POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}/listsecrets?api-version=2023-08-01-preview

+ Authorization: Bearer {{token}}

+ ```

+> [!NOTE]

+> The previous code snippets use a token in the `Authorization` header when making REST API calls. You can get the token by running `az account get-access-token`. For more information on getting a token, see [Get an access token](how-to-authenticate-online-endpoint.md#get-the-microsoft-entra-token-for-control-plane-operations).

+#### (Optional) Use Azure Key Vault as a secret store

+Create the key vault and set a secret to use in your deployment. For more information on creating the key vault, see [Set and retrieve a secret from Azure Key Vault using Azure CLI](../key-vault/secrets/quick-create-cli.md). Also,

+- [az keyvault CLI](/cli/azure/keyvault#az-keyvault-create) and [Set Secret REST API](/rest/api/keyvault/secrets/set-secret/set-secret) show how to set a secret.

+- [az keyvault secret show CLI](/cli/azure/keyvault/secret#az-keyvault-secret-show) and [Get Secret Versions REST API](/rest/api/keyvault/secrets/get-secret-versions/get-secret-versions) show how to retrieve a secret version.

+1. Create an Azure Key Vault:

+ ```azurecli

+ az keyvault create --name mykeyvault --resource-group myrg --location eastus

+ ```

+1. Create a secret:

+ ```azurecli

+ az keyvault secret set --vault-name mykeyvault --name secret1 --value <value>

+ ```

+ This command returns the secret version it creates. You can check the `id` property of the response to get the secret version. The returned response looks like `https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>`.

+1. Verify that the user identity can read the secret from the key vault:

+ ```azurecli

+ az keyvault secret show --vault-name mykeyvault --name secret1 --version <secret_version>

+ ```

+> [!IMPORTANT]

+> If you use the key vault as a secret store for secret injection, you must configure the key vault's permission model as Azure role-based access control (RBAC). For more information, see [Azure RBAC vs. access policy for Key Vault](/azure/key-vault/general/rbac-access-policy).

+## Choose a user identity

+Choose the user identity that you'll use to create the online endpoint and online deployment. This user identity can be a user account, a service principal account, or a managed identity in Microsoft Entra ID. To set up the user identity, follow the steps in [Set up authentication for Azure Machine Learning resources and workflows](how-to-setup-authentication.md).

+#### (Optional) Assign a role to the user identity

+- If your user identity wants the endpoint's system-assigned identity (SAI) to be automatically granted permission to read secrets from workspace connections, the user identity __must__ have the `Azure Machine Learning Workspace Connection Secrets Reader` role (or higher) on the scope of the workspace.

+ - An admin that has the `Microsoft.Authorization/roleAssignments/write` permission can run a CLI command to assign the role to the _user identity_:

+ ```azurecli

+ az role assignment create --assignee <UserIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

+ ```

+ > [!NOTE]

+ > The endpoint's system-assigned identity (SAI) won't be automatically granted permission for reading secrets from key vaults. Hence, the user identity doesn't need to be assigned a role for the Key Vault.

+- If you want to use a user-assigned identity (UAI) for the endpoint, you __don't need__ to assign the role to your user identity. Instead, if you intend to use the secret injection feature, you must assign the role to the endpoint's UAI manually.

+ - An admin that has the `Microsoft.Authorization/roleAssignments/write` permission can run the following commands to assign the role to the _endpoint identity_:

+ __For workspace connections__:

+ ```azurecli

+ az role assignment create --assignee <EndpointIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

+ ```

+

+ __For key vaults__:

+

+ ```azurecli

+ az role assignment create --assignee <EndpointIdentityID> --role "Key Vault Secrets User" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.KeyVault/vaults/<vaultName>

+ ```

+- Verify that an identity (either a user identity or endpoint identity) has the role assigned, by going to the resource in the Azure portal. For example, in the Azure Machine Learning workspace or the Key Vault:

+ 1. Select the __Access control (IAM)__ tab.

+ 1. Select the __Check access__ button and find the identity.

+ 1. Verify that the right role shows up under the __Current role assignments__ tab.

+## Create an endpoint

+### [System-assigned identity](#tab/sai)

+If you're using a system-assigned identity (SAI) as the endpoint identity, specify whether you want to enforce access to default secret stores (namely, workspace connections under the workspace) to the endpoint identity.

+1. Create an `endpoint.yaml` file:

+ ```YAML

+ $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json

+ name: my-endpoint

+ auth_mode: key

+ properties:

+ enforce_access_to_default_secret_stores: enabled # default: disabled

+ ```

+1. Create the endpoint, using the `endpoint.yaml` file:

+ ```azurecli

+ az ml online-endpoint create -f endpoint.yaml

+ ```

+If you don't specify the `identity` property in the endpoint definition, the endpoint will use an SAI by default.

+If the following conditions are met, the endpoint identity will automatically be granted the `Azure Machine Learning Workspace Connection Secrets Reader` role (or higher) on the scope of the workspace:

+

+- The user identity that creates the endpoint has the permission to read secrets from workspace connections (`Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action`).

+- The endpoint uses an SAI.

+- The endpoint is defined with a flag to enforce access to default secret stores (workspace connections under the current workspace) when creating the endpoint.

+The endpoint identity won't automatically be granted a role to read secrets from the Key Vault. If you want to use the Key Vault as a secret store, you need to manually assign a proper role such as `Key Vault Secrets User` to the _endpoint identity_ on the scope of the Key Vault. For more information on roles, see [Azure built-in roles for Key Vault data plane operations](../key-vault/general/rbac-guide.md#azure-built-in-roles-for-key-vault-data-plane-operations).

+### [User-assigned identity](#tab/uai)

+If you're using a user-assigned identity (UAI) as the endpoint identity, you're not allowed to specify the `enforce_access_to_default_secret_stores` flag.

+1. Create an `endpoint.yaml` file:

+ ```YAML

+ $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json

+ name: my-endpoint

+ auth_mode: key

+ identity:

+ type: user_assigned

+ user_assigned_identities: /subscriptions/00000000-0000-0000-000-000000000000/resourcegroups/myrg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-identity

+ ```

+1. Create the endpoint, using the `endpoint.yaml` file:

+ ```azurecli

+ az ml online-endpoint create -f endpoint.yaml

+ ```

+When using a UAI, you must manually assign any required roles to the endpoint identity as described in the optional section [Assign role to the user identity](#optional-assign-a-role-to-the-user-identity).

+## Create a deployment

+1. Author a scoring script or Dockerfile and the related scripts so that the deployment can consume the secrets via environment variables.

+

+ - There's no need for you to call the secret retrieval APIs for the workspace connections or key vaults. The environment variables are populated with the secrets when the user container in the deployment initiates.

+ - The value that gets injected into an environment variable can be one of the three types:

+ - The whole [List Secrets API (preview)](/rest/api/azureml/workspace-connections/list-secrets) response. You'll need to understand the API response structure, parse it, and use it in your user container.

+ - Individual secret or metadata from the workspace connection. You can use it without understanding the workspace connection API response structure.

+ - Individual secret version from the Key Vault. You can use it without understanding the Key Vault API response structure.

+1. Initiate the creation of the deployment, using either the scoring script (if you use a custom model) or a Dockerfile (if you take the BYOC approach to deployment). Specify environment variables the user expects within the user container.

+ If the values that are mapped to the environment variables follow certain patterns, the endpoint identity will be used to perform secret retrieval and injection.

+ | Pattern | Behavior |

+ | -- | -- |

+ | `${{azureml://connections/<connection_name>}}` | The whole [List Secrets API (preview)](/rest/api/azureml/workspace-connections/list-secrets) response is injected into the environment variable. |

+ | `${{azureml://connections/<connection_name>/credentials/<credential_name>}}` | The value of the credential is injected into the environment variable. |

+ | `${{azureml://connections/<connection_name>/metadata/<metadata_name>}}` | The value of the metadata is injected into the environment variable. |

+ | `${{azureml://connections/<connection_name>/target}}` | The value of the target (where applicable) is injected into the environment variable. |

+ | `${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}}` | The value of the secret version is injected into the environment variable. |

+ For example:

+ 1. Create `deployment.yaml`:

+ ```YAML

+ $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json

+ name: blue

+ endpoint_name: my-endpoint

+ #…

+ environment_variables:

+ AOAI_CONNECTION: ${{azureml://connections/aoai_connection}}

+ LANGCHAIN_CONNECTION: ${{azureml://connections/multi_connection_langchain}}

+

+ OPENAI_KEY: ${{azureml://connections/multi_connection_langchain/credentials/OPENAI_API_KEY}}

+ OPENAI_VERSION: ${{azureml://connections/multi_connection_langchain/metadata/OPENAI_API_VERSION}}

+

+ USER_SECRET_KV1_KEY: ${{keyvault:https://mykeyvault.vault.azure.net/secrets/secret1/secretversion1}}

+ ```

+ 1. Create the deployment:

+ ```azurecli

+ az ml online-deployment create -f deployment.yaml

+ ```

+If the `enforce_access_to_default_secret_stores` flag was set for the endpoint, the user identity's permission to read secrets from workspace connections will be checked both at endpoint creation and deployment creation time. If the user identity doesn't have the permission, the creation will fail.

+At deployment creation time, if any environment variable is mapped to a value that follows the patterns in the previous table, secret retrieval and injection will be performed with the endpoint identity (either an SAI or a UAI). If the endpoint identity doesn't have the permission to read secrets from designated secret stores (either workspace connections or key vaults), the deployment creation will fail. Also, if the specified secret reference doesn't exist in the secret stores, the deployment creation will fail.

+For more information on errors that can occur during deployment of Azure Machine Learning online endpoints, see [Secret Injection Errors](how-to-troubleshoot-online-endpoints.md#error-secretsinjectionerror).

+## Consume the secrets

+You can consume the secrets by retrieving them from the environment variables within the user container running in your deployments.

+## Related content

+- [Secret injection in online endpoints (preview)](concept-secret-injection.md)

+- [How to authenticate clients for online endpoint](how-to-authenticate-online-endpoint.md)

+- [Deploy and score a model using an online endpoint](how-to-deploy-online-endpoints.md)

+- [Use a custom container to deploy a model using an online endpoint](how-to-deploy-custom-container.md)

+```azurecli-interactive

+¹ This is a regional limit. For example, if current limit on number of endpoint is 100, you can create 100 endpoints in the East US region, 100 endpoints in the West US region, and 100 endpoints in each of the other supported regions in a single subscription. Same principle applies to all the other limits.

+² Single dashes like, `my-endpoint-name`, are accepted in endpoint and deployment names.

+³ Endpoints and deployments can be of different types, but limits apply to the sum of all types. For example, the sum of managed online endpoints, Kubernetes online endpoint and batch endpoint under each subscription can't exceed 100 per region by default. Similarly, the sum of managed online deployments, Kubernetes online deployments and batch deployments under each subscription can't exceed 500 per region by default.

+⁴ We reserve 20% extra compute resources for performing upgrades. For example, if you request 10 instances in a deployment, you must have a quota for 12. Otherwise, you receive an error. There are some VM SKUs that are exempt from extra quota. See [virtual machine quota allocation for deployment](how-to-deploy-online-endpoints.md#virtual-machine-quota-allocation-for-deployment) for more.

+⁵ Requests per second, connections, bandwidth etc are related. If you request for increase for any of these limits, ensure estimating/calculating other related limites together.

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

+### [Python SDK](#tab/python)

+### [Studio](#tab/studio)

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

+### [Python SDK](#tab/python)

+### [Studio](#tab/studio)

+ * [Azure Container Registry (ACR) authorization failure](#container-registry-authorization-failure)

+ * [Image build compute not set in a private workspace with VNet](#image-build-compute-not-set-in-a-private-workspace-with-vnet)

+ * [Generic or unknown failure](#generic-image-build-failure)

+ * [CPU](#cpu-quota)

+ * [Cluster](#cluster-quota)

+ * [Disk](#disk-quota)

+ * [Memory](#memory-quota)

+ * [Role assignments](#role-assignment-quota)

+ * [Endpoints](#endpoint-quota)

+ * [Region-wide VM capacity](#region-wide-vm-capacity)

+ * [Other](#other-quota)

+ * Common to both managed online endpoint and Kubernetes online endpoint

+ * [Subscription doesn't exist](#subscription-does-not-exist)

+ * [Startup task failed due to authorization error](#authorization-error)

+ * [Startup task failed due to incorrect role assignments on resource](#authorization-error)

+ * [Invalid template function specification](#invalid-template-function-specification)

+ * [Unable to download user container image](#unable-to-download-user-container-image)

+ * [Unable to download user model](#unable-to-download-user-model)

+ * Errors limited to Kubernetes online endpoint

+ * [Resource request was greater than limits](#resource-requests-greater-than-limits)

+ * [azureml-fe for kubernetes online endpoint isn't ready](#azureml-fe-not-ready)

+ * [Azure Resource Manager can't find a required resource](#resource-manager-cannot-find-a-resource)

+ * [Azure Container Registry is private or otherwise inaccessible](#container-registry-authorization-error)

+ * [Operation was canceled by another operation that has a higher priority](#operation-canceled-by-another-higher-priority-operation)

+ * [Operation was canceled due to a previous operation waiting for lock confirmation](#operation-canceled-waiting-for-lock-confirmation)

+* [SecretsInjectionError](#error-secretsinjectionerror)

+* [InternalServerError](#error-internalservererror)

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

+##### [Python SDK](#tab/python)

+##### [Studio](#tab/studio)

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

+##### [Python SDK](#tab/python)

+##### [Studio](#tab/studio)

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

+ ##### [Python SDK](#tab/python)

+ ##### [Studio](#tab/studio)

+### ERROR: SecretsInjectionError

+Secret retrieval and injection during online deployment creation uses the identity associated with the online endpoint to retrieve secrets from the workspace connections and/or key vaults. This error happens when:

+- The endpoint identity doesn't have the Azure RBAC permission to read the secrets from the workspace connections and/or key vaults, even though the secrets were specified by the deployment definition as references (mapped to environment variables). Remember that role assignment may take time for changes to take effect.

+- The format of the secret references are invalid, or the specified secrets do not exist in the workspace connections and/or key vaults.

+For more information, see [Secret injection in online endpoints (preview)](concept-secret-injection.md) and [Access secrets from online deployment using secret injection (preview)](how-to-deploy-online-endpoint-with-secret-injection.md).

+| Alert rules | Maximum number of alert rules that can be created | Not supported | 500 per instance |

+We're pleased to announce the launch of OpenShift 4.13 for Azure Red Hat OpenShift. This release enables [OpenShift Container Platform 4.13](https://docs.openshift.com/container-platform/4.13/release_notes/ocp-4-13-release-notes.html). Version 4.11 will be outside of support after January 26, 2024. Existing clusters version 4.11 and below should be upgraded before then.

+|4.11|August 2022| March 2 2023|January 26 2024|

+

+ Title: Business Continuity and Disaster recovery (BCDR) for Azure Operator Insights

+description: This article helps you understand BCDR concepts Azure Operator Insights.

+# Business continuity and disaster recovery

+Disasters can be hardware failures, natural disasters, or software failures. The process of preparing for and recovering from a disaster is called disaster recovery (DR). This article discusses recommended practices to achieve business continuity and disaster recovery (BCDR) for Azure Operator Insights.

+BCDR strategies include availability zone redundancy and user-managed recovery.

+## Control plane

+The Azure Operator Insights control plane is resilient both to software errors and failure of an Availability Zone. The ability to create and manage Data Products isn't affected by these failure modes.

+The control plane isn't regionally redundant. During an outage in an Azure region, you can't create new Data Products in that region or access/manage existing ones. Once the region recovers from the outage, you can access and manage existing Data Products again.

+## Data plane

+Data Products are resilient to software or hardware failures. For example, if a software bug causes the service to crash, or a hardware failure causes the compute resources for enrichment queries to be lost, service automatically recovers. The only impact is a slight delay in newly ingested data becoming available in the Data Product's storage endpoint and in the KQL consumption URL.

+### Zone redundancy

+Data Products don't support zone redundancy. When an availability zone fails, the Data Product's ingestion, blob/DFS and KQL/SQL APIs are all unavailable, and dashboards don't work. Transformation of already-ingested data is paused. No previously ingested data is lost. Processing resumes when the availability zone recovers.

+What happens to data that was generated during the availability zone outage depends on the behavior of the ingestion agent:

+* If the ingestion agent buffers data and resends it when the availability zone recovers, data isn't lost. Azure Operator Insights might take some time to work through its transformation backlog.

+* Otherwise, data is lost.

+### Disaster recovery

+Azure Operator Insights has no innate region redundancy. Regional outages affect Data Products in the same way as [availability zone failures](#zone-redundancy). We have recommendations and features to support customers that want to be able to handle failure of an entire Azure region.

+#### User-managed redundancy

+For maximal redundancy, you can deploy Data Products in an active-active mode. Deploy a second Data Product in a backup Azure region of your choice, and configure your ingestion agents to fork data to both Data Products simultaneously. The backup data product is unaffected by the failure of the primary region. During a regional outage, look at dashboards that use the backup Data Product as the data source. This architecture doubles the cost of the solution.

+Alternatively, you could use an active-passive mode. Deploy a second Data Product in a backup Azure region, and configure your ingestion agents to send to the primary Data Product. During a regional outage, reconfigure your ingestion agents to send data to the backup Data Product during a region outage. This architecture gives full access to data created during the outage (starting from the time where you reconfigure the ingestion agents), but during the outage you don't have access to data ingested before that time. This architecture requires a small infrastructure charge for the second Data Product, but no additional data processing charges.

+ Title: Manage permissions for Azure Operator Insights consumption plane

+description: This article helps you configure consumption URI permissions for Azure Operator Insights.

+# Manage permissions to the consumption URL

+Azure Operator Insights enables you to control access to the consumption URL of each Data Product based on email addresses or distribution lists. Use the following steps to configure read-only access to the consumption URL.

+Azure Operator Insights currently supports a single role that gives Read access to all tables and columns on the consumption URL.

+## Add user access

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

+1. Go to your Azure Operator Insights Data Product resource.

+1. In the left-hand menu under **Security**, select **Permissions**.

+1. Select **Add Reader** to add a new user.

+1. Type in the user's email address or distribution list and select **Add Reader(s)**.

+1. Wait for about 30 seconds, then refresh the page to view your changes.

+## Remove user access

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

+1. Go to your Azure Operator Insights Data Product resource.

+1. In the left-hand menu under **Security**, select **Permissions**.

+1. Select the **Delete** symbol next to the user who you want to remove.

+ > [!NOTE]

+ > There is no confirmation dialog box, so be careful when deleting users.

+1. Wait for about 30 seconds, then refresh the page to view your changes.

+#CustomerIntent: As a consumer of the Data Product, I want to query data that has been collected so that I can visualize the data and gain customized insights.

+- A deployed Data Product: see [Create an Azure Operator Insights Data Product](data-product-create.md).

+- The `Reader` role for the data for this Data Product, because access to the data is controlled by role-based access control (RBAC).

+ - To check your access, sign in to the [Azure portal](https://portal.azure.com), go to the Data Product resource and open the **Permissions** pane. You must have the `Reader` role.

+ - If you don't have this role, ask an owner of the resource to give you `Reader` permissions by following [Manage permissions to the consumption URL](consumption-plane-configure-permissions.md).

+## Add the consumption URL in Azure Data Explorer

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

+1. Go to your Azure Operator Insights Data Product resource.

+1. In the **Overview** pane, copy the Consumption URL.

+ Title: Manage virtual networks - Azure portal with Private Link - Azure Database for PostgreSQL - Flexible Server

+description: Learn how to create a PostgreSQL server with public access by using the Azure portal, and how to add private networking to the server based on Azure Private Link.

+# Create and manage virtual networks with Private Link for Azure Database for PostgreSQL - Flexible Server by using the Azure portal

+Azure Database for PostgreSQL - Flexible Server supports two types of mutually exclusive network connectivity methods to connect to your flexible server:

+* Public access through allowed IP addresses. You can further secure that method by using [Azure Private Link](./concepts-networking-private-link.md)-based networking with Azure Database for PostgreSQL - Flexible Server. The feature is in preview.

+* Private access through virtual network integration.

+This article focuses on creation of a PostgreSQL server with public access (allowed IP addresses) by the using Azure portal. You can then help secure the server by adding private networking based on Private Link technology.

+You can use [Private Link](../../private-link/private-link-overview.md) to access the following services over a private endpoint in your virtual network:

+* Azure platform as a service (PaaS) services, such as Azure Database for PostgreSQL - Flexible Server

+* Customer-owned or partner services that are hosted in Azure

+Traffic between your virtual network and a service traverses the Microsoft backbone network, which eliminates exposure to the public internet.

+To add a flexible server to a virtual network by using Private Link, you need:

+* A [virtual network](../../virtual-network/quick-create-portal.md#create-a-virtual-network). The virtual network and subnet should be in the same region and subscription as your flexible server.

+ Be sure to remove any locks (**Delete** or **Read only**) from your virtual network and all subnets before you add a server to the virtual network, because locks might interfere with operations on the network and DNS. You can reset the locks after server creation.

+* Registration of the [PostgreSQL private endpoint preview feature in your subscription](../../azure-resource-manager/management/preview-features.md).

+## Create an Azure Database for PostgreSQL - Flexible Server instance with a private endpoint

+1. In the upper-left corner of the Azure portal, select **Create a resource** (the plus sign).

+2. Select **Databases** > **Azure Database for PostgreSQL**.

+4. Fill out the **Basics** form with the following information:

+ |Setting |Value|

+ |||

+ |**Subscription**| Select your Azure subscription.|

+ |**Resource group**| Select your Azure resource group.|

+ |**Server name**| Enter a unique server name.|

+ |**Admin username** |Enter an administrator name of your choosing.|

+ |**Password**|Enter a password of your choosing. The password must have at least eight characters and meet the defined requirements.|

+ |**Location**|Select an Azure region where you want to want your PostgreSQL server to reside.|

+ |**Version**|Select the required database version of the PostgreSQL server.|

+ |**Compute + Storage**|Select the pricing tier that you need for the server, based on the workload.|

+5. Select **Next: Networking**.

+6. For **Connectivity method**, select the **Public access (allowed IP addresses) and private endpoint** checkbox.

+7. In the **Private Endpoint (preview)** section, select **Add private endpoint**.

+ :::image type="content" source="./media/how-to-manage-virtual-network-private-endpoint-portal/private-endpoint-selection.png" alt-text="Screenshot of the button for adding a private endpoint button on the Networking pane in the Azure portal." :::

+8. On the **Create Private Endpoint** pane, enter the following values:

+ |Setting|Value|

+ |||

+ |**Subscription**| Select your subscription.|

+ |**Resource group**| Select the resource group that you chose previously.|

+ |**Location**|Select an Azure region where you created your virtual network.|

+ |**Name**|Enter a name for the private endpoint.|

+ |**Target subresource**|Select **postgresqlServer**.|

+ |**NETWORKING**|

+ |**Virtual Network**| Enter a name for the Azure virtual network that you created previously. |

+ |**Subnet**|Enter the name of the Azure subnet that you created previously.|

+ |**PRIVATE DNS INTEGRATION**|

+ |**Integrate with Private DNS Zone**| Select **Yes**.|

+ |**Private DNS Zone**| Select **(New)privatelink.postgresql.database.azure.com**. This setting creates a new private DNS zone.|

+10. Select **Review + create**.

+11. On the **Review + create** tab, Azure validates your configuration. The **Networking** section lists information about your private endpoint.

+ When you see the message that your configuration passed validation, select **Create**.

+### Approval process for a private endpoint

+A separation of duties is common in many enterprises today:

+* A network administrator creates the cloud networking infrastructure, such as Azure Private Link services.

+* A database administrator (DBA) creates and manages database servers.

+After a network administrator creates a private endpoint, the PostgreSQL DBA can manage the private endpoint connection to Azure Database for PostgreSQL. The DBA uses the following approval process for a private endpoint connection:

+1. In the Azure portal, go to the Azure Database for PostgreSQL - Flexible Server resource.

+1. On the left pane, select **Networking**.

+1. A list of all private endpoint connections appears, along with corresponding private endpoints. Select a private endpoint connection from the list.

+1. Select **Approve** or **Reject**, and optionally add a short text response.

+ After approval or rejection, the list reflects the appropriate state, along with the response text.

+* Learn more about [networking in Azure Database for PostgreSQL - Flexible Server with Private Link](./concepts-networking-private-link.md).

+* Understand more about [virtual network integration in Azure Database for PostgreSQL - Flexible Server](./concepts-networking-private.md).

+- Learn more about [Logging](./concepts-logging.md)

+3. Select Save.

+## Next steps

+- To enable and disable Server logs from CLI, you can refer to the [article.](./how-to-server-logs-cli.md)

+- Learn more about [Logging](./concepts-logging.md)

+ Title: Connect to an Azure Data Factory privately networked pipeline with Azure Database for PostgreSQL - Flexible Server by using Azure Private Link

+description: This article describes how to connect Azure Database for PostgreSQL - Flexible Server to an Azure-hosted Data Factory pipeline via Private Link.

+# Connect to an Azure Data Factory privately networked pipeline with Azure Database for PostgreSQL - Flexible Server by using Azure Private Link

+In this article, you connect Azure Database for PostgreSQL - Flexible Server to an Azure Data Factory pipeline via Azure Private Link.

+[Azure Data Factory](../../data-factory/introduction.md) is a fully managed, serverless solution to ingest and transform data. An Azure [integration runtime](../../data-factory/concepts-integration-runtime.md#azure-integration-runtime) supports connecting to data stores and compute services with public accessible endpoints. When you enable a managed virtual network, an integration runtime supports connecting to data stores by using the Azure Private Link service in a private network environment.

+Data Factory offers three types of integration runtimes:

+- Azure-SQL Server Integration Services (Azure-SSIS)

+Choose the type that best serves your data integration capabilities and network environment requirements.

+Azure Database for PostgreSQL - Flexible Server provides for Private Link connectivity in preview. For more information, see [this article](../flexible-server/concepts-networking-private-link.md).

+- An Azure Database for PostgreSQL - Flexible Server instance that's [privately networked via Azure Private Link](../flexible-server/concepts-networking-private-link.md)

+- An Azure integration runtime within a [Data Factory managed virtual network](../../data-factory/data-factory-private-link.md)

+## Create a private endpoint in Data Factory

+An Azure Database for PostgreSQL connector currently supports *public connectivity only*. When you use an Azure Database for PostgreSQL connector in Azure Data Factory, you might get an error when you try to connect to a privately networked instance of Azure Database for PostgreSQL - Flexible Server.

+To work around this limitation, you can use the Azure CLI to create a private endpoint first. Then you can use the Data Factory user interface with the Azure Database for PostgreSQL connector to create a connection between privately networked Azure Database for PostgreSQL - Flexible Server and Azure Data Factory in a managed virtual network.

+The following example creates a private endpoint in Azure Data Factory. Substitute the placeholders *subscription_id*, *resource_group_name*, *azure_data_factory_name*, *endpoint_name*, and *flexible_server_name* with your own values.

+> An alternative command to create a private endpoint in Data Factory by using the Azure CLI is [az datafactory managed-private-endpoint create](/cli/azure/datafactory/managed-private-endpoint).

+After you successfully run the preceding command, you can view the private endpoint in the Azure portal by going to **Data Factory** > **Managed private endpoints**. The following screenshot shows an example.

+## Approve a private endpoint

+After you provision a private endpoint, you can approve it by following the **Manage approvals in Azure portal** link in the endpoint details. It takes several minutes for Data Factory to discover that the private endpoint is approved.

+## Add a networked server data source in Data Factory

+After you provision and approve a private endpoint, you can create a connection to Azure Database for PostgreSQL - Flexible Server by using a Data Factory connector.

+In the previous steps, when you selected the server for which you created the private endpoint, the private endpoint was also selected automatically.

+1. Select a database, enter a username and password, and select **SSL** as the encryption method. The following screenshot shows an example.

+1. Select **Test connection**. A "Connection Successful" message should appear.

+## Next step

+> [Networking with Private Link in Azure Database for PostgreSQL - Flexible Server](concepts-networking-private-link.md)

+>| Azure Cosmos DB (Microsoft.DocumentDB/databaseAccounts) | Analytical | privatelink.analytics.cosmos.azure.com | analytics.cosmos.azure.com |

+A multi-service resource references a set of Azure AI services as the offering, rather than individual services, with access granted through a single API key. This key is specified in a [**skillset**](/rest/api/searchservice/create-skillset) and allows Microsoft to charge you for using these

+Enrichments are billable operations. If you no longer need to call Azure AI services, follow these instructions to remove the multi-region key and prevent use of the external resource. Without the key, the skillset reverts to the default allocation of 20 free transactions per indexer, per day. Execution of billable skills stops at 20 transactions and a "Time Out" message appears in indexer execution history when the allocation is used up.

+The key is used for billing, but not for enrichment operations' connections. For connections, a search service [connects over the internal network](search-security-overview.md#internal-traffic) to an Azure AI services resource that's located in the [same physical region](https://azure.microsoft.com/global-infrastructure/services/?products=search). Most regions that offer Azure AI Search also offer other Azure AI services such as Language. If you attempt AI enrichment in a region that doesn't have both services, you'll see this message: "Provided key isn't a valid CognitiveServices type key for the region of your search service."

+Images are either standalone binary files or embedded in documents (PDF, RTF, and Microsoft application files). A maximum of 1000 images can be extracted from a given document. If there are more than 1000 images in a document, the first 1000 are extracted and then a warning is generated.

+After the source files are set up, enable image normalization by setting the `imageAction` parameter in indexer configuration. Image normalization helps make images more uniform for downstream processing. Image normalization includes the following operations:

+Metadata adjustments are captured in a complex type created for each image. You can't opt out of the image normalization requirement. Skills that iterate over images, such as OCR and image analysis, expect normalized images.

+1. Set `dataToExtract` to `contentAndMetadata` (required).

+1. Verify that the `parsingMode` is set to default (required).

+1. Set `imageAction` to enable the *normalized_images* node in an enrichment tree (required):

+ + `generateNormalizedImages` to generate an array of normalized images as part of document cracking.

+ + `generateNormalizedImagePerPage` (applies to PDF only) to generate an array of normalized images where each page in the PDF is rendered to one output image. For non-PDF files, the behavior of this parameter is similar as if you had set "generateNormalizedImages". However, note that setting "generateNormalizedImagePerPage" can make indexing operation less performant by design (especially for large documents) since several images would have to be generated.

+ + `normalizedImageMaxWidth` (in pixels). Default is 2000. Maximum value is 10000.

+ + `normalizedImageMaxHeight` (in pixels). Default is 2000. Maximum value is 10000.

+When `imageAction` is set to a value other than "none", the new *normalized_images* field contains an array of images. Each image is a complex type that has the following members:

+| contentOffset | The character offset within the content field where the image was extracted from. This field is only applicable for files with embedded images. The *contentOffset* for images extracted from PDF documents is always at the end of the text on the page it was extracted from in the document. This means images appear after all text on that page, regardless of the original location of the image in the page. |

+| pageNumber | If the image was extracted or rendered from a PDF, this field contains the page number in the PDF it was extracted or rendered from, starting from 1. If the image isn't from a PDF, this field is 0. |

+In a skillset, Image Analysis and OCR skill output is always text. Output text is represented as nodes in an internal enriched document tree, and each node must be mapped to fields in a search index, or to projections in a knowledge store, to make the content available in your app.

+1. In the skillset, review the `outputs` section of each skill to determine which nodes exist in the enriched document:

+ In the following fields collection example, "content" is blob content. "Metadata_storage_name" contains the name of the file (make sure it is "retrievable"). "Metadata_storage_path" is the unique path of the blob and is the default document key. "Merged_content" is output from Text Merge (useful when images are embedded).

+ Enriched documents are internal. To externalize the nodes in an enriched document tree, set up an output field mapping that specifies which index field receives node content. Enriched data is accessed by your app through an index field. The following example shows a "text" node (OCR output) in an enriched document that's mapped to a "text" field in a search index.

+OCR recognizes text in image files. This means that OCR fields ("text" and "layoutText") are empty if source documents are pure text or pure imagery. Similarly, image analysis fields ("imageCaption" and "imageTags") are empty if source document inputs are strictly text. Indexer execution emits warnings if imaging inputs are empty. Such warnings are to be expected when nodes are unpopulated in the enriched document. Recall that blob indexing lets you include or exclude file types if you want to work with content types in isolation. You can use these setting to reduce noise during indexer runs.

+An alternate query for checking results might include the "content" and "merged_content" fields. Notice that those fields include content for any blob file, even those where there was no image processing performed.

+When the images you want to process are embedded in other files, such as PDF or DOCX, the enrichment pipeline extracts just the images and then pass them to OCR or image analysis for processing. Image extraction occurs during the document cracking phase, and once the images are separated, they remain separate unless you explicitly merge the processed output back into the source text.

+[**Text Merge**](cognitive-search-skill-textmerger.md) is used to put image processing output back into the document. Although Text Merge isn't a hard requirement, it's frequently invoked so that image output (OCR text, OCR layoutText, image tags, image captions) can be reintroduced into the document. Depending on the skill, the image output replaces an embedded binary image with an in-place text equivalent. Image Analysis output can be merged at image location. OCR output always appears at the end of each page.

+1. Image outputs are passed into the enriched document tree, with each output as a separate node. Outputs vary by skill (text and layoutText for OCR, tags and captions for Image Analysis).

+Now that you have a merged_text field, you can map it as a searchable field in your indexer definition. All of the content of your files, including the text of the images, will be searchable.

+Since the OCR step is performed on the normalized images, the layout coordinates are in the normalized image space, but if you need to display the original image, convert coordinate points in the layout to the original image coordinate system.

+The following algorithm illustrates the pattern:

+The custom skill itself is external to the skillset. In this case, it's Python code that first loops through the batch of request records in the custom skill format, then converts the base64-encoded string to an image.

+description: A skillset defines steps for content extraction, natural language processing, and image analysis. A skillset is attached to indexer. It's used to enrich and extract information from source data for indexing in Azure AI Search.

+A skillset defines operations that generate textual content and structure from documents that contain images or unstructured text. Examples are OCR for images, entity recognition for undifferentiated text, and text translation. A skillset executes after text and images are extracted from an external data source, and after [field mappings](search-indexer-field-mappings.md) are processed.

+This article explains how to create a skillset using [REST APIs](/rest/api/searchservice/create-skillset), but the same concepts and steps apply to other programming languages.

+Indexers drive skillset execution. You need an [indexer](search-howto-create-indexers.md), [data source](search-data-sources-gallery.md), and [index](search-what-is-an-index.md) before you can test your skillset.

+Debug sessions work with all generally available [indexer data sources](search-data-sources-gallery.md) and most preview data sources. The following list notes the exceptions:

+1. In the left navigation page, select **Debug sessions**.

+1. In the action bar at the top, select **Add debug session**.

+1. In **Managed identity authentication**, choose **None** if the connection to Azure Storage doesn't use a managed identity. Otherwise, choose the managed identity to which you've granted **Storage Blob Data Contributor** permissions.

+1. In **Document to debug**, choose the first document in the index or select a specific document. If you select a specific document, depending on the data source, you're asked for a URI or a row ID.

+ If your specific document is a blob, provide the blob URI. You can find the URI in the blob property page in the portal.

+1. Your configuration should look similar to this screenshot. Select **Save session** to get started.

+Knowledge store is secondary storage for [AI-enriched content created by a skillset](cognitive-search-concept-intro.md) in Azure AI Search. In Azure AI Search, an indexing job always sends output to a search index, but if you attach a skillset to an indexer, you can optionally also send AI-enriched output to a container or table in Azure Storage. A knowledge store can be used for independent analysis or downstream processing in non-search scenarios like knowledge mining.

+The two outputs of indexing, a search index and knowledge store, are mutually exclusive products of the same pipeline. They're derived from the same inputs and contain the same data, but their content is structured, stored, and used in different applications.

+When viewed through Azure portal, a knowledge store looks like any other collection of tables, objects, or files. The following screenshot shows a knowledge store composed of three tables. You can adopt a naming convention, such as a `kstore` prefix, to keep your content together.

+Unlike a search index that can only be accessed through queries in Azure AI Search, a knowledge store is accessible to any tool, app, or process that supports connections to Azure Storage. This flexibility opens up new scenarios for consuming the analyzed and enriched content produced by an enrichment pipeline.

+| [Back up and Restore](https://github.com/liamc) | Download the retrievable fields of an index to your local device and then upload the index and its content to a new search service. | [https://github.com/liamca/azure-search-backup-restore](https://github.com/liamca/azure-search-backup-restore) |

+| [Chat with your data solution accelerator](https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator/README.md) | Code and docs to create interactive search solution in production environments. | [https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator](https://github.com/Azure-Samples/chat-with-your-data-solution-accelerator) |

+| [Knowledge Mining Accelerator](https://github.com/Azure-Samples/azure-search-knowledge-mining/blob/main/README.md) | Code and docs to jump start a knowledge store using your data. | [https://github.com/Azure-Samples/azure-search-knowledge-mining](https://github.com/Azure-Samples/azure-search-knowledge-mining) |

+| [Performance testing solution](https://github.com/Azure-Samples/azure-search-performance-testing/blob/main/README.md) | This solution helps you load test Azure AI Search. It uses Apache JMeter as an open source load and performance testing tool and Terraform to dynamically provision and destroy the required infrastructure on Azure. | [https://github.com/Azure-Samples/azure-search-performance-testing](https://github.com/Azure-Samples/azure-search-performance-testing) |

+REST is the definitive programming interface for Azure AI Search, and all operations that can be invoked programmatically are available first in REST, and then in SDKs. For this reason, most examples in the documentation use the REST APIs to demonstrate or explain important concepts.

+REST samples are usually developed and tested on the [Postman app](https://www.postman.com/downloads/), but you can use any client that supports HTTP calls. [Here's a quickstart](search-get-started-rest.md) that explains how to formulate the HTTP request from end-to-end in Postman.

+| Samples | Description |

+| [Quickstart](https://github.com/Azure-Samples/azure-search-postman-samples/tree/main/Quickstart) | Source code for [Quickstart: Create a search index using REST APIs](search-get-started-rest.md). This sample covers the basic workflow for creating, loading, and querying a search index using sample data. |

+| [Quickstart-vectors](https://github.com/Azure-Samples/azure-search-postman-samples/tree/main/Quickstart-vector) | Source code for [Quickstart: Vector search using REST APIs](search-get-started-vector.md). This sample covers the basic workflow for indexing and querying vector data. |

+| [Tutorial](https://github.com/Azure-Samples/azure-search-postman-samples/tree/main/Tutorial) | Source code for [Tutorial: Use REST and AI to generate searchable content from Azure blobs](cognitive-search-tutorial-blob.md). This sample shows you how to create a skillset that iterates over Azure blobs to extract information and infer structure.|

+| [Debug-sessions](https://github.com/Azure-Samples/azure-search-postman-samples/tree/main/Debug-sessions) | Source code for [Tutorial: Diagnose, repair, and commit changes to your skillset](cognitive-search-tutorial-debug-sessions.md). This sample shows you how to use a skillset debug session in the Azure portal. REST is used to create the objects used during debug.|

+| [custom-analyzers](https://github.com/Azure-Samples/azure-search-postman-samples/tree/main/custom-analyzers) | Source code for [Tutorial: Create a custom analyzer for phone numbers](tutorial-create-custom-analyzer.md). This sample explains how to use analyzers to preserve patterns and special characters in searchable content.|

+| [knowledge-store](https://github.com/Azure-Samples/azure-search-postman-samples/tree/main/knowledge-store) | Source code for [Create a knowledge store using REST and Postman](knowledge-store-create-rest.md). This sample explains the necessary steps for populating a knowledge store used for knowledge mining workflows. |

+| [semantic ranker](https://github.com/Azure-Samples/azure-search-postman-samples/tree/main/semantic-search) | Source code for [Define projections in a knowledge store](knowledge-store-projections-examples.md). This sample creates a basic search index with a semantic configuration, loads data into the index, and then creates a semantic query.|

+| [projections](https://github.com/Azure-Samples/azure-search-postman-samples/tree/main/projections) | Source code for [Define projections in a knowledge store](knowledge-store-projections-examples.md). This sample explains how to specify the physical data structures in a knowledge store.|

+The following samples are also published by the Azure AI Search team, but aren't referenced in documentation. Associated readme files provide usage instructions.

+All SDKs are based on REST API versions. If a REST version is discontinued, SDK packages based on that version are also discontinued. All Azure AI Search .NET SDKs older than [**3.0.0-rc**](https://www.nuget.org/packages/Microsoft.Azure.Search/3.0.0-rc) are now obsolete.

+Support for the above-listed versions ended on October 15, 2020. If you have code that uses a discontinued version, you can [migrate existing code](search-api-migration.md) to a newer [REST API version](/rest/api/searchservice/) or to a newer Azure SDK.

+| [Java azure-search-documents 11](/java/api/overview/azure/search-documents-readme) | Active | Use the `azure-search-documents` client library for data plane operations. |

+| [Java Management Client 1.35.0](/java/api/overview/azure/search/management) | Active | Use the `azure-mgmt-search` client library for control plane operations. |

+| [JavaScript @azure/search-documents 11.0](/javascript/api/overview/azure/search-documents-readme) | Active | Use the `@azure/search-documents` client library for data plane operations. |

+| [JavaScript @azure/arm-search](https://www.npmjs.com/package/@azure/arm-search) | Active | Use the `@azure/arm-search` client library for control plane operations. |

+| [Python azure-search-documents 11.0](/python/api/azure-search-documents) | Active | Use the `azure-search-documents` client library for data plane operations. |

+| [Python azure-mgmt-search 8.0](https://pypi.org/project/azure-mgmt-search/) | Active | Use the `azure-mgmt-search` client library for control plane operations. |

+description: Learn how capacity is structured and used in Azure AI Search, and how to estimate the resources needed for indexing and query workloads.

+Partitions are units of storage. Each new search service starts with one each, but you can add or remove replicas and partitions independently to accommodate fluctuating workloads. Adding capacity increases the [cost of running a search service](search-sku-manage-costs.md#billable-events).

+The physical characteristics of replicas and partitions, such as processing speed and disk IO, vary by [service tier](search-sku-tier.md). On a standard search service, the replicas and partitions are faster and larger than those of a basic service.

+|*Replica* | Instances of the search service, used primarily to load balance query operations. Each replica hosts one copy of an index. If you allocate three replicas, you have three copies of an index available for servicing query requests.|

+## Estimation targets

+Capacity planning must include object limits (for example, the maximum number of indexes allowed on a service) and storage limits. The service tier determines [object and storage limits](search-limits-quotas-capacity.md). Whichever limit is reached first is the effective limit.

+Attributes on the index, such as enabling filters and sorting, affect storage requirements. The use of suggesters also has storage implications. For more information, see [Attributes and index size](search-what-is-an-index.md#index-size).

+1. Add replicas for high availability or to mitigate slow query performance.

+Queries per second (QPS) is an important metric during performance tuning, but for capacity planning, it becomes a consideration only if you expect high query volume at the outset.

+description: Extract searchable text from JSON blobs using the Blob indexer in Azure AI Search. Indexers provide indexing automation for supported data sources like Azure Blob Storage.

+For blob indexing in Azure AI Search, this article shows you how to set properties for blobs or files consisting of JSON documents. JSON files in Azure Blob Storage or Azure File Storage commonly assume any of these forms:

+The blob indexer provides a `parsingMode` parameter to optimize the output of the search document based on JSON structure. Parsing modes consist of the following options:

+Although the default behavior is one search document per JSON blob, setting the **`json`** parsing mode changes the internal field mappings for content, promoting fields inside `content` to actual fields in the search index. An example indexer definition for the **`json`** parsing mode might look like this:

+The `parameters` property on the indexer contains parsing mode values. For a JSON array, the indexer definition should look similar to the following example.

+For JSON arrays having nested elements, you can specify a `documentRoot` to indicate a multi-level structure. For example, if your blobs look like this:

+Field mappings associate a source field with a destination field in situations where the field names and types aren't identical. But field mappings can also be used to match parts of a JSON document and "lift" them into top-level fields of the search document.

+description: Re-index a search index to add or update the schema or delete obsolete documents using a full rebuild or partial indexing.

+This article explains how to drop and rebuild an Azure AI Search index. It explains the circumstances under which rebuilds are required, and provides recommendations for mitigating the effects of rebuilds on ongoing query requests. If you have to rebuild frequently, we recommend using [index aliases](search-how-to-alias.md) to make it easier to swap which index your application is pointing to.

+During active development, it's common to drop and rebuild indexes when you're iterating over index design. Most developers work with a small representative sample of their data so that reindexing goes faster.

+The following table lists the modifications that require an index drop and rebuild.

+| Delete a field | To physically remove all traces of a field, you have to rebuild the index. When an immediate rebuild isn't practical, you can modify application code to redirect access away from an obsolete field or use the [searchFields](search-query-create.md#example-of-a-full-text-query-request) and [select](search-query-odata-select.md) query parameters to choose which fields are searched and returned. Physically, the field definition and contents remain in the index until the next rebuild, when you apply a schema that omits the field in question. |

+| Change a field definition | Revisions to a field name, data type, or specific [index attributes](/rest/api/searchservice/create-index) (searchable, filterable, sortable, facetable) require a full rebuild. |

+| Assign an analyzer to a field | [Analyzers](search-analyzers.md) are defined in an index, assigned to fields, and then invoked during indexing to inform how tokens are created. You can add a new analyzer definition to an index at any time, but you can only *assign* an analyzer when the field is created. This is true for both the **analyzer** and **indexAnalyzer** properties. The **searchAnalyzer** property is an exception (you can assign this property to an existing field). |

+| Add a field to a suggester | If a field already exists and you want to add it to a [Suggesters](index-add-suggesters.md) construct, rebuild the index. |

+| Switch tiers | In-place upgrades aren't supported. If you require more capacity, create a new service and rebuild your indexes from scratch. To help automate this process, you can use the **index-backup-restore** sample code in this [Azure AI Search .NET sample repo](https://github.com/Azure-Samples/azure-search-dotnet-utilities). This app will back up your index to a series of JSON files, and then recreate the index in a search service you specify.|

+1. Check for space. Search services are subject to [maximum number of indexes](search-limits-quotas-capacity.md), varying by service tier. Make sure you have room for a second index.

+Indexers target [supported data sources](#supported-data-sources). An indexer configuration specifies a data source (origin) and a search index (destination). Several sources, such as Azure Blob Storage, have more configuration properties specific to that content type.

+⁵ Regarding the 2 or 24 hour maximum duration for indexers: a 2-hour maximum is the most common and it's what you should plan for. The 24-hour limit is from an older indexer implementation. If you have unscheduled indexers that run continuously for 24 hours, it's because those indexers couldn't be migrated to the newer infrastructure. As a general rule, for indexing jobs that can't finish within two hours, put the indexer on a [2-hour schedule](search-howto-schedule-indexers.md). When the first 2-hour interval is complete, the indexer picks up where it left off when starting the next 2-hour interval.

+ Title: Portal administration

+description: Manage an Azure AI Search resource using the Azure portal.

+This article covers the Azure AI Search administration tasks that you can perform in the [Azure portal](https://portal.azure.com).

+Depending on your permission level, the portal provides coverage of most search service operations, including:

+The overview page is the "home" page of each service. In the following screenshot, the red boxes indicate tasks, tools, and tiles that you might use often, especially if you're new to the service.

+| 1 | A command bar at the top of the page includes [Import data wizard](search-get-started-portal.md) and [Search explorer](search-explorer.md), used for prototyping and exploration. |

+| 2 | The **Essentials** section lists service properties, such as the service endpoint, service tier, and replica and partition counts. |

+| 3 | Tabbed pages in the center provide quick access to usage statistics and service health metrics.|

+| 4 | Navigation links to existing indexes, indexers, data sources, and skillsets. |

+¹ Although there are ARM and bicep templates for service deployment, moving content is a manual effort.

+In Azure AI Search, a *normalizer* is a component that pre-processes text for keyword matching over fields marked as "filterable", "facetable", or "sortable". In contrast with full text "searchable" fields that are paired with [text analyzers](search-analyzers.md), content that's created for filter-facet-sort operations doesn't undergo analysis or tokenization. Omission of text analysis can produce unexpected results when casing and character differences show up, which is why you need a normalizer to homogenize variations in your content.

+A normalizer, which is invoked during indexing and query execution, adds light transformations that smooth out minor differences in text for filter, facet, and sort scenarios. In the previous examples, the variants of `"Las Vegas"` would be processed according to the normalizer you select (for example, all text is lower-cased) for more uniform results.

+Normalizers are specified in an index definition, on a per-field basis, on text fields (`Edm.String` and `Collection(Edm.String)`) that have at least one of "filterable", "sortable", or "facetable" properties set to true. Setting a normalizer is optional and is null by default. We recommend evaluating predefined normalizers before configuring a custom one.

+> To change the normalizer of an existing field, [rebuild the index](search-howto-reindex.md) entirely (you cannot rebuild individual fields).

+|asciifolding| Transforms characters that aren't in the Basic Latin Unicode block to their ASCII equivalent, if one exists. For example, changing `à` to `a`.|

+ Title: OData collection filters

+# Understand how OData collection filters work in Azure AI Search

+This article provides background for developers who are writing advanced filters with complex lambda expressions. The article explains why the rules for collection filters exist by exploring how Azure AI Search executes these filters.

+When you build a [filter](query-odata-filter-orderby-syntax.md) on collection fields in Azure AI Search, you can use the [`any` and `all` operators](search-query-odata-collection-operators.md) together with **lambda expressions**. Lambda expressions are Boolean expressions that refer to a **range variable**. In filters that use a lambda expression, the `any` and `all` operators are analogous to a `for` loop in most programming languages, with the range variable taking the role of loop variable, and the lambda expression as the body of the loop. The range variable takes on the "current" value of the collection during iteration of the loop.

+At least that's how it works conceptually. In reality, Azure AI Search implements filters in a very different way to how `for` loops work. Ideally, this difference would be invisible to you, but in certain situations it isn't. The end result is that there are rules you have to follow when writing lambda expressions.

+> [!NOTE]

+> For information on what the rules for collection filters are, including examples, see [Troubleshooting OData collection filters in Azure AI Search](search-query-troubleshoot-collection-filters.md).

+There are three underlying reasons why filter features aren't fully supported for all types of collections:

+1. Azure AI Search doesn't support *correlated search* on fields of type `Collection(Edm.ComplexType)`.

+When you apply multiple filter criteria over a collection of complex objects, the criteria are correlated because they apply to *each object in the collection*. For example, the following filter returns hotels that have at least one deluxe room with a rate less than 100:

+you might get hotels back where one room is deluxe, and a different room mentions "city view" in the description. For example, the document below with `Id` of `1` would match the query:

+You might have noticed that there are far fewer restrictions on lambda expressions over complex collections than there are for simple collections like `Collection(Edm.Int32)`, `Collection(Edm.GeographyPoint)`, and so on. This is because Azure AI Search stores complex collections as actual collections of subdocuments, while simple collections aren't stored as collections at all.

+Next, we look at how it's possible to combine multiple equality checks on the same range variable with `or`. It works thanks to algebra and [the distributive property of quantifiers](https://en.wikipedia.org/wiki/Existential_quantification#Negation). This expression:

+- Inside `all`, the rules are reversed. Only *negative checks* are allowed, you can use `and` always, and you can use `or` only for range checks expressed as ANDs of ORs (CNF).

+* The field containing group or user identity must be a string with the filterable attribute. It should be a collection. It shouldn't allow nulls.

+ POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2023-11-01

+Send an HTTP POST request to the docs collection of your index's URL endpoint (see [Documents - Index](/rest/api/searchservice/documents/)). The body of the HTTP request is a JSON rendering of the documents to be indexed:

+POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2023-11-01

+For full details on searching documents using Azure AI Search, you can read [Search Documents](/rest/api/searchservice/documents/search-post?).

+This article describes a pattern for filtering results based on user identity and the `search.in()` function. You can use this function to pass in principal identifiers for the requesting user to match against principal identifiers associated with each target document. When a search request is handled, the `search.in` function filters out search results for which none of the user's principals have read access. The principal identifiers can represent things like security groups, roles, or even the user's own identity.

+In this article, learn how to secure an Azure AI Search service so that it can't be accessed over a public internet connection:

+You can create a private endpoint for a search service in the Azure portal, as described in this article. Alternatively, you can use the [Management REST API version](/rest/api/searchmanagement/), [Azure PowerShell](/powershell/module/az.search), or [Azure CLI](/cli/azure/search).

+- **API**: Use the *DISCONNECT* API to send a PUT call with an empty body to the following URL:

+- *Workspace Manager Configurations*

+- **Value**: Enter **User**.

+[Azure Site Recovery](site-recovery-overview.md) contributes to your business continuity and disaster recovery (BCDR) strategy by keeping your business apps up and running during planned and unplanned outages. Site Recovery manages and orchestrates disaster recovery of on-premises machines and Azure virtual machines (VMs). Disaster recovery includes replication, failover, and recovery of various workloads.

+> [!IMPORTANT]

+> This article provides an overview of failover and failback during disaster recovery of on-premises machines to Azure with [Azure Site Recovery](site-recovery-overview.md) - Classic.

+><br>

+> For information about failover and failback in Azure Site Recovery Modernized release, [see this article](failover-failback-overview-modernized.md).

+> [!NOTE]

+> Running MARS agent of both ASR and Backup on the same Hyper-V host is not be supported.

+> [!IMPORTANT]

+> The above table is applicable across all supported Azure Site Recovery scenarios.

+With Application Configuration Service, you have a central place to manage external properties for applications across all environments. To understand the differences from Spring Cloud Config Server in the Basic and Standard plans, see the [Use Application Configuration Service for external configuration](./how-to-migrate-standard-tier-to-enterprise-tier.md#use-application-configuration-service-for-external-configuration) section of [Migrate an Azure Spring Apps Basic or Standard plan instance to the Enterprise plan](./how-to-migrate-standard-tier-to-enterprise-tier.md).

+The following table shows the subcomponent relationships:

+| Application Configuration Service generation | Subcomponents |

+| -- | |

+| Gen1 | `application-configuration-service` |

+| Gen2 | `application-configuration-service` <br/> `flux-source-controller` |

+- An already provisioned Azure Spring Apps Enterprise plan instance with Application Configuration Service enabled. For more information, see [Quickstart: Build and deploy apps to Azure Spring Apps using the Enterprise plan](quickstart-deploy-apps-enterprise.md).

+## Manage Application Configuration Service settings

+Application Configuration Service supports Azure DevOps, GitHub, GitLab, and Bitbucket for storing your configuration files.

+The following screenshot shows the three types of repository authentication supported by Application Configuration Service.

+ | `Host key` | No for Gen1 <br> Yes for Gen2 | The host key of the Git server. If you connect to the server via Git on the command line, the host key is in your *.ssh/known_hosts* file. Don't include the algorithm prefix, because it's specified in `Host key algorithm`. |

+| `Host key` | The host key of the Git server. If you connect to the server via Git on the command line, the host key is in your *.ssh/known_hosts* file. Don't include the algorithm prefix, because it's specified in `Host key algorithm`. |

+1. Select the **Settings** section and then select **Gen 2** in the **Generation** dropdown menu.

+ :::image type="content" source="media/how-to-enterprise-application-configuration-service/configuration-server-upgrade-gen2.png" alt-text="Screenshot of the Azure portal that shows the Application Configuration Service page with the Settings tab showing and the Generation menu open." lightbox="media/how-to-enterprise-application-configuration-service/configuration-server-upgrade-gen2.png":::

+ :::image type="content" source="media/how-to-enterprise-application-configuration-service/configuration-server-upgrade-gen2-settings.png" alt-text="Screenshot of the Azure portal that shows the Application Configuration Service page with the Settings tab showing and the Validate button highlighted." lightbox="media/how-to-enterprise-application-configuration-service/configuration-server-upgrade-gen2-settings.png":::

+The Application Configuration Service works seamlessly with Spring Boot applications. The properties generated by the service are imported as external configurations by Spring Boot and injected into the beans. You don't need to write extra code. You can consume the values by using the `@Value` annotation, accessed through Spring's Environment abstraction, or you can bind them to structured objects by using the `@ConfigurationProperties` annotation.

+1. Load the configuration to Application Configuration Service.

+## Configure Application Configuration Service settings

+Use the following steps to configure Application Configuration Service:

+1. Select **Overview** to view the running state and resources allocated to Application Configuration Service.

+ :::image type="content" source="media/how-to-enterprise-application-configuration-service/configuration-service-overview.png" alt-text="Screenshot of the Azure portal that shows the Application Configuration Service page with Overview tab highlighted." lightbox="media/how-to-enterprise-application-configuration-service/configuration-service-overview.png":::

+ :::image type="content" source="media/how-to-enterprise-application-configuration-service/configuration-service-settings-validate.png" alt-text="Screenshot of the Azure portal that shows the Application Configuration Service page with the Settings tab and Validate button highlighted." lightbox="media/how-to-enterprise-application-configuration-service/configuration-service-settings-validate.png":::

+Use the following command to configure Application Configuration Service:

+1. Navigate to your service resource and then select **Application Configuration Service**.

+ :::image type="content" source="media/how-to-enterprise-application-configuration-service/ca-certificate.png" alt-text="Screenshot of the Azure portal that shows the Application Configuration Service page with the Settings tab showing." lightbox="media/how-to-enterprise-application-configuration-service/ca-certificate.png":::

+Use the following command to configure the TLS certificate:

+## Use Application Configuration Service with applications

+When you use Application Configuration Service with a Git back end and use the centralized configurations, you must bind the app to Application Configuration Service.

+Use the following steps to use Application Configuration Service with applications:

+ :::image type="content" source="media/how-to-enterprise-application-configuration-service/configuration-service-app-bind-dropdown.png" alt-text="Screenshot of the Azure portal that shows the Application Configuration Service page with the App binding tab highlighted." lightbox="media/how-to-enterprise-application-configuration-service/configuration-service-app-bind-dropdown.png":::

+1. In the navigation pane, select **Configuration** and then select **General settings**.

+ :::image type="content" source="media/how-to-enterprise-application-configuration-service/configuration-service-pattern.png" alt-text="Screenshot of the Azure portal that shows the App Configuration page with the General settings tab and api-gateway options highlighted." lightbox="media/how-to-enterprise-application-configuration-service/configuration-service-pattern.png":::

+Use the following command to use Application Configuration Service with applications:

+You can enable and disable Application Configuration Service after service creation using the Azure portal or the Azure CLI. Before disabling Application Configuration Service, you're required to unbind all of your apps from it.

+1. Navigate to your service resource and then select **Application Configuration Service**.

+1. Select or unselect **Enable Application Configuration Service** and then select **Save**.

+## Check logs

+The following sections show you how to view application logs by using either the Azure CLI or the Azure portal.

+### Use real-time log streaming

+You can stream logs in real time with the Azure CLI. For more information, see [Stream Azure Spring Apps managed component logs in real time](./how-to-managed-component-log-streaming.md). The following examples show how you can use Azure CLI commands to continuously stream new logs for `application-configuration-service` and `flux-source-controller` subcomponents.

+Use the following command to stream logs for `application-configuration-service`:

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name application-configuration-service \

+ --all-instances \

+ --follow

+```

+Use the following command to stream logs for `flux-source-controller`:

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name flux-source-controller \

+ --all-instances \

+ --follow

+```

+### Use Log Analytics

+The following sections show you how to turn on and view System Logs using Log Analytics.

+#### Diagnostic settings for Log Analytics

+You must turn on System Logs and send the logs to your Log Analytics instance before you query the logs for Application Configuration Service. To enable System Logs in the Azure portal, use the following steps:

+1. Open your Azure Spring Apps instance.

+1. In the navigation pane, select **Diagnostics settings**.

+1. Select **Add diagnostic setting** or select **Edit setting** for an existing setting.

+1. In the **Logs** section, select the **System Logs** category.

+1. In the **Destination details** section, select **Send to Log Analytics workspace** and then select your workspace.

+1. Select **Save** to update the setting.

+#### Check logs in Log Analytics

+To check the logs of `application-configuration-service` and `flux-source-controller` using the Azure portal, use the following steps:

+1. Make sure you turned on **System Logs**. For more information, see the [Diagnostic settings for Log Analytics](#diagnostic-settings-for-log-analytics) section.

+1. Open your Azure Spring Apps instance.

+1. In the navigation menu, select **Logs** and then select **Overview**.

+1. Use the following sample queries in the query edit pane. Adjust the time range then select **Run** to search for logs.

+ - To view the logs for `application-configuration-service`, use the following query:

+ ```kusto

+ AppPlatformSystemLogs

+ | where LogType in ("ApplicationConfigurationService")

+ | project TimeGenerated , ServiceName , LogType, Log , _ResourceId

+ | limit 100

+ ```

+ :::image type="content" source="media/how-to-enterprise-application-configuration-service/query-logs-application-configuration-service.png" alt-text="Screenshot of the Azure portal that shows the query result of logs for application-configuration-service." lightbox="media/how-to-enterprise-application-configuration-service/query-logs-application-configuration-service.png":::

+ - To view the logs for `flux-source-controller`, use the following query:

+ ```kusto

+ AppPlatformSystemLogs

+ | where LogType in ("Flux")

+ | project TimeGenerated , ServiceName , LogType, Log , _ResourceId

+ | limit 100

+ ```

+ :::image type="content" source="media/how-to-enterprise-application-configuration-service/query-logs-flux-source-controller.png" alt-text="Screenshot of the Azure portal that shows the query result of logs for flux-source-controller." lightbox="media/how-to-enterprise-application-configuration-service/query-logs-flux-source-controller.png":::

+> [!NOTE]

+> There could be a few minutes delay before the logs are available in Log Analytics.

+This article describes how to enable log streaming in the Azure CLI to get real-time application console logs for troubleshooting. You can also use diagnostics settings to analyze diagnostics data in Azure Spring Apps. For more information, see [Analyze logs and metrics with diagnostics settings](./diagnostic-services.md).

+For streaming logs of managed components in Azure Spring Apps, see [Stream Azure Spring Apps managed component logs in real time](./how-to-managed-component-log-streaming.md).

+- [Azure CLI](/cli/azure/install-azure-cli) with the Azure Spring Apps extension, version 1.0.0 or higher. You can install the extension by using the following command: `az extension add --name spring`

+## Use the Azure CLI to produce tail logs

+This section provides examples of using the Azure CLI to produce tail logs. To avoid repeatedly specifying your resource group and service instance name, use the following commands to set your default resource group name and cluster name:

+The command returns logs similar to the following examples, where `auth-service` is the application name.

+The command produces results similar to the following output:

+By default, `az spring app logs` prints only existing logs streamed to the app console and then exits. If you want to stream new logs, add the `-f/--follow` argument, as shown in the following example:

+Use the following steps to enable a log streaming endpoint on the public network:

+1. Select the Azure Spring Apps service instance deployed in your virtual network and then select **Networking** in the navigation menu.

+1. Select the **Vnet injection** tab.

+1. Switch the status of **Dataplane resources on public network** to **enable** to enable a log streaming endpoint on the public network. This process takes a few minutes.

+ :::image type="content" source="media/how-to-log-streaming/dataplane-public-endpoint.png" alt-text="Screenshot of the Azure portal that shows the Networking page with the Vnet injection tab selected and the Troubleshooting section highlighted." lightbox="media/how-to-log-streaming/dataplane-public-endpoint.png":::

+Use the following command to enable the log stream public endpoint:

+After you enable the log stream public endpoint, you can access the app log from a public network just like you would access a normal instance.

+> If you can't access app logs in the virtual network injection instance from the internet after you enable a log stream public endpoint, check your network security group to see whether you allowed such inbound traffic.

+- [Stream Azure Spring Apps managed component logs in real time](./how-to-managed-component-log-streaming.md)

+ Title: Stream Azure Spring Apps managed component logs in real time

+description: Learn how to use log streaming to view managed component logs in real time.

+# Stream Azure Spring Apps managed component logs in real time

+> [!NOTE]

+> Azure Spring Apps is the new name for the Azure Spring Cloud service. Although the service has a new name, you'll see the old name in some places for a while as we work to update assets such as screenshots, videos, and diagrams.

+**This article applies to:** ❌ Basic/Standard ✔️ Enterprise

+This article describes how to use the Azure CLI to get real-time logs of managed components for troubleshooting. You can also use diagnostics settings to analyze diagnostics data in Azure Spring Apps. For more information, see [Analyze logs and metrics with diagnostics settings](./diagnostic-services.md).

+For streaming logs of applications in Azure Spring Apps, see [Stream Azure Spring Apps application console logs in real time](./how-to-log-streaming.md).

+## Prerequisites

+- [Azure CLI](/cli/azure/install-azure-cli) with the Azure Spring Apps extension, version 1.19.0 or higher. You can install the extension by using the following command: `az extension add --name spring`.

+## Supported managed components

+The following table lists the managed components that are currently supported, along with their subcomponents:

+| Managed component | Subcomponents |

+|--|-|

+| Application Configuration Service | `application-configuration-service` <br/> `flux-source-controller` (Supported in ACS Gen2 version) |

+| Spring Cloud Gateway | `spring-cloud-gateway` <br/> `spring-cloud-gateway-operator` |

+You can use the following command to list all subcomponents:

+```azurecli

+az spring component list

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name>

+```

+## Assign an Azure role

+To stream logs of managed components, you must have the relevant Azure roles assigned to you. The following table lists the required roles and the operations for which these roles are granted permissions:

+| Managed component | Required role | Operations |

+|--|||

+| Application Configuration Service | Azure Spring Apps Application Configuration Service Log Reader Role | `Microsoft.AppPlatform/Spring/ApplicationConfigurationService/logstream/action` |

+| Spring Cloud Gateway | Azure Spring Apps Spring Cloud Gateway Log Reader Role | `Microsoft.AppPlatform/Spring/SpringCloudGateway/logstream/action` |

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

+Use the following steps to assign an Azure role using the Azure portal:

+1. Open the [Azure portal](https://portal.azure.com).

+1. Open your Azure Spring Apps service instance.

+1. In the navigation pane, select **Access Control (IAM)**.

+1. On the **Access Control (IAM)** page, select **Add** and then select **Add role assignment**.

+ :::image type="content" source="media/how-to-managed-component-log-streaming/add-role-assignment.png" alt-text="Screenshot of the Azure portal that shows the Access Control (IAM) page for an Azure Spring Apps instance with the Add role assignment option highlighted." lightbox="media/how-to-managed-component-log-streaming/add-role-assignment.png":::

+1. On the **Add role assignment** page, in the **Name** list, search for and select the target role and then select **Next**.

+ :::image type="content" source="media/how-to-managed-component-log-streaming/application-configuration-service-log-reader-role.png" alt-text="Screenshot of the Azure portal that shows the Add role assignment page for an Azure Spring Apps instance with the Azure Spring Apps Application Configuration Service Log Reader Role name highlighted." lightbox="media/how-to-managed-component-log-streaming/application-configuration-service-log-reader-role.png":::

+1. Select **Members** and then search for and select your username.

+1. Select **Review + assign**.

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

+Use the following command to assign an Azure role:

+ ```azurecli

+ az role assignment create \

+ --role "<Log-reader-role-for-managed-component>" \

+ --scope "<service-instance-resource-id>" \

+ --assignee "<your-identity>"

+ ```

+## List all instances in a component

+Use the following command to list all instances in a component:

+```azurecli

+az spring component instance list \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --component <component-name>

+```

+For example, to list all instances for `flux-source-controller` in ACS Gen2 version, use the following command:

+```azurecli

+az spring component instance list \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --component flux-source-controller

+```

+## View tail logs

+This section provides examples of using the Azure CLI to produce tail logs.

+### View tail logs for a specific instance

+To view the tail logs for a specific instance, use the `az spring component logs` command with the `-i/--instance` argument, as shown in the next section.

+#### View tail logs for an instance of application-configuration-service

+Use the following command to view the tail logs for `application-configuration-service`:

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name application-configuration-service \

+ --instance <instance-name>

+```

+For ACS Gen2, the command returns logs similar to the following example:

+```output

+...

+2023-12-18T07:09:54.020Z INFO 16715 [main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8090 (https)

+2023-12-18T07:09:54.116Z INFO 16715 [main] org.apache.juli.logging.DirectJDKLog : Starting service [Tomcat]

+2023-12-18T07:09:54.117Z INFO 16715 [main] org.apache.juli.logging.DirectJDKLog : Starting Servlet engine: [Apache Tomcat/10.1.12]

+2023-12-18T07:09:54.522Z INFO 16715 [main] org.apache.juli.logging.DirectJDKLog : Initializing Spring embedded WebApplicationContext

+2023-12-18T07:09:54.524Z INFO 16715 [main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 14100 ms

+2023-12-18T07:09:56.920Z INFO 16715 [main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8090 (https) with context path ''

+2023-12-18T07:09:57.528Z INFO 16715 [main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat initialized with port(s): 8081 (http)

+2023-12-18T07:09:57.529Z INFO 16715 [main] org.apache.juli.logging.DirectJDKLog : Starting service [Tomcat]

+2023-12-18T07:09:57.529Z INFO 16715 [main] org.apache.juli.logging.DirectJDKLog : Starting Servlet engine: [Apache Tomcat/10.1.12]

+2023-12-18T07:09:57.629Z INFO 16715 [main] org.apache.juli.logging.DirectJDKLog : Initializing Spring embedded WebApplicationContext

+2023-12-18T07:09:57.629Z INFO 16715 [main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 603 ms

+2023-12-18T07:09:57.824Z INFO 16715 [main] o.s.b.w.embedded.tomcat.TomcatWebServer : Tomcat started on port(s): 8081 (http) with context path ''

+2023-12-18T07:09:58.127Z INFO 16715 [main] o.springframework.boot.StartupInfoLogger : Started ReconcilerApplication in 21.005 seconds (process running for 22.875)

+...

+```

+#### View tail logs for an instance of flux-source-controller

+Use the following command to view the tail logs for `flux-source-controller`:

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name flux-source-controller \

+ --instance <instance-name>

+```

+The command returns logs similar to the following example:

+```output

+...

+{"level":"info","ts":"2023-12-18T07:07:54.615Z","logger":"controller-runtime.metrics","msg":"Metrics server is starting to listen","addr":":8080"}

+{"level":"info","ts":"2023-12-18T07:07:54.615Z","logger":"setup","msg":"starting manager"}

+{"level":"info","ts":"2023-12-18T07:07:54.615Z","msg":"Starting server","path":"/metrics","kind":"metrics","addr":"[::]:8080"}

+{"level":"info","ts":"2023-12-18T07:07:54.615Z","msg":"Starting server","kind":"health probe","addr":"[::]:9440"}

+{"level":"info","ts":"2023-12-18T07:07:54.817Z","logger":"runtime","msg":"attempting to acquire leader lease flux-system/source-controller-leader-election...\n"}

+{"level":"info","ts":"2023-12-18T07:07:54.830Z","logger":"runtime","msg":"successfully acquired lease flux-system/source-controller-leader-election\n"}

+...

+```

+#### View tail logs for an instance of spring-cloud-gateway

+Use the following command to view the tail logs for `spring-cloud-gateway`:

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name spring-cloud-gateway \

+ --instance <instance-name>

+```

+The command returns logs similar to the following example:

+```output

+...

+2023-12-11T14:13:40.310Z INFO 1 [ main] i.p.s.c.g.s.SsoDeactivatedConfiguration : SSO is deactivated, setting up default security filters

+2023-12-11T14:13:40.506Z INFO 1 [ main] .h.HazelcastReactiveSessionConfiguration : Configuring Hazelcast as a session management storage

+2023-12-11T14:13:51.008Z INFO 1 [ main] o.s.b.web.embedded.netty.NettyWebServer : Netty started on port 8443

+2023-12-11T14:13:51.810Z INFO 1 [ main] o.s.b.a.e.web.EndpointLinksResolver : Exposing 7 endpoint(s) beneath base path '/actuator'

+2023-12-11T14:13:52.410Z INFO 1 [ main] o.s.b.web.embedded.netty.NettyWebServer : Netty started on port 8090

+2023-12-11T14:13:52.907Z INFO 1 [ main] i.p.s.c.g.r.h.HazelcastRateLimitsRemover : Removing Hazelcast map 'GLOBAL_RATE_LIMIT' with rate limit information

+2023-12-11T14:13:52.912Z INFO 1 [ main] i.p.s.cloud.gateway.GatewayApplication : Started GatewayApplication in 36.084 seconds (process running for 38.651)

+...

+```

+#### View tail logs for an instance of spring-cloud-gateway-operator

+Use the following command to view the tail logs for `spring-cloud-gateway-operator`:

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name spring-cloud-gateway-operator \

+ --instance <instance-name>

+```

+The command returns logs similar to the following example:

+```output

+...

+2023-12-01T08:37:05.080Z INFO 1 [ main] c.v.t.s.OperatorApplication : Starting OperatorApplication v2.0.6 using Java 17.0.7 with PID 1 (/workspace/BOOT-INF/classes started by cnb in /workspace)

+2023-12-01T08:37:05.157Z INFO 1 [ main] c.v.t.s.OperatorApplication : No active profile set, falling back to 1 default profile: "default"

+2023-12-01T08:37:14.379Z INFO 1 [ main] o.s.b.a.e.web.EndpointLinksResolver : Exposing 1 endpoint(s) beneath base path '/actuator'

+2023-12-01T08:37:15.274Z INFO 1 [ main] o.s.b.web.embedded.netty.NettyWebServer : Netty started on port 8080

+2023-12-01T08:37:15.366Z INFO 1 [ main] c.v.t.s.OperatorApplication : Started OperatorApplication in 11.489 seconds (process running for 12.467)

+...

+```

+### View tail logs for all instances in one command

+To view the tail logs for all instances, use the `--all-instances` argument, as shown in the following command. The instance name is the prefix of each log line. When there are multiple instances, logs are printed in batch for each instance, so logs of one instance aren't interleaved with the logs of another instance.

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name <component-name> \

+ --all-instances

+```

+## Stream new logs continuously

+By default, `az spring component logs` prints only existing logs streamed to the console and then exits. If you want to stream new logs, add the `-f/--follow` argument.

+When you use the `-f/--follow` option to tail instant logs, the Azure Spring Apps log streaming service sends heartbeat logs to the client every minute unless the component is writing logs constantly. Heartbeat log messages use the following format: `2023-12-18 09:12:17.745: No log from server`.

+### Stream logs for a specific instance

+Use the following command to stream logs for a specific instance:

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name <component-name> \

+ --instance <instance-name> \

+ --follow

+```

+### Stream logs for all instances

+Use the following command to stream logs for all instances:

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name <component-name> \

+ --all-instances \

+ --follow

+```

+When you stream logs for multiple instances in a component, the logs of one instance interleave with logs of others.

+## Stream logs in a virtual network injection instance

+For an Azure Spring Apps instance deployed in a custom virtual network, you can access log streaming by default from a private network. For more information, see [Deploy Azure Spring Apps in a virtual network](./how-to-deploy-in-azure-virtual-network.md)

+Azure Spring Apps also enables you to access real-time managed component logs from a public network.

+> [!NOTE]

+> Enabling the log streaming endpoint on the public network adds a public inbound IP to your virtual network. Be sure to use caution if this is a concern for you.

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

+Use the following steps to enable a log streaming endpoint on the public network:

+1. Select the Azure Spring Apps service instance deployed in your virtual network and then select **Networking** in the navigation menu.

+1. Select the **Vnet injection** tab.

+1. Switch the status of **Dataplane resources on public network** to **Enable** to enable a log streaming endpoint on the public network. This process takes a few minutes.

+ :::image type="content" source="media/how-to-managed-component-log-streaming/dataplane-public-endpoint.png" alt-text="Screenshot of the Azure portal that shows the Networking page with the Vnet injection tab selected and the Troubleshooting section highlighted." lightbox="media/how-to-log-streaming/dataplane-public-endpoint.png":::

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

+Use the following command to enable the log stream public endpoint.

+```azurecli

+az spring update \

+ --resource-group <resource-group-name> \

+ --service <service-instance-name> \

+ --enable-dataplane-public-endpoint true

+```

+After you enable the log stream public endpoint, you can access the managed component logs from a public network just like you would access a normal instance.

+## Secure traffic to the log streaming public endpoint

+Log streaming for managed components uses Azure RBAC to authenticate the connections to the components. As a result, only users who have the proper roles can access the logs.

+To ensure the security of your managed components when you expose a public endpoint for them, secure the endpoint by filtering network traffic to your service with a network security group. For more information, see [Tutorial: Filter network traffic with a network security group using the Azure portal](../virtual-network/tutorial-filter-network-traffic.md). A network security group contains security rules that allow or deny inbound network traffic to, or outbound network traffic from, several types of Azure resources. For each rule, you can specify source and destination, port, and protocol.

+> [!NOTE]

+> If you can't access managed component logs in the virtual network injection instance from the internet after you enable a log stream public endpoint, check your network security group to see whether you've allowed such inbound traffic.

+The following table shows an example of a basic rule that we recommend. You can use commands like `nslookup` with the endpoint `<service-name>.private.azuremicroservices.io` to get the target IP address of a service.

+| Priority | Name | Port | Protocol | Source | Destination | Action |

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

+| 100 | Rule name | 80 | TCP | Internet | Service IP address | Allow |

+| 110 | Rule name | 443 | TCP | Internet | Service IP address | Allow |

+## Next steps

+- [Troubleshoot VMware Spring Cloud Gateway](./how-to-troubleshoot-enterprise-spring-cloud-gateway.md)

+- [Use Application Configuration Service](./how-to-enterprise-application-configuration-service.md)

+- [Stream Azure Spring Apps application console logs in real time](./how-to-log-streaming.md)

+Spring Cloud Gateway is composed of following subcomponents:

+- `spring-cloud-gateway-operator` is for managing the Gateway.

+- `spring-cloud-gateway` fulfills the features.

+The logs of both subcomponents are available. The following sections describe how to check these logs.

+### Use real-time log streaming

+You can stream logs in real time with the Azure CLI. For more information, see [Stream Azure Spring Apps managed component logs in real time](./how-to-managed-component-log-streaming.md). The following examples show how you can use Azure CLI commands to continuously stream new logs for `spring-cloud-gateway` and `spring-cloud-gateway-operator` subcomponents.

+Use the following command to stream logs for `spring-cloud-gateway`:

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name spring-cloud-gateway \

+ --all-instances \

+ --follow

+```

+Use the following command to stream logs for `spring-cloud-gateway-operator`:

+```azurecli

+az spring component logs \

+ --resource-group <resource-group-name> \

+ --service <Azure-Spring-Apps-instance-name> \

+ --name spring-cloud-gateway-operator \

+ --all-instances \

+ --follow

+```

+### Use Log Analytics

+The following sections show you how to view System Logs using Log Analytics.

+#### Diagnostic settings for Log Analytics

+1. In the navigation menu, select **Diagnostics settings**.

+#### Check logs in Log Analytics

+To check the logs of `spring-cloud-gateway` and `spring-cloud-gateway-operator` using the Azure portal, use the following steps:

+1. Make sure you turned on **System Logs**. For more information, see the [Diagnostic settings for Log Analytics](#diagnostic-settings-for-log-analytics) section.

+1. Select **Logs** in the navigation pane and then select **Overview**.

+1. Use the following sample queries in the query edit pane. Adjust the time range then select **Run** to search for logs.

+ - To view the logs for `spring-cloud-gateway`, use the following query:

+ ```kusto

+ AppPlatformSystemLogs

+ | project TimeGenerated , ServiceName , LogType, Log , _ResourceId

+ :::image type="content" source="media/how-to-troubleshoot-enterprise-spring-cloud-gateway/query-logs-spring-cloud-gateway.png" alt-text="Screenshot of the Azure portal that shows the query result of logs for VMware Spring Cloud Gateway." lightbox="media/how-to-troubleshoot-enterprise-spring-cloud-gateway/query-logs-spring-cloud-gateway.png":::

+ - To view the logs for `spring-cloud-gateway-operator`, use the following query:

+ ```kusto

+ :::image type="content" source="media/how-to-troubleshoot-enterprise-spring-cloud-gateway/query-logs-spring-cloud-gateway-operator.png" alt-text="Screenshot of the Azure portal that shows the query result of logs for VMware Spring Cloud Gateway operator." lightbox="media/how-to-troubleshoot-enterprise-spring-cloud-gateway/query-logs-spring-cloud-gateway-operator.png":::

+> There could be a few minutes delay before the logs are available in Log Analytics.

+1. In your Azure Spring Apps instance, select **Spring Cloud Gateway** in the navigation pane and then select **Configuration**.

+- [Stream Azure Spring Apps managed component logs in real time](./how-to-managed-component-log-streaming.md)

+This article lists some examples of role assignment conditions for controlling access to Azure Blob Storage.

+For this condition to be effective for a security principal, you must add it to all role assignments for them that include the following actions:

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal visual editor.

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+```

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})

+ )

+ OR

+ (

+ @Resource[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags:Project<$key_case_sensitive$>] StringEquals 'Cascade'

+ )

+)

+```

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+There are two actions that allow you to create new blobs, so you must target both. You must add this condition to any role assignments that include one of the following actions:

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+```

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write'} AND SubOperationMatches{'Blob.Write.WithTagHeaders'})

+ AND

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action'} AND SubOperationMatches{'Blob.Write.WithTagHeaders'})

+ )

+ OR

+ (

+ @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags:Project<$key_case_sensitive$>] StringEquals 'Cascade'

+ )

+)

+```

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+There are two actions that allow you to update tags on existing blobs, so you must target both. You must add this condition to any role assignments that include one of the following actions:

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+```

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write'} AND SubOperationMatches{'Blob.Write.WithTagHeaders'})

+ AND

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/write'})

+ )

+ OR

+ (

+ @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags&$keys$&] ForAllOfAnyValues:StringEquals {'Project', 'Program'}

+ )

+)

+```

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+```

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write'} AND SubOperationMatches{'Blob.Write.WithTagHeaders'})

+ AND

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/write'})

+ )

+ OR

+ (

+ @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags&$keys$&] ForAnyOfAnyValues:StringEquals {'Project'}

+ AND

+ @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags:Project<$key_case_sensitive$>] ForAllOfAnyValues:StringEquals {'Cascade', 'Baker', 'Skagit'}

+ )

+)

+```

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal.

+> [!div class="mx-tableFixed"]

+> | Condition #1 | Setting |

+> | | |

+> | Actions | [Delete a blob](storage-auth-abac-attributes.md#delete-a-blob)<br/>[Read a blob](storage-auth-abac-attributes.md#read-a-blob)<br/>[Write to a blob](storage-auth-abac-attributes.md#write-to-a-blob)<br/>[Create a blob or snapshot, or append data](storage-auth-abac-attributes.md#create-a-blob-or-snapshot-or-append-data)<br/>[All data operations for accounts with hierarchical namespace enabled](storage-auth-abac-attributes.md#all-data-operations-for-accounts-with-hierarchical-namespace-enabled) (if applicable) |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Container name](storage-auth-abac-attributes.md#container-name) |

+> | Operator | [StringEquals](../../role-based-access-control/conditions-format.md#stringequals) |

+> | Value | {containerName} |

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+**Storage Blob Data Owner**

+**Storage Blob Data Contributor**

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal.

+> [!div class="mx-tableFixed"]

+> | Condition #1 | Setting |

+> | | |

+> | Actions | [Read a blob](storage-auth-abac-attributes.md#read-a-blob)<br/>[All data operations for accounts with hierarchical namespace enabled](storage-auth-abac-attributes.md#all-data-operations-for-accounts-with-hierarchical-namespace-enabled) (if applicable) |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Container name](storage-auth-abac-attributes.md#container-name) |

+> | Operator | [StringEquals](../../role-based-access-control/conditions-format.md#stringequals) |

+> | Value | {containerName} |

+> | **Expression 2** | |

+> | Operator | And |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Blob path](storage-auth-abac-attributes.md#blob-path) |

+> | Operator | [StringLike](../../role-based-access-control/conditions-format.md#stringlike) |

+> | Value | {pathString} |

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+**Storage Blob Data Owner**

+**Storage Blob Data Reader**, **Storage Blob Data Contributor**

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal.

+> [!NOTE]

+> The Azure portal uses prefix='' to list blobs from container's root directory. After the condition is added with the list blobs operation using prefix StringStartsWith 'readonly/', targeted users won't be able to list blobs from container's root directory in the Azure portal.

+> [!div class="mx-tableFixed"]

+> | Condition #1 | Setting |

+> | | |

+> | Actions | [Read a blob](storage-auth-abac-attributes.md#read-a-blob)<br/>[All data operations for accounts with hierarchical namespace enabled](storage-auth-abac-attributes.md#all-data-operations-for-accounts-with-hierarchical-namespace-enabled) (if applicable) |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Container name](storage-auth-abac-attributes.md#container-name) |

+> | Operator | [StringEquals](../../role-based-access-control/conditions-format.md#stringequals) |

+> | Value | {containerName} |

+> | **Expression 2** | |

+> | Operator | And |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Blob path](storage-auth-abac-attributes.md#blob-path) |

+> | Operator | [StringStartsWith](../../role-based-access-control/conditions-format.md#stringstartswith) |

+> | Value | {pathString} |

+> [!div class="mx-tableFixed"]

+> | Condition #2 | Setting |

+> | | |

+> | Actions | [List blobs](storage-auth-abac-attributes.md#list-blobs)<br/>[All data operations for accounts with hierarchical namespace enabled](storage-auth-abac-attributes.md#all-data-operations-for-accounts-with-hierarchical-namespace-enabled) (if applicable) |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Container name](storage-auth-abac-attributes.md#container-name) |

+> | Operator | [StringEquals](../../role-based-access-control/conditions-format.md#stringequals) |

+> | Value | {containerName} |

+> | **Expression 2** | |

+> | Operator | And |

+> | Attribute source | Request |

+> | Attribute | [Blob prefix](storage-auth-abac-attributes.md#blob-prefix) |

+> | Operator | [StringStartsWith](../../role-based-access-control/conditions-format.md#stringstartswith) |

+> | Value | {pathString} |

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+**Storage Blob Data Owner**

+```

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})

+ AND

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/runAsSuperUser/action'})

+ )

+ OR

+ (

+ @Resource[Microsoft.Storage/storageAccounts/blobServices/containers:name] StringEquals 'blobs-example-container'

+ AND

+ @Resource[Microsoft.Storage/storageAccounts/blobServices/containers/blobs:path] StringStartsWith 'readonly/'

+ )

+)

+AND

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND SubOperationMatches{'Blob.List'})

+**Storage Blob Data Reader**, **Storage Blob Data Contributor**

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+Currently no example provided.

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal.

+> [!div class="mx-tableFixed"]

+> | Condition #1 | Setting |

+> | | |

+> | Actions | [Write to a blob](storage-auth-abac-attributes.md#write-to-a-blob)<br/>[Create a blob or snapshot, or append data](storage-auth-abac-attributes.md#create-a-blob-or-snapshot-or-append-data)<br/>[All data operations for accounts with hierarchical namespace enabled](storage-auth-abac-attributes.md#all-data-operations-for-accounts-with-hierarchical-namespace-enabled) (if applicable) |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Container name](storage-auth-abac-attributes.md#container-name) |

+> | Operator | [StringEquals](../../role-based-access-control/conditions-format.md#stringequals) |

+> | Value | {containerName} |

+> | **Expression 2** | |

+> | Operator | And |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Blob path](storage-auth-abac-attributes.md#blob-path) |

+> | Operator | [StringLike](../../role-based-access-control/conditions-format.md#stringlike) |

+> | Value | {pathString} |

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+**Storage Blob Data Owner**

+**Storage Blob Data Contributor**

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+```

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})

+ )

+ OR

+ (

+ @Resource[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags:Program<$key_case_sensitive$>] StringEquals 'Alpine'

+ )

+)

+AND

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})

+ )

+ OR

+ (

+ @Resource[Microsoft.Storage/storageAccounts/blobServices/containers/blobs:path] StringLike 'logs*'

+ )

+)

+```

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal.

+> [!div class="mx-tableFixed"]

+> | Condition #1 | Setting |

+> | | |

+> | Actions | [Read a blob](storage-auth-abac-attributes.md#read-a-blob)<br/>[All data operations for accounts with hierarchical namespace enabled](storage-auth-abac-attributes.md#all-data-operations-for-accounts-with-hierarchical-namespace-enabled) (if applicable) |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Is Current Version](storage-auth-abac-attributes.md#is-current-version) |

+> | Operator | [BoolEquals](../../role-based-access-control/conditions-format.md#boolean-comparison-operators) |

+> | Value | True |

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+**Storage Blob Data Owner**

+**Storage Blob Data Reader**, **Storage Blob Data Contributor**

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+Currently no example provided.

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+```

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})

+ )

+ OR

+ (

+ @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs:versionId] DateTimeEquals '2022-06-01T23:38:32.8883645Z'

+ OR

+ @Resource[Microsoft.Storage/storageAccounts/blobServices/containers/blobs:isCurrentVersion] BoolEquals true

+ )

+)

+```

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+Currently no example provided.

+

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal.

+> [!div class="mx-tableFixed"]

+> | Condition #1 | Setting |

+> | | |

+> | Actions | [Delete a blob](storage-auth-abac-attributes.md#delete-a-blob)<br/>[Delete a version of a blob](storage-auth-abac-attributes.md#delete-a-version-of-a-blob) |

+> | Attribute source | Request |

+> | Attribute | [Version ID](storage-auth-abac-attributes.md#version-id) |

+> | Operator | [DateTimeLessThan](../../role-based-access-control/conditions-format.md#datetime-comparison-operators) |

+> | Value | &lt;blobVersionId&gt; |

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+Currently no example provided.

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal.

+> [!div class="mx-tableFixed"]

+> | Condition #1 | Setting |

+> | | |

+> | Actions | [Read a blob](storage-auth-abac-attributes.md#read-a-blob)<br/>[All data operations for accounts with hierarchical namespace enabled](storage-auth-abac-attributes.md#all-data-operations-for-accounts-with-hierarchical-namespace-enabled) (if applicable) |

+> | Attribute source | Request |

+> | Attribute | [Snapshot](storage-auth-abac-attributes.md#snapshot) |

+> | Exists | [Checked](../../role-based-access-control/conditions-format.md#exists) |

+> | **Expression 2** | |

+> | Operator | Or |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Is Current Version](storage-auth-abac-attributes.md#is-current-version) |

+> | Operator | [BoolEquals](../../role-based-access-control/conditions-format.md#boolean-comparison-operators) |

+> | Value | True |

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+**Storage Blob Data Owner**

+**Storage Blob Data Reader**, **Storage Blob Data Contributor**

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+Currently no example provided.

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal.

+> [!div class="mx-tableFixed"]

+> | Condition #1 | Setting |

+> | | |

+> | Actions | [Read a blob](storage-auth-abac-attributes.md#read-a-blob)<br/>[All data operations for accounts with hierarchical namespace enabled](storage-auth-abac-attributes.md#all-data-operations-for-accounts-with-hierarchical-namespace-enabled) (if applicable) |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Is hierarchical namespace enabled](storage-auth-abac-attributes.md#is-hierarchical-namespace-enabled) |

+> | Operator | [BoolEquals](../../role-based-access-control/conditions-format.md#boolean-comparison-operators) |

+> | Value | True |

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+**Storage Blob Data Owner**

+**Storage Blob Data Reader**, **Storage Blob Data Contributor**

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+Currently no example provided.

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal.

+> [!div class="mx-tableFixed"]

+> | Condition #1 | Setting |

+> | | |

+> | Actions | [Read a blob](storage-auth-abac-attributes.md#read-a-blob) |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Encryption scope name](storage-auth-abac-attributes.md#encryption-scope-name) |

+> | Operator | [ForAnyOfAnyValues:StringEquals](../../role-based-access-control/conditions-format.md#foranyofanyvalues) |

+> | Value | &lt;scopeName&gt; |

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+Currently no example provided.

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+Here are the settings to add this condition using the Azure portal.

+> [!div class="mx-tableFixed"]

+> | Condition #1 | Setting |

+> | | |

+> | Actions | [Read a blob](storage-auth-abac-attributes.md#read-a-blob)<br/>[Write to a blob](storage-auth-abac-attributes.md#write-to-a-blob)<br/>[Create a blob or snapshot, or append data](storage-auth-abac-attributes.md#create-a-blob-or-snapshot-or-append-data) |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Account name](storage-auth-abac-attributes.md#account-name) |

+> | Operator | [StringEquals](../../role-based-access-control/conditions-format.md#stringequals) |

+> | Value | &lt;accountName&gt; |

+> | **Expression 2** | |

+> | Operator | And |

+> | Attribute source | [Resource](../../role-based-access-control/conditions-format.md#resource-attributes) |

+> | Attribute | [Encryption scope name](storage-auth-abac-attributes.md#encryption-scope-name) |

+> | Operator | [ForAnyOfAnyValues:StringEquals](../../role-based-access-control/conditions-format.md#foranyofanyvalues) |

+> | Value | &lt;scopeName&gt; |

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+Currently no example provided.

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+```

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})

+ )

+ OR

+ (

+ @Principal[Microsoft.Directory/CustomSecurityAttributes/Id:Engineering_Project] StringEquals @Resource[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags:Project<$key_case_sensitive$>]

+ )

+)

+AND

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write'} AND SubOperationMatches{'Blob.Write.WithTagHeaders'})

+ AND

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action'} AND SubOperationMatches{'Blob.Write.WithTagHeaders'})

+ )

+ OR

+ (

+ @Principal[Microsoft.Directory/CustomSecurityAttributes/Id:Engineering_Project] StringEquals @Request[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags:Project<$key_case_sensitive$>]

+ )

+)

+```

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+Currently no example provided.

+The condition can be added to a role assignment using either the Azure portal or Azure PowerShell. The portal has two tools for building ABAC conditions - the visual editor and the code editor. You can switch between the two editors in the Azure portal to see your conditions in different views. Switch between the **Visual editor** tab and the **Code editor** tabs below to view the examples for your preferred portal editor.

+# [Portal: Visual editor](#tab/portal-visual-editor)

+# [Portal: Code editor](#tab/portal-code-editor)

+To add the condition using the code editor, copy the condition code sample below and paste it into the code editor.

+```

+(

+ (

+ !(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})

+ )

+ OR

+ (

+ @Resource[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags:Project<$key_case_sensitive$>] ForAnyOfAnyValues:StringEquals @Principal[Microsoft.Directory/CustomSecurityAttributes/Id:Engineering_Project]

+ )

+)

+```

+After entering your code, switch back to the visual editor to validate it.

+# [PowerShell](#tab/azure-powershell)

+Currently no example provided.

+Here's how to add this condition for the **Storage Blob Data Reader** role using Azure PowerShell.

+Here's how to add this condition for the **Storage Blob Data Contributor** role using Azure PowerShell.

+Here's how to add this condition for the **Storage Blob Data Reader** role using Azure PowerShell.

+Here's how to add this condition for the **Storage Blob Data Contributor** role using Azure PowerShell.

+Here's how to add this condition for the **Storage Blob Data Reader** role using Azure PowerShell.

+Feature support is impacted by the type of account that you create and the settings that enable on that account. You can use the tables in this article to assess feature support based on these factors. The items that appear in these tables will change over time as support continues to expand.

+| [Customer-managed account failover](../common/storage-disaster-recovery-guidance.md?toc=/azure/storage/blobs/toc.json) | &#x2705; | &#x1F7E6; | &nbsp;&#x2B24; | &nbsp;&#x2B24; |

+| [Storage Analytics metrics (classic)](../common/storage-analytics-metrics.md?toc=/azure/storage/blobs/toc.json) | &#x2705; | &#x2705; | &#x2705; | &#x2705; |

+| [Storage Analytics metrics (classic)](../common/storage-analytics-metrics.md?toc=/azure/storage/blobs/toc.json) | &#x2705; | &#x2705; | &#x2705; | &#x2705; |

+Azure Storage always stores multiple copies of your data so that it's protected from planned and unplanned events. This including transient hardware failures, network or power outages, and massive natural disasters. Redundancy ensures that your storage account meets the [Service-Level Agreement (SLA) for Azure Storage](https://azure.microsoft.com/support/legal/sla/storage/) even in the face of failures.

+In this article, you'll learn how to change the replication setting(s) for an existing storage account.

+For an overview of all of the redundancy options, see [Azure Storage redundancy](storage-redundancy.md).

+You can change how your storage account is replicated from any redundancy configuration to any other with some limitations. Before making any changes, review those [limitations](#limitations-for-changing-replication-types) along with the [downtime requirements](#downtime-requirements) to ensure you have a plan that provides the best end result within a time frame that suits your needs, and that satisfies your uptime requirements.

+- [Use the Azure portal, Azure PowerShell, or the Azure CLI](#change-the-replication-setting-using-the-portal-powershell-or-the-cli) to add or remove geo-replication or read access to the secondary region.

+- [Perform a conversion](#perform-a-conversion) to add or remove zone-redundancy.

+- [Perform a manual migration](#manual-migration) in scenarios where the first two options aren't supported, or to ensure the change completes within a specific time.

+If you want to change both zone-redundancy and either geo-replication or read-access, a two-step process is required. Geo-redundancy and read-access can be changed at the same time, but the zone-redundancy conversion must be performed separately. These steps can be performed in any order.

+The following table provides an overview of how to switch from each type of replication to another.

+> Manual migration is an option for any scenario in which you want to change the replication setting within the [limitations for changing replication types](#limitations-for-changing-replication-types). The manual migration option has been omitted from the provided table to simplify it.

+<sup>3</sup> The type of conversion supported depends on the storage account type. See [the storage account table](#storage-account-type) for more details.<br />

+<sup>4</sup> Conversion to ZRS or GZRS for an LRS account resulting from a failover isn't supported. For more details, see [Failover and failback](#failover-and-failback).<br />

+<sup>5</sup> Converting from LRS to ZRS is [not supported if the NFSv3 protocol support is enabled for Azure Blob Storage or if the storage account contains Azure Files NFSv4.1 shares](#protocol-support). <br />

+<sup>6</sup> Even though enabling geo-redundancy appears to occur instantaneously, failover to the secondary region cannot be initiated until data synchronization between the two regions has completed.<br />

+In most cases you can use the Azure portal, PowerShell, or the Azure CLI to change the geo-redundant or read access (RA) replication setting for a storage account. If you are initiating a zone redundancy conversion, you can change the setting from within the Azure portal, but not from PowerShell or the Azure CLI.

+ :::image type="content" source="media/redundancy-migration/change-replication-option.png" alt-text="Screenshot showing how to change replication option in portal." lightbox="media/redundancy-migration/change-replication-option.png":::

+To change the redundancy option for your storage account with PowerShell, call the [Set-AzStorageAccount](/powershell/module/az.storage/set-azstorageaccount) command and specify the `-SkuName` parameter:

+To change the redundancy option for your storage account with Azure CLI, call the [az storage account update](/cli/azure/storage/account#az-storage-account-update) command and specify the `--sku` parameter:

+ --name <storage-account>

+During a conversion, [there is no data loss or application downtime required](#downtime-requirements).

+> For more details about the timing of a customer-initiated conversion, see [Timing and frequency](#timing-and-frequency).

+Customer-initiated conversion is not available in all regions. See the [region limitations](#region) for more details.

+As the conversion request is evaluated and processed, the status should progress through the list shown in the table below:

+| In Progress<sup>1</sup> | The actual conversion has begun. |

+| Completed<br>**- or -**</br>Failed<sup>2</sup> | The conversion has successfully completed.<br>**- or -**</br>The conversion failed. |

+<sup>1</sup> Once initiated, the conversion could take up to 72 hours to actually **begin**. If the conversion does not enter the "In Progress" status within 96 hours of initiating the request, submit a support request to Microsoft to determine why. For more details about the timing of a customer-initiated conversion, see [Timing and frequency](#timing-and-frequency).<br />

+ :::image type="content" source="media/redundancy-migration/request-live-migration-problem-desc-portal.png" alt-text="Screenshot showing how to request a conversion - Problem description tab." lightbox="media/redundancy-migration/request-live-migration-problem-desc-portal.png":::

+ :::image type="content" source="media/redundancy-migration/request-live-migration-solutions-portal.png" alt-text="Screenshot showing how to check the eligibility of your storage account(s) for conversion - Solutions page." lightbox="media/redundancy-migration/request-live-migration-solutions-portal.png":::

+1. Take the appropriate action if the results indicate your storage account is not eligible for conversion. If it is eligible, select **Return to support request**.

+ :::image type="content" source="media/redundancy-migration/request-live-migration-details-portal.png" alt-text="Screenshot showing how to request a conversion - Additional details tab." lightbox="media/redundancy-migration/request-live-migration-details-portal.png":::

+1. Fill out the additional required information on the **Additional details** tab, then select **Review + create** to review and submit your support ticket. A support person will contact you to provide any assistance you may need.

+A manual migration provides more flexibility and control than a conversion. You can use this option if you need your data moved by a certain date, or if conversion is [not supported for your scenario](#limitations-for-changing-replication-types). Manual migration is also useful when moving a storage account to another region. See [Move an Azure Storage account to another region](storage-account-move.md) for more details.

+- Your storage account includes data in the archive tier and rehydrating the data is not desired.

+Make sure the region where your storage account is located supports all of the desired replication settings. For example, if you are converting your account to zone-redundant (ZRS, GZRS, or RA-GZRS), make sure your storage account is in a region that supports it. See the lists of supported regions for [Zone-redundant storage](storage-redundancy.md#zone-redundant-storage) and [Geo-zone-redundant storage](storage-redundancy.md#geo-zone-redundant-storage).

+> - (Europe) UK South

+Some storage account features are not compatible with other features or operations. For example, the ability to failover to the secondary region is the key feature of geo-redundancy, but other features are not compatible with failover. For more information about features and services not supported with failover, see [Unsupported features and services](storage-disaster-recovery-guidance.md#unsupported-features-and-services). Converting an account to GRS, GZRS, or RA-GZRS might be blocked if a conflicting feature is enabled, or it might be necessary to disable the feature later before initiating a failover.

+Some storage account types only support certain redundancy configurations, which affects whether they can be converted or migrated and, if so, how. For more details on Azure storage account types and the supported redundancy options, see [the storage account overview](storage-account-overview.md#types-of-storage-accounts).

+<sup>1</sup> Conversion for premium file shares is only available by [opening a support request](#support-requested-conversion); [Customer-initiated conversion](#customer-initiated-conversion) is not currently supported.<br />

+<sup>2</sup> Managed disks are available for LRS and ZRS, though ZRS disks have some [limitations](../../virtual-machines/disks-redundancy.md#limitations). If a LRS disk is regional (no zone specified) it may be converted by [changing the SKU](../../virtual-machines/disks-convert-types.md). If a LRS disk is zonal, then it can only be manually migrated by following the process in [Migrate your managed disks](../../reliability/migrate-vm.md#migrate-your-managed-disks). You can store snapshots and images for standard SSD managed disks on standard HDD storage and [choose between LRS and ZRS options](https://azure.microsoft.com/pricing/details/managed-disks/). For information about integration with availability sets, see [Introduction to Azure managed disks](../../virtual-machines/managed-disks-overview.md#integration-with-availability-sets).<br />

+<sup>3</sup> If your storage account is v1, you'll need to upgrade it to v2 before performing a conversion. To learn how to upgrade your v1 account, see [Upgrade to a general-purpose v2 storage account](storage-account-upgrade.md).<br />

+<sup>4</sup> ZRS Classic storage accounts have been deprecated. For information about converting ZRS Classic accounts, see [Converting ZRS Classic accounts](#converting-zrs-classic-accounts).<br />

+ZRS Classic accounts asynchronously replicated data across data centers within one to two regions. Replicated data was not available unless Microsoft initiated a failover to the secondary. A ZRS Classic account can't be converted to or from LRS, GRS, or RA-GRS. ZRS Classic accounts also don't support metrics or logging.

+If you want to migrate your data into a zone-redundant storage account located in a region different from the source account, you must perform a manual migration. For more details, see [Move an Azure Storage account to another region](storage-account-move.md).

+Make sure the desired redundancy option supports the access tiers currently used in the storage account. For example, ZRS, GZRS and RA-GZRS storage accounts do not support the archive tier. See [Hot, Cool, and Archive access tiers for blob data](../blobs/access-tiers-overview.md) for more details. To convert an LRS, GRS or RA-GRS account to one that supports zone-redundancy, first move the archived blobs to a storage account that supports blobs in the archive tier. Then convert the source account to ZRS, GZRS and RA-GZRS.

+To switch an LRS storage account that contains blobs in the archive tier to GRS or RA-GRS, you must first rehydrate all archived blobs to the Hot or Cool tier or perform a [manual migration](#manual-migration).

+Converting your storage account to zone-redundancy (ZRS, GZRS or RA-GZRS) is not supported if either of the following is true:

+After an account failover to the secondary region, it's possible to initiate a failback from the new primary back to the new secondary with PowerShell or Azure CLI (version 2.30.0 or later). For more information, see [How customer-managed storage account failover works](storage-failover-customer-managed-unplanned.md).

+If you performed an account failover for your GRS or RA-GRS account, the account is locally redundant (LRS) in the new primary region after the failover. Conversion to ZRS or GZRS for an LRS account resulting from a failover is not supported. This is true even in the case of so-called failback operations. For example, if you perform an account failover from RA-GRS to LRS in the secondary region, and then configure it again as RA-GRS, it will be LRS in the new secondary region (the original primary). If you then perform another account failover to failback to the original primary region, it will be LRS again in the original primary. In this case, you can't perform a conversion to ZRS, GZRS or RA-GZRS in the primary region. Instead, you'll need to perform a manual migration to add zone-redundancy.

+During a [conversion](#perform-a-conversion), you can access data in your storage account with no loss of durability or availability. [The Azure Storage SLA](https://azure.microsoft.com/support/legal/sla/storage/) is maintained during the migration process and there is no data loss associated with a conversion. Service endpoints, access keys, shared access signatures, and other account options remain unchanged after the migration.

+If you initiate a zone-redundancy [conversion](#customer-initiated-conversion) from the Azure portal, the conversion process could take up to 72 hours to actually **begin**. It could take longer to start if you [request a conversion by opening a support request](#support-requested-conversion). If a customer-initiated conversion does not enter the "In Progress" status within 96 hours of initiating the request, submit a support request to Microsoft to determine why. To monitor the progress of a customer-initiated conversion, see [Monitoring customer-initiated conversion progress](#monitoring-customer-initiated-conversion-progress).

+Ordering from the least to the most expensive, Azure Storage redundancy offerings include LRS, ZRS, GRS, RA-GRS, GZRS, and RA-GZRS.

+The costs associated with changing how data is replicated in your storage account depend on which [aspects of your redundancy configuration](#options-for-changing-the-replication-type) you change. A combination of data storage and egress bandwidth pricing determine the cost of making a change. For details on pricing, see [Azure Storage Pricing page](https://azure.microsoft.com/pricing/details/storage/blobs/).

+If you add zone-redundancy in the primary region, there is no initial cost associated with making that conversion, but the ongoing data storage cost will be higher due to the additional replication and storage space required.

+If you add geo-redundancy, you will incur an egress bandwidth charge at the time of the change because your entire storage account is being replicated to the secondary region. All subsequent writes to the primary region also incur egress bandwidth charges to replicate the write to the secondary region.

+If you remove geo-redundancy (change from GRS to LRS), there is no cost for making the change, but your replicated data is deleted from the secondary location.

+### Monitoring existing storage accounts

+To monitor your existing storage accounts and gather this data, you can make use of Azure Storage Analytics, which performs logging and provides metrics data for a storage account. Storage Analytics can store metrics that include aggregated transaction statistics and capacity data about requests to the storage service for GPv1, GPv2, and Blob storage account types. This data is stored in well-known tables in the same storage account.

+For more information, see [About Storage Analytics Metrics](../blobs/monitor-blob-storage.md) and [Storage Analytics Metrics Table Schema](/rest/api/storageservices/Storage-Analytics-Metrics-Table-Schema)

+> [!NOTE]

+> Blob storage accounts expose the Table service endpoint only for storing and accessing the metrics data for that account.

+To monitor the storage consumption for Blob storage, you need to enable the capacity metrics.

+With this enabled, capacity data is recorded daily for a storage account's Blob service and recorded as a table entry that is written to the *$MetricsCapacityBlob* table within the same storage account.

+To monitor data access patterns for Blob storage, you need to enable the hourly transaction metrics from the API. With hourly transaction metrics enabled, per API transactions are aggregated every hour, and recorded as a table entry that is written to the *$MetricsHourPrimaryTransactionsBlob* table within the same storage account. The *$MetricsHourSecondaryTransactionsBlob* table records the transactions to the secondary endpoint when using RA-GRS storage accounts.

+> [!NOTE]

+> If you have a general-purpose storage account in which you have stored page blobs and virtual machine disks, or queues, files, or tables, alongside block and append blob data, this estimation process isn't applicable. The capacity data doesn't differentiate block blobs from other types, and doesn't give capacity data for other data types. If you use these types, an alternative methodology is to look at the quantities on your most recent bill.

+To get a good approximation of your data consumption and access pattern, we recommend you choose a retention period for the metrics that is representative of your regular usage and extrapolate. One option is to retain the metrics data for seven days and collect the data every week, for analysis at the end of the month. Another option is to retain the metrics data for the last 30 days and collect and analyze the data at the end of the 30-day period.

+For details on enabling, collecting, and viewing metrics data, see [Storage analytics metrics](../common/storage-analytics-metrics.md?toc=/azure/storage/blobs/toc.json).

+> [!NOTE]

+> Storing, accessing, and downloading analytics data is also charged just like regular user data.

+### Utilizing usage metrics to estimate costs

+#### Capacity costs

+The latest entry in the capacity metrics table *$MetricsCapacityBlob* with the row key *'data'* shows the storage capacity consumed by user data. The latest entry in the capacity metrics table *$MetricsCapacityBlob* with the row key *'analytics'* shows the storage capacity consumed by the analytics logs.

+This total capacity consumed by both user data and analytics logs (if enabled) can then be used to estimate the cost of storing data in the storage account. The same method can also be used for estimating storage costs in GPv1 storage accounts.

+#### Transaction costs

+The sum of *'TotalBillableRequests'*, across all entries for an API in the transaction metrics table indicates the total number of transactions for that particular API. *For example*, the total number of *'GetBlob'* transactions in a given period can be calculated by the sum of total billable requests for all entries with the row key *'user;GetBlob'*.

+In order to estimate transaction costs for Blob storage accounts, you need to break down the transactions into three groups since they're priced differently.

+- Write transactions such as *'PutBlob'*, *'PutBlock'*, *'PutBlockList'*, *'AppendBlock'*, *'ListBlobs'*, *'ListContainers'*, *'CreateContainer'*, *'SnapshotBlob'*, and *'CopyBlob'*.

+- Delete transactions such as *'DeleteBlob'* and *'DeleteContainer'*.

+- All other transactions.

+In order to estimate transaction costs for GPv1 storage accounts, you need to aggregate all transactions irrespective of the operation/API.

+#### Data access and geo-replication data transfer costs

+While storage analytics doesn't provide the amount of data read from and written to a storage account, it can be roughly estimated by looking at the transaction metrics table. The sum of *'TotalIngress'* across all entries for an API in the transaction metrics table indicates the total amount of ingress data in bytes for that particular API. Similarly the sum of *'TotalEgress'* indicates the total amount of egress data, in bytes.

+In order to estimate the data access costs for Blob storage accounts, you need to break down the transactions into two groups.

+- The amount of data retrieved from the storage account can be estimated by looking at the sum of *'TotalEgress'* for primarily the *'GetBlob'* and *'CopyBlob'* operations.

+- The amount of data written to the storage account can be estimated by looking at the sum of *'TotalIngress'* for primarily the *'PutBlob'*, *'PutBlock'*, *'CopyBlob'* and *'AppendBlock'* operations.

+ Title: Use Azure Storage analytics to collect logs and metrics data

+Azure Storage Analytics performs logging and provides metrics data for a storage account. You can use this data to trace requests, analyze usage trends, and diagnose issues with your storage account.

+The aggregated data is stored in a well-known blob (for logging) and in well-known tables (for metrics), which may be accessed using the Blob service and Table service APIs.

+All metrics data is written by the services of a storage account. As a result, each write operation performed by Storage Analytics is billable. Additionally, the amount of storage used by metrics data is also billable.

+The following actions performed by Storage Analytics are billable:

+- Requests to create blobs for logging.

+- Requests to create table entities for metrics.

+If you have configured a data retention policy, you can reduce the spending by deleting old logging and metrics data. For more information about retention policies, see [Setting a Storage Analytics Data Retention Policy](/rest/api/storageservices/Setting-a-Storage-Analytics-Data-Retention-Policy).

+Every request made to an account's storage service is either billable or non-billable. Storage Analytics logs each individual request made to a service, including a status message that indicates how the request was handled. Similarly, Storage Analytics stores metrics for both a service and the API operations of that service, including the percentages and count of certain status messages. Together, these features can help you analyze your billable requests, make improvements on your application, and diagnose issues with requests to your services. For more information about billing, see [Understanding Azure Storage Billing - Bandwidth, Transactions, and Capacity](/archive/blogs/windowsazurestorage/understanding-windows-azure-storage-billing-bandwidth-transactions-and-capacity).

+When looking at Storage Analytics data, you can use the tables in the [Storage Analytics Logged Operations and Status Messages](/rest/api/storageservices/storage-analytics-logged-operations-and-status-messages) topic to determine what requests are billable. Then you can compare your logs and metrics data to the status messages to see if you were charged for a particular request. You can also use the tables in the previous topic to investigate availability for a storage service or individual API operation.

+- [Storage Analytics Metrics](storage-analytics-metrics.md)

+Microsoft strives to ensure that Azure services are always available. However, unplanned service outages may occur. Key components of a good disaster recovery plan include strategies for:

+This article focuses on failover for globally redundant storage accounts (GRS, GZRS, and RA-GZRS), and how to design your applications to be highly available if there's an outage and subsequent failover.

+Azure Storage maintains multiple copies of your storage account to ensure durability and high availability. Which redundancy option you choose for your account depends on the degree of resiliency you need for your applications.

+With locally redundant storage (LRS), three copies of your storage account are automatically stored and replicated within a single datacenter. With zone-redundant storage (ZRS), a copy is stored and replicated in each of three separate availability zones within the same region. For more information about availability zones, see [Azure availability zones](../../availability-zones/az-overview.md).

+Recovery of a single copy of a storage account occurs automatically with LRS and ZRS.

+With globally redundant storage (GRS, GZRS, and RA-GZRS), Azure copies your data asynchronously to a secondary geographic region at least hundreds of miles away. This allows you to recover your data if there's an outage in the primary region. A feature that distinguishes globally redundant storage from LRS and ZRS is the ability to fail over to the secondary region if there's an outage in the primary region. The process of failing over updates the DNS entries for your storage account service endpoints such that the endpoints for the secondary region become the new primary endpoints for your storage account. Once the failover is complete, clients can begin writing to the new primary endpoints.

+RA-GRS and RA-GZRS redundancy configurations provide geo-redundant storage with the added benefit of read access to the secondary endpoint if there is an outage in the primary region. If an outage occurs in the primary endpoint, applications configured for read access to the secondary region and designed for high availability can continue to read from the secondary endpoint. Microsoft recommends RA-GZRS for maximum availability and durability of your storage accounts.

+For more information about redundancy in Azure Storage, see [Azure Storage redundancy](storage-redundancy.md).

+Azure Storage accounts support two types of failover:

+- [**Microsoft-managed failover**](#microsoft-managed-failover) - Potentially initiated by Microsoft only in the case of a severe disaster in the primary region. <sup>1,2</sup>

+<sup>1</sup>Microsoft-managed failover can't be initiated for individual storage accounts, subscriptions, or tenants. For more details see [Microsoft-managed failover](#microsoft-managed-failover). <br/>

+<sup>2</sup> Your disaster recovery plan should be based on customer-managed failover. **Do not** rely on Microsoft-managed failover, which would only be used in extreme circumstances. <br/>

+Each type of failover has a unique set of use cases, corresponding expectations for data loss, and support for accounts with a hierarchical namespace enabled (Azure Data Lake Storage Gen2). This table summarizes those aspects of each type of failover :

+| Type | Failover Scope | Use case | Expected data loss | HNS supported |

+||--|-|||

+| Customer-managed | Storage account | The storage service endpoints for the primary region become unavailable, but the secondary region is available. <br></br> You received an Azure Advisory in which Microsoft advises you to perform a failover operation of storage accounts potentially affected by an outage. | [Yes](#anticipate-data-loss-and-inconsistencies) | [Yes ](#azure-data-lake-storage-gen2)*[(In preview)](#azure-data-lake-storage-gen2)* |

+| Microsoft-managed | Entire region or scale unit | The primary region becomes completely unavailable due to a significant disaster, but the secondary region is available. | [Yes](#anticipate-data-loss-and-inconsistencies) | [Yes](#azure-data-lake-storage-gen2) |

+To fully understand the impact that customer-managed account failover would have on your users and applications, it is helpful to know what happens during every step of the failover and failback process. For details about how the process works, see [How customer-managed storage account failover works](storage-failover-customer-managed-unplanned.md).

+In extreme circumstances where the original primary region is deemed unrecoverable within a reasonable amount of time due to a major disaster, Microsoft **may** initiate a regional failover. In this case, no action on your part is required. Until the Microsoft-managed failover has completed, you won't have write access to your storage account. Your applications can read from the secondary region if your storage account is configured for RA-GRS or RA-GZRS.

+> A Microsoft-managed failover would be initiated for an entire physical unit, such as a region or scale unit. It can't be initiated for individual storage accounts, subscriptions, or tenants. For the ability to selectively failover your individual storage accounts, use [customer-managed account failover](#customer-managed-failover).

+> Storage account failover usually involves some data loss, and potentially file and data inconsistencies. In your disaster recovery plan, it's important to consider the impact that an account failover would have on your data before initiating one.

+Because data is written asynchronously from the primary region to the secondary region, there's always a delay before a write to the primary region is copied to the secondary. If the primary region becomes unavailable, the most recent writes may not yet have been copied to the secondary.

+When a failover occurs, all data in the primary region is lost as the secondary region becomes the new primary. All data already copied to the secondary is maintained when the failover happens. However, any data written to the primary that hasn't also been copied to the secondary region is lost permanently.

+The **Last Sync Time** property indicates the most recent time that data from the primary region is guaranteed to have been written to the secondary region. For accounts that have a hierarchical namespace, the same **Last Sync Time** property also applies to the metadata managed by the hierarchical namespace, including ACLs. All data and metadata written prior to the last sync time is available on the secondary, while data and metadata written after the last sync time may not have been written to the secondary, and may be lost. Use this property if there's an outage to estimate the amount of data loss you may incur by initiating an account failover.

+As a best practice, design your application so that you can use the last sync time to evaluate expected data loss. For example, if you're logging all write operations, then you can compare the time of your last write operations to the last sync time to determine which writes haven't been synced to the secondary.

+Replication for storage accounts with a [hierarchical namespace enabled (Azure Data Lake Storage Gen2)](../blobs/data-lake-storage-introduction.md) occurs at the file level. This means if an outage in the primary region occurs, it is possible that only some of the files in a container or directory might have successfully replicated to the secondary region. Consistency for all files in a container or directory after a storage account failover is not guaranteed.

+Storage account failover of geo-redundant storage accounts with [change feed](../blobs/storage-blob-change-feed.md) enabled may result in inconsistencies between the change feed logs and the blob data and/or metadata. Such inconsistencies can result from the asynchronous nature of both updates to the change logs and the replication of blob data from the primary to the secondary region. The only situation in which inconsistencies would not be expected is when all of the current log records have been successfully flushed to the log files, and all of the storage data has been successfully replicated from the primary to the secondary region.

+For information about how change feed works see [How the change feed works](../blobs/storage-blob-change-feed.md#how-the-change-feed-works).

+Keep in mind that other storage account features require the change feed to be enabled such as [operational backup of Azure Blob Storage](../../backup/blob-backup-support-matrix.md#limitations), [Object replication](../blobs/object-replication-overview.md) and [Point-in-time restore for block blobs](../blobs/point-in-time-restore-overview.md).

+Customer-managed failover is supported for general-purpose v2 standard tier storage accounts that include block blobs. However, performing a customer-managed failover on a storage account resets the earliest possible restore point for the account. Data for [Point-in-time restore for block blobs](../blobs/point-in-time-restore-overview.md) is only consistent up to the failover completion time. As a result, you can only restore block blobs to a point in time no earlier than the failover completion time. You can check the failover completion time in the redundancy tab of your storage account in the Azure Portal.

+For example, suppose you have set the retention period to 30 days. If more than 30 days have elapsed since the failover, then you can restore to any point within that 30 days. However, if fewer than 30 days have elapsed since the failover, then you can't restore to a point prior to the failover, regardless of the retention period. For example, if it's been 10 days since the failover, then the earliest possible restore point is 10 days in the past, not 30 days in the past.

+The time it takes for failover to complete after being initiated can vary, although it typically takes less than one hour.

+A customer-managed failover loses its geo-redundancy after a failover (and failback). Your storage account is automatically converted to locally redundant storage (LRS) in the new primary region during a failover, and the storage account in the original primary region is deleted.

+You can re-enable geo-redundant storage (GRS) or read-access geo-redundant storage (RA-GRS) for the account, but note that converting from LRS to GRS or RA-GRS incurs an additional cost. The cost is due to the network egress charges to re-replicate the data to the new secondary region. Also, all archived blobs need to be rehydrated to an online tier before the account can be configured for geo-redundancy, which will incur a cost. For more information about pricing, see:

+After you re-enable GRS for your storage account, Microsoft begins replicating the data in your account to the new secondary region. Replication time depends on many factors, which include:

+| **Customer-managed failover** | General-purpose v2 accounts</br> General-purpose v1 accounts</br> Legacy Blob Storage accounts | General-purpose v2 accounts |

+| **Microsoft-managed failover** | All account types | General-purpose v2 accounts |

+> Customer-managed account failover is only supported for storage accounts deployed using the Azure Resource Manager (ARM) deployment model. The Azure Service Manager (ASM) deployment model, also known as *classic*, isn't supported. To make classic storage accounts eligible for customer-managed account failover, they must first be [migrated to the ARM model](classic-account-migration-overview.md). Your storage account must be accessible to perform the upgrade, so the primary region can't currently be in a failed state.

+> if there's a disaster that affects the primary region, Microsoft will manage the failover for classic storage accounts. For more information, see [Microsoft-managed failover](#microsoft-managed-failover).

+> if there's a significant disaster that affects the primary region, Microsoft will manage the failover for accounts with a hierarchical namespace. For more information, see [Microsoft-managed failover](#microsoft-managed-failover).

+- Azure File Sync doesn't support storage account failover. Storage accounts containing Azure file shares being used as cloud endpoints in Azure File Sync shouldn't be failed over. Doing so will cause sync to stop working and may also cause unexpected data loss in the case of newly tiered files.

+- To failover an account with SSH File Transfer Protocol (SFTP) enabled, you must first [disable SFTP for the account](../blobs/secure-file-transfer-protocol-support-how-to.md#disable-sftp-support). If you want to resume using SFTP after the failover is complete, simply [re-enable it](../blobs/secure-file-transfer-protocol-support-how-to.md#enable-sftp-support).

+### Failover is not for account migration

+Storage account failover shouldn't be used as part of your data migration strategy. Failover is a temporary solution to a service outage. For information about how to migrate your storage accounts, see [Azure Storage migration overview](storage-migration-overview.md).

+Storage accounts containing archived blobs support account failover. However, after a [customer-managed failover](#customer-managed-failover) is complete, all archived blobs need to be rehydrated to an online tier before the account can be configured for geo-redundancy.

+Microsoft provides two REST APIs for working with Azure Storage resources. These APIs form the basis of all actions you can perform against Azure Storage. The Azure Storage REST API enables you to work with data in your storage account, including blob, queue, file, and table data. The Azure Storage resource provider REST API enables you to manage the storage account and related resources.

+After a failover is complete, clients can again read and write Azure Storage data in the new primary region. However, the Azure Storage resource provider does not fail over, so resource management operations must still take place in the primary region. If the primary region is unavailable, you will not be able to perform management operations on the storage account.

+Because the Azure Storage resource provider does not fail over, the [Location](/dotnet/api/microsoft.azure.management.storage.models.trackedresource.location) property will return the original primary location after the failover is complete.

+Azure virtual machines (VMs) don't fail over as part of an account failover. If the primary region becomes unavailable, and you fail over to the secondary region, then you will need to recreate any VMs after the failover. Also, there's a potential data loss associated with the account failover. Microsoft recommends following the [high availability](../../virtual-machines/availability.md) and [disaster recovery](../../virtual-machines/backup-recovery.md) guidance specific to virtual machines in Azure.

+Keep in mind that any data stored in a temporary disk is lost when the VM is shut down.

+As a best practice, Microsoft recommends converting unmanaged disks to managed disks. However, if you need to fail over an account that contains unmanaged disks attached to Azure VMs, you will need to shut down the VM before initiating the failover.

+Unmanaged disks are stored as page blobs in Azure Storage. When a VM is running in Azure, any unmanaged disks attached to the VM are leased. An account failover can't proceed when there's a lease on a blob. To perform the failover, follow these steps:

+1. Before you begin, note the names of any unmanaged disks, their logical unit numbers (LUN), and the VM to which they are attached. Doing so will make it easier to reattach the disks after the failover.

+2. Shut down the VM.

+3. Delete the VM, but retain the VHD files for the unmanaged disks. Note the time at which you deleted the VM.

+4. Wait until the **Last Sync Time** has updated, and is later than the time at which you deleted the VM. This step is important, because if the secondary endpoint hasn't been fully updated with the VHD files when the failover occurs, then the VM may not function properly in the new primary region.

+5. Initiate the account failover.

+6. Wait until the account failover is complete and the secondary region has become the new primary region.

+7. Create a VM in the new primary region and reattach the VHDs.

+8. Start the new VM.

+If your storage account is configured for read access to the secondary region, then you can design your application to read from the secondary endpoint. If you prefer not to fail over if there's an outage in the primary region, you can use tools such as [AzCopy](./storage-use-azcopy-v10.md) or [Azure PowerShell](/powershell/module/az.storage/) to copy data from your storage account in the secondary region to another storage account in an unaffected region. You can then point your applications to that storage account for both read and write availability.

+It's important to design your application for high availability from the start. Refer to these Azure resources for guidance in designing your application and planning for disaster recovery:

+Keep in mind these best practices for maintaining high availability for your Azure Storage data:

+- **Disks:** Use [Azure Backup](https://azure.microsoft.com/services/backup/) to back up the VM disks used by your Azure virtual machines. Also consider using [Azure Site Recovery](https://azure.microsoft.com/services/site-recovery/) to protect your VMs if there's a regional disaster.

+Customers may subscribe to the [Azure Service Health Dashboard](https://azure.microsoft.com/status/) to track the health and status of Azure Storage and other Azure services.

+- [How customer-managed storage account failover works](storage-failover-customer-managed-unplanned.md)

+ Title: How Azure Storage account customer-managed failover works

+# How customer-managed storage account failover works

+The original and current redundancy configurations are stored in the properties of the storage account to allow you eventually return to your original configuration when you fail back.

+The failback process is essentially the same as the failover process except Azure restores the replication configuration to its original state before it was failed over (the replication configuration, not the data). So, if your storage account was originally configured as GZRS, the primary region after faillback becomes ZRS.

+description: Learn how to initiate an account failover in the event that the primary endpoint for your storage account becomes unavailable. The failover updates the secondary region to become the primary region for your storage account.

+If the primary endpoint for your geo-redundant storage account becomes unavailable for any reason, you can initiate an account failover. An account failover updates the secondary endpoint to become the primary endpoint for your storage account. Once the failover is complete, clients can begin writing to the new primary region. Forced failover enables you to maintain high availability for your applications.

+This article shows how to initiate an account failover for your storage account using the Azure portal, PowerShell, or Azure CLI. To learn more about account failover, see [Disaster recovery and storage account failover](storage-disaster-recovery-guidance.md).

+Before you can perform an account failover on your storage account, make sure that:

+> [!div class="checklist"]

+> - Your storage account is configured for geo-replication (GRS, GZRS, RA-GRS or RA-GZRS). For more information about Azure Storage redundancy, see [Azure Storage redundancy](storage-redundancy.md).

+> - The type of your storage account supports customer-initiated failover. See [Supported storage account types](storage-disaster-recovery-guidance.md#supported-storage-account-types).

+> - Your storage account doesn't have any features or services enabled that are not supported for account failover. See [Unsupported features and services](storage-disaster-recovery-guidance.md#unsupported-features-and-services) for a detailed list.

+You can initiate an account failover from the Azure portal, PowerShell, or the Azure CLI.

+1. Under **Settings**, select **Geo-replication**. The following image shows the geo-replication and failover status of a storage account.

+ :::image type="content" source="media/storage-initiate-account-failover/portal-failover-prepare.png" alt-text="Screenshot showing geo-replication and failover status":::

+1. Verify that your storage account is configured for geo-redundant storage (GRS) or read-access geo-redundant storage (RA-GRS). If it's not, then select **Configuration** under **Settings** to update your account to be geo-redundant.

+1. The **Last Sync Time** property indicates how far the secondary is behind from the primary. **Last Sync Time** provides an estimate of the extent of data loss that you will experience after the failover is completed. For more information about checking the **Last Sync Time** property, see [Check the Last Sync Time property for a storage account](last-sync-time-get.md).

+1. Select **Prepare for failover**.

+1. Review the confirmation dialog. When you are ready, enter **Yes** to confirm and initiate the failover.

+ :::image type="content" source="media/storage-initiate-account-failover/portal-failover-confirm.png" alt-text="Screenshot showing confirmation dialog for an account failover":::

+To use PowerShell to initiate an account failover, install the [Az.Storage](https://www.powershellgallery.com/packages/Az.Storage) module, version 2.0.0 or later. For more information about installing Azure PowerShell, see [Install the Azure Az PowerShell module](/powershell/azure/install-azure-powershell).

+To initiate an account failover from PowerShell, call the following command:

+Invoke-AzStorageAccountFailover -ResourceGroupName <resource-group-name> -Name <account-name>

+To use Azure CLI to initiate an account failover, call the following commands:

+```azurecli-interactive

+az storage account show \ --name accountName \ --expand geoReplicationStats

+az storage account failover \ --name accountName

+## Important implications of account failover

+When you initiate an account failover for your storage account, the DNS records for the secondary endpoint are updated so that the secondary endpoint becomes the primary endpoint. Make sure that you understand the potential impact to your storage account before you initiate a failover.

+To estimate the extent of likely data loss before you initiate a failover, check the **Last Sync Time** property. For more information about checking the **Last Sync Time** property, see [Check the Last Sync Time property for a storage account](last-sync-time-get.md).

+The time it takes to failover after initiation can vary though typically less than one hour.

+After the failover, your storage account type is automatically converted to locally redundant storage (LRS) in the new primary region. You can re-enable geo-redundant storage (GRS) or read-access geo-redundant storage (RA-GRS) for the account. Note that converting from LRS to GRS or RA-GRS incurs an additional cost. The cost is due to the network egress charges to re-replicate the data to the new secondary region. For additional information, see [Bandwidth Pricing Details](https://azure.microsoft.com/pricing/details/bandwidth/).

+After you re-enable GRS for your storage account, Microsoft begins replicating the data in your account to the new secondary region. Replication time depends on many factors, which include:

+- The number and size of the objects in the storage account. Many small objects can take longer than fewer and larger objects.

+- The available resources for background replication, such as CPU, memory, disk, and WAN capacity. Live traffic takes priority over geo replication.

+- If using Blob storage, the number of snapshots per blob.

+- If using Table storage, the [data partitioning strategy](/rest/api/storageservices/designing-a-scalable-partitioning-strategy-for-azure-table-storage). The replication process can't scale beyond the number of partition keys that you use.

+## Next steps

+On **January 9, 2024** Storage Analytics metrics, also referred to as *classic metrics* will be retired. If you use classic metrics, make sure to transition to metrics in Azure Monitor prior to that date. This article helps you make the transition.

+Azure Storage always stores multiple copies of your data so that it's protected from planned and unplanned events, including transient hardware failures, network or power outages, and massive natural disasters. Redundancy ensures that your storage account meets its availability and durability targets even in the face of failures.

+The redundancy setting for a storage account is shared for all storage services exposed by that account. All storage resources deployed in the same storage account have the same redundancy setting. You may want to isolate different types of resources in separate storage accounts if they have different redundancy requirements.

+LRS is the lowest-cost redundancy option and offers the least durability compared to other options. LRS protects your data against server rack and drive failures. However, if a disaster such as fire or flooding occurs within the data center, all replicas of a storage account using LRS may be lost or unrecoverable. To mitigate this risk, Microsoft recommends using [zone-redundant storage](#zone-redundant-storage) (ZRS), [geo-redundant storage](#geo-redundant-storage) (GRS), or [geo-zone-redundant storage](#geo-zone-redundant-storage) (GZRS).

+- If your application stores data that can be easily reconstructed if data loss occurs, you may opt for LRS.

+- If your application is restricted to replicating data only within a country or region due to data governance requirements, you may opt for LRS. In some cases, the paired regions across which the data is geo-replicated may be in another country or region. For more information on paired regions, see [Azure regions](https://azure.microsoft.com/regions/).

+- If your scenario is using Azure unmanaged disks, you may opt for LRS. While it's possible to create a storage account for Azure unmanaged disks that uses GRS, it isn't recommended due to potential issues with consistency over asynchronous geo-replication.

+With ZRS, your data is still accessible for both read and write operations even if a zone becomes unavailable. If a zone becomes unavailable, Azure undertakes networking updates, such as DNS repointing. These updates may affect your application if you access data before the updates have completed. When designing applications for ZRS, follow practices for transient fault handling, including implementing retry policies with exponential back-off.

+ZRS provides excellent performance, low latency, and resiliency for your data if it becomes temporarily unavailable. However, ZRS by itself may not protect your data against a regional disaster where multiple zones are permanently affected. For protection against regional disasters, Microsoft recommends using [geo-zone-redundant storage](#geo-zone-redundant-storage) (GZRS), which uses ZRS in the primary region and also geo-replicates your data to a secondary region.

+- Azure Blob storage (hot and cool block blobs and append blobs, non-disk page blobs)

+For applications requiring high durability, you can choose to additionally copy the data in your storage account to a secondary region that is hundreds of miles away from the primary region. If your storage account is copied to a secondary region, then your data is durable even in the case of a complete regional outage or a disaster in which the primary region isn't recoverable.

+If the primary region becomes unavailable, you can choose to fail over to the secondary region. After the failover has completed, the secondary region becomes the primary region, and you can again read and write data. For more information on disaster recovery and to learn how to fail over to the secondary region, see [Disaster recovery and storage account failover](storage-disaster-recovery-guidance.md).

+Geo-zone-redundant storage (GZRS) combines the high availability provided by redundancy across availability zones with protection from regional outages provided by geo-replication. Data in a GZRS storage account is copied across three [Azure availability zones](../../availability-zones/az-overview.md) in the primary region and is also replicated to a secondary geographic region for protection from regional disasters. Microsoft recommends using GZRS for applications requiring maximum consistency, durability, and availability, excellent performance, and resilience for disaster recovery.

+With a GZRS storage account, you can continue to read and write data if an availability zone becomes unavailable or is unrecoverable. Additionally, your data is also durable in the case of a complete regional outage or a disaster in which the primary region isn't recoverable. GZRS is designed to provide at least 99.99999999999999% (16 9's) durability of objects over a given year.

+Only standard general-purpose v2 storage accounts support GZRS. GZRS is supported by all of the Azure Storage services, including:

+- Azure Blob storage (hot and cool block blobs, non-disk page blobs)

+Geo-redundant storage (with GRS or GZRS) replicates your data to another physical location in the secondary region to protect against regional outages. With an account configured for GRS or GZRS, data in the secondary region is not directly accessible to users or applications, unless a failover occurs. The failover process updates the DNS entry provided by Azure Storage so that the secondary endpoint becomes the new primary endpoint for your storage account. During the failover process, your data is inaccessible. After the failover is complete, you can read and write data to the new primary region. For more information, see [How customer-managed storage account failover works](storage-failover-customer-managed-unplanned.md).

+The secondary region is available for read access after you enable RA-GRS or RA-GZRS, so that you can test your application in advance to make sure that it will properly read from the secondary in the event of an outage. For more information about how to design your applications to take advantage of geo-redundancy, see [Use geo-redundancy to design highly available applications](geo-redundant-design.md).

+When read access to the secondary is enabled, your application can be read from the secondary endpoint as well as from the primary endpoint. The secondary endpoint appends the suffix *-secondary* to the account name. For example, if your primary endpoint for Blob storage is `myaccount.blob.core.windows.net`, then the secondary endpoint is `myaccount-secondary.blob.core.windows.net`. The account access keys for your storage account are the same for both the primary and secondary endpoints.

+Because data is replicated asynchronously from the primary to the secondary region, the secondary region is typically behind the primary region in terms of write operations. If a disaster were to strike the primary region, it's likely that some data would be lost and that files within a directory or container would not be consistent. For more information about how to plan for potential data loss, see [Data loss and inconsistencies](storage-disaster-recovery-guidance.md#anticipate-data-loss-and-inconsistencies).

+| Percent durability of objects over a given year | at least 99.999999999% (11 9's) | at least 99.9999999999% (12 9's) | at least 99.99999999999999% (16 9's) | at least 99.99999999999999% (16 9's) |

+| An entire data center (zonal or non-zonal) becomes unavailable | No | Yes | Yes<sup>1</sup> | Yes |

+The following table shows which redundancy options are supported by each Azure Storage service.

+Block blob storage accounts support locally redundant storage (LRS) and zone redundant storage (ZRS) in certain regions.

+$Env:AZCOPY_AUTO_LOGIN_TYPE="PSCRED"

+> Keep in mind that converting a locally redundant storage account to use geo-redundancy incurs both cost and time. For more information, see [Important implications of account failover](../common/storage-initiate-account-failover.md#important-implications-of-account-failover).

+Remember to sync your identities in order for the set permissions to take effect. You can set ACLs for not-synced identities, but these ACLs won't be enforced because the not-synced identities won't be present in the Kerberos ticket used for authentication/authorization.

+The targets listed here might be affected by other variables in your deployment. For example, the performance of I/O for a file might be impacted by your SMB client's behavior and by your available network bandwidth. You should test your usage pattern to determine whether the scalability and performance of Azure Files meet your requirements.

+<sup>3 Azure Files supports 10,000 open handles on the root directory and 2,000 open handles per file and directory within the share. The number of active users supported per share is dependent on the applications that are accessing the share. If you're using Azure Files to store disk images for large-scale virtual desktop workloads, you might run out of handles for the root directory or per file/directory. In this case, you might need to use two Azure file shares. If your applications aren't opening a handle on the root directory, Azure Files can support more than 10,000 active users per share.</sup>

+ > [!NOTE]

+ > A maximum of 50 triggers is supported currently.

+- You need to use version 4.2.1 of the *Az.DesktopVirtualization* PowerShell module, which contains the cmdlets that support app attach. You can download and install the Az.DesktopVirtualization PowerShell module from the [PowerShell Gallery](https://www.powershellgallery.com/packages/Az.DesktopVirtualization/).