+| [Self-Service password reset](add-password-reset-policy.md) | GA| GA| Available in China cloud, but only for custom policies.

+| [Force password reset](force-password-reset.md) | GA | GA | Available in China cloud, but only for custom policies. |

+| [Phone sign-up and sign-in](phone-authentication-user-flows.md) | GA | GA | Available in China cloud, but only for custom policies. |

+| [Conditional Access and Identity Protection](conditional-access-user-flow.md) | GA | GA | Not available for SAML applications. Limited CA features are available in China cloud. Identity Protection is not available in China cloud. |

+| [Multi-language support](localization.md)| GA | GA | Available in China cloud, but only for custom policies. |

+| [Custom domains](custom-domain.md)| GA | GA | Available in China cloud, but only for custom policies. |

+| [Page layout version](page-layout.md) | GA | GA | Available in China cloud, but only for custom policies. |

+| [JavaScript](javascript-and-page-layout.md) | GA | GA | Available in China cloud, but only for custom policies. |

+| [Password complexity](password-complexity.md) | GA | GA | Available in China cloud, but only for custom policies. |

+|[Apple](identity-provider-apple-id.md) | GA | GA | Available in China cloud, but only for custom policies. |

+|[WeChat](identity-provider-wechat.md) | Preview | GA | Available in China cloud, but only for custom policies. |

+| [Default SSO session provider](custom-policy-reference-sso.md#defaultssosessionprovider) | GA | Available in China cloud, but only for custom policies. |

+| [External login session provider](custom-policy-reference-sso.md#externalloginssosessionprovider) | GA | Available in China cloud, but only for custom policies. |

+| [SAML SSO session provider](custom-policy-reference-sso.md#samlssosessionprovider) | GA | Available in China cloud, but only for custom policies. |

+| [OAuth SSO Session Provider](custom-policy-reference-sso.md#oauthssosessionprovider) | GA| Available in China cloud, but only for custom policies. |

+| [Phone factor authentication](phone-factor-technical-profile.md) | GA | Available in China cloud, but only for custom policies. |

+|Subscription Owner<br>Subscription Contributor|View reviews for a workload, triage recommendations linked to those reviews, manage the recommendation lifecycle.|

+|Advisor Recommendations Contributor (Assessments and Reviews)|View accepted recommendations, and manage the recommendation lifecycle.|

+>

+> For information on configuring Azure AI Studio, see the [Azure AI Studio documentation](../ai-studio/how-to/configure-private-link.md).

+| F0 | 50 |

+| S0 | 50 |

+In the simple case without the _reasoning_ feature, the Groundedness detection API classifies the ungroundedness of the submitted content as `true` or `false`.

+To test a summarization task instead of a question answering (QnA) task, use the following sample JSON body:

+```json

+{

+ "domain": "Medical",

+ "task": "Summarization",

+ "text": "Ms Johnson has been in the hospital after experiencing a stroke.",

+ "groundingSources": ["Our patient, Ms. Johnson, presented with persistent fatigue, unexplained weight loss, and frequent night sweats. After a series of tests, she was diagnosed with HodgkinΓÇÖs lymphoma, a type of cancer that affects the lymphatic system. The diagnosis was confirmed through a lymph node biopsy revealing the presence of Reed-Sternberg cells, a characteristic of this disease. She was further staged using PET-CT scans. Her treatment plan includes chemotherapy and possibly radiation therapy, depending on her response to treatment. The medical team remains optimistic about her prognosis given the high cure rate of HodgkinΓÇÖs lymphoma."],

+ "reasoning": false

+}

+```

+| **reasoning** | (Optional) Specifies whether to use the reasoning feature. The default value is `false`. If `true`, you need to bring your own Azure OpenAI GPT-4 Turbo resources to provide an explanation. Be careful: using reasoning increases the processing time.| Boolean |

+| -**`text`** | The specific text that is ungrounded. | String |

+> [!TIP]

+> At the moment, we only support **Azure OpenAI GPT-4 Turbo** resources and do not support other GPT types. Your GPT-4 Turbo resources can be deployed in any region; however, we recommend that they be located in the same region as the content safety resources to minimize potential latency.

+In order to use your Azure OpenAI GPT4-Turbo resource to enable the reasoning feature, use Managed Identity to allow your Content Safety resource to access the Azure OpenAI resource:

+In your request to the Groundedness detection API, set the `"reasoning"` body parameter to `true`, and provide the other needed parameters:

+| **llmResource** | (Required) If you want to use your own Azure OpenAI GPT4-Turbo resource to enable reasoning, add this field and include the subfields for the resources used. | String |

+| - `resourceType `| Specifies the type of resource being used. Currently it only allows `AzureOpenAI`. We only support Azure OpenAI GPT-4 Turbo resources and do not support other GPT types. Your GPT-4 Turbo resources can be deployed in any region; however, we recommend that they be located in the same region as the content safety resources to minimize potential latency. | Enum|

+| -**`text`** | The specific text that is ungrounded. | String |

+| -**`reason`** | Offers explanations for detected ungroundedness. | String |

+* [Language detection overview](overview.md)

+You can use NER resolutions to implement actions or retrieve further information. For example, your service can extract datetime entities to extract dates and times that will be provided to a meeting scheduling system.

+> [!IMPORTANT]

+> Starting from version 2023-04-15-preview, the entity resolution feature is replaced by [entity metadata](entity-metadata.md)

+Use this article to get an overview of the new API changes starting from `2023-04-15-preview` version. This API change mainly introduces two new concepts (`entity types` and `entity tags`) replacing the `category` and `subcategory` fields in the current Generally Available API. A detailed overview of each API parameter and the supported API versions it corresponds to can be found on the [Skill Parameters][../how-to/skill-parameters.md] page

+The changes introduce better flexibility for the named entity recognition service, including:

+Updates to the structure of input formats:

+ΓÇó InclusionList

+ΓÇó ExclusionList

+ΓÇó Overlap policy

+Updates to the handling of output formats:

+* More granular entity recognition outputs through introducing the tags list where an entity could be tagged by more than one entity tag.

+| PhoneNumber | PhoneNumber |

+| Temperature | Numeric, Dimension, Temperature |

+| Speed | Numeric, Dimension, Speed |

+| Weight | Numeric, Dimension, Weight |

+| Height | Numeric, Dimension, Height |

+| Length | Numeric, Dimension, Length |

+| Volume | Numeric, Dimension, Volume |

+| Area | Numeric, Dimension, Area |

+| Information | Numeric, Dimension, Information |

+| ComputingProduct | Product, ComputingProduct |

+ Title: Named entity recognition skill parameters

+description: Learn about skill parameters for named entity recognition.

+#

+# Learn about named entity recognition skill parameters

+Use this article to get an overview of the different API parameters used to adjust the input to a NER API call.

+## InclusionList parameter

+The ΓÇ£inclusionListΓÇ¥ parameter allows for you to specify which of the NER entity tags, listed here [link to Preview API table], you would like included in the entity list output in your inference JSON listing out all words and categorizations recognized by the NER service. By default, all recognized entities will be listed.

+## ExclusionList parameter

+The ΓÇ£exclusionListΓÇ¥ parameter allows for you to specify which of the NER entity tags, listed here [link to Preview API table], you would like excluded in the entity list output in your inference JSON listing out all words and categorizations recognized by the NER service. By default, all recognized entities will be listed.

+## Example

+To do: work with Bidisha & Mikael to update with a good example

+## overlapPolicy parameter

+The ΓÇ£overlapPolicyΓÇ¥ parameter allows for you to specify how you like the NER service to respond to recognized words/phrases that fall into more than one category.

+By default, the overlapPolicy parameter will be set to ΓÇ£matchLongestΓÇ¥. This option will categorize the extracted word/phrase under the entity category that can encompass the longest span of the extracted word/phrase (longest defined by the most number of characters included).

+The alternative option for this parameter is ΓÇ£allowOverlapΓÇ¥, where all possible entity categories will be listed.

+Parameters by supported API version

+|Parameter |API versions which support |

+||--|

+|inclusionList |2023-04-15-preview, 2023-11-15-preview|

+|exclusionList |2023-04-15-preview, 2023-11-15-preview|

+|Overlap policy |2023-04-15-preview, 2023-11-15-preview|

+|[Entity resolution](link to archived Entity Resolution page)|2022-10-01-preview |

+## Next steps

+* See [Configure containers](../../concepts/configure-containers.md) for configuration settings.

+Named Entity Recognition (NER) is one of the features offered by [Azure AI Language](../overview.md), a collection of machine learning and AI algorithms in the cloud for developing intelligent applications that involve written language. The NER feature can identify and categorize entities in unstructured text. For example: people, places, organizations, and quantities. The prebuilt NER feature has a pre-set list of [recognized entities](concepts/named-entity-categories.md). The custom NER feature allows you to train the model to recognize specialized entities specific to your use case.

+> [!NOTE]

+> [Entity Resolution](concepts/entity-resolutions.md) was upgraded to the [Entity Metadata](concepts/entity-metadata.md) starting in API version 2023-04-15-preview. If you are calling the preview version of the API equal or newer than 2023-04-15-preview, please check out the [Entity Metadata](concepts/entity-metadata.md) article to use the resolution feature.

+* An Azure Language Service resource and custom question answering project. If you donΓÇÖt have one already, then [create one](../quickstart/sdk.md).

+* [Using Azure OpenAI on your data](../../../openai/concepts/use-your-data.md)

+> [!NOTE]

+> [Azure Open AI On Your Data](../../openai/concepts/use-your-data.md) utilizes large language models (LLMs) to produce similar results to Custom Question Answering. If you wish to connect an existing Custom Question Answering project to Azure Open AI On Your Data, please check out our [guide]( how-to/azure-openai-integration.md).

+> [!NOTE]

+> [Azure Open AI On Your Data](../../../openai/concepts/use-your-data.md) utilizes large language models (LLMs) to produce similar results to Custom Question Answering. If you wish to connect an existing Custom Question Answering project to Azure Open AI On Your Data, please check out our [guide](../how-to/azure-openai-integration.md).

+ Title: Azure OpenAI Service getting started with customizing a large language model (LLM)

+description: Learn more about the concepts behind customizing an LLM with Azure OpenAI.

+recommendations: false

+# Getting started with customizing a large language model (LLM)

+There are several techniques for adapting a pre-trained language model to suit a specific task or domain. These include prompt engineering, RAG (Retrieval Augmented Generation), and fine-tuning. These three techniques are not mutually exclusive but are complementary methods that in combination can be applicable to a specific use case. In this article, we'll explore these techniques, illustrative use cases, things to consider, and provide links to resources to learn more and get started with each.

+## Prompt engineering

+### Definition

+[Prompt engineering](./prompt-engineering.md) is a technique that is both art and science, which involves designing prompts for generative AI models. This process utilizes in-context learning ([zero shot and few shot](./prompt-engineering.md#examples)) and, with iteration, improves accuracy and relevancy in responses, optimizing the performance of the model.

+### Illustrative use cases

+A Marketing Manager at an environmentally conscious company can use prompt engineering to help guide the model to generate descriptions that are more aligned with their brandΓÇÖs tone and style. For instance, they can add a prompt like "Write a product description for a new line of eco-friendly cleaning products that emphasizes quality, effectiveness, and highlights the use of environmentally friendly ingredients" to the input. This will help the model generate descriptions that are aligned with their brandΓÇÖs values and messaging.

+### Things to consider

+- **Prompt engineering** is the starting point for generating desired output from generative AI models.

+- **Craft clear instructions**: Instructions are commonly used in prompts and guide the model's behavior. Be specific and leave as little room for interpretation as possible. Use analogies and descriptive language to help the model understand your desired outcome.

+- **Experiment and iterate**: Prompt engineering is an art that requires experimentation and iteration. Practice and gain experience in crafting prompts for different tasks. Every model might behave differently, so it's important to adapt prompt engineering techniques accordingly.

+### Getting started

+- [Introduction to prompt engineering](./prompt-engineering.md)

+- [Prompt engineering techniques](./advanced-prompt-engineering.md)

+- [15 tips to become a better prompt engineer for generative AI](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/15-tips-to-become-a-better-prompt-engineer-for-generative-ai/ba-p/3882935)

+- [The basics of prompt engineering (video)](https://www.youtube.com/watch?v=e7w6QV1NX1c)

+## RAG (Retrieval Augmented Generation)

+### Definition

+[RAG (Retrieval Augmented Generation)](../../../ai-studio/concepts/retrieval-augmented-generation.md) is a method that integrates external data into a Large Language Model prompt to generate relevant responses. This approach is particularly beneficial when using a large corpus of unstructured text based on different topics. It allows for answers to be grounded in the organizationΓÇÖs knowledge base (KB), providing a more tailored and accurate response.

+RAG is also advantageous when answering questions based on an organizationΓÇÖs private data or when the public data that the model was trained on might have become outdated. This helps ensure that the responses are always up-to-date and relevant, regardless of the changes in the data landscape.

+### Illustrative use case

+A corporate HR department is looking to provide an intelligent assistant that answers specific employee health insurance related questions such as "are eyeglasses covered?" RAG is used to ingest the extensive and numerous documents associated with insurance plan policies to enable the answering of these specific types of questions.

+### Things to consider

+- RAG helps ground AI output in real-world data and reduces the likelihood of fabrication.

+- RAG is helpful when there is a need to answer questions based on private proprietary data.

+- RAG is helpful when you might want questions answered that are recent (for example, before the cutoff date of when the [model version](./models.md) was last trained).

+### Getting started

+- [Retrieval Augmented Generation in Azure AI Studio - Azure AI Studio | Microsoft Learn](../../../ai-studio/concepts/retrieval-augmented-generation.md)

+- [Retrieval Augmented Generation (RAG) in Azure AI Search](../../../search/retrieval-augmented-generation-overview.md)

+- [Retrieval Augmented Generation using Azure Machine Learning prompt flow (preview)](../../../machine-learning/concept-retrieval-augmented-generation.md)

+## Fine-tuning

+### Definition

+[Fine-tuning](../how-to/fine-tuning.md), specifically [supervised fine-tuning](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/fine-tuning-now-available-with-azure-openai-service/ba-p/3954693?lightbox-message-images-3954693=516596iC5D02C785903595A) in this context, is an iterative process that adapts an existing large language model to a provided training set in order to improve performance, teach the model new skills, or reduce latency. This approach is used when the model needs to learn and generalize over specific topics, particularly when these topics are generally small in scope.

+Fine-tuning requires the use of high-quality training data, in a [special example based format](../how-to/fine-tuning.md#example-file-format), to create the new fine-tuned Large Language Model. By focusing on specific topics, fine-tuning allows the model to provide more accurate and relevant responses within those areas of focus.

+### Illustrative use case

+An IT department has been using GPT-4 to convert natural language queries to SQL, but they have found that the responses are not always reliably grounded in their schema, and the cost is prohibitively high.

+They fine-tune GPT-3.5-Turbo with hundreds of requests and correct responses and produce a model that performs better than the base model with lower costs and latency.

+### Things to consider

+- Fine-tuning is an advanced capability; it enhances LLM with after-cutoff-date knowledge and/or domain specific knowledge. Start by evaluating the baseline performance of a standard model against their requirements before considering this option.

+- Having a baseline for performance without fine-tuning is essential for knowing whether fine-tuning has improved model performance. Fine-tuning with bad data makes the base model worse, but without a baseline, it's hard to detect regressions.

+- Good cases for fine-tuning include steering the model to output content in a specific and customized style, tone, or format, or tasks where the information needed to steer the model is too long or complex to fit into the prompt window.

+- Fine-tuning costs:

+ - Fine-tuning can reduce costs across two dimensions: (1) by using fewer tokens depending on the task (2) by using a smaller model (for example GPT 3.5 Turbo can potentially be fine-tuned to achieve the same quality of GPT-4 on a particular task).

+ - Fine-tuning has upfront costs for training the model. And additional hourly costs for hosting the custom model once it's deployed.

+### Getting started

+- [When to use Azure OpenAI fine-tuning](./fine-tuning-considerations.md)

+- [Customize a model with fine-tuning](../how-to/fine-tuning.md)

+- [Azure OpenAI GPT 3.5 Turbo fine-tuning tutorial](../tutorials/fine-tune.md)

+- [To fine-tune or not to fine-tune? (Video)](https://www.youtube.com/watch?v=0Jo-z-MFxJs)

+> Version `0613` of `gpt-35-turbo` and `gpt-35-turbo-16k` will be retired no earlier than July 13, 2024. Version `0301` of `gpt-35-turbo` will be retired no earlier than June 13, 2024. See [model updates](../how-to/working-with-models.md#model-updates) for model upgrade behavior.

+#### Azure Government regions

+The following GPT-3.5 turbo models are available with [Azure Government](/azure/azure-government/documentation-government-welcome):

+|Model ID | Model Availability |

+|--|--|

+| `gpt-35-turbo` (1106-Preview) | US Gov Virginia |

+--model-name gpt-4 \

+You need to connect to a data source to upload your data. When you want to use your data to chat with an Azure OpenAI model, your data is chunked in a search index so that relevant data can be found based on user queries.

+The [Integrated Vector Database in vCore-based Azure Cosmos DB for MongoDB](/azure/cosmos-db/mongodb/vcore/vector-search) natively supports integration with Azure OpenAI On Your Data.

+For some data sources such as uploading files from your local machine (preview) or data contained in a blob storage account (preview), Azure AI Search is used. When you choose the following data sources, your data is ingested into an Azure AI Search index.

+>[!TIP]

+>If you use Azure Cosmos DB (except for its vCore-based API for MongoDB), you may be eligible for the [Azure AI Advantage offer](/azure/cosmos-db/ai-advantage), which provides the equivalent of up to $6,000 in Azure Cosmos DB throughput credits.

+| [Azure Cosmos DB](/azure/cosmos-db/introduction) | Azure Cosmos DB's API for Postgres and vCore-based API for MongoDB have natively integrated vector indexing and do not require Azure AI Search; however, its other APIs do require Azure AI Search for vector indexing. Azure Cosmos DB for NoSQL will offer a natively integrated vector database by mid-2024. |

+# [Vector Database in Azure Cosmos DB for MongoDB](#tab/mongo-db)

+* [vCore-based Azure Cosmos DB for MongoDB](/azure/cosmos-db/mongodb/vcore/introduction) account

+* Only vCore-based Azure Cosmos DB for MongoDB is supported.

+* The search type is limited to [Integrated Vector Database in Azure Cosmos DB for MongoDB](/azure/cosmos-db/mongodb/vcore/vector-search) with an Azure OpenAI embedding model.

+To add vCore-based Azure Cosmos DB for MongoDB as a data source, you will need an existing Azure Cosmos DB for MongoDB index containing your data, and a deployed Azure OpenAI Ada embeddings model that will be used for vector search.

+1. In the [Azure OpenAI portal](https://oai.azure.com/portal) chat playground, select **Add your data**. In the panel that appears, select ** vCore-based Azure Cosmos DB for MongoDB** as the data source.

+When you add your vCore-based Azure Cosmos DB for MongoDB data source, you can specify data fields to properly map your data for retrieval.

+### Uncited references

+It's possible for the model to return `"TYPE":"UNCITED_REFERENCE"` instead of `"TYPE":CONTENT` in the API for documents that are retrieved from the data source, but not included in the citation. This can be useful for debugging, and you can control this behavior by modifying the **strictness** and **retrieved documents** runtime parameters described above.

+To troubleshoot failed operations, always look out for errors or warnings specified either in the API response or Azure OpenAI studio. Here are some of the common errors and warnings:

+### Failed ingestion jobs

+### 503 errors when sending queries with Azure AI Search

+Each user message can translate to multiple search queries, all of which get sent to the search resource in parallel. This can produce throttling behavior when the amount of search replicas and partitions is low. The maximum number of queries per second that a single partition and single replica can support may not be sufficient. In this case, consider increasing your replicas and partitions, or adding sleep/retry logic in your application. See the [Azure AI Search documentation](../../../search/performance-benchmarks.md) for more information.

+ Title: How to work with the Chat Markup Language (preview)

+description: Learn how to work with Chat Markup Language (preview)

+keywords: ChatGPT

+# Chat Markup Language ChatML (Preview)

+> [!IMPORTANT]

+> Using GPT-3.5-Turbo models with the completion endpoint as described in this article remains in preview and is only possible with `gpt-35-turbo` version (0301) which is [slated for retirement as early as June 13th, 2024](../concepts/model-retirements.md#current-models). We strongly recommend using the [GA Chat Completion API/endpoint](./chatgpt.md). The Chat Completion API is the recommended method of interacting with the GPT-3.5-Turbo models. The Chat Completion API is also the only way to access the GPT-4 models.

+The following code snippet shows the most basic way to use the GPT-3.5-Turbo models with ChatML. If this is your first time using these models programmatically we recommend starting with our [GPT-35-Turbo & GPT-4 Quickstart](../chatgpt-quickstart.md).

+> [!NOTE]

+> In the Azure OpenAI documentation we refer to GPT-3.5-Turbo, and GPT-35-Turbo interchangeably. The official name of the model on OpenAI is `gpt-3.5-turbo`, but for Azure OpenAI due to Azure specific character constraints the underlying model name is `gpt-35-turbo`.

+```python

+import os

+import openai

+openai.api_type = "azure"

+openai.api_base = "https://{your-resource-name}.openai.azure.com/"

+openai.api_version = "2024-02-01"

+openai.api_key = os.getenv("OPENAI_API_KEY")

+response = openai.Completion.create(

+ engine="gpt-35-turbo", # The deployment name you chose when you deployed the GPT-35-Turbo model

+ prompt="<|im_start|>system\nAssistant is a large language model trained by OpenAI.\n<|im_end|>\n<|im_start|>user\nWho were the founders of Microsoft?\n<|im_end|>\n<|im_start|>assistant\n",

+ temperature=0,

+ max_tokens=500,

+ top_p=0.5,

+ stop=["<|im_end|>"])

+print(response['choices'][0]['text'])

+```

+> [!NOTE]

+> The following parameters aren't available with the gpt-35-turbo model: `logprobs`, `best_of`, and `echo`. If you set any of these parameters, you'll get an error.

+The `<|im_end|>` token indicates the end of a message. When using ChatML it is recommended to include `<|im_end|>` token as a stop sequence to ensure that the model stops generating text when it reaches the end of the message.

+Consider setting `max_tokens` to a slightly higher value than normal such as 300 or 500. This ensures that the model doesn't stop generating text before it reaches the end of the message.

+## Model versioning

+> [!NOTE]

+> `gpt-35-turbo` is equivalent to the `gpt-3.5-turbo` model from OpenAI.

+Unlike previous GPT-3 and GPT-3.5 models, the `gpt-35-turbo` model as well as the `gpt-4` and `gpt-4-32k` models will continue to be updated. When creating a [deployment](../how-to/create-resource.md#deploy-a-model) of these models, you'll also need to specify a model version.

+You can find the model retirement dates for these models on our [models](../concepts/models.md) page.

+## Working with Chat Markup Language (ChatML)

+> [!NOTE]

+> OpenAI continues to improve the GPT-35-Turbo and the Chat Markup Language used with the models will continue to evolve in the future. We'll keep this document updated with the latest information.

+OpenAI trained GPT-35-Turbo on special tokens that delineate the different parts of the prompt. The prompt starts with a system message that is used to prime the model followed by a series of messages between the user and the assistant.

+The format of a basic ChatML prompt is as follows:

+```

+<|im_start|>system

+Provide some context and/or instructions to the model.

+<|im_end|>

+<|im_start|>user

+The userΓÇÖs message goes here

+<|im_end|>

+<|im_start|>assistant

+```

+### System message

+The system message is included at the beginning of the prompt between the `<|im_start|>system` and `<|im_end|>` tokens. This message provides the initial instructions to the model. You can provide various information in the system message including:

+* A brief description of the assistant

+* Personality traits of the assistant

+* Instructions or rules you would like the assistant to follow

+* Data or information needed for the model, such as relevant questions from an FAQ

+You can customize the system message for your use case or just include a basic system message. The system message is optional, but it's recommended to at least include a basic one to get the best results.

+### Messages

+After the system message, you can include a series of messages between the **user** and the **assistant**. Each message should begin with the `<|im_start|>` token followed by the role (`user` or `assistant`) and end with the `<|im_end|>` token.

+```

+<|im_start|>user

+What is thermodynamics?

+<|im_end|>

+```

+To trigger a response from the model, the prompt should end with `<|im_start|>assistant` token indicating that it's the assistant's turn to respond. You can also include messages between the user and the assistant in the prompt as a way to do few shot learning.

+### Prompt examples

+The following section shows examples of different styles of prompts that you could use with the GPT-35-Turbo and GPT-4 models. These examples are just a starting point, and you can experiment with different prompts to customize the behavior for your own use cases.

+#### Basic example

+If you want the GPT-35-Turbo and GPT-4 models to behave similarly to [chat.openai.com](https://chat.openai.com/), you can use a basic system message like "Assistant is a large language model trained by OpenAI."

+```

+<|im_start|>system

+Assistant is a large language model trained by OpenAI.

+<|im_end|>

+<|im_start|>user

+Who were the founders of Microsoft?

+<|im_end|>

+<|im_start|>assistant

+```

+#### Example with instructions

+For some scenarios, you might want to give additional instructions to the model to define guardrails for what the model is able to do.

+```

+<|im_start|>system

+Assistant is an intelligent chatbot designed to help users answer their tax related questions.

+Instructions:

+- Only answer questions related to taxes.

+- If you're unsure of an answer, you can say "I don't know" or "I'm not sure" and recommend users go to the IRS website for more information.

+<|im_end|>

+<|im_start|>user

+When are my taxes due?

+<|im_end|>

+<|im_start|>assistant

+```

+#### Using data for grounding

+You can also include relevant data or information in the system message to give the model extra context for the conversation. If you only need to include a small amount of information, you can hard code it in the system message. If you have a large amount of data that the model should be aware of, you can use [embeddings](../tutorials/embeddings.md?tabs=command-line) or a product like [Azure AI Search](https://techcommunity.microsoft.com/t5/ai-applied-ai-blog/revolutionize-your-enterprise-data-with-chatgpt-next-gen-apps-w/ba-p/3762087) to retrieve the most relevant information at query time.

+```

+<|im_start|>system

+Assistant is an intelligent chatbot designed to help users answer technical questions about Azure OpenAI Serivce. Only answer questions using the context below and if you're not sure of an answer, you can say "I don't know".

+Context:

+- Azure OpenAI Service provides REST API access to OpenAI's powerful language models including the GPT-3, Codex and Embeddings model series.

+- Azure OpenAI Service gives customers advanced language AI with OpenAI GPT-3, Codex, and DALL-E models with the security and enterprise promise of Azure. Azure OpenAI co-develops the APIs with OpenAI, ensuring compatibility and a smooth transition from one to the other.

+- At Microsoft, we're committed to the advancement of AI driven by principles that put people first. Microsoft has made significant investments to help guard against abuse and unintended harm, which includes requiring applicants to show well-defined use cases, incorporating MicrosoftΓÇÖs principles for responsible AI use

+<|im_end|>

+<|im_start|>user

+What is Azure OpenAI Service?

+<|im_end|>

+<|im_start|>assistant

+```

+#### Few shot learning with ChatML

+You can also give few shot examples to the model. The approach for few shot learning has changed slightly because of the new prompt format. You can now include a series of messages between the user and the assistant in the prompt as few shot examples. These examples can be used to seed answers to common questions to prime the model or teach particular behaviors to the model.

+This is only one example of how you can use few shot learning with GPT-35-Turbo. You can experiment with different approaches to see what works best for your use case.

+```

+<|im_start|>system

+Assistant is an intelligent chatbot designed to help users answer their tax related questions.

+<|im_end|>

+<|im_start|>user

+When do I need to file my taxes by?

+<|im_end|>

+<|im_start|>assistant

+In 2023, you will need to file your taxes by April 18th. The date falls after the usual April 15th deadline because April 15th falls on a Saturday in 2023. For more details, see https://www.irs.gov/filing/individuals/when-to-file

+<|im_end|>

+<|im_start|>user

+How can I check the status of my tax refund?

+<|im_end|>

+<|im_start|>assistant

+You can check the status of your tax refund by visiting https://www.irs.gov/refunds

+<|im_end|>

+```

+#### Using Chat Markup Language for non-chat scenarios

+ChatML is designed to make multi-turn conversations easier to manage, but it also works well for non-chat scenarios.

+For example, for an entity extraction scenario, you might use the following prompt:

+```

+<|im_start|>system

+You are an assistant designed to extract entities from text. Users will paste in a string of text and you will respond with entities you've extracted from the text as a JSON object. Here's an example of your output format:

+{

+ "name": "",

+ "company": "",

+ "phone_number": ""

+}

+<|im_end|>

+<|im_start|>user

+Hello. My name is Robert Smith. IΓÇÖm calling from Contoso Insurance, Delaware. My colleague mentioned that you are interested in learning about our comprehensive benefits policy. Could you give me a call back at (555) 346-9322 when you get a chance so we can go over the benefits?

+<|im_end|>

+<|im_start|>assistant

+```

+## Preventing unsafe user inputs

+It's important to add mitigations into your application to ensure safe use of the Chat Markup Language.

+We recommend that you prevent end-users from being able to include special tokens in their input such as `<|im_start|>` and `<|im_end|>`. We also recommend that you include additional validation to ensure the prompts you're sending to the model are well formed and follow the Chat Markup Language format as described in this document.

+You can also provide instructions in the system message to guide the model on how to respond to certain types of user inputs. For example, you can instruct the model to only reply to messages about a certain subject. You can also reinforce this behavior with few shot examples.

+## Managing conversations

+The token limit for `gpt-35-turbo` is 4096 tokens. This limit includes the token count from both the prompt and completion. The number of tokens in the prompt combined with the value of the `max_tokens` parameter must stay under 4096 or you'll receive an error.

+ItΓÇÖs your responsibility to ensure the prompt and completion falls within the token limit. This means that for longer conversations, you need to keep track of the token count and only send the model a prompt that falls within the token limit.

+The following code sample shows a simple example of how you could keep track of the separate messages in the conversation.

+```python

+import os

+import openai

+openai.api_type = "azure"

+openai.api_base = "https://{your-resource-name}.openai.azure.com/" #This corresponds to your Azure OpenAI resource's endpoint value

+openai.api_version = "2024-02-01"

+openai.api_key = os.getenv("OPENAI_API_KEY")

+# defining a function to create the prompt from the system message and the conversation messages

+def create_prompt(system_message, messages):

+ prompt = system_message

+ for message in messages:

+ prompt += f"\n<|im_start|>{message['sender']}\n{message['text']}\n<|im_end|>"

+ prompt += "\n<|im_start|>assistant\n"

+ return prompt

+# defining the user input and the system message

+user_input = "<your user input>"

+system_message = f"<|im_start|>system\n{'<your system message>'}\n<|im_end|>"

+# creating a list of messages to track the conversation

+messages = [{"sender": "user", "text": user_input}]

+response = openai.Completion.create(

+ engine="gpt-35-turbo", # The deployment name you chose when you deployed the GPT-35-Turbo model.

+ prompt=create_prompt(system_message, messages),

+ temperature=0.5,

+ max_tokens=250,

+ top_p=0.9,

+ frequency_penalty=0,

+ presence_penalty=0,

+ stop=['<|im_end|>']

+)

+messages.append({"sender": "assistant", "text": response['choices'][0]['text']})

+print(response['choices'][0]['text'])

+```

+## Staying under the token limit

+The simplest approach to staying under the token limit is to remove the oldest messages in the conversation when you reach the token limit.

+You can choose to always include as many tokens as possible while staying under the limit or you could always include a set number of previous messages assuming those messages stay within the limit. It's important to keep in mind that longer prompts take longer to generate a response and incur a higher cost than shorter prompts.

+You can estimate the number of tokens in a string by using the [tiktoken](https://github.com/openai/tiktoken) Python library as shown below.

+```python

+import tiktoken

+cl100k_base = tiktoken.get_encoding("cl100k_base")

+enc = tiktoken.Encoding(

+ name="gpt-35-turbo",

+ pat_str=cl100k_base._pat_str,

+ mergeable_ranks=cl100k_base._mergeable_ranks,

+ special_tokens={

+ **cl100k_base._special_tokens,

+ "<|im_start|>": 100264,

+ "<|im_end|>": 100265

+ }

+)

+tokens = enc.encode(

+ "<|im_start|>user\nHello<|im_end|><|im_start|>assistant",

+ allowed_special={"<|im_start|>", "<|im_end|>"}

+)

+assert len(tokens) == 7

+assert tokens == [100264, 882, 198, 9906, 100265, 100264, 78191]

+```

+## Next steps

+* [Learn more about Azure OpenAI](../overview.md).

+* Get started with the GPT-35-Turbo model with [the GPT-35-Turbo & GPT-4 quickstart](../chatgpt-quickstart.md).

+* For more examples, check out the [Azure OpenAI Samples GitHub repository](https://aka.ms/AOAICodeSamples)

+# Learn how to work with the GPT-3.5-Turbo and GPT-4 models

+The GPT-3.5-Turbo and GPT-4 models are language models that are optimized for conversational interfaces. The models behave differently than the older GPT-3 models. Previous models were text-in and text-out, meaning they accepted a prompt string and returned a completion to append to the prompt. However, the GPT-3.5-Turbo and GPT-4 models are conversation-in and message-out. The models expect input formatted in a specific chat-like transcript format, and return a completion that represents a model-written message in the chat. While this format was designed specifically for multi-turn conversations, you'll find it can also work well for non-chat scenarios too.

+This article walks you through getting started with the GPT-3.5-Turbo and GPT-4 models. It's important to use the techniques described here to get the best results. If you try to interact with the models the same way you did with the older model series, the models will often be verbose and provide less useful responses.

+| `Generated Completion Tokens` | Usage | Sum | Number of generated tokens (output) from an Azure OpenAI model. Applies to PayGo, PTU, and PTU-manged SKUs | `ApiName`, `ModelDeploymentName`,`ModelName`, `Region`|

+| `Processed FineTuned Training Hours` | Usage |Sum| Number of training hours processed on an Azure OpenAI fine-tuned model. | `ApiName`, `ModelDeploymentName`,`ModelName`, `Region`|

+| `Processed Inference Tokens` | Usage | Sum| Number of inference tokens processed by an Azure OpenAI model. Calculated as prompt tokens (input) + generated tokens. Applies to PayGo, PTU, and PTU-manged SKUs.|`ApiName`, `ModelDeploymentName`,`ModelName`, `Region`|

+| `Processed Prompt Tokens` | Usage | Sum | Total number of prompt tokens (input) processed on an Azure OpenAI model. Applies to PayGo, PTU, and PTU-managed SKUs.|`ApiName`, `ModelDeploymentName`,`ModelName`, `Region`|

+description: Learn how to generate reproducible output (preview) with Azure OpenAI Service.

+By default if you ask an Azure OpenAI Chat Completion model the same question multiple times you're likely to get a different response. The responses are therefore considered to be non-deterministic. Reproducible output is a new preview feature that allows you to selectively change the default behavior to help product more deterministic outputs.

+* `gpt-35-turbo` (1106) - [region availability](../concepts/models.md#gpt-35-turbo-model-availability)

+* `gpt-35-turbo` (0125) - [region availability](../concepts/models.md#gpt-35-turbo-model-availability)

+* `gpt-4` (1106-Preview) - [region availability](../concepts/models.md#gpt-4-and-gpt-4-turbo-preview-model-availability)

+* `gpt-4` (0125-Preview) - [region availability](../concepts/models.md#gpt-4-and-gpt-4-turbo-preview-model-availability)

+Support for reproducible output was first added in API version [`2023-12-01-preview`](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-12-01-preview/inference.json)

+ api_version="2024-02-01"

+ model="gpt-35-turbo-0125", # Model = should match the deployment name you chose for your 0125-preview model deployment

+ max_tokens =50,

+ api_version = '2024-02-01' # may change in the future

+ max_tokens = 50

+Once upon a time, before there was time, there was nothing but a vast emptiness. In this emptiness, there existed a tiny, infinitely dense point of energy. This point contained all the potential for the universe as we know it. And

+Once upon a time, long before the existence of time itself, there was nothing but darkness and silence. The universe lay dormant, a vast expanse of emptiness waiting to be awakened. And then, in a moment that defies comprehension, there

+Once upon a time, before time even existed, there was nothing but darkness and stillness. In this vast emptiness, there was a tiny speck of unimaginable energy and potential. This speck held within it all the elements that would come

+ api_version="2024-02-01"

+ model="gpt-35-turbo-0125", # Model = should match the deployment name you chose for your 0125-preview model deployment

+ max_tokens =50,

+ api_version = '2024-02-01' # may change in the future

+ max_tokens = 50

+In the beginning, there was nothing but darkness and silence. Then, suddenly, a tiny point of light appeared. This point of light contained all the energy and matter that would eventually form the entire universe. With a massive explosion known as the Big Bang

+In the beginning, there was nothing but darkness and silence. Then, suddenly, a tiny point of light appeared. This point of light contained all the energy and matter that would eventually form the entire universe. With a massive explosion known as the Big Bang

+In the beginning, there was nothing but darkness and silence. Then, suddenly, a tiny point of light appeared. This was the moment when the universe was born.

+The point of light began to expand rapidly, creating space and time as it grew.

+By using the same `seed` parameter of 42 for each of our three requests, while keeping all other parameters the same, we're able to produce much more consistent results.

+> [!IMPORTANT]

+> Determinism is not guaranteed with reproducible output. Even in cases where the seed parameter and `system_fingerprint` are the same across API calls it is currently not uncommon to still observe a degree of variability in responses. Identical API calls with larger `max_tokens` values, will generally result in less deterministic responses even when the seed parameter is set.

+Consider either clicking the **watch** or **star** buttons on the web app's [GitHub](https://github.com/microsoft/sample-app-aoai-chatGPT) repo to be notified about changes and updates to the source code.

+## Resource configuration

+> [!TIP]

+> You can use the bash script available on [GitHub](https://github.com/microsoft/sample-app-aoai-chatGPT/blob/main/scripts/validate-oyd-vnet.sh) to validate your setup, and determine if all of the requirements listed here are being met.

+See the [ingestion API reference article](/rest/api/azureopenai/ingestion-jobs?context=/azure/ai-services/openai/context/context) for details on the request and response objects used by the ingestion API.

+The Whisper models can be used to transcribe and translate speech to text.

+You can use a Whisper model in Azure OpenAI Service for speech to text transcription or speech translation. For more information about using a Whisper model, see the [quickstart](./whisper-quickstart.md) and [the Whisper model overview](../speech-service/whisper-overview.md).

+| ```file```| file | Yes | N/A | The audio file object (not file name) to transcribe, in one of these formats: `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav`, or `webm`.<br/><br/>The file size limit for the Whisper model in Azure OpenAI Service is 25 MB. If you need to transcribe a file larger than 25 MB, break it into chunks. Alternatively you can use the Azure AI Speech [batch transcription](../speech-service/batch-transcription-create.md#use-a-whisper-model) API.<br/><br/>You can get sample audio files from the [Azure AI Speech SDK repository at GitHub](https://github.com/Azure-Samples/cognitive-services-speech-sdk/tree/master/sampledata/audiofiles). |

+Azure OpenAI is deployed as a part of the Azure AI services. All Azure AI services rely on the same set of management APIs for creation, update, and delete operations. The management APIs are also used for deploying models within an Azure OpenAI resource.

+If you want to clean up and remove an Azure OpenAI resource, you can delete the resource. Before deleting the resource, you must first delete any deployed models.

+If you created an Azure OpenAI resource solely for completing this tutorial and want to clean up and remove an Azure OpenAI resource, you'll need to delete your deployed models, and then delete the resource or associated resource group if it's dedicated to your test resource. Deleting the resource group also deletes any other resources associated with it.

+If you want to clean up and remove an Azure OpenAI or Azure AI Search resource, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.

+**Content filtering is temporarily off** by default. Azure content moderation works differently than Azure OpenAI. Azure OpenAI runs content filters during the generation call to detect harmful or abusive content and filters them from the response. [Learn MoreΓÇï](./concepts/content-filter.md)

+If you want to clean up and remove an Azure OpenAI resource, you can delete the resource. Before deleting the resource, you must first delete any deployed models.

+> [!NOTE]

+> [Azure Open AI On Your Data](../../openai/concepts/use-your-data.md) utilizes large language models (LLMs) to produce similar results to QnA Maker. If you wish to migrate your QnA Maker project to Azure Open AI On Your Data, please check out our [guide](../How-To/migrate-to-openai.md).

+> [!NOTE]

+> [Azure Open AI On Your Data](../../openai/concepts/use-your-data.md) utilizes large language models (LLMs) to produce similar results to QnA Maker. If you wish to migrate your QnA Maker project to Azure Open AI On Your Data, please check out our [guide](../How-To/migrate-to-openai.md).

+> [!NOTE]

+> [Azure Open AI On Your Data](../../openai/concepts/use-your-data.md) utilizes large language models (LLMs) to produce similar results to QnA Maker. If you wish to migrate your QnA Maker project to Azure Open AI On Your Data, please check out our [guide](../How-To/migrate-to-openai.md).

+> [!NOTE]

+> [Azure Open AI On Your Data](../../openai/concepts/use-your-data.md) utilizes large language models (LLMs) to produce similar results to QnA Maker. If you wish to migrate your QnA Maker project to Azure Open AI On Your Data, please check out our [guide](../How-To/migrate-to-openai.md).

+> [!NOTE]

+> [Azure Open AI On Your Data](../../openai/concepts/use-your-data.md) utilizes large language models (LLMs) to produce similar results to QnA Maker. If you wish to migrate your QnA Maker project to Azure Open AI On Your Data, please check out our [guide](../How-To/migrate-to-openai.md).

+|  [Azure AI Search](../../search/index.yml) | Bring AI-powered cloud search to your mobile and web apps | [Azure AI Search API](/rest/api/searchservice) |

+| </br>&bullet; [fine-tuning](/rest/api/azureopenai/fine-tuning) |

+|  [Bot Service](/composer/) | Create bots and connect them across channels | [Bot Service API](/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0&preserve-view=true) |

+|  [Content Safety](../content-safety/index.yml) | An AI service that detects unwanted contents | [Content Safety API](https://westus.dev.cognitive.microsoft.com/docs/services/content-safety-service-2023-10-15-preview/operations/TextBlocklists_AddOrUpdateBlocklistItems) |

+|  [Custom Vision](../custom-vision-service/index.yml) | Customize image recognition for your business applications. |**Custom Vision APIs**<br>&bullet; [prediction](https://westus2.dev.cognitive.microsoft.com/docs/services/Custom_Vision_Prediction_3.1/operations/5eb37d24548b571998fde5f3)<br>&bullet; [training](https://westus2.dev.cognitive.microsoft.com/docs/services/Custom_Vision_Training_3.3/operations/5eb0bcc6548b571998fddebd)|

+|  [Document Intelligence](../document-intelligence/index.yml) | Turn documents into intelligent data-driven solutions | [Document Intelligence API](/rest/api/aiservices/document-models?view=rest-aiservices-2023-07-31&preserve-view=true) |

+|  |

+|  [Language](../language-service/index.yml) | Build apps with industry-leading natural language understanding capabilities | [REST API](/rest/api/language/) |

+|  |

+| |

+|  [Video Indexer](/azure/azure-video-indexer) | Extract actionable insights from your videos | [Video Indexer API](/rest/api/videoindexer/accounts?view=rest-videoindexer-2024-01-01&preserve-view=true) |

+|  [Vision](../computer-vision/index.yml) | Analyze content in images and videos | [Vision API](https://eastus.dev.cognitive.microsoft.com/docs/services/Cognitive_Services_Unified_Vision_API_2024-02-01/operations/61d65934cd35050c20f73ab6) |

+|  [Anomaly Detector](../Anomaly-Detector/index.yml) <br>(deprecated 2023) | Identify potential problems early on | [Anomaly Detector API](https://westus2.dev.cognitive.microsoft.com/docs/services/AnomalyDetector-v1-1/operations/CreateMultivariateModel) |

+|  |

+|  [Language understanding (LUIS)](../luis/index.yml) <br>(deprecated 2023) | Understand natural language in your apps | [LUIS API](https://westus.dev.cognitive.microsoft.com/docs/services/luis-endpoint-api-v3-0/operations/5cb0a9459a1fe8fa44c28dd8) |

+|  [Metrics Advisor](../metrics-advisor/index.yml) <br>(deprecated 2023) | An AI service that detects unwanted contents | [Metrics Advisor API](https://westus.dev.cognitive.microsoft.com/docs/services/MetricsAdvisor/operations/createDataFeed) |

+|  [Personalizer](../personalizer/index.yml) <br>(deprecated 2023) | Create rich, personalized experiences for each user | [Personalizer API](https://westus2.dev.cognitive.microsoft.com/docs/services/personalizer-api/operations/Rank) |

+|  [QnA maker](../qnamaker/index.yml) <br>(deprecated 2022) | Distill information into easy-to-navigate questions and answers | [QnA Maker API](https://westus.dev.cognitive.microsoft.com/docs/services/5a93fcf85b4ccd136866eb37/operations/5ac266295b4ccd1554da75ff) |

+Whisper models by batch transcription are supported in the Australia East, Central US, East US, North Central US, South Central US, Southeast Asia, and West Europe regions.

+ <version>1.37.0</version>

+ implementation 'com.microsoft.cognitiveservices.speech:client-sdk-embedded:1.37.0@aar'

+- The Whisper model via Azure OpenAI Service is available in the following regions: EastUS 2, India South, North Central, Norway East, Sweden Central, and West Europe.

+- The Whisper model via Azure AI Speech is available in the following regions: Australia East, East US, North Central US, South Central US, Southeast Asia, UK South, and West Europe.

+ Title: Configure containers - Translator

+description: The Translator container runtime environment is configured using the `docker run` command arguments. There are both required and optional settings.

+#

+recommendations: false

+# Configure Translator Docker containers

+Azure AI services provide each container with a common configuration framework. You can easily configure your Translator containers to build Translator application architecture optimized for robust cloud capabilities and edge locality.

+The **Translator** container runtime environment is configured using the `docker run` command arguments. This container has both required and optional settings. The required container-specific settings are the billing settings.

+## Configuration settings

+The container has the following configuration settings:

+|Required|Setting|Purpose|

+|--|--|--|

+|Yes|[ApiKey](#apikey-configuration-setting)|Tracks billing information.|

+|No|[ApplicationInsights](#applicationinsights-setting)|Enables adding [Azure Application Insights](/azure/application-insights) telemetric support to your container.|

+|Yes|[Billing](#billing-configuration-setting)|Specifies the endpoint URI of the service resource on Azure.|

+|Yes|[EULA](#eula-setting)| Indicates that you accepted the end-user license agreement (EULA) for the container.|

+|No|[Fluentd](#fluentd-settings)|Writes log and, optionally, metric data to a Fluentd server.|

+|No|HTTP Proxy|Configures an HTTP proxy for making outbound requests.|

+|No|[Logging](#logging-settings)|Provides ASP.NET Core logging support for your container. |

+|Yes|[Mounts](#mount-settings)|Reads and writes data from the host computer to the container and from the container back to the host computer.|

+ > [!IMPORTANT]

+> The [**ApiKey**](#apikey-configuration-setting), [**Billing**](#billing-configuration-setting), and [**EULA**](#eula-setting) settings are used together, and you must provide valid values for all three of them; otherwise your container won't start. For more information about using these configuration settings to instantiate a container.

+## ApiKey configuration setting

+The `ApiKey` setting specifies the Azure resource key used to track billing information for the container. You must specify a value for the ApiKey and the value must be a valid key for the _Translator_ resource specified for the [`Billing`](#billing-configuration-setting) configuration setting.

+This setting can be found in the following place:

+* Azure portal: **Translator** resource management, under **Keys**

+## ApplicationInsights setting

+## Billing configuration setting

+The `Billing` setting specifies the endpoint URI of the _Translator_ resource on Azure used to meter billing information for the container. You must specify a value for this configuration setting, and the value must be a valid endpoint URI for a _Translator_ resource on Azure. The container reports usage about every 10 to 15 minutes.

+This setting can be found in the following place:

+* Azure portal: **Translator** Overview page labeled `Endpoint`

+| Required | Name | Data type | Description |

+| -- | - | | -- |

+| Yes | `Billing` | String | Billing endpoint URI. For more information on obtaining the billing URI, see [gathering required parameters](translator-how-to-install-container.md#required-input). For more information and a complete list of regional endpoints, see [Custom subdomain names for Azure AI services](../../cognitive-services-custom-subdomains.md). |

+## EULA setting

+## Fluentd settings

+## HTTP/HTTPS proxy credentials settings

+If you need to configure an HTTP proxy for making outbound requests, use these two arguments:

+| Name | Data type | Description |

+|--|--|--|

+|HTTPS_PROXY|string|The proxy to use, for example, `https://proxy:8888`<br>`<proxy-url>`|

+|HTTP_PROXY_CREDS|string|Any credentials needed to authenticate against the proxy, for example, `username:password`. This value **must be in lower-case**. |

+|`<proxy-user>`|string|The user for the proxy.|

+|`<proxy-password>`|string|The password associated with `<proxy-user>` for the proxy.|

+||||

+```bash

+docker run --rm -it -p 5000:5000 \

+--memory 2g --cpus 1 \

+--mount type-bind,src=/home/azureuser/output,target=/output \

+<registry-location>/<image-name> \

+Eula=accept \

+Billing=<endpoint> \

+ApiKey=<api-key> \

+HTTPS_PROXY=<proxy-url> \

+HTTP_PROXY_CREDS=<proxy-user>:<proxy-password> \

+```

+## Logging settings

+Translator containers support the following logging providers:

+|Provider|Purpose|

+|--|--|

+|[Console](/aspnet/core/fundamentals/logging/#console-provider)|The ASP.NET Core `Console` logging provider. All of the ASP.NET Core configuration settings and default values for this logging provider are supported.|

+|[Debug](/aspnet/core/fundamentals/logging/#debug-provider)|The ASP.NET Core `Debug` logging provider. All of the ASP.NET Core configuration settings and default values for this logging provider are supported.|

+|[Disk](#disk-logging)|The JSON logging provider. This logging provider writes log data to the output mount.|

+* The `Logging` settings manage ASP.NET Core logging support for your container. You can use the same configuration settings and values for your container that you use for an ASP.NET Core application.

+* The `Logging.LogLevel` specifies the minimum level to log. The severity of the `LogLevel` ranges from 0 to 6. When a `LogLevel` is specified, logging is enabled for messages at the specified level and higher: Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5, None = 6.

+* Currently, Translator containers have the ability to restrict logs at the **Warning** LogLevel or higher.

+The general command syntax for logging is as follows:

+```bash

+ -Logging:LogLevel:{Provider}={FilterSpecs}

+```

+The following command starts the Docker container with the `LogLevel` set to **Warning** and logging provider set to **Console**. This command prints anomalous or unexpected events during the application flow to the console:

+```bash

+docker run --rm -it -p 5000:5000

+-v /mnt/d/TranslatorContainer:/usr/local/models \

+-e apikey={API_KEY} \

+-e eula=accept \

+-e billing={ENDPOINT_URI} \

+-e Languages=en,fr,es,ar,ru \

+-e Logging:LogLevel:Console="Warning"

+mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest

+```

+### Disk logging

+The `Disk` logging provider supports the following configuration settings:

+| Name | Data type | Description |

+||--|-|

+| `Format` | String | The output format for log files.<br/> **Note:** This value must be set to `json` to enable the logging provider. If this value is specified without also specifying an output mount while instantiating a container, an error occurs. |

+| `MaxFileSize` | Integer | The maximum size, in megabytes (MB), of a log file. When the size of the current log file meets or exceeds this value, the logging provider starts a new log file. If -1 is specified, the size of the log file is limited only by the maximum file size, if any, for the output mount. The default value is 1. |

+#### Disk provider example

+```bash

+docker run --rm -it -p 5000:5000 \

+--memory 2g --cpus 1 \

+--mount type-bind,src=/home/azureuser/output,target=/output \

+-e apikey={API_KEY} \

+-e eula=accept \

+-e billing={ENDPOINT_URI} \

+-e Languages=en,fr,es,ar,ru \

+Eula=accept \

+Billing=<endpoint> \

+ApiKey=<api-key> \

+Logging:Disk:Format=json \

+Mounts:Output=/output

+```

+For more information about configuring ASP.NET Core logging support, see [Settings file configuration](/aspnet/core/fundamentals/logging/).

+## Mount settings

+Use bind mounts to read and write data to and from the container. You can specify an input mount or output mount by specifying the `--mount` option in the [docker run](https://docs.docker.com/engine/reference/commandline/run/) command.

+## Next steps

+> [!div class="nextstepaction"]

+> [Learn more about Azure AI containers](../../cognitive-services-container-support.md)

+ Title: Install and run Translator container using Docker API

+description: Use the Translator container and API to translate text and documents.

+#

+recommendations: false

+keywords: on-premises, Docker, container, identify

+<!-- markdownlint-disable MD001 -->

+<!-- markdownlint-disable MD033 -->

+# Install and run Azure AI Translator container

+> [!IMPORTANT]

+>

+> * To use the Translator container, you must submit an online request and have it approved. For more information, *see* [Request container access](overview.md#request-container-access).

+> * Azure AI Translator container supports limited features compared to the cloud offerings.

+Containers enable you to host the Azure AI Translator API on your own infrastructure. The container image includes all libraries, tools, and dependencies needed to run an application consistently in any private, public, or personal computing environment. If your security or data governance requirements can't be fulfilled by calling Azure AI Translator API remotely, containers are a good option.

+In this article, learn how to install and run the Translator container online with Docker API. The Azure AI Translator container supports the following operations:

+* **Text Translation**. Translate the contextual meaning of words or phrases from supported `source` to supported `target` language in real time. For more information, *see* [**Container: translate text**](translator-container-supported-parameters.md).

+* **Text Transliteration**. Convert text from one language script or writing system to another language script or writing system in real time. For more information, *see* [Container: transliterate text](transliterate-text-parameters.md).

+* **Document translation**. Synchronously translate documents while preserving structure and format in real time. For more information, *see* [Container:translate documents](translate-document-parameters.md).

+## Prerequisites

+To get started, you need the following resources, access approval, and tools:

+##### Azure resources

+* An active [**Azure subscription**](https://portal.azure.com/). If you don't have one, you can [**create a free 12-month account**](https://azure.microsoft.com/free/).

+* An approved access request to either a [Translator connected container](https://aka.ms/csgate-translator) or [Translator disconnected container](https://aka.ms/csdisconnectedcontainers).

+* An [**Azure AI Translator resource**](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) (**not** a multi-service Azure AI services resource) created under the approved subscription ID. You need the API key and endpoint URI associated with your resource. Both values are required to start the container and can be found on the resource overview page in the Azure portal.

+ * For Translator **connected** containers, select the `S1` pricing tier.

+ * For Translator **disconnected** containers, select **`Commitment tier disconnected containers`** as your pricing tier. You only see the option to purchase a commitment tier if your disconnected container access request is approved.

+ :::image type="content" source="media/disconnected-pricing-tier.png" alt-text="A screenshot showing resource creation on the Azure portal.":::

+##### Docker tools

+You should have a basic understanding of Docker concepts like registries, repositories, containers, and container images, as well as knowledge of basic `docker` [terminology and commands](/dotnet/architecture/microservices/container-docker-introduction/docker-terminology). For a primer on Docker and container basics, see the [Docker overview](https://docs.docker.com/engine/docker-overview/).

+ > [!TIP]

+ >

+ > Consider adding **Docker Desktop** to your computing environment. Docker Desktop is a graphical user interface (GUI) that enables you to build, run, and share containerized applications directly from your desktop.

+ >

+ > DockerDesktop includes Docker Engine, Docker CLI client, Docker Compose and provides packages that configure Docker for your preferred operating system:

+ >

+ > * [macOS](https://docs.docker.com/docker-for-mac/),

+ > * [Windows](https://docs.docker.com/docker-for-windows/)

+ > * [Linux](https://docs.docker.com/engine/installation/#supported-platforms).

+|Tool|Description|Condition|

+|-|--||

+|[**Docker Engine**](https://docs.docker.com/engine/)|The **Docker Engine** is the core component of the Docker containerization platform. It must be installed on a [host computer](#host-computer-requirements) to enable you to build, run, and manage your containers.|***Required*** for all operations.|

+|[**Docker Compose**](https://docs.docker.com/compose/)| The **Docker Compose** tool is used to define and run multi-container applications.|***Required*** for [supporting containers](#use-cases-for-supporting-containers).|

+|[**Docker CLI**](https://docs.docker.com/engine/reference/commandline/cli/)|The Docker command-line interface enables you to interact with Docker Engine and manage Docker containers directly from your local machine.|***Recommended***|

+##### Host computer requirements

+##### Recommended CPU cores and memory

+> [!NOTE]

+> The minimum and recommended specifications are based on Docker limits, not host machine resources.

+The following table describes the minimum and recommended specifications and the allowable Transactions Per Second (TPS) for each container.

+ |Function | Minimum recommended |Notes|

+ |--|||

+ |Text translation| 4 Core, 4-GB memory ||

+ |Text transliteration| 4 Core, 2-GB memory ||

+ |Document translation | 4 Core, 6-GB memory|The number of documents that can be processed concurrently can be calculated with the following formula: [minimum of (`n-2`), (`m-6)/4`)]. <br>&bullet; `n` is number of CPU cores.<br>&bullet; `m` is GB of memory.<br>&bullet; **Example**: 8 Core, 32-GB memory can process six(6) concurrent documents [minimum of (`8-2`), `(36-6)/4)`].|

+* Each core must be at least 2.6 gigahertz (GHz) or faster.

+* For every language pair, 2 GB of memory is recommended.

+* In addition to baseline requirements, 4 GB of memory for every concurrent document processing.

+ > [!TIP]

+ > You can use the [docker images](https://docs.docker.com/engine/reference/commandline/images/) command to list your downloaded container images. For example, the following command lists the ID, repository, and tag of each downloaded container image, formatted as a table:

+ >

+ > ```docker

+ > docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

+ >

+ > IMAGE ID REPOSITORY TAG

+ > <image-id> <repository-path/name> <tag-name>

+ > ```

+## Required input

+All Azure AI containers require the following input values:

+* **EULA accept setting**. You must have an end-user license agreement (EULA) set with a value of `Eula=accept`.

+* **API key** and **Endpoint URL**. The API key is used to start the container. You can retrieve the API key and Endpoint URL values by navigating to your Azure AI Translator resource **Keys and Endpoint** page and selecting the `Copy to clipboard` <span class="docon docon-edit-copy x-hidden-focus"></span> icon.

+* If you're translating documents, be sure to use the document translation endpoint.

+> [!IMPORTANT]

+>

+> * Keys are used to access your Azure AI resource. Do not share your keys. Store them securely, for example, using Azure Key Vault.

+>

+> * We also recommend regenerating these keys regularly. Only one key is necessary to make an API call. When regenerating the first key, you can use the second key for continued access to the service.

+## Billing

+* Queries to the container are billed at the pricing tier of the Azure resource used for the API `Key`.

+* You're billed for each container instance used to process your documents and images.

+* The [docker run](https://docs.docker.com/engine/reference/commandline/run/) command downloads an image from Microsoft Artifact Registry and starts the container when all three of the following options are provided with valid values:

+| Option | Description |

+|--|-|

+| `ApiKey` | The key of the Azure AI services resource used to track billing information.<br/>The value of this option must be set to a key for the provisioned resource specified in `Billing`. |

+| `Billing` | The endpoint of the Azure AI services resource used to track billing information.<br/>The value of this option must be set to the endpoint URI of a provisioned Azure resource.|

+| `Eula` | Indicates that you accepted the license for the container.<br/>The value of this option must be set to **accept**. |

+### Connecting to Azure

+* The container billing argument values allow the container to connect to the billing endpoint and run.

+* The container reports usage about every 10 to 15 minutes. If the container doesn't connect to Azure within the allowed time window, the container continues to run, but doesn't serve queries until the billing endpoint is restored.

+* A connection is attempted 10 times at the same time interval of 10 to 15 minutes. If it can't connect to the billing endpoint within the 10 tries, the container stops serving requests. See the [Azure AI container FAQ](../../../ai-services/containers/container-faq.yml#how-does-billing-work) for an example of the information sent to Microsoft for billing.

+## Container images and tags

+The Azure AI services container images can be found in the [**Microsoft Artifact Registry**](https://mcr.microsoft.com/catalog?page=3) catalog. Azure AI Translator container resides within the azure-cognitive-services/translator repository and is named `text-translation`. The fully qualified container image name is `mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest`.

+To use the latest version of the container, use the latest tag. You can view the full list of [Azure AI services Text Translation](https://mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation/tags) version tags on MCR.

+## Use containers

+Select a tab to choose your Azure AI Translator container environment:

+## [**Connected containers**](#tab/connected)

+Azure AI Translator containers enable you to run the Azure AI Translator service `on-premise` in your own environment. Connected containers run locally and send usage information to the cloud for billing.

+## Download and run container image

+The [docker run](https://docs.docker.com/engine/reference/commandline/run/) command downloads an image from Microsoft Artifact Registry and starts the container.

+> [!IMPORTANT]

+>

+> * The docker commands in the following sections use the back slash, `\`, as a line continuation character. Replace or remove this based on your host operating system's requirements.

+> * The `EULA`, `Billing`, and `ApiKey` options must be specified to run the container; otherwise, the container won't start.

+> * If you're translating documents, be sure to use the document translation endpoint.

+```bash

+docker run --rm -it -p 5000:5000 --memory 12g --cpus 4 \

+-v /mnt/d/TranslatorContainer:/usr/local/models \

+-e apikey={API_KEY} \

+-e eula=accept \

+-e billing={ENDPOINT_URI} \

+-e Languages=en,fr,es,ar,ru \

+mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest

+```

+The above command:

+* Creates a running Translator container from a downloaded container image.

+* Allocates 12 gigabytes (GB) of memory and four CPU core.

+* Exposes transmission control protocol (TCP) port 5000 and allocates a pseudo-TTY for the container. Now, the `localhost` address points to the container itself, not your host machine.

+* Accepts the end-user agreement (EULA).

+* Configures billing endpoint.

+* Downloads translation models for languages English, French, Spanish, Arabic, and Russian.

+* Automatically removes the container after it exits. The container image is still available on the host computer.

+> [!TIP]

+> Additional Docker command:

+>

+> * `docker ps` lists running containers.

+> * `docker pause {your-container name}` pauses a running container.

+> * `docker unpause {your-container-name}` unpauses a paused container.

+> * `docker restart {your-container-name}` restarts a running container.

+> * `docker exec` enables you to execute commands lto *detach* or *set environment variables* in a running container.

+>

+> For more information, *see* [docker CLI reference](https://docs.docker.com/engine/reference/commandline/docker/).

+### Run multiple containers on the same host

+If you intend to run multiple containers with exposed ports, make sure to run each container with a different exposed port. For example, run the first container on port 5000 and the second container on port 5001.

+You can have this container and a different Azure AI container running on the HOST together. You also can have multiple containers of the same Azure AI container running.

+## Query the Translator container endpoint

+The container provides a REST-based Translator endpoint API. Here's an example request with source language (`from=en`) specified:

+ ```bash

+ curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

+ ```

+> [!NOTE]

+>

+> * Source language detection requires an additional container. For more information, *see* [Supporting containers](#use-cases-for-supporting-containers)

+>

+> * If the cURL POST request returns a `Service is temporarily unavailable` response the container isn't ready. Wait a few minutes, then try again.

+### [**Disconnected (offline) containers**](#tab/disconnected)

+Disconnected containers enable you to use the Azure AI Translator API by exporting the docker image to your machine with internet access and then using Docker offline. Disconnected containers are intended for scenarios where no connectivity with the cloud is needed for the containers to run.

+## Disconnected container commitment plan

+* Commitment plans for disconnected containers have a calendar year commitment period.

+* When you purchase a plan, you're charged the full price immediately.

+* During the commitment period, you can't change your commitment plan; however you can purchase more units at a pro-rated price for the remaining days in the year.

+* You have until midnight (UTC) on the last day of your commitment, to end or change a commitment plan.

+* You can choose a different commitment plan in the **Commitment tier pricing** settings of your resource under the **Resource Management** section.

+## Create a new Translator resource and purchase a commitment plan

+1. Create a [Translator resource](https://portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation) in the Azure portal.

+1. To create your resource, enter the applicable information. Be sure to select **Commitment tier disconnected containers** as your pricing tier. You only see the option to purchase a commitment tier if you're approved.

+ :::image type="content" source="media/disconnected-pricing-tier.png" alt-text="A screenshot showing resource creation on the Azure portal.":::

+1. Select **Review + Create** at the bottom of the page. Review the information, and select **Create**.

+### End a commitment plan

+* If you decide that you don't want to continue purchasing a commitment plan, you can set your resource's autorenewal to **Do not auto-renew**.

+* Your commitment plan expires on the displayed commitment end date. After this date, you won't be charged for the commitment plan. You're still able to continue using the Azure resource to make API calls, charged at pay-as-you-go pricing.

+* You have until midnight (UTC) on the last day of the year to end a commitment plan for disconnected containers. If you do so, you avoid charges for the following year.

+## Gather required parameters

+There are three required parameters for all Azure AI services' containers:

+* The end-user license agreement (EULA) must be present with a value of *accept*.

+* The ***Containers*** endpoint URL for your resource from the Azure portal.

+* The API key for your resource from the Azure portal.

+Both the endpoint URL and API key are needed when you first run the container to implement the disconnected usage configuration. You can find the key and endpoint on the **Key and endpoint** page for your resource in the Azure portal:

+ :::image type="content" source="media/keys-endpoint-container.png" alt-text="Screenshot of Azure portal keys and endpoint page.":::

+> [!IMPORTANT]

+> You will only use your key and endpoint to configure the container to run in a disconnected.

+> If you're translating **documents**, be sure to use the document translation endpoint.

+> environment. After you configure the container, you won't need the key and endpoint values to send API requests. Store them securely, for example, using Azure Key Vault. Only one key is necessary for this process.

+## Pull and load the Translator container image

+1. You should have [Docker tools](#docker-tools) installed in your local environment.

+1. Download the Azure AI Translator container with `docker pull`.

+ |Docker pull command | Value |Format|

+ |-|-||

+ |&bullet; **`docker pull [image]`**</br>&bullet; **`docker pull [image]:latest`**|The latest container image.|&bullet; mcr.microsoft.com/azure-cognitive-services/translator/text-translation</br> </br>&bullet; mcr.microsoft.com/azure-cognitive-services/translator/text-translation: latest |

+ ||||

+ |&bullet; **`docker pull [image]:[version]`** | A specific container image |mcr.microsoft.com/azure-cognitive-services/translator/text-translation:1.0.019410001-amd64 |

+ **Example Docker pull command:**

+ ```docker

+ docker pull mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest

+ ```

+1. Save the image to a `.tar` file.

+1. Load the `.tar` file to your local Docker instance. For more information, *see* [Docker: load images from a file](https://docs.docker.com/reference/cli/docker/image/load/#input).

+ ```bash

+ $docker load --input {path-to-your-file}.tar

+ ```

+## Configure the container to run in a disconnected environment

+Now that you downloaded your container, you can execute the `docker run` command with the following parameters:

+* **`DownloadLicense=True`**. This parameter downloads a license file that enables your Docker container to run when it isn't connected to the internet. It also contains an expiration date, after which the license file is invalid to run the container. You can only use the license file in corresponding approved container.

+* **`Languages={language list}`**. You must include this parameter to download model files for the [languages](../language-support.md) you want to translate.

+> [!IMPORTANT]

+> The `docker run` command will generate a template that you can use to run the container. The template contains parameters you'll need for the downloaded models and configuration file. Make sure you save this template.

+The following example shows the formatting for the `docker run` command with placeholder values. Replace these placeholder values with your own values.

+| Placeholder | Value | Format|

+|:-|:-|::|

+| `[image]` | The container image you want to use. | `mcr.microsoft.com/azure-cognitive-services/translator/text-translation` |

+| `{LICENSE_MOUNT}` | The path where the license is downloaded, and mounted. | `/host/license:/path/to/license/directory` |

+ | `{MODEL_MOUNT_PATH}`| The path where the machine translation models are downloaded, and mounted. Your directory structure must be formatted as **/usr/local/models** | `/host/translator/models:/usr/local/models`|

+| `{ENDPOINT_URI}` | The endpoint for authenticating your service request. You can find it on your resource's **Key and endpoint** page, in the Azure portal. | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |

+| `{API_KEY}` | The key for your Text Translation resource. You can find it on your resource's **Key and endpoint** page, in the Azure portal. |`{string}`|

+| `{LANGUAGES_LIST}` | List of language codes separated by commas. It's mandatory to have English (en) language as part of the list.| `en`, `fr`, `it`, `zu`, `uk` |

+| `{CONTAINER_LICENSE_DIRECTORY}` | Location of the license folder on the container's local filesystem. | `/path/to/license/directory` |

+ **Example `docker run` command**

+```bash

+docker run --rm -it -p 5000:5000 \

+-v {MODEL_MOUNT_PATH} \

+-v {LICENSE_MOUNT_PATH} \

+-e Mounts:License={CONTAINER_LICENSE_DIRECTORY} \

+-e DownloadLicense=true \

+-e eula=accept \

+-e billing={ENDPOINT_URI} \

+-e apikey={API_KEY} \

+-e Languages={LANGUAGES_LIST} \

+[image]

+```

+### Translator translation models and container configuration

+After you [configured the container](#configure-the-container-to-run-in-a-disconnected-environment), the values for the downloaded translation models and container configuration will be generated and displayed in the container output:

+```bash

+ -e MODELS= usr/local/models/model1/, usr/local/models/model2/

+ -e TRANSLATORSYSTEMCONFIG=/usr/local/models/Config/5a72fa7c-394b-45db-8c06-ecdfc98c0832

+```

+## Run the container in a disconnected environment

+Once the license file is downloaded, you can run the container in a disconnected environment with your license, appropriate memory, and suitable CPU allocations. The following example shows the formatting of the `docker run` command with placeholder values. Replace these placeholders values with your own values.

+Whenever the container runs, the license file must be mounted to the container and the location of the license folder on the container's local filesystem must be specified with `Mounts:License=`. In addition, an output mount must be specified so that billing usage records can be written.

+|Placeholder | Value | Format|

+|-|-||

+| `[image]`| The container image you want to use. | `mcr.microsoft.com/azure-cognitive-services/translator/text-translation` |

+|`{MEMORY_SIZE}` | The appropriate size of memory to allocate for your container. | `16g` |

+| `{NUMBER_CPUS}` | The appropriate number of CPUs to allocate for your container. | `4` |

+| `{LICENSE_MOUNT}` | The path where the license is located and mounted. | `/host/translator/license:/path/to/license/directory` |

+|`{MODEL_MOUNT_PATH}`| The path where the machine translation models are downloaded, and mounted. Your directory structure must be formatted as **/usr/local/models** | `/host/translator/models:/usr/local/models`|

+|`{MODELS_DIRECTORY_LIST}`|List of comma separated directories each having a machine translation model. | `/usr/local/models/enu_esn_generalnn_2022240501,/usr/local/models/esn_enu_generalnn_2022240501` |

+| `{OUTPUT_PATH}` | The output path for logging [usage records](#usage-records). | `/host/output:/path/to/output/directory` |

+| `{CONTAINER_LICENSE_DIRECTORY}` | Location of the license folder on the container's local filesystem. | `/path/to/license/directory` |

+| `{CONTAINER_OUTPUT_DIRECTORY}` | Location of the output folder on the container's local filesystem. | `/path/to/output/directory` |

+|`{TRANSLATOR_CONFIG_JSON}`| Translator system configuration file used by container internally.| `/usr/local/models/Config/5a72fa7c-394b-45db-8c06-ecdfc98c0832` |

+ **Example `docker run` command**

+```docker

+docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \

+-v {MODEL_MOUNT_PATH} \

+-v {LICENSE_MOUNT_PATH} \

+-v {OUTPUT_MOUNT_PATH} \

+-e Mounts:License={CONTAINER_LICENSE_DIRECTORY} \

+-e Mounts:Output={CONTAINER_OUTPUT_DIRECTORY} \

+-e MODELS={MODELS_DIRECTORY_LIST} \

+-e TRANSLATORSYSTEMCONFIG={TRANSLATOR_CONFIG_JSON} \

+-e eula=accept \

+[image]

+```

+### Troubleshooting

+Run the container with an output mount and logging enabled. These settings enable the container to generate log files that are helpful for troubleshooting issues that occur while starting or running the container.

+> [!TIP]

+> For more troubleshooting information and guidance, see [Disconnected containers Frequently asked questions (FAQ)](../../containers/disconnected-container-faq.yml).

+## Validate that a container is running

+There are several ways to validate that the container is running:

+* The container provides a homepage at `/` as a visual validation that the container is running.

+* You can open your favorite web browser and navigate to the external IP address and exposed port of the container in question. Use the following request URLs to validate the container is running. The example request URLs listed point to `http://localhost:5000`, but your specific container can vary. Keep in mind that you're navigating to your container's **External IP address** and exposed port.

+| Request URL | Purpose |

+|--|--|

+| `http://localhost:5000/` | The container provides a home page. |

+| `http://localhost:5000/ready` | Requested with GET. Provides a verification that the container is ready to accept a query against the model. This request can be used for Kubernetes [liveness and readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). |

+| `http://localhost:5000/status` | Requested with GET. Verifies if the api-key used to start the container is valid without causing an endpoint query. This request can be used for Kubernetes [liveness and readiness probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/). |

+| `http://localhost:5000/swagger` | The container provides a full set of documentation for the endpoints and a **Try it out** feature. With this feature, you can enter your settings into a web-based HTML form and make the query without having to write any code. After the query returns, an example CURL command is provided to demonstrate the required HTTP headers and body format. |

+## Stop the container

+## Use cases for supporting containers

+Some Translator queries require supporting containers to successfully complete operations. **If you are using Office documents and don't require source language detection, only the Translator container is required.** However if source language detection is required or you're using scanned PDF documents, supporting containers are required:

+The following table lists the required supporting containers for your text and document translation operations. The Translator container sends billing information to Azure via the Azure AI Translator resource on your Azure account.

+|Operation|Request query|Document type|Supporting containers|

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

+|&bullet; Text translation<br>&bullet; Document Translation |`from` specified. |Office documents| None|

+|&bullet; Text translation<br>&bullet; Document Translation|`from` not specified. Requires automatic language detection to determine the source language. |Office documents |✔️ [**Text analytics:language**](../../language-service/language-detection/how-to/use-containers.md) container|

+|&bullet; Text translation<br>&bullet; Document Translation |`from` specified. |Scanned PDF documents| ✔️ [**Vision:read**](../../computer-vision/computer-vision-how-to-install-containers.md) container|

+|&bullet; Text translation<br>&bullet; Document Translation|`from` not specified requiring automatic language detection to determine source language.|Scanned PDF documents| ✔️ [**Text analytics:language**](../../language-service/language-detection/how-to/use-containers.md) container<br><br>✔️ [**Vision:read**](../../computer-vision/computer-vision-how-to-install-containers.md) container|

+## Operate supporting containers with `docker compose`

+Docker compose is a tool that enables you to configure multi-container applications using a single YAML file typically named `compose.yaml`. Use the `docker compose up` command to start your container application and the `docker compose down` command to stop and remove your containers.

+If you installed Docker Desktop CLI, it includes Docker compose and its prerequisites. If you don't have Docker Desktop, see the [Installing Docker Compose overview](https://docs.docker.com/compose/install/).

+### Create your application

+1. Using your preferred editor or IDE, create a new directory for your app named `container-environment` or a name of your choice.

+1. Create a new YAML file named `compose.yaml`. Both the .yml or .yaml extensions can be used for the `compose` file.

+1. Copy and paste the following YAML code sample into your `compose.yaml` file. Replace `{TRANSLATOR_KEY}` and `{TRANSLATOR_ENDPOINT_URI}` with the key and endpoint values from your Azure portal Translator instance. If you're translating documents, make sure to use the `document translation endpoint`.

+1. The top-level name (`azure-ai-translator`, `azure-ai-language`, `azure-ai-read`) is parameter that you specify.

+1. The `container_name` is an optional parameter that sets a name for the container when it runs, rather than letting `docker compose` generate a name.

+ ```yml

+

+ azure-ai-translator:

+ container_name: azure-ai-translator

+ image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest

+ environment:

+ - EULA=accept

+ - billing={TRANSLATOR_ENDPOINT_URI}

+ - apiKey={TRANSLATOR_KEY}

+ - AzureAiLanguageHost=http://azure-ai-language:5000

+ - AzureAiReadHost=http://azure-ai-read:5000

+ ports:

+ - "5000:5000"

+ azure-ai-language:

+ container_name: azure-ai-language

+ image: mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest

+ environment:

+ - EULA=accept

+ - billing={TRANSLATOR_ENDPOINT_URI}

+ - apiKey={TRANSLATOR_KEY}

+ azure-ai-read:

+ container_name: azure-ai-read

+ image: mcr.microsoft.com/azure-cognitive-services/vision/read:latest

+ environment:

+ - EULA=accept

+ - billing={TRANSLATOR_ENDPOINT_URI}

+ - apiKey={TRANSLATOR_KEY}

+ ```

+1. Open a terminal navigate to the `container-environment` folder, and start the containers with the following `docker-compose` command:

+ ```bash

+ docker compose up

+ ```

+1. To stop the containers, use the following command:

+ ```bash

+ docker compose down

+ ```

+ > [!TIP]

+ > Helpful Docker commands:

+ >

+ > * `docker compose pause` pauses running containers.

+ > * `docker compose unpause {your-container-name}` unpauses paused containers.

+ > * `docker compose restart` restarts all stopped and running container with all its previous changes intact. If you make changes to your `compose.yaml` configuration, these changes aren't updated with the `docker compose restart` command. You have to use the `docker compose up` command to reflect updates and changes in the `compose.yaml` file.

+ > * `docker compose ps -a` lists all containers, including those that are stopped.

+ > * `docker compose exec` enables you to execute commands to *detach* or *set environment variables* in a running container.

+ >

+ > For more information, *see* [docker CLI reference](https://docs.docker.com/engine/reference/commandline/docker/).

+### Translator and supporting container images and tags

+The Azure AI services container images can be found in the [**Microsoft Artifact Registry**](https://mcr.microsoft.com/catalog?page=3) catalog. The following table lists the fully qualified image location for text and document translation:

+|Container|Image location|Notes|

+|--|-||

+|Translator: Text and document translation| `mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest`| You can view the full list of [Azure AI services Text Translation](https://mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation/tags) version tags on MCR.|

+|Text analytics: language|`mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest` |You can view the full list of [Azure AI services Text Analytics Language](https://mcr.microsoft.com/product/azure-cognitive-services/textanalytics/language/tags) version tags on MCR.|

+|Vision: read|`mcr.microsoft.com/azure-cognitive-services/vision/read:latest`|You can view the full list of [Azure AI services Computer Vision Read `OCR`](https://mcr.microsoft.com/product/azure-cognitive-services/vision/read/tags) version tags on MCR.|

+## Other parameters and commands

+Here are a few more parameters and commands you can use to run the container:

+#### Usage records

+When operating Docker containers in a disconnected environment, the container will write usage records to a volume where they're collected over time. You can also call a REST API endpoint to generate a report about service usage.

+#### Arguments for storing logs

+When run in a disconnected environment, an output mount must be available to the container to store usage logs. For example, you would include `-v /host/output:{OUTPUT_PATH}` and `Mounts:Output={OUTPUT_PATH}` in the following example, replacing `{OUTPUT_PATH}` with the path where the logs are stored:

+ **Example `docker run` command**

+```docker

+docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}

+```

+#### Environment variable names in Kubernetes deployments

+* Some Azure AI Containers, for example Translator, require users to pass environmental variable names that include colons (`:`) when running the container.

+* Kubernetes doesn't accept colons in environmental variable names.

+To resolve, you can replace colons with two underscore characters (`__`) when deploying to Kubernetes. See the following example of an acceptable format for environmental variable names:

+```Kubernetes

+ env:

+ - name: Mounts__License

+ value: "/license"

+ - name: Mounts__Output

+ value: "/output"

+```

+This example replaces the default format for the `Mounts:License` and `Mounts:Output` environment variable names in the docker run command.

+#### Get usage records using the container endpoints

+The container provides two endpoints for returning records regarding its usage.

+#### Get all records

+The following endpoint provides a report summarizing all of the usage collected in the mounted billing record directory.

+```HTTP

+https://<service>/records/usage-logs/

+```

+***Example HTTPS endpoint to retrieve all records***

+ `http://localhost:5000/records/usage-logs`

+#### Get records for a specific month

+The following endpoint provides a report summarizing usage over a specific month and year:

+```HTTP

+https://<service>/records/usage-logs/{MONTH}/{YEAR}

+```

+***Example HTTPS endpoint to retrieve records for a specific month and year***

+ `http://localhost:5000/records/usage-logs/03/2024`

+The usage-logs endpoints return a JSON response similar to the following example:

+***Connected container***

+The `quantity` is the amount you're charged for connected container usage.

+ ```json

+ {

+ "apiType": "string",

+ "serviceName": "string",

+ "meters": [

+ {

+ "name": "string",

+ "quantity": 256345435

+ }

+ ]

+ }

+ ```

+***Disconnected container***

+ ```json

+ {

+ "type": "CommerceUsageResponse",

+ "meters": [

+ {

+ "name": "CognitiveServices.TextTranslation.Container.OneDocumentTranslatedCharacters",

+ "quantity": 1250000,

+ "billedUnit": 1875000

+ },

+ {

+ "name": "CognitiveServices.TextTranslation.Container.TranslatedCharacters",

+ "quantity": 1250000,

+ "billedUnit": 1250000

+ }

+ ],

+ "apiType": "texttranslation",

+ "serviceName": "texttranslation"

+ }

+ ```

+The aggregated value of `billedUnit` for the following meters is counted towards the characters you licensed for your disconnected container usage:

+* `CognitiveServices.TextTranslation.Container.OneDocumentTranslatedCharacters`

+* `CognitiveServices.TextTranslation.Container.TranslatedCharacters`

+### Summary

+In this article, you learned concepts and workflows for downloading, installing, and running an Azure AI Translator container:

+* Azure AI Translator container supports text translation, synchronous document translation, and text transliteration.

+* Container images are downloaded from the container registry and run in Docker.

+* The billing information must be specified when you instantiate a container.

+## Next steps

+> [!div class="nextstepaction"]

+> [Learn more about Azure AI container configuration](translator-container-configuration.md) [Learn more about container language support](../language-support.md#translation).

+ Title: What is Azure AI Translator container?

+description: Translate text and documents using the Azure AI Translator container.

+# What is Azure AI Translator container?

+> [!IMPORTANT]

+>

+> * To use the Translator container, you must submit an online request and have it approved. For more information, *see* [Request container access](#request-container-access).

+> * Azure AI Translator container supports limited features compared to the cloud offerings. For more information, *see* [**Container translate methods**](translator-container-supported-parameters.md).

+Azure AI Translator container enables you to build translator application architecture that is optimized for both robust cloud capabilities and edge locality. A container is a running instance of an executable software image. The Translator container image includes all libraries, tools, and dependencies needed to run an application consistently in any private, public, or personal computing environment. Containers are isolated, lightweight, portable, and are great for implementing specific security or data governance requirements. Translator container is available in [connected](#connected-containers) and [disconnected (offline)](#disconnected-containers) modalities.

+## Connected containers

+* **Translator connected container** is deployed on premises and processes content in your environment. It requires internet connectivity to transmit usage metadata for billing; however, your customer content isn't transmitted outside of your premises.

+You're billed for connected containers monthly, based on the usage and consumption. The container needs to be configured to send metering data to Azure, and transactions are billed accordingly. Queries to the container are billed at the pricing tier of the Azure resource used for the API Key. You're billed for each container instance used to process your documents and images.

+ ***Sample billing metadata transmitted by Translator connected container***

+ The `quantity` is the amount you're charged for connected container usage.

+ ```json

+ {

+ "apiType": "texttranslation",

+ "id": "ab1cf234-0056-789d-e012-f3ghi4j5klmn",

+ "containerType": "123a5bc06d7e",

+ "quantity": 125000

+ }

+ ```

+## Disconnected containers

+* **Translator disconnected container** is deployed on premises and processes content in your environment. It doesn't require internet connectivity at runtime. Customer must license the container for projected usage over a year and is charged affront.

+Disconnected containers are offered through commitment tier pricing offered at a discounted rate compared to pay-as-you-go pricing. With commitment tier pricing, you can commit to using Translator Service features for a fixed fee, at a predictable total cost, based on the needs of your workload. Commitment plans for disconnected containers have a calendar year commitment period.

+When you purchase a plan, you're charged the full price immediately. During the commitment period, you can't change your commitment plan; however you can purchase more units at a pro-rated price for the remaining days in the year. You have until midnight (UTC) on the last day of your commitment, to end a commitment plan.

+ ***Sample billing metadata transmitted by Translator disconnected container***

+ ```json

+ {

+ "type": "CommerceUsageResponse",

+ "meters": [

+ {

+ "name": "CognitiveServices.TextTranslation.Container.OneDocumentTranslatedCharacters",

+ "quantity": 1250000,

+ "billedUnit": 1875000

+ },

+ {

+ "name": "CognitiveServices.TextTranslation.Container.TranslatedCharacters",

+ "quantity": 1250000,

+ "billedUnit": 1250000

+ }

+ ],

+ "apiType": "texttranslation",

+ "serviceName": "texttranslation"

+ }

+```

+The aggregated value of `billedUnit` for the following meters is counted towards the characters you licensed for your disconnected container usage:

+* `CognitiveServices.TextTranslation.Container.OneDocumentTranslatedCharacters`

+* `CognitiveServices.TextTranslation.Container.TranslatedCharacters`

+## Request container access

+Translator containers are a gated offering. To use the Translator container, you must submit an online request and for approval.

+* To request access to a connected container, complete and submit the [**connected container access request form**](https://aka.ms/csgate-translator).

+* To request access t a disconnected container, complete and submit the [**disconnected container request form**](https://aka.ms/csdisconnectedcontainers).

+* The form requests information about you, your company, and the user scenario for which you use the container. After you submit the form, the Azure AI services team reviews it and emails you with a decision within 10 business days.

+ > [!IMPORTANT]

+ > ✔️ On the form, you must use an email address associated with an Azure subscription ID.

+ >

+ > ✔️ The Azure resource you use to run the container must have been created with the approved Azure subscription ID.

+ >

+ > ✔️ Check your email (both inbox and junk folders) for updates on the status of your application from Microsoft.

+* After you're approved, you'll be able to run the container after you download it from the Microsoft Container Registry (MCR).

+* You can't access the container if your Azure subscription is't approved.

+## Next steps

+[Install and run Azure AI translator containers](install-run.md).

+ Title: "Container: Translate document method"

+description: Understand the parameters, headers, and body request/response messages for the Azure AI Translator container translate document operation.

+#

+# Container: Translate Documents

+**Translate document with source language specified**.

+## Request URL (using cURL)

+`POST` request:

+```http

+ POST {Endpoint}/translate?api-version=3.0&to={to}

+```

+***With optional parameters***

+```http

+POST {Endpoint}/translate?api-version=3.0&from={from}&to={to}&textType={textType}&category={category}&profanityAction={profanityAction}&profanityMarker={profanityMarker}&includeAlignment={includeAlignment}&includeSentenceLength={includeSentenceLength}&suggestedFrom={suggestedFrom}&fromScript={fromScript}&toScript={toScript}

+```

+Example:

+```bash

+`curl -i -X POST "http://localhost:5000/translator/document:translate?sourceLanguage=en&targetLanguage=hi&api-version=2023-11-01-preview" -F "document={path-to-your-document-with-file-extension};type={ContentType}/{file-extension" -o "{path-to-output-file-with-file-extension}"`

+```

+## Synchronous request headers and parameters

+Use synchronous translation processing to send a document as part of the HTTP request body and receive the translated document in the HTTP response.

+|Query parameter&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;&emsp;|Description| Condition|

+|||-|

+|`-X` or `--request` `POST`|The -X flag specifies the request method to access the API.|*Required* |

+|`{endpoint}` |The URL for your Document Translation resource endpoint|*Required* |

+|`targetLanguage`|Specifies the language of the output document. The target language must be one of the supported languages included in the translation scope.|*Required* |

+|`sourceLanguage`|Specifies the language of the input document. If the `sourceLanguage` parameter isn't specified, automatic language detection is applied to determine the source language. |*Optional*|

+|`-H` or `--header` `"Ocp-Apim-Subscription-Key:{KEY}` | Request header that specifies the Document Translation resource key authorizing access to the API.|*Required*|

+|`-F` or `--form` |The filepath to the document that you want to include with your request. Only one source document is allowed.|*Required*|

+|&bull; `document=`<br> &bull; `type={contentType}/fileExtension` |&bull; Path to the file location for your source document.</br> &bull; Content type and file extension.</br></br> Ex: **"document=@C:\Test\test-file.md;type=text/markdown**|*Required*|

+|`-o` or `--output`|The filepath to the response results.|*Required*|

+|`-F` or `--form` |The filepath to an optional glossary to include with your request. The glossary requires a separate `--form` flag.|*Optional*|

+| &bull; `glossary=`<br> &bull; `type={contentType}/fileExtension`|&bull; Path to the file location for your optional glossary file.</br> &bull; Content type and file extension.</br></br> Ex: **"glossary=@C:\Test\glossary-file.txt;type=text/plain**|*Optional*|

+✔️ For more information on **`contentType`**, *see* [**Supported document formats**](../document-translation/overview.md#synchronous-supported-document-formats).

+## Code sample: document translation

+> [!NOTE]

+>

+> * Each sample runs on the `localhost` that you specified with the `docker compose up` command.

+> * While your container is running, `localhost` points to the container itself.

+> * You don't have to use `localhost:5000`. You can use any port that is not already in use in your host environment.

+### Sample document

+For this project, you need a source document to translate. You can download our [document translation sample document](https://raw.githubusercontent.com/Azure-Samples/cognitive-services-REST-api-samples/master/curl/Translator/document-translation-sample.docx) for and store it in the same folder as your `compose.yaml` file (`container-environment`). The file name is `document-translation-sample.docx` and the source language is English.

+### Query Azure AI Translator endpoint (document)

+Here's an example cURL HTTP request using localhost:5000:

+```bash

+curl -v "http://localhost:5000/translator/documents:translateDocument?from=en&to=es&api-version=v1.0" -F "document=@document-translation-sample-docx"

+```

+***Upon successful completion***:

+* The translated document is returned with the response.

+* The successful POST method returns a `200 OK` response code indicating that the service created the request.

+## Next steps

+> [!div class="nextstepaction"]

+> [Learn more about synchronous document translation](../document-translation/reference/synchronous-rest-api-guide.md)

+ Title: "Container: Translate text method"

+description: Understand the parameters, headers, and body messages for the Azure AI Translator container translate document operation.

+# Container: Translate Text

+**Translate text**.

+## Request URL

+Send a `POST` request to:

+```HTTP

+POST {Endpoint}/translate?api-version=3.0&&from={from}&to={to}

+```

+***Example request***

+```rest

+POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=es

+[

+ {

+ "Text": "I would really like to drive your car."

+ }

+]

+```

+***Example response***

+```json

+[

+ {

+ "translations": [

+ {

+ "text": "Realmente me gustaría conducir su coche.",

+ "to": "es"

+ }

+ ]

+ }

+]

+```

+## Request parameters

+Request parameters passed on the query string are:

+### Required parameters

+| Query parameter | Description |Condition|

+| | ||

+| api-version | Version of the API requested by the client. Value must be `3.0`. |*Required parameter*|

+| from |Specifies the language of the input text.|*Required parameter*|

+| to |Specifies the language of the output text. For example, use `to=de` to translate to German.<br>It's possible to translate to multiple languages simultaneously by repeating the parameter in the query string. For example, use `to=de&to=it` to translate to German and Italian. |*Required parameter*|

+* You can query the service for `translation` scope [supported languages](../reference/v3-0-languages.md).

+* *See also* [Language support for transliteration](../language-support.md#translation).

+### Optional parameters

+| Query parameter | Description |

+| | |

+| textType | _Optional parameter_. <br>Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, complete element. Possible values are: `plain` (default) or `html`. |

+| includeSentenceLength | _Optional parameter_. <br>Specifies whether to include sentence boundaries for the input text and the translated text. Possible values are: `true` or `false` (default). |

+### Request headers

+| Headers | Description |Condition|

+| | ||

+| Authentication headers |*See* [available options for authentication](../reference/v3-0-reference.md#authentication). |*Required request header*|

+| Content-Type |Specifies the content type of the payload. <br>Accepted value is `application/json; charset=UTF-8`. |*Required request header*|

+| Content-Length |The length of the request body. |*Optional*|

+| X-ClientTraceId | A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named `ClientTraceId`. |*Optional*|

+## Request body

+The body of the request is a JSON array. Each array element is a JSON object with a string property named `Text`, which represents the string to translate.

+```json

+[

+ {"Text":"I would really like to drive your car around the block a few times."}

+]

+```

+The following limitations apply:

+* The array can have at most 100 elements.

+* The entire text included in the request can't exceed 10,000 characters including spaces.

+## Response body

+A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:

+* `translations`: An array of translation results. The size of the array matches the number of target languages specified through the `to` query parameter. Each element in the array includes:

+* `to`: A string representing the language code of the target language.

+* `text`: A string giving the translated text.

+* `sentLen`: An object returning sentence boundaries in the input and output texts.

+* `srcSentLen`: An integer array representing the lengths of the sentences in the input text. The length of the array is the number of sentences, and the values are the length of each sentence.

+* `transSentLen`: An integer array representing the lengths of the sentences in the translated text. The length of the array is the number of sentences, and the values are the length of each sentence.

+ Sentence boundaries are only included when the request parameter `includeSentenceLength` is `true`.

+ * `sourceText`: An object with a single string property named `text`, which gives the input text in the default script of the source language. `sourceText` property is present only when the input is expressed in a script that's not the usual script for the language. For example, if the input were Arabic written in Latin script, then `sourceText.text` would be the same Arabic text converted into Arab script.

+## Response headers

+| Headers | Description |

+| | |

+| X-RequestId | Value generated by the service to identify the request and used for troubleshooting purposes. |

+| X-MT-System | Specifies the system type that was used for translation for each 'to' language requested for translation. The value is a comma-separated list of strings. Each string indicates a type: </br></br>&FilledVerySmallSquare; Custom - Request includes a custom system and at least one custom system was used during translation.</br>&FilledVerySmallSquare; Team - All other requests |

+## Response status codes

+If an error occurs, the request returns a JSON error response. The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. Common error codes can be found on the [v3 Translator reference page](../reference/v3-0-reference.md#errors).

+## Code samples: translate text

+> [!NOTE]

+>

+> * Each sample runs on the `localhost` that you specified with the `docker run` command.

+> * While your container is running, `localhost` points to the container itself.

+> * You don't have to use `localhost:5000`. You can use any port that is not already in use in your host environment.

+> To specify a port, use the `-p` option.

+### Translate a single input

+This example shows how to translate a single sentence from English to Simplified Chinese.

+```bash

+curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

+```

+The response body is:

+```json

+[

+ {

+ "translations":[

+ {"text":"你好, 你叫什么名字？","to":"zh-Hans"}

+ ]

+ }

+]

+```

+The `translations` array includes one element, which provides the translation of the single piece of text in the input.

+### Query Azure AI Translator endpoint (text)

+Here's an example cURL HTTP request using localhost:5000 that you specified with the `docker run` command:

+```bash

+ curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS"

+ -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

+```

+> [!NOTE]

+> If you attempt the cURL POST request before the container is ready, you'll end up getting a *Service is temporarily unavailable* response. Wait until the container is ready, then try again.

+### Translate text using Swagger API

+#### English &leftrightarrow; German

+1. Navigate to the Swagger page: `http://localhost:5000/swagger/https://docsupdatetracker.net/index.html`

+1. Select **POST /translate**

+1. Select **Try it out**

+1. Enter the **From** parameter as `en`

+1. Enter the **To** parameter as `de`

+1. Enter the **api-version** parameter as `3.0`

+1. Under **texts**, replace `string` with the following JSON

+```json

+ [

+ {

+ "text": "hello, how are you"

+ }

+ ]

+```

+Select **Execute**, the resulting translations are output in the **Response Body**. You should see the following response:

+```json

+"translations": [

+ {

+ "text": "hallo, wie geht es dir",

+ "to": "de"

+ }

+ ]

+```

+### Translate text with Python

+#### English &leftrightarrow; French

+```python

+import requests, json

+url = 'http://localhost:5000/translate?api-version=3.0&from=en&to=fr'

+headers = { 'Content-Type': 'application/json' }

+body = [{ 'text': 'Hello, how are you' }]

+request = requests.post(url, headers=headers, json=body)

+response = request.json()

+print(json.dumps(

+ response,

+ sort_keys=True,

+ indent=4,

+ ensure_ascii=False,

+ separators=(',', ': ')))

+```

+### Translate text with C#/.NET console app

+#### English &leftrightarrow; Spanish

+Launch Visual Studio, and create a new console application. Edit the `*.csproj` file to add the `<LangVersion>7.1</LangVersion>` nodeΓÇöspecifies C# 7.1. Add the [Newtoonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/) NuGet package version 11.0.2.

+In the `Program.cs` replace all the existing code with the following script:

+```csharp

+using Newtonsoft.Json;

+using System;

+using System.Net.Http;

+using System.Text;

+using System.Threading.Tasks;

+namespace TranslateContainer

+{

+ class Program

+ {

+ const string ApiHostEndpoint = "http://localhost:5000";

+ const string TranslateApi = "/translate?api-version=3.0&from=en&to=es";

+ static async Task Main(string[] args)

+ {

+ var textToTranslate = "Sunny day in Seattle";

+ var result = await TranslateTextAsync(textToTranslate);

+ Console.WriteLine(result);

+ Console.ReadLine();

+ }

+ static async Task<string> TranslateTextAsync(string textToTranslate)

+ {

+ var body = new object[] { new { Text = textToTranslate } };

+ var requestBody = JsonConvert.SerializeObject(body);

+ var client = new HttpClient();

+ using (var request =

+ new HttpRequestMessage

+ {

+ Method = HttpMethod.Post,

+ RequestUri = new Uri($"{ApiHostEndpoint}{TranslateApi}"),

+ Content = new StringContent(requestBody, Encoding.UTF8, "application/json")

+ })

+ {

+ // Send the request and await a response.

+ var response = await client.SendAsync(request);

+ return await response.Content.ReadAsStringAsync();

+ }

+ }

+ }

+}

+```

+### Translate multiple strings

+Translating multiple strings at once is simply a matter of specifying an array of strings in the request body.

+```bash

+curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}, {'Text':'I am fine, thank you.'}]"

+```

+The response contains the translation of all pieces of text in the exact same order as in the request.

+The response body is:

+```json

+[

+ {

+ "translations":[

+ {"text":"你好, 你叫什么名字？","to":"zh-Hans"}

+ ]

+ },

+ {

+ "translations":[

+ {"text":"我很好，谢谢你。","to":"zh-Hans"}

+ ]

+ }

+]

+```

+### Translate to multiple languages

+This example shows how to translate the same input to several languages in one request.

+```bash

+curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'Hello, what is your name?'}]"

+```

+The response body is:

+```json

+[

+ {

+ "translations":[

+ {"text":"你好, 你叫什么名字？","to":"zh-Hans"},

+ {"text":"Hallo, was ist dein Name?","to":"de"}

+ ]

+ }

+]

+```

+### Translate content with markup and specify translated content

+It's common to translate content that includes markup such as content from an HTML page or content from an XML document. Include query parameter `textType=html` when translating content with tags. In addition, it's sometimes useful to exclude specific content from translation. You can use the attribute `class=notranslate` to specify content that should remain in its original language. In the following example, the content inside the first `div` element isn't translated, while the content in the second `div` element is translated.

+```html

+<div class="notranslate">This will not be translated.</div>

+<div>This will be translated. </div>

+```

+Here's a sample request to illustrate.

+```bash

+curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=zh-Hans&textType=html" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'<div class=\"notranslate\">This will not be translated.</div><div>This will be translated.</div>'}]"

+```

+The response is:

+```json

+[

+ {

+ "translations":[

+ {"text":"<div class=\"notranslate\">This will not be translated.</div><div>这将被翻译。</div>","to":"zh-Hans"}

+ ]

+ }

+]

+```

+### Translate with dynamic dictionary

+If you already know the translation you want to apply to a word or a phrase, you can supply it as markup within the request. The dynamic dictionary is only safe for proper nouns such as personal names and product names.

+The markup to supply uses the following syntax.

+```html

+<mstrans:dictionary translation="translation of phrase">phrase</mstrans:dictionary>

+```

+For example, consider the English sentence "The word wordomatic is a dictionary entry." To preserve the word _wordomatic_ in the translation, send the request:

+```bash

+curl -X POST "http://localhost:{port}/translate?api-version=3.0&from=en&to=de" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json; charset=UTF-8" -d "[{'Text':'The word <mstrans:dictionary translation=\"wordomatic\">word or phrase</mstrans:dictionary> is a dictionary entry.'}]"

+```

+The result is:

+```json

+[

+ {

+ "translations":[

+ {"text":"Das Wort \"wordomatic\" ist ein W├╢rterbucheintrag.","to":"de"}

+ ]

+ }

+]

+```

+This feature works the same way with `textType=text` or with `textType=html`. The feature should be used sparingly. The appropriate and far better way of customizing translation is by using Custom Translator. Custom Translator makes full use of context and statistical probabilities. If you created training data that shows your work or phrase in context, you get better results. [Learn more about Custom Translator](../custom-translator/concepts/customization.md).

+## Request limits

+Each translate request is limited to 10,000 characters, across all the target languages you're translating to. For example, sending a translate request of 3,000 characters to translate to three different languages results in a request size of 3000x3 = 9,000 characters, which satisfy the request limit. You're charged per character, not by the number of requests. We recommended sending shorter requests.

+The following table lists array element and character limits for the Translator **translation** operation.

+| Operation | Maximum size of array element | Maximum number of array elements | Maximum request size (characters) |

+|:-|:-|:-|:-|

+| translate | 10,000 | 100 | 10,000 |

+## Use docker compose: Translator with supporting containers

+Docker compose is a tool enables you to configure multi-container applications using a single YAML file typically named `compose.yaml`. Use the `docker compose up` command to start your container application and the `docker compose down` command to stop and remove your containers.

+If you installed Docker Desktop CLI, it includes Docker compose and its prerequisites. If you don't have Docker Desktop, see the [Installing Docker Compose overview](https://docs.docker.com/compose/install/).

+The following table lists the required supporting containers for your text and document translation operations. The Translator container sends billing information to Azure via the Azure AI Translator resource on your Azure account.

+|Operation|Request query|Document type|Supporting containers|

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

+|&bullet; Text translation<br>&bullet; Document Translation |`from` specified. |Office documents| None|

+|&bullet; Text translation<br>&bullet; Document Translation|`from` not specified. Requires automatic language detection to determine the source language. |Office documents |✔️ [**Text analytics:language**](../../language-service/language-detection/how-to/use-containers.md) container|

+|&bullet; Text translation<br>&bullet; Document Translation |`from` specified. |Scanned PDF documents| ✔️ [**Vision:read**](../../computer-vision/computer-vision-how-to-install-containers.md) container|

+|&bullet; Text translation<br>&bullet; Document Translation|`from` not specified requiring automatic language detection to determine source language.|Scanned PDF documents| ✔️ [**Text analytics:language**](../../language-service/language-detection/how-to/use-containers.md) container<br><br>✔️ [**Vision:read**](../../computer-vision/computer-vision-how-to-install-containers.md) container|

+##### Container images and tags

+The Azure AI services container images can be found in the [**Microsoft Artifact Registry**](https://mcr.microsoft.com/catalog?page=3) catalog. The following table lists the fully qualified image location for text and document translation:

+|Container|Image location|Notes|

+|--|-||

+|Translator: Text translation| `mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest`| You can view the full list of [Azure AI services Text Translation](https://mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation/tags) version tags on MCR.|

+|Translator: Document translation|**TODO**| **TODO**|

+|Text analytics: language|`mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest` |You can view the full list of [Azure AI services Text Analytics Language](https://mcr.microsoft.com/product/azure-cognitive-services/textanalytics/language/tags) version tags on MCR.|

+|Vision: read|`mcr.microsoft.com/azure-cognitive-services/vision/read:latest`|You can view the full list of [Azure AI services Computer Vision Read `OCR`](https://mcr.microsoft.com/product/azure-cognitive-services/vision/read/tags) version tags on MCR.|

+### Create your application

+1. Using your preferred editor or IDE, create a new directory for your app named `container-environment` or a name of your choice.

+1. Create a new YAML file named `compose.yaml`. Both the .yml or .yaml extensions can be used for the `compose` file.

+1. Copy and paste the following YAML code sample into your `compose.yaml` file. Replace `{TRANSLATOR_KEY}` and `{TRANSLATOR_ENDPOINT_URI}` with the key and endpoint values from your Azure portal Translator instance. Make sure you use the `document translation endpoint`.

+1. The top-level name (`azure-ai-translator`, `azure-ai-language`, `azure-ai-read`) is parameter that you specify.

+1. The `container_name` is an optional parameter that sets a name for the container when it runs, rather than letting `docker compose` generate a name.

+ ```yml

+

+ azure-ai-translator:

+ container_name: azure-ai-translator

+ image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest

+ environment:

+ - EULA=accept

+ - billing={TRANSLATOR_ENDPOINT_URI}

+ - apiKey={TRANSLATOR_KEY}

+ - AzureAiLanguageHost=http://azure-ai-language:5000

+ - AzureAiReadHost=http://azure-ai-read:5000

+ ports:

+ - "5000:5000"

+ azure-ai-language:

+ container_name: azure-ai-language

+ image: mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest

+ environment:

+ - EULA=accept

+ - billing={TRANSLATOR_ENDPOINT_URI}

+ - apiKey={TRANSLATOR_KEY}

+ azure-ai-read:

+ container_name: azure-ai-read

+ image: mcr.microsoft.com/azure-cognitive-services/vision/read:latest

+ environment:

+ - EULA=accept

+ - billing={TRANSLATOR_ENDPOINT_URI}

+ - apiKey={TRANSLATOR_KEY}

+ ```

+1. Open a terminal navigate to the `container-environment` folder, and start the containers with the following `docker-compose` command:

+ ```bash

+ docker compose up

+ ```

+1. To stop the containers, use the following command:

+ ```bash

+ docker compose down

+ ```

+ > [!TIP]

+ > **`docker compose` commands:**

+ >

+ > * `docker compose pause` pauses running containers.

+ > * `docker compose unpause {your-container-name}` unpauses paused containers.

+ > * `docker compose restart` restarts all stopped and running container with all its previous changes intact. If you make changes to your `compose.yaml` configuration, these changes aren't updated with the `docker compose restart` command. You have to use the `docker compose up` command to reflect updates and changes in the `compose.yaml` file.

+ > * `docker compose ps -a` lists all containers, including those that are stopped.

+ > * `docker compose exec` enables you to execute commands to *detach* or *set environment variables* in a running container.

+ >

+ > For more information, *see* [docker CLI reference](https://docs.docker.com/engine/reference/commandline/docker/).

+## Next Steps

+> [!div class="nextstepaction"]

+> [Learn more about text translation](../translator-text-apis.md#translate-text)

+ Title: "Container: Transliterate document method"

+description: Understand the parameters, headers, and body messages for the Azure AI Translator container transliterate text operation.

+#

+# Container: Transliterate Text

+Convert characters or letters of a source language to the corresponding characters or letters of a target language.

+## Request URL

+`POST` request:

+```HTTP

+ POST {Endpoint}/transliterate?api-version=3.0&language={language}&fromScript={fromScript}&toScript={toScript}

+```

+*See* [**Virtual Network Support**](../reference/v3-0-reference.md#virtual-network-support) for Translator service selected network and private endpoint configuration and support.

+## Request parameters

+Request parameters passed on the query string are:

+| Query parameter | Description |Condition|

+| | | |

+| api-version |Version of the API requested by the client. Value must be `3.0`. |*Required parameter*|

+| language |Specifies the source language of the text to convert from one script to another.| *Required parameter*|

+| fromScript | Specifies the script used by the input text. |*Required parameter*|

+| toScript |Specifies the output script.|*Required parameter*|

+* You can query the service for `transliteration` scope [supported languages](../reference/v3-0-languages.md).

+* *See also* [Language support for transliteration](../language-support.md#transliteration).

+## Request headers

+| Headers | Description |Condition|

+| | | |

+| Authentication headers | *See* [available options for authentication](../reference/v3-0-reference.md#authentication)|*Required request header*|

+| Content-Type | Specifies the content type of the payload. Possible value: `application/json` |*Required request header*|

+| Content-Length |The length of the request body. |*Optional*|

+| X-ClientTraceId |A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named `ClientTraceId`. |*Optional*|

+## Response body

+A successful response is a JSON array with one result for each element in the input array. A result object includes the following properties:

+* `text`: A string that results from converting the input string to the output script.

+* `script`: A string specifying the script used in the output.

+## Response headers

+| Headers | Description |

+| | |

+| X-RequestId | Value generated by the service to identify the request. It can be used for troubleshooting purposes. |

+### Sample request

+```http

+https://api.cognitive.microsofttranslator.com/transliterate?api-version=3.0&language=ja&fromScript=Jpan&toScript=Latn

+```

+### Sample request body

+The body of the request is a JSON array. Each array element is a JSON object with a string property named `Text`, which represents the string to convert.

+```json

+[

+ {"Text":"πüôπéôπü½πüíπü»"},

+ {"Text":"さようなら"}

+]

+```

+The following limitations apply:

+* The array can have a maximum of 10 elements.

+* The text value of an array element can't exceed 1,000 characters including spaces.

+* The entire text included in the request can't exceed 5,000 characters including spaces.

+### Sample JSON response:

+```json

+[

+ {

+ "text": "Kon'nichiwaΓÇï",

+ "script": "Latn"

+ },

+ {

+ "text": "sayonara",

+ "script": "Latn"

+ }

+]

+```

+## Code samples: transliterate text

+> [!NOTE]

+>

+> * Each sample runs on the `localhost` that you specified with the `docker run` command.

+> * While your container is running, `localhost` points to the container itself.

+> * You don't have to use `localhost:5000`. You can use any port that is not already in use in your host environment.

+> To specify a port, use the `-p` option.

+### Transliterate with REST API

+```rest

+ POST https://api.cognitive.microsofttranslator.com/transliterate?api-version=3.0&language=ja&fromScript=Jpan&toScript=Latn HTTP/1.1

+ Ocp-Apim-Subscription-Key: ba6c4278a6c0412da1d8015ef9930d44

+ Content-Type: application/json

+ [

+ {"Text":"πüôπéôπü½πüíπü»"},

+ {"Text":"さようなら"}

+ ]

+```

+## Next Steps

+> [!div class="nextstepaction"]

+> [Learn more about text transliteration](../translator-text-apis.md#transliterate-text)

+description: Get answers to Document Translation frequently asked questions.

+When text is translated from the source to target language, the overall length of translated text can differ from source. The result could be reflow of text across pages. The same fonts aren't always available in both source and target language. In general, the same font style is applied in target language to retain formatting closer to source.

+&#8203;No. The text in an image within a document isn't translated.

+&#8203;No. The service can't translate encrypted or password-protected documents. If your scanned or text-embedded PDFs are password-locked, you must remove the lock before submission.

+&#8203;No. Don't include SAS token-appended URLs. Managed identities eliminate the need for you to include shared access signature tokens (SAS) with your HTTP requests.

+* When using a compute instance with a managed network, you can't connect to the compute instance using SSH.

+ Title: How to configure a private link for Azure AI hub

+description: Learn how to configure a private link for Azure AI hub. A private link is used to secure communication with the AI hub.

+# Customer intent: As an admin, I want to configure a private link for Azure AI hub so that I can secure my Azure AI hub resources.

+# How to configure a private link for Azure AI hub

+We have two network isolation aspects. One is the network isolation to access an Azure AI hub. Another is the network isolation of computing resources in your Azure AI hub and Azure AI projects such as compute instances, serverless, and managed online endpoints. This article explains the former highlighted in the diagram. You can use private link to establish the private connection to your Azure AI hub and its default resources. This article is for Azure AI Studio (AI hub and AI projects). For information on Azure AI Services, see the [Azure AI Services documentation](/azure/ai-services/cognitive-services-virtual-networks).

+You get several Azure AI hub default resources in your resource group. You need to configure following network isolation configurations.

+- Disable public network access of Azure AI hub default resources such as Azure Storage, Azure Key Vault, and Azure Container Registry.

+- Establish private endpoint connection to Azure AI hub default resources. You need to have both a blob and file private endpoint for the default storage account.

+- Azure AI Services and Azure AI Search should be public.

+* You must have an existing Azure Virtual Network to create the private endpoint in.

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

+1. From the [Azure portal](https://portal.azure.com), go to Azure AI Studio and choose __+ New Azure AI__.

+1. Choose network isolation mode in __Networking__ tab.

+1. Scroll down to __Workspace Inbound access__ and choose __+ Add__.

+1. Input required fields. When selecting the __Region__, select the same region as your virtual network.

+After creating the Azure AI hub, use the [Azure networking CLI commands](/cli/azure/network/private-endpoint#az-network-private-endpoint-create) to create a private link endpoint for the Azure AI.

+## Add a private endpoint to an Azure AI hub

+Use one of the following methods to add a private endpoint to an existing Azure AI hub:

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

+1. From the [Azure portal](https://portal.azure.com), select your Azure AI hub.

+1. From the left side of the page, select __Networking__ and then select the __Private endpoint connections__ tab.

+1. When selecting the __Region__, select the same region as your virtual network.

+1. When selecting __Resource type__, use `azuremlworkspace`.

+1. Set the __Resource__ to your workspace name.

+Finally, select __Create__ to create the private endpoint.

+Use the [Azure networking CLI commands](/cli/azure/network/private-endpoint#az-network-private-endpoint-create) to create a private link endpoint for the Azure AI hub.

+You can remove one or all private endpoints for an Azure AI hub. Removing a private endpoint removes the Azure AI hub from the Azure Virtual Network that the endpoint was associated with. Removing the private endpoint might prevent the Azure AI hub from accessing resources in that virtual network, or resources in the virtual network from accessing the workspace. For example, if the virtual network doesn't allow access to or from the public internet.

+> Removing the private endpoints for an AI hub __doesn't make it publicly accessible__. To make the AI hub publicly accessible, use the steps in the [Enable public access](#enable-public-access) section.

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

+1. From the [Azure portal](https://portal.azure.com), select your Azure AI hub.

+1. From the left side of the page, select __Networking__ and then select the __Private endpoint connections__ tab.

+1. Select the endpoint to remove and then select __Remove__.

+In some situations, you might want to allow someone to connect to your secured Azure AI hub over a public endpoint, instead of through the virtual network. Or you might want to remove the workspace from the virtual network and re-enable public access.

+> Enabling public access doesn't remove any private endpoints that exist. All communications between components behind the virtual network that the private endpoint(s) connect to are still secured. It enables public access only to the Azure AI hub, in addition to the private access through any private endpoints.

+1. From the [Azure portal](https://portal.azure.com), select your Azure AI hub.

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

+Not available in AI CLI, but you can use [Azure Machine Learning CLI](../../machine-learning/how-to-configure-private-link.md#enable-public-access). Use your Azure AI hub name as workspace name in Azure Machine Learning CLI.

+A manged identity configuration is required if you make your storage account private. Our services need to read/write data in your private storage account using [Allow Azure services on the trusted services list to access this storage account](../../storage/common/storage-network-security.md#grant-access-to-trusted-azure-services) with following managed identity configurations. Enable the system assigned managed identity of Azure AI Service and Azure AI Search, then configure role-based access control for each managed identity.

+| `Storage File Data Privileged Contributor` | Azure AI project | Storage Account | Read/Write prompt flow data. | [Prompt flow doc](../../machine-learning/prompt-flow/how-to-secure-prompt-flow.md#secure-prompt-flow-with-workspace-managed-virtual-network) |

+| `Storage Blob Data Contributor` | Azure AI Search | Storage Account | Read blob and write knowledge store | [Search doc](../../search/search-howto-managed-identities-data-sources.md). |

+See [Azure Machine Learning custom DNS](../../machine-learning/how-to-custom-dns.md#example-custom-dns-server-hosted-in-vnet) article for the DNS forwarding configurations.

+If you need to configure custom DNS server without DNS forwarding, use the following patterns for the required A records.

+To find the private IP addresses for your A records, see the [Azure Machine Learning custom DNS](../../machine-learning/how-to-custom-dns.md#find-the-ip-addresses) article.

+To check AI-PROJECT-GUID, go to the Azure portal, select your Azure AI project, settings, properties, and the workspace ID is displayed.

+* Private Azure AI Services and Azure AI Search aren't supported.

+* You might encounter problems trying to access the private endpoint for your Azure AI hub if you're using Mozilla Firefox. This problem might be related to DNS over HTTPS in Mozilla Firefox. We recommend using Microsoft Edge or Google Chrome.

+- [Create an Azure AI project](create-projects.md)

+python --version # use version 3.8 or later

+## Create an index from the Indexes tab

+1. Choose your **Source data**. You can choose source data from a list of your recent data sources, a storage URL on the cloud, or upload files and folders from the local machine. You can also add a connection to another data source such as Azure Blob Storage.

+ 1. The ***Vector settings*** defaults to true for Add vector search to this search resource. As noted, this enables Hybrid and Hybrid + Semantic search options. Disabling this limits vector search options to Keyword and Semantic.

+ 1. For the hybrid option to work, you need an embedding model. Choose an embedding model from the dropdown.

+

+ If a non-Azure OpenAI model isn't appearing in the dropdown follow these steps:

+ 1. Navigate to the Project settings in [Azure AI Studio](https://ai.azure.com).

+ 1. Navigate to connections section in the settings tab and select New connection.

+ 1. Select **Serverless Model**.

+ 1. Type in the name of your embedding model deployment and select Add connection. If the model doesn't appear in the dropdown, select the **Enter manually** option.

+ 1. Enter the deployment API endpoint, model name, and API key in the corresponding fields. Then add connection.

+ 1. The embedding model should now appear in the dropdown.

+

+ :::image type="content" source="../media/index-retrieve/serverless-connection.png" alt-text="Screenshot of connect a serverless model." lightbox="../media/index-retrieve/serverless-connection.png":::

+ 1. Schedule updates. You can choose to update the index hourly or daily.

+## Create an index from the Playground

+1. Open your AI Studio project.

+1. Navigate to the Playground tab.

+1. The Select available project index is displayed for existing indexes in the project. If an existing index isn't being used, continue to the next steps.

+1. Select the Add your data dropdown.

+

+ :::image type="content" source="../media/index-retrieve/add-data-dropdown.png" alt-text="Screenshot of the playground add your data dropdown." lightbox="../media/index-retrieve/add-data-dropdown.png":::

+1. If a new index is being created, select the ***Add your data*** option. Then follow the steps from ***Create an index from the Indexes tab*** to navigate through the wizard to create an index.

+ 1. If there's an external index that is being used, select the ***Connect external index*** option.

+ 1. In the **Index Source**

+ 1. Select your data source

+ 1. Select your AI Search Service

+ 1. Select the index to be used.

+ :::image type="content" source="../media/index-retrieve/connect-external-index.png" alt-text="Screenshot of the page where you select an index." lightbox="../media/index-retrieve/connect-external-index.png":::

+

+ 1. Select **Next** after configuring search settings.

+ 1. In the **Index settings**

+ 1. Enter a name for your index or use the autopopulated name

+ 1. Schedule updates. You can choose to update the index hourly or daily.

+ 1. Choose the compute where you want to run the jobs to create the index. You can

+ - Auto select to allow Azure AI to choose an appropriate VM size that is available

+ - Choose a VM size from a list of recommended options

+ - Choose a VM size from a list of all possible options

+ 1. Review the details you entered and select **Create.**

+ 1. The index is now ready to be used in the Playground.

+ :::image type="content" source="../media/index-retrieve/configure-index-lookup-tool.png" alt-text="Screenshot of the prompt flow node to configure index lookup." lightbox="../media/index-retrieve/configure-index-lookup-tool.png":::

+- [Learn more about RAG](../concepts/retrieval-augmented-generation.md)

+description: This article introduces you to the Azure OpenAI GPT-4 Turbo with Vision tool for flows in Azure AI Studio.

+The prompt flow Azure OpenAI GPT-4 Turbo with Vision tool enables you to use your Azure OpenAI GPT-4 Turbo with Vision model deployment to analyze images and provide textual responses to questions about them.

+- An Azure subscription. <a href="https://azure.microsoft.com/free/cognitive-services" target="_blank">You can create one for free</a>.

+ Currently, you must apply for access to this service. To apply for access to Azure OpenAI, complete the form at <a href="https://aka.ms/oai/access" target="_blank">https://aka.ms/oai/access</a>. Open an issue on this repo to contact us if you have an issue.

+- An [Azure AI hub resource](../../how-to/create-azure-ai-resource.md) with a GPT-4 Turbo with Vision model deployed in [one of the regions that support GPT-4 Turbo with Vision](../../../ai-services/openai/concepts/models.md#model-summary-table-and-region-availability). When you deploy from your project's **Deployments** page, select `gpt-4` as the model name and `vision-preview` as the model version.

+ :::image type="content" source="../../media/prompt-flow/azure-openai-gpt-4-vision-tool.png" alt-text="Screenshot that shows the Azure OpenAI GPT-4 Turbo with Vision tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/azure-openai-gpt-4-vision-tool.png":::

+1. Enter values for the Azure OpenAI GPT-4 Turbo with Vision tool input parameters described in the [Inputs table](#inputs). For example, you can use this example prompt:

+1. Specify an image to analyze in the `image_input` input parameter. For example, you can upload an image or enter the URL of an image to analyze. Otherwise, you can paste or drag and drop an image into the tool.

+1. Add more tools to your flow, as needed. Or select **Run** to run the flow.

+The outputs are described in the [Outputs table](#outputs).

+The following input parameters are available.

+| prompt | string | The text prompt that the language model uses to generate its response. The Jinja template for composing prompts in this tool follows a similar structure to the chat API in the large language model (LLM) tool. To represent an image input within your prompt, you can use the syntax ``. Image input can be passed in the `user`, `system`, and `assistant` messages. | Yes |

+| max\_tokens | integer | The maximum number of tokens to generate in the response. Default is 512. | No |

+| temperature | float | The randomness of the generated text. Default is 1. | No |

+| stop | list | The stopping sequence for the generated text. Default is null. | No |

+| top_p | float | The probability of using the top choice from the generated tokens. Default is 1. | No |

+| presence\_penalty | float | The value that controls the model's behavior regarding repeating phrases. Default is 0. | No |

+| frequency\_penalty | float | The value that controls the model's behavior regarding generating rare phrases. Default is 0. | No |

+The following output parameters are available.

+| Return type | Description |

+## Next steps

+- Learn more about [how to create a flow](../flow-develop.md).

+description: This article introduces you to the Content Safety tool for flows in Azure AI Studio.

+The prompt flow Content Safety tool enables you to use Azure AI Content Safety in Azure AI Studio.

+To create an Azure Content Safety connection:

+1. Complete all steps in the **Create a new connection** dialog. You can use an Azure AI hub resource or Azure AI Content Safety resource. We recommend that you use an Azure AI hub resource that supports multiple Azure AI services.

+ :::image type="content" source="../../media/prompt-flow/content-safety-tool.png" alt-text="Screenshot that shows the Content Safety tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/content-safety-tool.png":::

+1. Enter values for the Content Safety tool input parameters described in the [Inputs table](#inputs).

+1. Add more tools to your flow, as needed. Or select **Run** to run the flow.

+1. The outputs are described in the [Outputs table](#outputs).

+The following input parameters are available.

+| hate_category | string | The moderation sensitivity for the Hate category. You can choose from four options: `disable`, `low_sensitivity`, `medium_sensitivity`, or `high_sensitivity`. The `disable` option means no moderation for the Hate category. The other three options mean different degrees of strictness in filtering out hate content. The default option is `medium_sensitivity`. | Yes |

+| sexual_category | string | The moderation sensitivity for the Sexual category. You can choose from four options: `disable`, `low_sensitivity`, `medium_sensitivity`, or `high_sensitivity`. The `disable` option means no moderation for the Sexual category. The other three options mean different degrees of strictness in filtering out sexual content. The default option is `medium_sensitivity`. | Yes |

+| self_harm_category | string | The moderation sensitivity for the Self-harm category. You can choose from four options: `disable`, `low_sensitivity`, `medium_sensitivity`, or `high_sensitivity`. The `disable` option means no moderation for the Self-harm category. The other three options mean different degrees of strictness in filtering out self-harm content. The default option is `medium_sensitivity`. | Yes |

+| violence_category | string | The moderation sensitivity for the Violence category. You can choose from four options: `disable`, `low_sensitivity`, `medium_sensitivity`, or `high_sensitivity`. The `disable` option means no moderation for the Violence category. The other three options mean different degrees of strictness in filtering out violence content. The default option is `medium_sensitivity`. | Yes |

+You can use the following parameters as inputs for this tool.

+| action_by_category | string | A binary value for each category: `Accept` or `Reject`. This value shows if the text meets the sensitivity level that you set in the request parameters for that category. |

+| suggested_action | string | An overall recommendation based on the four categories. If any category has a `Reject` value, `suggested_action` is also `Reject`. |

+description: This article introduces you to the Embedding tool for flows in Azure AI Studio.

+The prompt flow Embedding tool enables you to convert text into dense vector representations for various natural language processing tasks.

+> For chat and completion tools, learn more about the large language model [(LLM) tool](llm-tool.md).

+ :::image type="content" source="../../media/prompt-flow/embedding-tool.png" alt-text="Screenshot that shows the Embedding tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/embedding-tool.png":::

+1. Enter values for the Embedding tool input parameters described in the [Inputs table](#inputs).

+1. Add more tools to your flow, as needed. Or select **Run** to run the flow.

+1. The outputs are described in the [Outputs table](#outputs).

+The following input parameters are available.

+| input | string | The input text to embed. | Yes |

+| model, deployment_name | string | The instance of the text-embedding engine to use. | Yes |

+- [Learn more about how to create a flow](../flow-develop.md)

+> Vector, Vector DB and Faiss Index Lookup tools are deprecated and will be retired soon. [Migrated to the new Index Lookup tool (preview).](index-lookup-tool.md#migrate-from-legacy-tools-to-the-index-lookup-tool)

+description: This article introduces you to the Index Lookup tool for flows in Azure AI Studio.

+The prompt flow Index Lookup tool enables the use of common vector indices (such as Azure AI Search, Faiss, and Pinecone) for retrieval augmented generation in prompt flow. The tool automatically detects the indices in the workspace and allows the selection of the index to be used in the flow.

+ :::image type="content" source="../../media/prompt-flow/configure-index-lookup-tool.png" alt-text="Screenshot that shows the Index Lookup tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/configure-index-lookup-tool.png":::

+1. Enter values for the Index Lookup tool [input parameters](#inputs). The large language model [(LLM) tool](llm-tool.md) can generate the vector input.

+1. Add more tools to your flow, as needed. Or select **Run** to run the flow.

+1. To learn more about the returned output, see the [Outputs table](#outputs).

+The following input parameters are available.

+| mlindex_content | string | The type of index to be used. Input depends on the index type. An example of an Azure AI Search index JSON can be seen underneath the table. | Yes |

+Here's an example of an Azure AI Search index input:

+The following JSON format response is an example returned by the tool that includes the top-k scored entities. The entity follows a generic schema of vector search results provided by the `promptflow-vectordb` SDK. For the Vector Index Search, the following fields are populated:

+| Field name | Type | Description |

+| metadata | dict | The customized key-value pairs provided by the user when creating the index. |

+| page_content | string | The content of the vector chunk being used in the lookup. |

+| score | float | Depends on the index type defined in the Vector Index. If the index type is Faiss, the score is L2 distance. If the index type is Azure AI Search, the score is cosine similarity. |

+## Migrate from legacy tools to the Index Lookup tool

+The Index Lookup tool looks to replace the three deprecated legacy index tools: the [Vector Index Lookup tool](./vector-index-lookup-tool.md), the [Vector DB Lookup tool](./vector-db-lookup-tool.md), and the [Faiss Index Lookup tool](./faiss-index-lookup-tool.md).

+If you have a flow that contains one of these tools, follow the next steps to upgrade your flow.

+1. To update your runtime, go to the AI project **Settings** tab on the left pane in AI Studio. In the list of prompt flow runtimes that appears, select the name of the runtime you want to update. Then select **Update**. Wait for the runtime to update itself.

+1. To go to your flow, select the **Prompt flow** tab on the left pane in AI Studio. Select the **Flows** tab, and then select the name of your flow.

+1. Inside the flow, select **+ More tools**. In the dropdown list, select **Index Lookup** [Preview] to add an instance of the Index Lookup tool.

+ :::image type="content" source="../../media/prompt-flow/upgrade-index-tools/index-dropdown.png" alt-text="Screenshot that shows the More tools dropdown list in the prompt flow." lightbox="../../media/prompt-flow/upgrade-index-tools/index-dropdown.png":::

+1. Name the new node and select **Add**.

+ :::image type="content" source="../../media/prompt-flow/upgrade-index-tools/save-node.png" alt-text="Screenshot that shows the Index Lookup node with a name." lightbox="../../media/prompt-flow/upgrade-index-tools/save-node.png":::

+1. In the new node, select the **mlindex_content** textbox. It should be the first textbox in the list.

+ :::image type="content" source="../../media/prompt-flow/upgrade-index-tools/mlindex-box.png" alt-text="Screenshot that shows the expanded Index Lookup node with the mlindex_content textbox." lightbox="../../media/prompt-flow/upgrade-index-tools/mlindex-box.png":::

+1. In **Generate**, follow these steps to upgrade from the three legacy tools:

+ - **Vector Index Lookup**: Select **Registered Index** in the **index_type** dropdown. Select your vector index asset from the **mlindex_asset_id** dropdown list.

+ - **Faiss Index Lookup**: Select **Faiss** in the **index_type** dropdown list. Specify the same path as in the legacy tool.

+ - **Vector DB Lookup**: Select AI Search or Pinecone depending on the DB type in the **index_type** dropdown list. Fill in the information, as necessary.

+1. Select **Save**.

+1. Back in the node, information is now populated in the **mlindex_content** textbox. Select the **queries** textbox and select the search terms you want to query. Select the same value as the input to the **embed_the_question** node. This value is typically either `\${inputs.question}` or `${modify_query_with_history.output}`. Use `\${inputs.question}` if you're in a standard flow. Use `${modify_query_with_history.output}` if you're in a chat flow.

+ :::image type="content" source="../../media/prompt-flow/upgrade-index-tools/mlindex-with-content.png" alt-text="Screenshot that shows the expanded Index Lookup node with index information in the cells." lightbox="../../media/prompt-flow/upgrade-index-tools/mlindex-with-content.png":::

+1. Select a query type by selecting the dropdown next to **query_type**. **Vector** produces identical results as the legacy flow. Depending on your index configuration, other options such as **Hybrid** and **Semantic** might be available.

+ :::image type="content" source="../../media/prompt-flow/upgrade-index-tools/vector-search.png" alt-text="Screenshot that shows the expanded Index Lookup node with Vector search." lightbox="../../media/prompt-flow/upgrade-index-tools/vector-search.png":::

+1. Edit downstream components to consume the output of your newly added node, instead of the output of the legacy Vector Index Lookup node.

+1. Delete the Vector Index Lookup node and its parent embedding node.

+description: This article introduces you to the large language model (LLM) tool for flows in Azure AI Studio.

+To use large language models (LLMs) for natural language processing, you use the prompt flow LLM tool.

+Prepare a prompt as described in the [Prompt tool](prompt-tool.md#prerequisites) documentation. The LLM tool and Prompt tool both support [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) templates. For more information and best practices, see [Prompt engineering techniques](../../../ai-services/openai/concepts/advanced-prompt-engineering.md).

+ :::image type="content" source="../../media/prompt-flow/llm-tool.png" alt-text="Screenshot that shows the LLM tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/llm-tool.png":::

+1. From the **Api** dropdown list, select **chat** or **completion**.

+1. Enter values for the LLM tool input parameters described in the [Text completion inputs table](#inputs). If you selected the **chat** API, see the [Chat inputs table](#chat-inputs). If you selected the **completion** API, see the [Text completion inputs table](#text-completion-inputs). For information about how to prepare the prompt input, see [Prerequisites](#prerequisites).

+1. Add more tools to your flow, as needed. Or select **Run** to run the flow.

+1. The outputs are described in the [Outputs table](#outputs).

+The following input parameters are available.

+| prompt | string | Text prompt for the language model. | Yes |

+| model, deployment_name | string | The language model to use. | Yes |

+| max\_tokens | integer | The maximum number of tokens to generate in the completion. Default is 16. | No |

+| temperature | float | The randomness of the generated text. Default is 1. | No |

+| stop | list | The stopping sequence for the generated text. Default is null. | No |

+| suffix | string | The text appended to the end of the completion. | No |

+| top_p | float | The probability of using the top choice from the generated tokens. Default is 1. | No |

+| logprobs | integer | The number of log probabilities to generate. Default is null. | No |

+| echo | boolean | The value that indicates whether to echo back the prompt in the response. Default is false. | No |

+| presence\_penalty | float | The value that controls the model's behavior regarding repeating phrases. Default is 0. | No |

+| frequency\_penalty | float | The value that controls the model's behavior regarding generating rare phrases. Default is 0. | No |

+| best\_of | integer | The number of best completions to generate. Default is 1. | No |

+| logit\_bias | dictionary | The logit bias for the language model. Default is empty dictionary. | No |

+| prompt | string | The text prompt that the language model should reply to. | Yes |

+| model, deployment_name | string | The language model to use. | Yes |

+| max\_tokens | integer | The maximum number of tokens to generate in the response. Default is inf. | No |

+| temperature | float | The randomness of the generated text. Default is 1. | No |

+| stop | list | The stopping sequence for the generated text. Default is null. | No |

+| top_p | float | The probability of using the top choice from the generated tokens. Default is 1. | No |

+| presence\_penalty | float | The value that controls the model's behavior regarding repeating phrases. Default is 0. | No |

+| frequency\_penalty | float | The value that controls the model's behavior regarding generating rare phrases. Default is 0. | No |

+| logit\_bias | dictionary | The logit bias for the language model. Default is empty dictionary. | No |

+| API | Return type | Description |

+| Completion | string | The text of one predicted completion. |

+| Chat | string | The text of one response of conversation. |

+The following table provides an index of tools in prompt flow.

+| Tool name | Description | Package name |

+| [LLM](./llm-tool.md) | Use large language models (LLM) with the Azure OpenAI Service for tasks such as text completion or chat. | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

+| [Prompt](./prompt-tool.md) | Craft a prompt by using Jinja as the templating language. | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

+| [Python](./python-tool.md) | Run Python code. | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

+| [Azure OpenAI GPT-4 Turbo with Vision](./azure-open-ai-gpt-4v-tool.md) | Use an Azure OpenAI GPT-4 Turbo with Vision model deployment to analyze images and provide textual responses to questions about them. | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

+| [Content Safety (Text)](./content-safety-tool.md) | Use Azure AI Content Safety to detect harmful content. | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

+| [Embedding](./embedding-tool.md) | Use Azure OpenAI embedding models to create an embedding vector that represents the input text. | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

+| [Serp API](./serp-api-tool.md) | Use Serp API to obtain search results from a specific search engine. | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

+| [Index Lookup](./index-lookup-tool.md) | Search a vector-based query for relevant results using one or more text queries. | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |

+| [Vector Index Lookup](./vector-index-lookup-tool.md)¹ | Search text or a vector-based query from a vector index. | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |

+| [Faiss Index Lookup](./faiss-index-lookup-tool.md)¹ | Search a vector-based query from the Faiss index file. | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |

+| [Vector DB Lookup](./vector-db-lookup-tool.md)¹ For | Search a vector-based query from an existing vector database. | [promptflow-vectordb](https://pypi.org/project/promptflow-vectordb/) |

+¹ The Index Lookup tool replaces the three deprecated legacy index tools: Vector Index Lookup, Vector DB Lookup, and Faiss Index Lookup. If you have a flow that contains one of those tools, follow the [migration steps](./index-lookup-tool.md#migrate-from-legacy-tools-to-the-index-lookup-tool) to upgrade your flow.

+## Custom tools

+To discover more custom tools developed by the open-source community such as [Azure AI Language tools](https://pypi.org/project/promptflow-azure-ai-language/), see [More custom tools](https://microsoft.github.io/promptflow/integrations/tools/https://docsupdatetracker.net/index.html).

+- To install the custom tools, if you're using the automatic runtime, you can readily install the publicly released package by adding the custom tool package name in the `requirements.txt` file in the flow folder. Then select **Save and install** to start installation. After completion, the custom tools appear in the tool list. If you want to use a local or private feed package, build an image first, and then set up the runtime based on your image. To learn more, see [How to create and manage a runtime](../create-manage-runtime.md).

+ :::image type="content" source="../../media/prompt-flow/install-package-on-automatic-runtime.png" alt-text="Screenshot that shows how to install packages on automatic runtime."lightbox = "../../media/prompt-flow/install-package-on-automatic-runtime.png":::

+description: This article introduces you to the Prompt tool for flows in Azure AI Studio.

+The prompt flow Prompt tool offers a collection of textual templates that serve as a starting point for creating prompts. These templates, based on the [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) template engine, facilitate the definition of prompts. The tool proves useful when prompt tuning is required before the prompts are fed into the large language model (LLM) in the prompt flow.

+Prepare a prompt. The [LLM tool](llm-tool.md) and Prompt tool both support [Jinja](https://jinja.palletsprojects.com/en/3.1.x/) templates.

+In this example, the prompt incorporates Jinja templating syntax to dynamically generate the welcome message and personalize it based on the user's name. It also presents a menu of options for the user to choose from. Depending on whether the `user_name` variable is provided, it either addresses the user by name or uses a generic greeting.

+For more information and best practices, see [Prompt engineering techniques](../../../ai-services/openai/concepts/advanced-prompt-engineering.md).

+ :::image type="content" source="../../media/prompt-flow/prompt-tool.png" alt-text="Screenshot that shows the Prompt tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/prompt-tool.png":::

+1. Enter values for the Prompt tool input parameters described in the [Inputs table](#inputs). For information about how to prepare the prompt input, see [Prerequisites](#prerequisites).

+1. Add more tools (such as the [LLM tool](llm-tool.md)) to your flow, as needed. Or select **Run** to run the flow.

+1. The outputs are described in the [Outputs table](#outputs).

+The following input parameters are available.

+| prompt | string | The prompt template in Jinja. | Yes |

+| Inputs | - | The list of variables of a prompt template and its assignments. | - |

+Inputs:

+| Variable | Type | Sample value |

+Outputs:

+Inputs:

+| Variable | Type | Sample value |

+Outputs:

+description: This article introduces you to the Python tool for flows in Azure AI Studio.

+The prompt flow Python tool offers customized code snippets as self-contained executable nodes. You can quickly create Python tools, edit code, and verify results.

+ :::image type="content" source="../../media/prompt-flow/python-tool.png" alt-text="Screenshot that shows the Python tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/python-tool.png":::

+1. Enter values for the Python tool input parameters that are described in the [Inputs table](#inputs). For example, in the **Code** input text box, you can enter the following Python code:

+1. Add more tools to your flow, as needed. Or select **Run** to run the flow.

+1. The outputs are described in the [Outputs table](#outputs). Based on the previous example Python code input, if the input message is "world," the output is `hello world`.

+The list of inputs change based on the arguments of the tool function, after you save the code. Adding type to arguments and `return` values helps the tool show the types properly.

+| Code | string | The Python code snippet. | Yes |

+| Inputs | - | The list of the tool function parameters and its assignments. | - |

+The output is the `return` value of the Python tool function. For example, consider the following Python tool function:

+If the input message is "world," the output is `hello world`.

+| Connection | param: CustomConnection | Connection type is handled specially. |

+Parameters with `Connection` type annotation are treated as connection inputs, which means:

+- The prompt flow extension shows a selector to select the connection.

+- During execution time, the prompt flow tries to find the connection with the same name from the parameter value that was passed in.

+> [!NOTE]

+> The `Union[...]` type annotation is only supported for connection type. An example is `param: Union[CustomConnection, OpenAIConnection]`.

+- Python tool code should consist of a complete Python code, including any necessary module imports.

+- Python tool code must contain a function decorated with `@tool` (tool function), serving as the entry point for execution. The `@tool` decorator should be applied only once within the snippet.

+- Python tool function parameters must be assigned in the `Inputs` section.

+## Consume a custom connection in the Python tool

+If you're developing a Python tool that requires calling external services with authentication, you can use the custom connection in a prompt flow. It allows you to securely store the access key and then retrieve it in your Python code.

+Create a custom connection that stores all your large language model API key or other required credentials.

+1. Go to **AI project settings**. Then select **New Connection**.

+1. Select **Custom** service. You can define your connection name. You can add multiple key-value pairs to store your credentials and keys by selecting **Add key-value pairs**.

+ > Make sure at least one key-value pair is set as secret. Otherwise, the connection won't be created successfully. To set one key-value pair as secret, select **is secret** to encrypt and store your key value.

+ :::image type="content" source="../../media/prompt-flow/create-connection.png" alt-text="Screenshot that shows creating a connection in AI Studio." lightbox = "../../media/prompt-flow/create-connection.png":::

+ :::image type="content" source="../../media/prompt-flow/custom-connection-keys.png" alt-text="Screenshot that shows adding extra information to a custom connection in AI Studio." lightbox = "../../media/prompt-flow/custom-connection-keys.png":::

+### Consume a custom connection in Python

+To consume a custom connection in your Python code:

+1. In the code section in your Python node, import the custom connection library `from promptflow.connections import CustomConnection`. Define an input parameter of the type `CustomConnection` in the tool function.

+1. Parse the input to the input section. Then select your target custom connection in the value dropdown list.

+description: This article introduces you to the Serp API tool for flows in Azure AI Studio.

+The prompt flow Serp API tool provides a wrapper to the [Serp API Google Search Engine Results API](https://serpapi.com/search-api) and [Serp API Bing Search Engine Results API](https://serpapi.com/bing-search-api).

+You can use the tool to retrieve search results from many different search engines, including Google and Bing. You can specify a range of search parameters, such as the search query, location, and device type.

+Sign up on the [Serp API home page](https://serpapi.com/).

+To create a Serp connection:

+ - `api_key`: Your Serp API key. You must select the **is secret** checkbox to keep the API key secure.

+ :::image type="content" source="../../media/prompt-flow/serp-custom-connection-keys.png" alt-text="Screenshot that shows adding extra information to a custom connection in AI Studio." lightbox = "../../media/prompt-flow/serp-custom-connection-keys.png":::

+The connection is the model used to establish connections with the Serp API. Get your API key from the Serp API account dashboard.

+| Type | Name | API key |

+ :::image type="content" source="../../media/prompt-flow/serp-api-tool.png" alt-text="Screenshot that shows the Serp API tool added to a flow in Azure AI Studio." lightbox="../../media/prompt-flow/serp-api-tool.png":::

+1. Enter values for the Serp API tool input parameters described in the [Inputs table](#inputs).

+1. Add more tools to your flow, as needed. Or select **Run** to run the flow.

+1. The outputs are described in the [Outputs table](#outputs).

+The following input parameters are available.

+| location | string | The geographic location from which to execute the search. | No |

+The JSON representation from a `serpapi` query:

+| Engine | Return type | Output |

+> Vector, Vector DB and Faiss Index Lookup tools are deprecated and will be retired soon. [Migrated to the new Index Lookup tool (preview).](index-lookup-tool.md#migrate-from-legacy-tools-to-the-index-lookup-tool)

+> Vector, Vector DB and Faiss Index Lookup tools are deprecated and will be retired soon. [Migrated to the new Index Lookup tool (preview).](index-lookup-tool.md#migrate-from-legacy-tools-to-the-index-lookup-tool)

+- An [Azure AI hub resource](../how-to/create-azure-ai-resource.md) with a GPT-4 Turbo with Vision model deployed in one of the [regions that support GPT-4 Turbo with Vision](../../ai-services/openai/concepts/models.md#gpt-4-and-gpt-4-turbo-preview-model-availability). When you deploy from your Azure AI project's **Deployments** page, select: `gpt-4` as the model name and `vision-preview` as the model version.

+ > Evaluation with AI-assisted metrics needs to call another GPT model to do the calculation. For best performance, use a model that supports at least 16k tokens such as gpt-4-32k or gpt-35-turbo-16k model. If you didn't previously deploy such a model, you can deploy another model by following the steps in [Deploy a chat model](#deploy-a-chat-model). Then return to this step and select the model you deployed.

+ Title: Use the Azure Kubernetes Service (AKS) extension for Visual Studio Code

+description: Learn how to the Azure Kubernetes Service (AKS) extension for Visual Studio Code to manage your Kubernetes clusters.

+# Use the Azure Kubernetes Service (AKS) extension for Visual Studio Code

+The Azure Kubernetes Service (AKS) extension for Visual Studio Code allows you to easily view and manage your AKS clusters from your development environment.

+## Features

+The Azure Kubernetes Service (AKS) extension for Visual Studio Code provides a rich set of features to help you manage your AKS clusters, including:

+* **Merge into Kubeconfig**: Merge your AKS cluster into your `kubeconfig` file to manage your cluster from the command line.

+* **Save Kubeconfig**: Save your AKS cluster configuration to a file.

+* **AKS Diagnostics**: View diagnostics information based on your cluster's backend telemetry for identity, security, networking, node health, and create, upgrade, delete, and scale issues.

+* **AKS Periscope**: Extract detailed diagnostic information and export it to an Azure storage account for further analysis.

+* **Install Azure Service Operator (ASO)**: Deploy the latest version of ASO and provision Azure resources within Kubernetes.

+* **Start or stop a cluster**: Start or stop your AKS cluster to save costs when you're not using it.

+For more information, see [AKS extension for Visual Studio Code features](https://code.visualstudio.com/docs/azure/aksextensions#_features).

+## Installation

+1. Open Visual Studio Code.

+2. In the **Extensions** view, search for **Azure Kubernetes Service**.

+3. Select the **Azure Kubernetes Service** extension and then select **Install**.

+For more information, see [Install the AKS extension for Visual Studio Code](https://code.visualstudio.com/docs/azure/aksextensions#_install-the-azure-kubernetes-services-extension).

+## Next steps

+To learn more about other AKS add-ons and extensions, see [Add-ons, extensions, and other integrations with AKS](./integrations.md).

+- The following snippet annotations are blocked and will prevent an Ingress from being configured: `load_module`, `lua_package`, `_by_lua`, `location`, `root`, `proxy_pass`, `serviceaccount`, `{`, `}`, `'`.

+|DiskIOPSReadWrite | [UltraSSD disk][ultra-ssd-disks] or [Premium SSD v2][premiumv2_lrs_disks] IOPS Capability (minimum: 2 IOPS/GiB) | 100~160000 | No | `500`|

+|DiskMBpsReadWrite | [UltraSSD disk][ultra-ssd-disks] or [Premium SSD v2][premiumv2_lrs_disks] Throughput Capability(minimum: 0.032/GiB) | 1~2000 | No | `100`|

+Reducing the size of a PVC is not supported due to the risk of data loss. You can edit an existing storage class using the `kubectl edit sc` command, or you can create your own custom storage class. For example, if you want to use a disk of size 4 TiB, you must create a storage class that defines `cachingmode: None` because [disk caching isn't supported for disks 4 TiB and larger][disk-host-cache-setting]. For more information about storage classes and creating your own storage class, see [Storage options for applications in AKS][storage-class-concepts].

+This section provides guidance for cluster administrators who want to create one or more persistent volumes that include details of Azure Disks for use by a workload.

+### Static provisioning parameters for a persistent volume

+The following table includes parameters you can use to define a persistent volume.

+ ```

+ The output of the command resembles the following example:

+

+ ```output

+1. Create a disk using the [`az disk create`][az-disk-create] command. Specify the node resource group name and a name for the disk resource, such as *myAKSDisk*. The following example creates a *20*GiB disk, and outputs the ID of the disk after it's created. If you need to create a disk for use with Windows Server containers, add the `--os-type windows` parameter to correctly format the disk.

+[premiumv2_lrs_disks]: ../virtual-machines/disks-types.md#premium-ssd-v2

+ Title: Concepts - Services in Azure Kubernetes Services (AKS)

+description: Learn about networking Services in Azure Kubernetes Service (AKS), including what services are in Kubernetes and what types of Services are available in AKS.

+# Kubernetes Services in AKS

+Kubernetes Services are used to logically group pods and provide network connectivity by allowing direct access to them through a specific IP address or DNS name on a designated port. This allows you to expose your application workloads to other services within the cluster or to external clients without having to manually manage the network configuration for each pod hosting a workload.

+You can specify a Kubernetes _ServiceType_ to define the type of Service you want, e.g., if you want to expose a Service on an external IP address outside of your cluster. For more information, see the Kubernetes documentation on [Publishing Services (ServiceTypes)][service-types].

+The following ServiceTypes are available in AKS:

+## ClusterIP

+

+ ClusterIP creates an internal IP address for use within the AKS cluster. The ClusterIP Service is good for _internal-only applications_ that support other workloads within the cluster. ClusterIP is used by default if you don't explicitly specify a type for a Service.

+ ![Diagram showing ClusterIP traffic flow in an AKS cluster.][aks-clusterip]

+## NodePort

+ NodePort creates a port mapping on the underlying node that allows the application to be accessed directly with the node IP address and port.

+ ![Diagram showing NodePort traffic flow in an AKS cluster.][aks-nodeport]

+## LoadBalancer

+ LoadBalancer creates an Azure load balancer resource, configures an external IP address, and connects the requested pods to the load balancer backend pool. To allow customers' traffic to reach the application, load balancing rules are created on the desired ports.

+ ![Diagram showing Load Balancer traffic flow in an AKS cluster.][aks-loadbalancer]

+ For HTTP load balancing of inbound traffic, another option is to use an [Ingress controller][ingress-controllers].

+## ExternalName

+ Creates a specific DNS entry for easier application access.

+Either the load balancers and services IP address can be dynamically assigned, or you can specify an existing static IP address. You can assign both internal and external static IP addresses. Existing static IP addresses are often tied to a DNS entry.

+You can create both _internal_ and _external_ load balancers. Internal load balancers are only assigned a private IP address, so they can't be accessed from the Internet.

+Learn more about Services in the [Kubernetes docs][k8s-service].

+<!-- IMAGES -->

+[aks-clusterip]: media/concepts-network/aks-clusterip.png

+[aks-nodeport]: media/concepts-network/aks-nodeport.png

+[aks-loadbalancer]: media/concepts-network/aks-loadbalancer.png

+<!-- LINKS - External -->

+[k8s-service]: https://kubernetes.io/docs/concepts/services-networking/service/

+[service-types]: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types

+<!-- LINKS - Internal -->

+[ingress-controllers]:concepts-network.md#ingress-controllers

+- You can connect to and expose applications internally or externally.

+- You can build highly available applications by load balancing your applications.

+- You can restrict the flow of network traffic into or between pods and nodes to improve security.

+- You can configure Ingress traffic for SSL/TLS termination or routing of multiple components for your more complex applications.

+- [Azure virtual networks](#azure-virtual-networks)

+- [Ingress controllers](#ingress-controllers)

+- [Network policies](#network-policies)

+- ***Kubenet* networking**

+- ***Azure Container Networking Interface (CNI)* networking**

+- **kubenet**

+ - Conserves IP address space.

+ - Uses Kubernetes internal or external load balancers to reach pods from outside of the cluster.

+ - You manually manage and maintain user-defined routes (UDRs).

+ - Maximum of 400 nodes per cluster.

+- **Azure CNI**

+- The Azure platform can automatically create and configure the virtual network resources when you create an AKS cluster.

+- You can manually create and configure the virtual network resources and attach to those resources when you create your AKS cluster.

+- If you manually create the virtual network resources for an AKS cluster, you're supported when configuring your own UDRs or service endpoints.

+- If the Azure platform automatically creates the virtual network resources for your AKS cluster, you can't manually change those AKS-managed resources to configure your own UDRs or service endpoints.

+- Easy configuration of managed NGINX Ingress controllers based on Kubernetes NGINX Ingress controller.

+- Integration with Azure DNS for public and private zone management.

+- SSL termination with certificates stored in Azure Key Vault.

+- Back-end applications are only exposed to required frontend services.

+- Database components are only accessible to the application tiers that connect to them.

+- [Kubernetes / AKS clusters and workloads][aks-concepts-clusters-workloads]

+- [Kubernetes / AKS access and identity][aks-concepts-identity]

+- [Kubernetes / AKS security][aks-concepts-security]

+- [Kubernetes / AKS storage][aks-concepts-storage]

+- [Kubernetes / AKS scale][aks-concepts-scale]

+

+ > The **Containers** category includes Kubernetes applications. This walkthrough is specific to Kubernetes applications.

+description: Deploy a Java application with Open Liberty or WebSphere Liberty on an AKS cluster by using the Azure Marketplace offer, which automatically provisions resources.

+# Deploy a Java application with Open Liberty or WebSphere Liberty on an Azure Kubernetes Service cluster

+* Run your Java, Java EE, Jakarta EE, or MicroProfile application on the [Open Liberty](https://openliberty.io/) or [IBM WebSphere Liberty](https://www.ibm.com/cloud/websphere-liberty) runtime.

+* Build the application's Docker image by using Open Liberty or WebSphere Liberty container images.

+* Deploy the containerized application to an Azure Kubernetes Service (AKS) cluster by using the Open Liberty Operator or WebSphere Liberty Operator.

+The Open Liberty Operator simplifies the deployment and management of applications running on Kubernetes clusters. With the Open Liberty Operator or WebSphere Liberty Operator, you can also perform more advanced operations, such as gathering traces and dumps.

+This article uses the Azure Marketplace offer for Open Liberty or WebSphere Liberty to accelerate your journey to AKS. The offer automatically provisions some Azure resources, including:

+* An Azure Container Registry instance.

+* An AKS cluster.

+* An Application Gateway Ingress Controller (AGIC) instance.

+* The Open Liberty Operator and WebSphere Liberty Operator.

+* Optionally, a container image that includes Liberty and your application.

+If you prefer manual step-by-step guidance for running Liberty on AKS, see [Manually deploy a Java application with Open Liberty or WebSphere Liberty on an Azure Kubernetes Service (AKS) cluster](/azure/developer/java/ee/howto-deploy-java-liberty-app-manual).

+This article is intended to help you quickly get to deployment. Before you go to production, you should explore the [IBM documentation about tuning Liberty](https://www.ibm.com/docs/was-liberty/base?topic=tuning-liberty).

+## Prerequisites

+* Install the [Azure CLI](/cli/azure/install-azure-cli). If you're running on Windows or macOS, consider running the Azure CLI in a Docker container. For more information, see [How to run the Azure CLI in a Docker container](/cli/azure/run-azure-cli-docker).

+* Sign in to the Azure CLI by using the [az login](/cli/azure/reference-index#az-login) command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see [Authentication methods](/cli/azure/authenticate-azure-cli).

+* When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see [Use and manage extensions with the Azure CLI](/cli/azure/azure-cli-extensions-overview).

+* Run [az version](/cli/azure/reference-index?#az-version) to find the version and dependent libraries that are installed. To upgrade to the latest version, run [az upgrade](/cli/azure/reference-index?#az-upgrade). This article requires at least version 2.31.0 of the Azure CLI.

+* Install a Java SE implementation, version 17 or later (for example, [Eclipse Open J9](https://www.eclipse.org/openj9/)).

+* Install [Maven](https://maven.apache.org/download.cgi) 3.5.0 or later.

+* Install [Docker](https://docs.docker.com/get-docker/) for your operating system.

+* Ensure that [Git](https://git-scm.com) is installed.

+* Make sure you're assigned either the Owner role or the Contributor and User Access Administrator roles in the subscription. You can verify roles by following the steps in [List role assignments for a user or group](../role-based-access-control/role-assignments-list-portal.md#list-role-assignments-for-a-user-or-group).

+> You can also run the commands in this article from [Azure Cloud Shell](/azure/cloud-shell/quickstart). This approach has all the prerequisite tools preinstalled, with the exception of Docker.

+> :::image type="icon" source="~/reusable-content/ce-skilling/azure/media/cloud-shell/launch-cloud-shell-button.png" alt-text="Button to open Azure Cloud Shell." border="false" link="https://shell.azure.com":::

+## Create a deployment of Liberty on AKS by using the portal

+The following steps guide you to create a Liberty runtime on AKS. After you complete these steps, you'll have a Container Registry instance and an AKS cluster for deploying your containerized application.

+1. Go to the [Azure portal](https://portal.azure.com/). In the search box at the top of the page, enter **IBM Liberty on AKS**. When the suggestions appear, select the one and only match in the **Marketplace** section.

+ If you prefer, you can [go directly to the offer](https://aka.ms/liberty-aks).

+1. On the **Basics** pane:

+ 1. Create a new resource group. Because resource groups must be unique within a subscription, choose a unique name. An easy way to have unique names is to use a combination of your initials, today's date, and some identifier (for example, `ejb0913-java-liberty-project-rg`).

+ 1. For **Region**, select **East US**.

+ 1. Create an environment variable in your shell for the resource group names for the cluster and the database:

+ ### [Bash](#tab/in-bash)

+ ```bash

+ export RESOURCE_GROUP_NAME=<your-resource-group-name>

+ ```

+ ### [PowerShell](#tab/in-powershell)

+ ```powershell

+ $Env:RESOURCE_GROUP_NAME="<your-resource-group-name>"

+ ```

+

+1. Select **Next**. On the **AKS** pane, you can optionally select an existing AKS cluster and Container Registry instance, instead of causing the deployment to create new ones. This choice enables you to use the sidecar pattern, as shown in the [Azure Architecture Center](/azure/architecture/patterns/sidecar). You can also adjust the settings for the size and number of the virtual machines in the AKS node pool.

+ For the purposes of this article, just keep all the defaults on this pane.

+1. Select **Next**. On the **Load Balancing** pane, next to **Connect to Azure Application Gateway?**, select **Yes**. In this section, you can customize the following deployment options:

+ * For **Virtual network** and **Subnet**, you can optionally customize the virtual network and subnet into which the deployment places the resources. You don't need to change the remaining values from their defaults.

+ * For **TLS/SSL certificate**, you can provide the TLS/SSL certificate from Azure Application Gateway. Leave the values at their defaults to cause the offer to generate a self-signed certificate.

+ Don't go to production with a self-signed certificate. For more information about self-signed certificates, see [Create a self-signed public certificate to authenticate your application](../active-directory/develop/howto-create-self-signed-certificate.md).

+ * You can select **Enable cookie based affinity**, also known as sticky sessions. This article uses sticky sessions, so be sure to select this option.

+1. Select **Next**. On the **Operator and application** pane, this article uses all the defaults. However, you can customize the following deployment options:

+ * You can deploy WebSphere Liberty Operator by selecting **Yes** for the option **IBM supported?**. Leaving the default **No** deploys Open Liberty Operator.

+ * You can deploy an application for your selected operator by selecting **Yes** for the option **Deploy an application?**. Leaving the default **No** doesn't deploy any application.

+1. Select **Review + create** to validate your selected options. On the **Review + create** pane, when you see **Create** become available after validation passes, select it.

+ The deployment can take up to 20 minutes. While you wait for the deployment to finish, you can follow the steps in the section [Create an Azure SQL Database instance](#create-an-azure-sql-database-instance). After you complete that section, come back here and continue.

+If you moved away from the **Deployment is in progress** pane, the following steps show you how to get back to that pane. If you're still on the pane that shows **Your deployment is complete**, go to the newly created resource group and skip to the third step.

+1. In the corner of any portal page, select the menu button, and then select **Resource groups**.

+1. In the box with the text **Filter for any field**, enter the first few characters of the resource group that you created previously. If you followed the recommended convention, enter your initials, and then select the appropriate resource group.

+1. In the list of resources in the resource group, select the resource with the **Type** value of **Container registry**.

+1. On the navigation pane, under **Settings**, select **Access keys**.

+1. Save aside the values for **Login server**, **Registry name**, **Username**, and **Password**. You can use the copy icon next to each field to copy the value to the system clipboard.

+1. Go back to the resource group into which you deployed the resources.

+1. Select the bottom-most deployment in the list. The **Deployment name** value matches the publisher ID of the offer. It contains the string `ibm`.

+1. On the navigation pane, select **Outputs**.

+1. By using the same copy technique as with the preceding values, save aside the values for the following outputs:

+ * `appDeploymentTemplateYaml` if the deployment doesn't include an application. That is, you selected **No** for **Deploy an application?** when you deployed the Marketplace offer.

+ * `appDeploymentYaml` if the deployment does include an application. That is, you selected **Yes** for **Deploy an application?**.

+ Paste the value of `appDeploymentTemplateYaml` or `appDeploymentYaml` into a Bash shell, append `| grep secretName`, and run the command.

+ The output of this command is the ingress TLS secret name, such as `- secretName: secret785e2c`. Save aside the `secretName` value.

+ Paste the quoted string in `appDeploymentTemplateYaml` or `appDeploymentYaml` into PowerShell (excluding the `| base64` portion), append `| ForEach-Object { [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($_)) } | Select-String "secretName"`, and run the command.

+ The output of this command is the ingress TLS secret name, such as `- secretName: secret785e2c`. Save aside the `secretName` value.

+

+You'll use these values later in this article. Note that the outputs list several other useful commands.

+## Create an Azure SQL Database instance

+Create an environment variable in your shell for the resource group name for the database:

+### [Bash](#tab/in-bash)

+```bash

+export DB_RESOURCE_GROUP_NAME=<db-resource-group>

+```

+### [PowerShell](#tab/in-powershell)

+```powershell

+$Env:DB_RESOURCE_GROUP_NAME="<db-resource-group>"

+```

+Now that you've created the database and AKS cluster, you can proceed to preparing AKS to host your Open Liberty application.

+Clone the sample code for this article. The sample is on [GitHub](https://github.com/Azure-Samples/open-liberty-on-aks).

+There are a few samples in the repository. This article uses *java-app/*. Run the following commands to get the sample:

+If you see a message about being in "detached HEAD" state, you can safely ignore it. The message just means that you checked out a tag.

+Here's the file structure of the application:

+In the *aks* directory, there are five deployment files:

+* *db-secret.xml*: Use this file to create [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) with database connection credentials.

+* *openlibertyapplication-agic.yaml*: Use this file to deploy the Open Liberty application with AGIC. This article assumes that you use this file.

+* *openlibertyapplication.yaml*: Use this file if you want to deploy the Open Liberty application without AGIC.

+* *webspherelibertyapplication-agic.yaml*: Use this file to deploy the WebSphere Liberty application with AGIC if you deployed WebSphere Liberty Operator [earlier in this article](#create-a-deployment-of-liberty-on-aks-by-using-the-portal).

+* *webspherelibertyapplication.yaml*: Use this file to deploy the WebSphere Liberty application without AGIC if you deployed WebSphere Liberty Operator earlier in this article.

+In the *docker* directory, there are two files to create the application image:

+* *Dockerfile*: Use this file to build the application image with Open Liberty in this article.

+* *Dockerfile-wlp*: Use this file to build the application image with WebSphere Liberty if you deployed WebSphere Liberty Operator earlier in this article.

+In the *liberty/config* directory, you use the *server.xml* file to configure the database connection for the Open Liberty and WebSphere Liberty cluster.

+Now that you have the necessary properties, you can build the application. The POM file for the project reads many variables from the environment. As part of the Maven build, these variables are used to populate values in the YAML files located in *src/main/aks*. You can do something similar for your application outside Maven if you prefer.

+# The following variables are used for deployment file generation into the target.

+# The following variables are used for deployment file generation into the target.

+$Env:LOGIN_SERVER="<Azure-Container-Registry-Login-Server-URL>"

+$Env:REGISTRY_NAME="<Azure-Container-Registry-name>"

+$Env:USER_NAME="<Azure-Container-Registry-username>"

+$Env:PASSWORD="<Azure-Container-Registry-password>"

+$Env:DB_SERVER_NAME="<server-name>.database.windows.net"

+$Env:DB_NAME="<database-name>"

+$Env:DB_USER="<server-admin-login>@<server-name>"

+$Env:DB_PASSWORD="<server-admin-password>"

+$Env:INGRESS_TLS_SECRET="<ingress-TLS-secret-name>"

+Run and test the project locally before deploying to Azure. For convenience, this article uses `liberty-maven-plugin`. To learn more about `liberty-maven-plugin`, see the Open Liberty article [Building a web application with Maven](https://openliberty.io/guides/maven-intro.html).

+For your application, you can do something similar by using any other mechanism, such as your local development environment. You can also consider using the `liberty:devc` option intended for development with containers. You can read more about `liberty:devc` in the [Open Liberty documentation](https://openliberty.io/docs/latest/development-mode.html#_container_support_for_dev_mode).

+1. Start the application by using `liberty:run`. `liberty:run` also uses the environment variables that you defined earlier.

+1. If the test is successful, a message similar to `[INFO] [AUDIT] CWWKZ0003I: The application javaee-cafe updated in 1.930 seconds` appears in the command output. Go to `http://localhost:9080/` in your browser and verify that the application is accessible and all functions are working.

+1. Select <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop.

+### Build the image for AKS deployment

+You can now run the `docker build` command to build the image:

+Use the following steps to test the Docker image locally before deploying to Azure:

+1. Run the image by using the following command. This command uses the environment variables that you defined previously.

+1. After the container starts, go to `http://localhost:9080/` in your browser to access the application.

+1. Select <kbd>Ctrl</kbd>+<kbd>C</kbd> to stop.

+### Upload the image to Azure Container Registry

+Upload the built image to the Container Registry instance that you created in the offer:

+ Paste the value of `cmdToConnectToCluster` into a shell and run the command.

+1. Apply the database secret:

+ The output is `secret/db-secret-sql created`.

+1. Apply the deployment file:

+ Output similar to the following example indicates that all the pods are running:

+1. Verify the results:

+ 1. Get the address of the ingress resource deployed with the application:

+ Copy the value of `ADDRESS` from the output. This value is the front-end public IP address of the deployed Application Gateway instance.

+ 1. Go to `https://<ADDRESS>` to test the application. For your convenience, this shell command creates an environment variable whose value you can paste straight into the browser:

+ If the webpage doesn't render correctly or returns a `502 Bad Gateway` error, the app is still starting in the background. Wait for a few minutes and then try again.

+To avoid Azure charges, you should clean up unnecessary resources. When you no longer need the cluster, use the [az group delete](/cli/azure/group#az-group-delete) command to remove the resource group, the container service, the container registry, the database, and all related resources:

+* [Open Liberty server configuration](https://openliberty.io/docs/ref/config/)

+Quarkus dev mode enables live reload with background compilation. If you modify any aspect of your app source code and refresh your browser, you can see the changes. If there are any issues with compilation or deployment, an error page lets you know. Quarkus dev mode listens for a debugger on port 5005. If you want to wait for the debugger to attach before running, pass `-Dsuspend` on the command line. If you don't want the debugger at all, you can use `-Ddebug=false`.

+1. If you have successfully created the image, then it should now be in your local machine's Docker repository. You can verify the image creation by using the following command:

+[](https://go.microsoft.com/fwlink/?linkid=2262758)

+Azure Kubernetes Service (AKS) is a managed Kubernetes service that lets you quickly deploy and manage clusters. In this quickstart, you learn how to:

+## Define environment variables

+Define the following environment variables for use throughout this quickstart:

+```azurecli-interactive

+export RANDOM_ID="$(openssl rand -hex 3)"

+export MY_RESOURCE_GROUP_NAME="myAKSResourceGroup$RANDOM_ID"

+export REGION="westeurope"

+export MY_AKS_CLUSTER_NAME="myAKSCluster$RANDOM_ID"

+export MY_DNS_LABEL="mydnslabel$RANDOM_ID"

+```

+## Create a resource group

+An [Azure resource group][azure-resource-group] is a logical group in which Azure resources are deployed and managed. When you create a resource group, you're prompted to specify a location. This location is the storage location of your resource group metadata and where your resources run in Azure if you don't specify another region during resource creation.

+Create a resource group using the [`az group create`][az-group-create] command.

+```azurecli-interactive

+az group create --name $MY_RESOURCE_GROUP_NAME --location $REGION

+```

+Results:

+<!-- expected_similarity=0.3 -->

+```JSON

+{

+ "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myAKSResourceGroupxxxxxx",

+ "location": "eastus",

+ "managedBy": null,

+ "name": "testResourceGroup",

+ "properties": {

+ "provisioningState": "Succeeded"

+ },

+ "tags": null,

+ "type": "Microsoft.Resources/resourceGroups"

+}

+```

+Create an AKS cluster using the [`az aks create`][az-aks-create] command. The following example creates a cluster with one node and enables a system-assigned managed identity.

+```azurecli-interactive

+az aks create --resource-group $MY_RESOURCE_GROUP_NAME --name $MY_AKS_CLUSTER_NAME --enable-managed-identity --node-count 1 --generate-ssh-keys

+```

+> [!NOTE]

+> When you create a new cluster, AKS automatically creates a second resource group 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 [`az aks install-cli`][az-aks-install-cli] command.

+ ```azurecli-interactive

+ az aks get-credentials --resource-group $MY_RESOURCE_GROUP_NAME --name $MY_AKS_CLUSTER_NAME

+ ```azurecli-interactive

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

+ ```azurecli-interactive

+You can validate that the application is running by visiting the public IP address or the application URL.

+Get the application URL using the following commands:

+```azurecli-interactive

+runtime="5 minute"

+endtime=$(date -ud "$runtime" +%s)

+while [[ $(date -u +%s) -le $endtime ]]

+do

+ STATUS=$(kubectl get pods -l app=store-front -o 'jsonpath={..status.conditions[?(@.type=="Ready")].status}')

+ echo $STATUS

+ if [ "$STATUS" == 'True' ]

+ then

+ export IP_ADDRESS=$(kubectl get service store-front --output 'jsonpath={..status.loadBalancer.ingress[0].ip}')

+ echo "Service IP Address: $IP_ADDRESS"

+ break

+ else

+ sleep 10

+ fi

+done

+```

+```azurecli-interactive

+curl $IP_ADDRESS

+```

+Results:

+<!-- expected_similarity=0.3 -->

+```JSON

+<!doctype html>

+<html lang="">

+ <head>

+ <meta charset="utf-8">

+ <meta http-equiv="X-UA-Compatible" content="IE=edge">

+ <meta name="viewport" content="width=device-width,initial-scale=1">

+ <link rel="icon" href="/favicon.ico">

+ <title>store-front</title>

+ <script defer="defer" src="/js/chunk-vendors.df69ae47.js"></script>

+ <script defer="defer" src="/js/app.7e8cfbb2.js"></script>

+ <link href="/css/app.a5dc49f6.css" rel="stylesheet">

+ </head>

+ <body>

+ <div id="app"></div>

+ </body>

+</html>

+```

+```JSON

+echo "You can now visit your web server at $IP_ADDRESS"

+```

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

+> [!NOTE]

+> The AKS cluster was created with a system-assigned managed identity, which is the default identity option used in this quickstart. The platform manages this identity so you don't need to manually remove it.

+[kubernetes-service]: ../concepts-network-services.md

+[kubernetes-service]: ../concepts-network-services.md

+[kubernetes-service]: ../concepts-network-services.md

+Sometimes deployment or other processes running within pods on nodes in a cluster can run for periods of time longer than expected due to various reasons. You can get insight into the progress of any ongoing operation, such as create, upgrade, and scale, using any preview API version after `2024-01-02-preview` using the following az rest command:

+```azurecli-interactive

+export ResourceID="You cluster ResourceID"

+az rest --method get --url "https://management.azure.com$ResourceID/operations/latest?api-version=2024-01-02-preview"

+```

+This command provides you with a percentage that indicates how close the operation is to completion. You can use this method to get these insights for up to 50 of the latest operations on your cluster. The "percentComplete" attribute denotes the extent of completion for the ongoing operation, as shown in the following example:

+```azurecli-interactive

+"id": "/subscriptions/26fe00f8-9173-4872-9134-bb1d2e00343a/resourcegroups/testStatus/providers/Microsoft.ContainerService/managedClusters/contoso/operations/fc10e97d-b7a8-4a54-84de-397c45f322e1",

+ "name": "fc10e97d-b7a8-4a54-84de-397c45f322e1",

+ "percentComplete": 10,

+ "startTime": "2024-04-08T18:21:31Z",

+ "status": "InProgress"

+```

+While it's important to allow operations to gracefully terminate when they're no longer needed, there are circumstances where you need to release control of node pools and clusters with long running operations using an *abort* command.

+| 1.30 | Apr 2024 | May 2024 | Jun 2024 | | Until 1.34 GA |

+Platform support policy applies to clusters in an n-3 version (where n is the latest supported AKS GA minor version), before the cluster drops to n-4. For example, Kubernetes v1.26 is considered platform support when v1.29 is the latest GA version. However, during the v1.30 GA release, v1.26 will then auto-upgrade to v1.27. If you are a running an n-2 version, the moment it becomes n-3 it also becomes deprecated, and you enter into the platform support policy.

+### What is the allowed difference in versions between control plane and node pool?

+The [version skew policy](https://kubernetes.io/releases/version-skew-policy/) now allows a difference of upto 3 versions between control plane and agent pools. AKS follows this skew version policy change starting from version 1.28 onwards.

+When performing an upgrade from an _unsupported version_ that skips two or more minor versions, the upgrade is performed without any guarantee of functionality and is excluded from the service-level agreements and limited warranty.Clusters running _unsupported version_ has the flexibility of decoupling control plane upgrades with node pool upgrades. However if your version is significantly out of date, we recommend that you re-create the cluster.

+No. You aren't allowed to add node pools of the deprecated version to your cluster. Creation or upgrade of node pools upto the _unsupported version_ control plane version is allowed , irrespective of version difference between node pool and the control plane. Only alias minor upgrades are allowed.

+* Starting with 1.30 kubernetes version and 1.27 LTS versions the beta apis will be disabled by default when you upgrade to them.

+* [Spectral extension](https://marketplace.visualstudio.com/items?itemName=stoplight.spectral) - to run shift-left API design conformance checks in Visual Studio Code

+| [Managed domain certificates](configure-custom-domain.md?tabs=managed#domain-certificate-options) | Developer, Basic, Standard, Premium | ✔️ | ❌ | ❌ |

+8. Depending on your scenario, you might need to change the [service type](../aks/concepts-network-services.md).

+| client-application-ids | Contains a list of acceptable client application IDs. If multiple `application-id` elements are present, then each value is tried until either all are exhausted (in which case validation fails) or until one succeeds. If a client application ID isn't provided, one or more `audience` claims should be specified. Policy expressions aren't allowed. | Yes |

+This guide provides key concepts and instructions for containerization of Windows apps in App Service. New Azure App Service users should follow the [custom container quickstart](quickstart-custom-container.md) and [tutorial](tutorial-custom-container.md) first.

+This guide provides key concepts and instructions for containerization of Linux apps in App Service. If are new to Azure App Service, follow the [custom container quickstart](quickstart-custom-container.md) and [tutorial](tutorial-custom-container.md) first. There's also a [multi-container app quickstart](quickstart-multi-container.md) and [tutorial](tutorial-multi-container-app.md). For sidecar containers (preview), see [Tutorial: Configure a sidecar container for custom container in Azure App Service (preview)](tutorial-custom-container-sidecar.md).

+Use the following steps to configure your web app to pull from Azure Container Registry (ACR) using managed identity. The steps use system-assigned managed identity, but you can use user-assigned managed identity as well.

+ Replace `<app-name>` with the name you used in the previous step. The output of the command (filtered by the `--query` and `--output` arguments) is the service principal ID of the assigned identity.

+1. (Optional) If your app uses a [user-assigned managed identity](overview-managed-identity.md#add-a-user-assigned-identity), make sure the identity is configured on the web app and then set the `acrUserManagedIdentityID` property to specify its client ID:

+To connect and pull from a registry inside a virtual network or on-premises, your app must integrate with a virtual network (VNET). VNET integration is also needed for Azure Container Registry with private endpoint. When your network and DNS resolution is configured, you enable the routing of the image pull through the virtual network by configuring the `vnetImagePullEnabled` site setting:

+- Any change you make to the container from within the SSH session **doesn't** persist when your app is restarted (except for changes in the shared storage), because it's not part of the Docker image. To persist your changes, such as registry settings and software installation, make them part of the Dockerfile.

+- [Azure portal](#in-azure-portal)

+- [Kudu](#from-kudu)

+- [Kudu API](#with-the-kudu-api)

+- [Azure monitor](troubleshoot-diagnostic-logs.md#send-logs-to-azure-monitor)

+Navigate to `https://<app-name>.scm.azurewebsites.net/DebugConsole` and select the **LogFiles** folder to see the individual log files. To download the entire **LogFiles** directory, select the **"Download"** icon to the left of the directory name. You can also access this folder using an FTP client.

+By default all Windows Containers deployed in Azure App Service have a memory limit configured. The following table lists the default settings per App Service Plan SKU.

+The value is defined in MB and must be less and equal to the total physical memory of the host. For example, in an App Service plan with 8 GB RAM, the cumulative total of `WEBSITE_MEMORY_LIMIT_MB` for all the apps must not exceed 8 GB. Information on how much memory is available for each pricing tier can be found in [App Service pricing](https://azure.microsoft.com/pricing/details/app-service/windows/), in the **Premium v3 service plan** section.

+App Service considers a container to be successfully started when the container starts and responds to an HTTP ping. The health ping request contains the header `User-Agent= "App Service Hyper-V Container Availability Check"`. If the container starts but doesn't respond pings after a certain amount of time, App Service logs an event in the Docker log, saying that the container didn't start.

+Further troubleshooting information is available at the Azure App Service blog: [Enabling SSH on Linux Web App for Containers](https://azureossd.github.io/2022/04/27/2022-Enabling-SSH-on-Linux-Web-App-for-Containers/https://docsupdatetracker.net/index.html#troubleshooting)

+ - "${WEBAPP_STORAGE_HOME}/site/wwwroot:/var/www/html"

+ - "${WEBAPP_STORAGE_HOME}/phpmyadmin:/var/www/phpmyadmin"

+ - "${WEBAPP_STORAGE_HOME}/LogFiles:/var/log"

+- image > volume section must be quoted and can't have permissions definitions

+You have two App Service Environments at this stage in the migration process. Your apps are running in both environments. You need to update any dependent resources to use the new IP inbound address for your new App Service Environment v3. For internal facing (ILB) App Service Environments, you need to update your private DNS zones to point to the new inbound IP address. This step is where you can validate your new environment and make any remaining necessary updates to your dependent resources.

+## 11. Redirect customer traffic, validate your App Service Environment v3, and complete migration

+This step is your opportunity to test and validate your new App Service Environment v3. Your App Service Environment v2 front ends are still running, but the backing compute is an App Service Environment v3. If you're able to access your apps without issues that means you're ready to complete the migration. If you want to test your App Service Environment v3 front ends, you can do so by using the inbound IP address you got in the previous step.

+Once you confirm your apps are working as expected, you can redirect customer traffic to your new App Service Environment v3 by running the following command. This command also deletes your old environment.

+If you find any issues or decide at this point that you no longer want to proceed with the migration, contact support to revert the migration. Don't run the DNS change command if you need to revert the migration. For more information, see [Revert migration](./side-by-side-migrate.md#redirect-customer-traffic-validate-your-app-service-environment-v3-and-complete-migration).

+If your migration includes a custom domain suffix, for App Service Environment v3, the custom domain isn't displayed in the **Essentials** section of the **Overview** page of the portal as it is for App Service Environment v1/v2. Instead, for App Service Environment v3, go to the **Custom domain suffix** page where you can confirm your custom domain suffix is configured correctly. Also, on App Service Environment v2, if you have a custom domain suffix, the default host name includes your custom domain suffix and is in the form *APP-NAME.internal.contoso.com*. On App Service Environment v3, the default host name always uses the default domain suffix and is in the form *APP-NAME.ASE-NAME.appserviceenvironment.net*. This difference is because App Service Environment v3 keeps the default domain suffix when you add a custom domain suffix. With App Service Environment v2, there's only a single domain suffix.

+You receive the new inbound IP address once migration is complete but before you make the [DNS change to redirect customer traffic to your new App Service Environment v3](#redirect-customer-traffic-validate-your-app-service-environment-v3-and-complete-migration). You don't get the inbound IP at this point in the process because there are dependencies on App Service Environment v3 resources that get created during the migration step. You have a chance to update any resources that are dependent on the new inbound IP before you redirect traffic to your new App Service Environment v3.

+If your migration includes a custom domain suffix, for App Service Environment v3, the custom domain isn't displayed in the **Essentials** section of the **Overview** page of the portal as it is for App Service Environment v1/v2. Instead, for App Service Environment v3, go to the **Custom domain suffix** page where you can confirm your custom domain suffix is configured correctly. Also, on App Service Environment v2, if you have a custom domain suffix, the default host name includes your custom domain suffix and is in the form *APP-NAME.internal.contoso.com*. On App Service Environment v3, the default host name always uses the default domain suffix and is in the form *APP-NAME.ASE-NAME.appserviceenvironment.net*. This difference is because App Service Environment v3 keeps the default domain suffix when you add a custom domain suffix. With App Service Environment v2, there's only a single domain suffix.

+- The underlying compute for your apps is moved to the new App Service Environment v3. Your App Service Environment v2 front ends are still serving traffic. Your old inbound IP address remains in use.

+ - For ILB App Service Environments, your App Service Environment v3 front ends aren't used until you update your private DNS zones with the new inbound IP address.

+ - For ELB App Service Environments, the migration process doesn't redirect to the App Service Environment v3 front ends until you complete the final step of the migration.

+The new inbound IP address is given so that you can set up new endpoints with services like [Traffic Manager](../../traffic-manager/traffic-manager-overview.md) or [Azure Front Door](../../frontdoor/front-door-overview.md) and update any of your private DNS zones. Don't move on to the next step until you make these changes. There's downtime if you don't update dependent resources with the new inbound IP. **It's your responsibility to update any and all resources that are impacted by the IP address change associated with the new App Service Environment v3. Don't move on to the next step until you've made all required updates.**

+### Redirect customer traffic, validate your App Service Environment v3, and complete migration

+The final step is to redirect traffic to your new App Service Environment v3 and complete the migration. The platform does this change for you, but only when you initiate it. Before you do this step, you should review your new App Service Environment v3 and perform any needed testing to validate that it's functioning as intended. Your App Service Environment v2 front ends are still running, but the backing compute is an App Service Environment v3. If you're using an ILB App Service Environment v3, you can test your App Service Environment v3 front ends by updating your private DNS zones with the new inbound IP address. Testing this change allows you to fully validate your App Service Environment v3 before initiating the final step of the migration where your old App Service Environment is deleted.

+|**3**|**Testing and troubleshooting**|Upgrading using one of the automated migration features requires a 3-6 hour service window. If you use the side-by-side migration feature, you have the opportunity to [test and validate your App Service Environment v3](./side-by-side-migrate.md#redirect-customer-traffic-validate-your-app-service-environment-v3-and-complete-migration) before completing the upgrade. Support teams are monitoring upgrades to ensure success. If you have a support plan and you need technical help, create a [support request](https://portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade/newsupportrequest).|

+| **Python** | linuxFxVersion="PYTHON&#124;3.8" |

+The IPv6 Application Gateway is available to all public cloud regions where Application Gateway v2 SKU is supported. It's also available in [Microsoft Azure operated by 21Vianet](https://www.azure.cn/) and [Azure Government](https://azure.microsoft.com/overview/clouds/government/)

+ > For the Application Gateway v2 SKU, there must be a **Public** frontend IP configuration. A private IPv6 frontend IP configuration (Only ILB mode) is currently not supported for the IPv6 Application Gateway.

+ > IPv6 Application Gateway supports up to 4 frontend IP addresses: two IPv4 addresses (Public and Private) and two IPv6 addresses (Public and Private)

+description: Enable Azure RBAC to authorize access to your Azure App Configuration instance.

+Besides using Hash-based Message Authentication Code (HMAC), Azure App Configuration supports using Microsoft Entra ID to authorize requests to App Configuration instances. Microsoft Entra ID allows you to use Azure role-based access control (Azure RBAC) to grant permissions to a security principal. A security principal may be a user, a [managed identity](../active-directory/managed-identities-azure-resources/overview.md), or an [application service principal](../active-directory/develop/app-objects-and-service-principals.md). To learn more about roles and role assignments, see [Understanding different roles](../role-based-access-control/overview.md).

+1. The security principal's identity is authenticated and an OAuth 2.0 token is returned. The resource name to request a token is `https://login.microsoftonline.com/{tenantID}` where `{tenantID}` matches the Microsoft Entra tenant ID to which the service principal belongs.

+The authentication step requires that an application request contains an OAuth 2.0 access token at runtime. If an application is running within an Azure entity, such as an Azure Functions app, an Azure Web App, or an Azure VM, it can use a managed identity to access the resources. To learn how to authenticate requests made by a managed identity to Azure App Configuration, see [Authenticate access to Azure App Configuration resources with Microsoft Entra ID and managed identities for Azure Resources](howto-integrate-azure-managed-service-identity.md).

+- **App Configuration Data Owner**: Use this role to give read/write/delete access to App Configuration data. This role doesn't grant access to the App Configuration resource.

+- **App Configuration Data Reader**: Use this role to give read access to App Configuration data. This role doesn't grant access to the App Configuration resource.

+- **Contributor** or **Owner**: Use this role to manage the App Configuration resource. It grants access to the resource's access keys. While the App Configuration data can be accessed using access keys, this role doesn't grant direct access to the data using Microsoft Entra ID. This role is required if you access the App Configuration data via ARM template, Bicep, or Terraform during deployment. For more information, see [deployment](quickstart-deployment-overview.md).

+- **Reader**: Use this role to give read access to the App Configuration resource. This role doesn't grant access to the resource's access keys, nor to the data stored in App Configuration.

+description: Learn how to disable access key authentication for an Azure App Configuration instance.

+Disabling access key authentication will delete all access keys. If any running applications are using access keys for authentication, they will begin to fail once access key authentication is disabled. Enabling access key authentication again will generate a new set of access keys and any applications attempting to use the old access keys will still fail.

+2. Locate the **Access settings** setting under **Settings**.

+ :::image type="content" border="true" source="./media/access-settings-blade.png" alt-text="Screenshot showing how to access an Azure App Configuration resources access key blade.":::

+To verify that access key authentication is no longer permitted, a request can be made to list the access keys for the Azure App Configuration resource. If access key authentication is disabled, there will be no access keys, and the list operation will return an empty list.

+2. Locate the **Access settings** setting under **Settings**.

+ :::image type="content" border="true" source="./media/access-settings-blade.png" alt-text="Screenshot showing how to access an Azure App Configuration resources access key blade.":::

+If access key authentication is disabled, then an empty list will be returned.

+Be careful to restrict assignment of these roles only to those users who require the ability to create an App Configuration resource or update its properties. Use the principle of least privilege to ensure that users have the fewest permissions that they need to accomplish their tasks. For more information about managing access with Azure RBAC, see [Best practices for Azure RBAC](../role-based-access-control/best-practices.md).

+> [!NOTE]

+> When access key authentication is disabled and [ARM authentication mode](./quickstart-deployment-overview.md#azure-resource-manager-authentication-mode) of App Configuration store is local, the capability to read/write key-values in an [ARM template](./quickstart-resource-manager.md) will be disabled as well. This is because access to the Microsoft.AppConfiguration/configurationStores/keyValues resource used in ARM templates requires access key authentication with local ARM authentication mode. It's recommended to use pass-through ARM authentication mode. For more information, see [Deployment overview](./quickstart-deployment-overview.md).

+## Authorization

+Managing an Azure App Configuration resource with Bicep file requires an Azure Resource Manager role, such as contributor or owner. Accessing Azure App Configuration data (key-values, snapshots) requires an Azure Resource Manager role and an additional Azure App Configuration [data plane role](concept-enable-rbac.md) when the configuration store's ARM authentication mode is set to [pass-through](./quickstart-deployment-overview.md#azure-resource-manager-authentication-mode) ARM authentication mode.

+ Title: Deployment overview

+description: Learn how to use Azure App Configuration in deployment.

+# Deployment

+Azure App Configuration supports the following methods to read and manage your configuration during deployment:

+- [ARM template](./quickstart-resource-manager.md)

+- [Bicep](./quickstart-bicep.md)

+- Terraform

+## Manage Azure App Configuration resources in deployment

+### Azure Resource Manager Authorization

+You must have Azure Resource Manager permissions to manage Azure App Configuration resources. Azure role-based access control (Azure RBAC) roles that provide these permissions include the Microsoft.AppConfiguration/configurationStores/write or Microsoft.AppConfiguration/configurationStores/* action. Built-in roles with this action include:

+- Owner

+- Contributor

+To learn more about Azure RBAC and Microsoft Entra ID, see [Authorize access to Azure App Configuration using Microsoft Entra ID](./concept-enable-rbac.md).

+## Manage Azure App Configuration data in deployment

+Azure App Configuration data, such as key-values and snapshots, can be managed in deployment. When managing App Configuration data using this method, it's recommended to set your configuration store's Azure Resource Manager authentication mode to **Pass-through**. This authentication mode ensures that data access requires a combination of data plane and Azure Resource Manager management roles and ensuring that data access can be properly attributed to the deployment caller for auditing purpose.

+### Azure Resource Manager authentication mode

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

+To configure the Azure Resource Manager authentication mode of an Azure App Configuration resource in the Azure portal, follow these steps:

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

+2. Locate the **Access settings** setting under **Settings**

+ :::image type="content" border="true" source="./media/access-settings-blade.png" alt-text="Screenshot showing how to access an Azure App Configuration resources access settings blade.":::

+3. Select the recommended **Pass-through** authentication mode under **Azure Resource Manager Authentication Mode**

+ :::image type="content" border="true" source="./media/quickstarts/deployment/select-passthrough-authentication-mode.png" alt-text="Screenshot showing pass-through authentication mode being selected under Azure Resource Manager Authentication Mode.":::

+> [!NOTE]

+> Local authentication mode is for backward compatibility and has several limitations. It does not support proper auditing for accessing data in deployment. Under local authentication mode, key-value data access inside an ARM template/Bicep/Terraform is disabled if [access key authentication is disabled](./howto-disable-access-key-authentication.md). Azure App Configuration data plane permissions are not required for accessing data under local authentication mode.

+### Azure App Configuration Authorization

+When your App Configuration resource has its Azure Resource Manager authentication mode set to **Pass-through**, you must have Azure App Configuration data plane permissions to read and manage Azure App Configuration data in deployment. This requirement is in addition to baseline management permission requirements of the resource. Azure App Configuration data plane permissions include Microsoft.AppConfiguration/configurationStores/\*/read and Microsoft.AppConfiguration/configurationStores/\*/write. Built-in roles with this action include:

+- App Configuration Data Owner

+- App Configuration Data Reader

+To learn more about Azure RBAC and Microsoft Entra ID, see [Authorize access to Azure App Configuration using Microsoft Entra ID](./concept-enable-rbac.md).

+### Private network access

+When an App Configuration resource is restricted to private network access, deployments accessing App Configuration data through public networks will be blocked. To enable successful deployments when access to an App Configuration resource is restricted to private networks the following actions must be taken:

+- [Azure Resource Management Private Link](../azure-resource-manager/management/create-private-link-access-portal.md) must be set up

+- The App Configuration resource must have Azure Resource Manager authentication mode set to **Pass-through**

+- The App Configuration resource must have Azure Resource Manager private network access enabled

+- Deployments accessing App Configuration data must run through the configured Azure Resource Manager private link

+If all of these criteria are met, then deployments accessing App Configuration data will be successful.

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

+To enable Azure Resource Manager private network access for an Azure App Configuration resource in the Azure portal, follow these steps:

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

+2. Locate the **Networking** setting under **Settings**

+ :::image type="content" border="true" source="./media/networking-blade.png" alt-text="Screenshot showing how to access an Azure App Configuration resources networking blade.":::

+3. Check **Enable Azure Resource Manager Private Access** under **Private Access**

+ :::image type="content" border="true" source="./media/quickstarts/deployment/enable-azure-resource-manager-private-access.png" alt-text="Screenshot showing Enable Azure Resource Manager Private Access is checked.":::

+> [!NOTE]

+> Azure Resource Manager private network access can only be enabled under **Pass-through** authentication mode.

+## Next steps

+To learn about deployment using ARM template and Bicep, check the documentations linked below.

+- [Quickstart: Create an Azure App Configuration store by using an ARM template](./quickstart-resource-manager.md)

+- [Quickstart: Create an Azure App Configuration store using Bicep](./quickstart-bicep.md)

+This quickstart describes how to:

+Managing Azure App Configuration resource inside an ARM template requires Azure Resource Manager role, such as contributor or owner. Accessing Azure App Configuration data (key-values, snapshots) requires Azure Resource Manager role and Azure App Configuration [data plane role](concept-enable-rbac.md) under [pass-through](./quickstart-deployment-overview.md#azure-resource-manager-authentication-mode) ARM authentication mode.

+ Title: Choosing the right Azure Arc service for machines

+description: Learn about the different services offered by Azure Arc and how to choose the right one for your machines.

+# Choosing the right Azure Arc service for machines

+Azure Arc offers different services based on your existing IT infrastructure and management needs. Before onboarding your resources to Azure Arc-enabled servers, you should investigate the different Azure Arc offerings to determine which best suits your requirements. Choosing the right Azure Arc service provides the best possible inventorying and management of your resources.

+There are several different ways you can connect your existing Windows and Linux machines to Azure Arc:

+- Azure Arc-enabled servers

+- Azure Arc-enabled VMware vSphere

+- Azure Arc-enabled System Center Virtual Machine Manager (SCVMM)

+- Azure Arc-enabled Azure Stack HCI

+Each of these services extends the Azure control plane to your existing infrastructure and enables the use of [Azure security, governance, and management capabilities using the Connected Machine agent](/azure/azure-arc/servers/overview). Other services besides Azure Arc-enabled servers also use an [Azure Arc resource bridge](/azure/azure-arc/resource-bridge/overview), a part of the core Azure Arc platform that provides self-servicing and additional management capabilities.

+General recommendations about the right service to use are as follows:

+|If your machine is a... |...connect to Azure with... |

+|||

+|VMware VM (not running on AVS) |[Azure Arc-enabled VMware vSphere](vmware-vsphere/overview.md) |

+|Azure VMware Solution (AVS) VM |[Azure Arc-enabled VMware vSphere for Azure VMware Solution](/azure/azure-vmware/deploy-arc-for-azure-vmware-solution?tabs=windows) |

+|VM managed by System Center Virtual Machine Manager |[Azure Arc-enabled SCVMM](vmware-vsphere/overview.md) |

+|Azure Stack HCI VM |[Arc-enabled Azure Stack HCI](/azure-stack/hci/overview) |

+|Physical server |[Azure Arc-enabled servers](servers/overview.md) |

+|VM on another hypervisor |[Azure Arc-enabled servers](servers/overview.md) |

+|VM on another cloud provider |[Azure Arc-enabled servers](servers/overview.md) |

+If you're unsure about which of these services to use, you can start with Azure Arc-enabled servers and add a resource bridge for additional management capabilities later. Azure Arc-enabled servers allows you to connect servers containing all of the types of VMs supported by the other services and provides a wide range of capabilities such as Azure Policy and monitoring, while adding resource bridge can extend additional capabilities.

+Region availability also varies between Azure Arc services, so you may need to use Azure Arc-enabled servers if a more specialized version of Azure Arc is unavailable in your preferred region. See [Azure Products by Region](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/?products=azure-arc&regions=all&rar=true) to learn more about region availability for Azure Arc services.

+Where your machine runs determines the best Azure Arc service to use. Organizations with diverse infrastructure may end up using more than one Azure Arc service; this is alright. The core set of features remains the same no matter which Azure Arc service you use.

+## Azure Arc-enabled servers

+[Azure Arc-enabled servers](servers/overview.md) lets you manage Windows and Linux physical servers and virtual machines hosted outside of Azure, on your corporate network, or other cloud provider. When connecting your machine to Azure Arc-enabled servers, you can perform various operational functions similar to native Azure virtual machines.

+### Capabilities

+- Govern: Assign Azure Automanage machine configurations to audit settings within the machine. Utilize Azure Policy pricing guide for cost understanding.

+- Protect: Safeguard non-Azure servers with Microsoft Defender for Endpoint, integrated through Microsoft Defender for Cloud. This includes threat detection, vulnerability management, and proactive security monitoring. Utilize Microsoft Sentinel for collecting security events and correlating them with other data sources.

+- Configure: Employ Azure Automation for managing tasks using PowerShell and Python runbooks. Use Change Tracking and Inventory for assessing configuration changes. Utilize Update Management for handling OS updates. Perform post-deployment configuration and automation tasks using supported Azure Arc-enabled servers VM extensions.

+- Monitor: Utilize VM insights for monitoring OS performance and discovering application components. Collect log data, such as performance data and events, through the Log Analytics agent, storing it in a Log Analytics workspace.

+- Procure Extended Security Updates (ESUs) at scale for your Windows Server 2012 and 2012R2 machines running on vCenter managed estate.

+> [!IMPORTANT]

+> Azure Arc-enabled VMware vSphere and Azure Arc-enabled SCVMM have all the capabilities of Azure Arc-enabled servers, but also provide specific, additional capabilities.

+>

+## Azure Arc-enabled VMware vSphere

+[Azure Arc-enabled VMware vSphere](vmware-vsphere/overview.md) simplifies the management of hybrid IT resources distributed across VMware vSphere and Azure.

+Running software in Azure VMware Solution, as a private cloud in Azure, offers some benefits not realized by operating your environment outside of Azure. For software running in a VM, such as SQL Server and Windows Server, running in Azure VMware Solution provides additional value such as free Extended Security Updates (ESUs).

+To take advantage of these benefits if you're running in an Azure VMware Solution, it's important to follow respective [onboarding](/azure/azure-vmware/deploy-arc-for-azure-vmware-solution?tabs=windows) processes to fully integrate the experience with the AVS private cloud.

+Additionally, when a VM in Azure VMware Solution private cloud is Azure Arc-enabled using a method distinct from the one outlined in the AVS public document, the steps are provided in the [document](/azure/azure-vmware/deploy-arc-for-azure-vmware-solution?tabs=windows) to refresh the integration between the Azure Arc-enabled VMs and Azure VMware Solution.

+### Capabilities

+- Discover your VMware vSphere estate (VMs, templates, networks, datastores, clusters/hosts/resource pools) and register resources with Azure Arc at scale.

+- Perform various virtual machine (VM) operations directly from Azure, such as create, resize, delete, and power cycle operations such as start/stop/restart on VMware VMs consistently with Azure.

+- Empower developers and application teams to self-serve VM operations on-demand using Azure role-based access control (RBAC).

+- Install the Azure Arc-connected machine agent at scale on VMware VMs to govern, protect, configure, and monitor them.

+- Browse your VMware vSphere resources (VMs, templates, networks, and storage) in Azure, providing you with a single pane view for your infrastructure across both environments.

+## Azure Arc-enabled System Center Virtual Machine Manager (SCVMM)

+[Azure Arc-enabled System Center Virtual Machine Manager](system-center-virtual-machine-manager/overview.md) (SCVMM) empowers System Center customers to connect their VMM environment to Azure and perform VM self-service operations from Azure portal.

+Azure Arc-enabled System Center Virtual Machine Manager also allows you to manage your hybrid environment consistently and perform self-service VM operations through Azure portal. For Microsoft Azure Pack customers, this solution is intended as an alternative to perform VM self-service operations.

+### Capabilities

+- Discover and onboard existing SCVMM managed VMs to Azure.

+- Perform various VM lifecycle operations such as start, stop, pause, and delete VMs on SCVMM managed VMs directly from Azure.

+- Empower developers and application teams to self-serve VM operations on demand using Azure role-based access control (RBAC).

+- Browse your VMM resources (VMs, templates, VM networks, and storage) in Azure, providing you with a single pane view for your infrastructure across both environments.

+- Install the Azure Arc-connected machine agents at scale on SCVMM VMs to govern, protect, configure, and monitor them.

+## Azure Stack HCI

+[Azure Stack HCI](/azure-stack/hci/overview) is a hyperconverged infrastructure operating system delivered as an Azure service. This is a hybrid solution that is designed to host virtualized Windows and Linux VM or containerized workloads and their storage. Azure Stack HCI is a hybrid product that is offered on validated hardware and connects on-premises estates to Azure, enabling cloud-based services, monitoring and management. This helps customers manage their infrastructure from Azure and run virtualized workloads on-premises, making it easy for them to consolidate aging infrastructure and connect to Azure.

+> [!NOTE]

+> Azure Stack HCI comes with Azure resource bridge installed and uses the Azure Arc control plane for infrastructure and workload management, allowing you to monitor, update, and secure your HCI infrastructure from the Azure portal.

+>

+### Capabilities

+- Deploy and manage workloads, including VMs and Kubernetes clusters from Azure through the Azure Arc resource bridge.

+- Manage VM lifecycle operations such as start, stop, delete from Azure control plane.

+- Manage Kubernetes lifecycle operations such as scale, update, upgrade, and delete clusters from Azure control plane.

+- Install Azure connected machine agent and Azure Arc-enabled Kubernetes agent on your VM and Kubernetes clusters to use Azure services (i.e., Azure Monitor, Azure Defender for cloud, etc.).

+- Leverage Azure Virtual Desktop for Azure Stack HCI to deploy session hosts on to your on-premises infrastructure to better meet your performance or data locality requirements.

+- Empower developers and application teams to self-serve VM and Kubernetes cluster operations on demand using Azure role-based access control (RBAC).

+- Monitor, update, and secure your Azure Stack HCI infrastructure and workloads across fleets of locations directly from the Azure portal.

+- Deploy and manage static and DHCP-based logical networks on-premises to host your workloads.

+- VM image management with Azure Marketplace integration and ability to bring your own images from Azure storage account and cluster shared volumes.

+- Create and manage storage paths to store your VM disks and config files.

+## Capabilities at a glance

+The following table provides a quick way to see the major capabilities of the three Azure Arc services that connect your existing Windows and Linux machines to Azure Arc.

+| |Arc-enabled servers |Arc-enabled VMware vSphere |Arc-enabled SCVMM |Arc-enabled Azure Stack HCI |SQL Server enabled by Azure Arc |

+||||||

+|Microsoft Defender for Cloud |Γ£ô |Γ£ô |Γ£ô |Γ£ô |Γ£ô |

+|Microsoft Sentinel | Γ£ô |Γ£ô |Γ£ô |Γ£ô |Γ£ô |

+|Azure Automation |Γ£ô |Γ£ô |Γ£ô |Γ£ô |Γ£ô |

+|Azure Update Manager |Γ£ô |Γ£ô |Γ£ô |Γ£ô |Γ£ô |

+|VM extensions |Γ£ô |Γ£ô |Γ£ô |Γ£ô |Γ£ô |

+|Azure Monitor |Γ£ô |Γ£ô |Γ£ô |Γ£ô |Γ£ô |

+|Extended Security Updates for Windows Server 2012/2012R2 |Γ£ô |Γ£ô |Γ£ô |Γ£ô |Γ£ô |

+|Discover & onboard VMs to Azure | |Γ£ô |Γ£ô |Γ£ô |Γ£ô |

+|Lifecycle operations (start/stop VMs, etc.) | |Γ£ô |Γ£ô |Γ£ô |Γ£ô |

+|Self-serve VM provisioning | |Γ£ô |Γ£ô |Γ£ô |Γ£ô |

+## Switching from Arc-enabled servers to another service

+If you currently use Azure Arc-enabled servers, you can get the additional capabilities that come with Arc-enabled VMware vSphere or Arc-enabled SCVMM:

+- [Enable virtual hardware and VM CRUD capabilities in a machine with Azure Arc agent installed](/azure/azure-arc/vmware-vsphere/enable-virtual-hardware)

+- [Enable virtual hardware and VM CRUD capabilities in an SCVMM machine with Azure Arc agent installed](/azure/azure-arc/system-center-virtual-machine-manager/enable-virtual-hardware-scvmm)

+## April 9, 2024

+**Image tag**:`v1.29.0_2024-04-09`

+For complete release version information, review [Version log](version-log.md#april-9-2024).

+**Image tag**:`v1.28.0_2024-03-12`

+## April 9, 2024

+|Component|Value|

+|--|--|

+|Container images tag |`v1.29.0_2024-04-09`|

+|**CRD names and version:**| |

+|`activedirectoryconnectors.arcdata.microsoft.com`| v1beta1, v1beta2, v1, v2|

+|`datacontrollers.arcdata.microsoft.com`| v1beta1, v1 through v5|

+|`exporttasks.tasks.arcdata.microsoft.com`| v1beta1, v1, v2|

+|`failovergroups.sql.arcdata.microsoft.com`| v1beta1, v1beta2, v1, v2|

+|`kafkas.arcdata.microsoft.com`| v1beta1 through v1beta4|

+|`monitors.arcdata.microsoft.com`| v1beta1, v1, v3|

+|`postgresqls.arcdata.microsoft.com`| v1beta1 through v1beta6|

+|`postgresqlrestoretasks.tasks.postgresql.arcdata.microsoft.com`| v1beta1|

+|`sqlmanagedinstances.sql.arcdata.microsoft.com`| v1beta1, v1 through v13|

+|`sqlmanagedinstancemonitoringprofiles.arcdata.microsoft.com`| v1beta1, v1beta2|

+|`sqlmanagedinstancereprovisionreplicatasks.tasks.sql.arcdata.microsoft.com`| v1beta1|

+|`sqlmanagedinstancerestoretasks.tasks.sql.arcdata.microsoft.com`| v1beta1, v1|

+|`telemetrycollectors.arcdata.microsoft.com`| v1beta1 through v1beta5|

+|`telemetryrouters.arcdata.microsoft.com`| v1beta1 through v1beta5|

+|Azure Resource Manager (ARM) API version|2023-11-01-preview|

+|`arcdata` Azure CLI extension version|1.5.11 ([Download](https://aka.ms/az-cli-arcdata-ext))|

+|Arc-enabled Kubernetes helm chart extension version|1.28.0|

+|Azure Arc Extension for Azure Data Studio<br/>`arc`<br/>`azcli`|<br/>1.8.0 ([Download](https://aka.ms/ads-arcdata-ext))</br>1.8.0 ([Download](https://aka.ms/ads-azcli-ext))|

+|SQL Database version | 964 |

+|`arcdata` Azure CLI extension version|1.5.13 ([Download](https://aka.ms/az-cli-arcdata-ext))|

+|Arc-enabled Kubernetes helm chart extension version|1.29.0|

+For issues encountered with Arc resource bridge, collect logs for further investigation using the Azure CLI [`az arcappliance logs`](/cli/azure/arcappliance/logs) command. This command needs to be run from the same management machine that was used to run commands to deploy the Arc resource bridge. If you're using a different machine to collect logs, you need to run the `az arcappliance get-credentials` command first before collecting logs.

+If you're unsure of your appliance VM IP, there's also the option to use the kubeconfig. You can retrieve the kubeconfig by running the [get-credentials command](/cli/azure/arcappliance) then run the logs command.

+If the resource bridge is offline, this is typically due to a networking change in the infrastructure, environment or cluster that stops the appliance VM from being able to communicate with its counterpart Azure resource. If you're unable to determine what changed, you can reboot the appliance VM, collect logs and submit a support ticket for further investigation.

+### Private link is unsupported

+### No such host - .local not supported

+### No such host - dp.kubernetesconfiguration.azure.com

+An error that contains `dial tcp: lookup westeurope.dp.kubernetesconfiguration.azure.com: no such host` while deploying Arc resource bridge means that the configuration dataplane is currently unavailable in the specified region. The service may be temporarily unavailable. Please wait for the service to be available and then retry the deployment.

+### Proxy connect tcp - No such host for Arc resource bridge required URL

+An error that contains an Arc resource bridge required URL with the message `proxyconnect tcp: dial tcp: lookup http: no such host` indicates that DNS is not able to resolve the URL. The error may look similar to the example below, where the required URL is `https://msk8s.api.cdp.microsoft.com`:

+`Error: { _errorCode_: _InvalidEntityError_, _errorResponse_: _{\n\_message\_: \_Post \\\_https://msk8s.api.cdp.microsoft.com/api/v1.1/contents/default/namespaces/default/names/arc-appliance-stable-catalogs-ext/versions/latest?action=select\\\_: POST https://msk8s.api.cdp.microsoft.com/api/v1.1/contents/default/namespaces/default/names/arc-appliance-stable-catalogs-ext/versions/latest?action=select giving up after 6 attempt(s): Post \\\_https://msk8s.api.cdp.microsoft.com/api/v1.1/contents/default/namespaces/default/names/arc-appliance-stable-catalogs-ext/versions/latest?action=select\\\_: proxyconnect tcp: dial tcp: lookup http: no such host\_\n}_ }`

+This error can occur if the DNS settings provided during deployment are not correct or there is a problem with the DNS server(s). You can check if your DNS server is able to resolve the url by running the following command from the management machine or a machine that has access to the DNS server(s):

+```

+nslookup

+> set debug

+> <hostname> <DNS server IP>

+```

+In order to resolve the error, your DNS server(s) must be configured to resolve all Arc resource bridge required URLs and the DNS server(s) should be correctly provided during deployment of Arc resource bridge.

+The KVA timeout error is a generic error that can be the result of a variety of network misconfigurations that involve the management machine, Appliance VM, or Control Plane IP not having communication with each other, to the internet, or required URLs. This communication failure is often due to issues with DNS resolution, proxy settings, network configuration, or internet access.

+For clarity, management machine refers to the machine where deployment CLI commands are being run. Appliance VM is the VM that hosts Arc resource bridge. Control Plane IP is the IP of the control plane for the Kubernetes management cluster in the Appliance VM.

+1. The management machine must be able to communicate with the Appliance VM IP and Control Plane IP. Ping the Control Plane IP and Appliance VM IP from the management machine and verify there's a response from both IPs.

+

+### vSphere SDK client 403 Forbidden or 404 not found

+If you receive an error that contains `errorCode_: _CreateConfigKvaCustomerError_, _errorResponse_: _error getting the vsphere sdk client: POST \_/sdk\_: 403 Forbidden` or `404 not found` while deploying Arc resource bridge, this is most likely due to an incorrect vCenter URL being provided during configuration file creation where you're prompted to enter the vCenter address as either FQDN or IP address. There are different ways to find your vCenter address. One option is to access the vSphere client via its web interface. The vCenter FQDN or IP address is typically what you use in the browser to access the vSphere client. If you're already logged in, you can look at the browser's address bar; the URL you use to access vSphere is your vCenter server's FQDN or IP address. Alternatively, after logging in, go to the Menu > Administration section. Under System Configuration, choose Nodes. Your vCenter server instance(s) will be listed there along with its FQDN. Verify your vCenter address and then re-try the deployment.

+### Pre-deployment validation errors

+If you're receiving a variety of `pre-deployment validation of your download\upload connectivity wasn't successful` errors, such as:

+`Pre-deployment validation of your download/upload connectivity wasn't successful. {\\n \\\_code\\\_: \\\_ImageProvisionError\\\_,\\n \\\_message\\\_: \\\_Post \\\\\\\_https://vcenter-server.com/nfc/unique-identifier/disk-0.vmdk\\\\\\\_: Service Unavailable`

+`Pre-deployment validation of your download/upload connectivity wasn't successful. {\\n \\\_code\\\_: \\\_ImageProvisionError\\\_,\\n \\\_message\\\_: \\\_Post \\\\\\\_https://vcenter-server.com/nfc/unique-identifier/disk-0.vmdk\\\\\\\_: dial tcp 172.16.60.10:443: connectex: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.`

+`Pre-deployment validation of your download/upload connectivity wasn't successful. {\\n \\\_code\\\_: \\\_ImageProvisionError\\\_,\\n \\\_message\\\_: \\\_Post \\\\\\\_https://vcenter-server.com/nfc/unique-identifier/disk-0.vmdk\\\\\\\_: use of closed network connection.`

+`Pre-deployment validation of your download/upload connectivity wasn't successful. {\\n \\\_code\\\_: \\\_ImageProvisionError\\\_,\\n \\\_message\\\_: \\\_Post \\\\\\\_https://vcenter-server.com/nfc/unique-identifier/disk-0.vmdk\\\\\\\_: dial tcp: lookup hostname.domain: no such host`

+A combination of these errors usually indicates that the management machine has lost connection to the datastore or there's a networking issue causing the datastore to be unreachable. This connection is needed in order to upload the OVA from the management machine used to build the appliance VM in vCenter. The connection between the management machine and datastore needs to be reestablished, then retry deployment of Arc resource bridge.

+### x509 certificate has expired or isn't yet valid

+When you deploy Arc resource bridge, you may encounter the error:

+`Error: { _errorCode_: _PostOperationsError_, _errorResponse_: _{\n\_message\_: \_{\\n \\\_code\\\_: \\\_GuestInternetConnectivityError\\\_,\\n \\\_message\\\_: \\\_Not able to connect to https://msk8s.api.cdp.microsoft.com. Error returned: action failed after 3 attempts: Get \\\\\\\_https://msk8s.api.cdp.microsoft.com\\\\\\\_: x509: certificate has expired or isn't yet valid: current time 2022-01-18T11:35:56Z is before 2023-09-07T19:13:21Z. Arc Resource Bridge network and internet connectivity validation failed: http-connectivity-test-arc. 1. Please check your networking setup and ensure the URLs mentioned in : https://aka.ms/AAla73m are reachable from the Appliance VM. 2. Check firewall/proxy settings`

+This error is caused when there's a clock/time difference between ESXi host(s) and the management machine where the deployment commands for Arc resource bridge are being executed. To resolve this issue, turn on NTP time sync on the ESXi host(s) and confirm that the management machine is also synced to NTP, then try the deployment again.

+If you have been using the same template to deploy and delete the Arc resource bridge multiple times, you might encounter the following error:

+`Appliance cluster deployment failed with error: Error: An error occurred during host configuration`

+To resolve this issue, manually delete the existing template. Then run [`az arcappliance prepare`](/cli/azure/arcappliance/prepare) to download a new template for deployment.

+When deploying the resource bridge on VMware vCenter, you specify the folder in which the template and VM will be created. The folder must be VM and template folder type. Other types of folder, such as storage folders, network folders, or host and cluster folders, can't be used for the resource bridge deployment.

+Three factors impact billing for Extended Security Updates (ESUs):

+- The number of cores provisioned

+Billing is monthly. Decrementing, deactivating, or deleting a license results in charges for up to five more calendar days from the time of decrement, deactivation, or deletion. Reduction in billing isn't immediate. This is an Azure-billed service and can be used to decrement a customer's Microsoft Azure Consumption Commitment (MACC) and be eligible for Azure Consumption Discount (ACD).

+Licenses that are provisioned after the End of Support (EOS) date of October 10, 2023 are charged a back bill for the time elapsed since the EOS date. For example, an ESU license provisioned in December 2023 is back-billed for October and November upon provisioning. Enrolling late in WS2012 ESUs makes you eligible for all the critical security patches up to that point. The back-billing charge reflects the value of these critical security patches.

+If you deactivate and then later reactivate a license, you're billed for the window during which the license was deactivated. It isn't possible to evade charges by deactivating a license before a critical security patch and reactivating it shortly before.

+If the region of an ESU license is changed, this will be subject to back-billing charges.

+ - [Configure Windows machines](https://portal.azure.com/#view/Microsoft_Azure_Policy/InitiativeDetail.ReactView/id/%2Fproviders%2FMicrosoft.Authorization%2FpolicySetDefinitions%2F9575b8b7-78ab-4281-b53b-d3c1ace2260b/scopes/undefined)

+ - [Configure Linux machines](https://portal.azure.com/#view/Microsoft_Azure_Policy/InitiativeDetail.ReactView/id/%2Fproviders%2FMicrosoft.Authorization%2FpolicySetDefinitions%2F118f04da-0375-44d1-84e3-0fd9e1849403/scopes/undefined)

+For Windows Server 2022, Azure Arc Setup is an optional component that can be removed using the **Remove Roles and Features Wizard**. For Windows Server 2025 and later, Azure Arc Setup is a [Features On Demand](/windows-hardware/manufacture/desktop/features-on-demand-v2--capabilities?view=windows-11). Essentially, this means that the procedures for removal and enablement differ between OS versions. See for more information.

+> The Azure Arc Setup feature only applies to Windows Server 2022 and later. It was released in the [Cumulative Update of 10/10/2023](https://support.microsoft.com/en-us/topic/october-10-2023-kb5031364-os-build-20348-2031-7f1d69e7-c468-4566-887a-1902af791bbc).

+> [!NOTE]

+> Uninstalling Azure Arc Setup does not uninstall the Azure Connected Machine agent from the machine. For instructions on uninstalling the agent, see [Managing and maintaining the Connected Machine agent](manage-agent.md).

+>

+To uninstall Azure Arc Setup from a Windows Server 2022 machine:

+1. In the Server Manager, navigate to the **Remove Roles and Features Wizard**. (See [Remove roles, role services, and features by using the Remove Roles and Features Wizard](/windows-server/administration/server-manager/install-or-uninstall-roles-role-services-or-features#remove-roles-role-services-and-features-by-using-the-remove-roles-and-features-wizard) for more information.)

+To uninstall Azure Arc Setup from a Windows Server 2025 machine:

+1. Open the Settings app on the machine and select **System**, then select **Optional features**.

+1. Select **AzureArcSetup**, and then select **Remove**.

+To uninstall Azure Arc Setup from a Windows Server 2025 machine from the command line, run the following line of code:

+`DISM /online /Remove-Capability /CapabilityName:AzureArcSetup~~~~`

+> [!NOTE]

+> For additional guidance regarding the different services Azure Arc offers, see [Choosing the right Azure Arc service for machines](../choose-service.md).

+>

+ Title: SSH access to Azure Arc-enabled servers with PowerShell remoting

+description: Use PowerShell remoting over SSH to access and manage Azure Arc-enabled servers.

+# PowerShell remoting to Azure Arc-enabled servers

+SSH for Arc-enabled servers enables SSH based connections to Arc-enabled servers without requiring a public IP address or additional open ports.

+[PowerShell remoting over SSH](/powershell/scripting/security/remoting/ssh-remoting-in-powershell) is available for Windows and Linux machines.

+## Prerequisites

+To leverage PowerShell remoting over SSH access to Azure Arc-enabled servers, ensure the following:

+ - Ensure the requirements for SSH access to Azure Arc-enabled servers are met.

+ - Ensure the requirements for PowerShell remoting over SSH are met.

+ - The Azure PowerShell module or the Azure CLI extension for connecting to Arc machines is present on the client machine.

+## How to connect via PowerShell remoting

+Follow the below steps to connect via PowerShell remoting to an Arc-enabled server.

+#### [Generate a SSH config file with Azure CLI:](#tab/azure-cli)

+```bash

+az ssh config --resource-group <myRG> --name <myMachine> --local-user <localUser> --resource-type Microsoft.HybridCompute --file <SSH config file>

+```

+

+#### [Generate a SSH config file with Azure PowerShell:](#tab/azure-powershell)

+ ```powershell

+Export-AzSshConfig -ResourceGroupName <myRG> -Name <myMachine> -LocalUser <localUser> -ResourceType Microsoft.HybridCompute/machines -ConfigFilePath <SSH config file>

+```

+

+#### Find newly created entry in the SSH config file

+Open the created or modified SSH config file. The entry should have a similar format to the following.

+```powershell

+Host <myRG>-<myMachine>-<localUser>

+ HostName <myMachine>

+ User <localUser>

+ ProxyCommand "<path to proxy>\.clientsshproxy\sshProxy_windows_amd64_1_3_022941.exe" -r "<path to relay info>\az_ssh_config\<myRG>-<myMachine>\<myRG>-<myMachine>-relay_info"

+```

+#### Leveraging the -Options parameter

+Levering the [options](/powershell/module/microsoft.powershell.core/new-pssession#-options) parameter allows you to specify a hashtable of SSH options used when connecting to a remote SSH-based session.

+Create the hashtable by following the below format. Be mindful of the locations of quotation marks.

+```powershell

+$options = @{ProxyCommand = '"<path to proxy>\.clientsshproxy\sshProxy_windows_amd64_1_3_022941.exe -r <path to relay info>\az_ssh_config\<myRG>-<myMachine>\<myRG>-<myMachine>-relay_info"'}

+```

+Next leverage the options hashtable in a PowerShell remoting command.

+```powershell

+New-PSSession -HostName <myMachine> -UserName <localUser> -Options $options

+```

+## Next steps

+- Learn about [OpenSSH for Windows](/windows-server/administration/openssh/openssh_overview)

+- Learn about troubleshooting [SSH access to Azure Arc-enabled servers](ssh-arc-troubleshoot.md).

+- Learn about troubleshooting [agent connection issues](troubleshoot-agent-onboard.md).

+For information on using Microsoft Entra ID with Azure CLI, see the [references pages for identity](/cli/azure/redis/identity).

+## Related content

+- [Reference pages for identity](/cli/azure/redis/identity)

+## Enterprise Flash Best Practices

+The Enterprise Flash tier utilizes both NVMe Flash storage and RAM. Because Flash storage is lower cost, using the Enterprise Flash tier allows you to trade off some performance for price efficiency.

+On Enterprise Flash instances, 20% of the cache space is on RAM, while the other 80% uses Flash storage. All of the _keys_ are stored on RAM, while the _values_ can be stored either in Flash storage or RAM. The location of the values is determined intelligently by the Redis software. "Hot" values that are accessed fequently are stored on RAM, while "Cold" values that are less commonly used are kept on Flash. Before data is read or written, it must be moved to RAM, becoming "Hot" data.

+Because Redis will optmize for the best performance, the instance will first fill up the available RAM before adding items to Flash storage. This has a few implications for performance:

+- When testing with low memory usage, performance and latency may be significantly better than with a full cache instance because only RAM is being used.

+- As you write more data to the cache, the proportion of data in RAM compared to Flash storage will decrease, typically causing latency and throughput performance to decrease as well.

+### Workloads well-suited for the Enterprise Flash tier

+Workloads that are likely to run well on the Enterprise Flash tier often have the following characteristics:

+- Read heavy, with a high ratio of read commands to write commands.

+- Access is focused on a subset of keys which are used much more frequently than the rest of the dataset.

+- Relatively large values in comparison to key names. (Since key names are always stored in RAM, this can become a bottleneck for memory growth.)

+### Workloads that are not well-suited for the Enterprise Flash tier

+Some workloads have access characteristics that are less optimized for the design of the Flash tier:

+- Write heavy workloads.

+- Random or uniform data access paterns across most of the dataset.

+- Long key names with relatively small value sizes.

+- **System-assigned identity** is specific to the resource. In this case, the cache is the resource. When the cache is deleted, the identity is deleted.

+1. Open the **Access control (IAM)** from the Resource menu. Then, select **Add**, and **Add role assignment**.

+1. Search for the **Storage Blob Data Contributor** on the Role pane. Select it and **Next**.

+1. Select the **Members** tab. Under **Assign access to** select **Managed Identity**, and select on **Select members**. A sidebar pops up next to the working pane.

+1. Use the drop-down under **Managed Identity** to choose either a **User-assigned managed identity** or a **System-assigned managed identity**. If you have many managed identities, you can search by name. Choose the managed identities you want and then **Select**. Then, **Review + assign** to confirm.

+1. You can confirm if the identity has been assigned successfully by checking your storage account's role assignments under **Storage Blob Data Contributor**.

+1. Change the **Authentication Method** to **Managed Identity** and select the storage account you configured earlier in the article. select **Save**.

+1. Data persistence backups can now be saved to the storage account using managed identity authentication.

+1. If importing data, choose the blob storage location that holds your chosen RDB file. If exporting data, type your desired blob name prefix and storage container. In both situations, you must use the storage account you've configured for managed identity access.

+1. Under **Authentication Method**, choose **Managed Identity** and select **Import** or **Export**, respectively.

+## Related content

+The Bicep file used in this quickstart is from [Azure Quickstart Templates](https://azure.microsoft.com/resources/templates//).

+description: In this quickstart, learn how to create an instance of Azure Cache for Redis in use the Enterprise tier.

+The Azure Cache for Redis Enterprise tiers provide fully integrated and managed [Redis Enterprise](https://redislabs.com/redis-enterprise/) on Azure. These tiers are:

+- Enterprise, which uses volatile memory (DRAM) on a virtual machine to store data

+- Enterprise Flash, which uses both volatile and nonvolatile memory (NVMe or SSD) to store data.

+- You need an Azure subscription before you begin. If you don't have one, create an [account](https://azure.microsoft.com/). For more information, see [special considerations for Enterprise tiers](cache-overview.md#special-considerations-for-enterprise-tiers).

+ | **DNS name** | Enter a name that is unique in the region. | The cache name must be a string between 1 and 63 characters when _combined with the cache's region name_ that contain only numbers, letters, or hyphens. (If the cache name is fewer than 45 characters long it should work in all currently available regions.) The name must start and end with a number or letter, and can't contain consecutive hyphens. Your cache instance's _host name_ is `\<DNS name\>.\<Azure region\>.redisenterprise.cache.azure.net`. |

+ | **Cache type** | Drop down and select an _Enterprise_ or _Enterprise Flash_ tier and a size. | The tier determines the size, performance, and features that are available for the cache. |

+ > Enterprise and Enterprise Flash tiers are inherently clustered, in contrast to the Basic, Standard, and Premium tiers. Redis Enterprise supports two clustering policies.

+ >- Use the **Enterprise** policy to access your cache using the Redis API.

+ >- Use **OSS** to use the OSS Cluster API.

+ >

+ > You can't change modules after you create a cache instance. Modules must be enabled at the time you create an Azure Cache for Redis instance. There is no option to enable the configuration of a module after you create a cache.

+## Related content

+You need to install the latest version of the Netherite Extension on NuGet. This usually means including a reference to it in your `.csproj` file and building the project.

+The snippet above is just a *minimal* configuration. Later, you may want to consider [other parameters](https://microsoft.github.io/durabletask-netherite/#/settings?id=typical-configuration).

+> [!NOTE]

+> If you are using local storage emulation on a Windows OS, please ensure you're using the [Azurite](../../storage/common/storage-use-azurite.md) storage emulator and not the legacy "Azure Storage Emulator" component. Local storage emulation with Netherite is only supported via Azurite.

+You need to set up an Event Hubs namespace to run Netherite on Azure. You can also set it up if you prefer to use Event Hubs during local development.

+ |**Select an Azure Database Server**| Choose **Core (NoSQL)** to create a document database that you can query by using a SQL syntax or a Query Copilot ([Preview](../cosmos-db/nosql/query/how-to-enable-use-copilot.md)) converting natural language prompts to queries. [Learn more about the Azure Cosmos DB](../cosmos-db/introduction.md). |

+The App Service platform maintains a native deployment service ([Project Kudu](https://github.com/projectkudu/kudu/wiki)) to support local Git deployment, some container deployments, and other deployment sources not supported by either Pipelines or GitHub Actions. Remote builds, packaging, and other maintainence tasks are performed in a subdomain of `scm.azurewebsites.net` dedicated to your app, such as `https://myfunctionapp.scm.azurewebsites.net`. This build service can only be used when the `scm` site can be accessed by your deployment. Many publishing tools require basic authentication to connect to the `scm` endpoint. For more information, see [Enable basic authentication for deployments](#enable-basic-authentication-for-deployments).

+This build provider is used when you deploy your code project by using Visual Studio, Visual Studio Code, or Azure Functions Core Tools. If you haven't already deployed by using one of these tools, you might need to Enable basic authentication on the SCM endpoint.

+## Continuous deployment during app creation

+Currently, you can configure continuous deployment from GitHub using GitHub Actions when you create your function app in the Azure portal. You can do this on the **Deployment** tab in the **Create Function App** page.

+If you want to use a different deployment source or build provider for continuous integration, first create your function app and then return to the portal and [set up continuous integration in the Deployment Center](#credentials).

+## Enable basic authentication for deployments

+By default, your function app is created with basic authentication access to the `scm` endpoint disabled. This blocks publishing by all methods that can't use managed identities to access the `scm` endpoint. The publishing impacts of having the `scm` endpoint disabled are detailed in [Deployment without basic authentication](../app-service/configure-basic-auth-disable.md#deployment-without-basic-authentication).

+> [!IMPORTANT]

+> When you use basic authenication, credentials are sent in clear text. To protect these credentials, you must only access the `scm` endpoint over an encrypted connection ( HTTPS) when using basic authentication. For more information, see [Secure deployment](security-concepts.md#secure-deployment).

+To enable basic authentication to the `scm` endpoint:

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

+1. In the [Azure portal](https://portal.azure.com), navigate to your function app.

+1. In the app's left menu, select **Configuration** > **General settings**.

+1. Set **SCM Basic Auth Publishing Credentials** to **On**, then select **Save**.

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

+You can use the Azure CLI to turn on basic authentication by using this [`az resource update`](/cli/azure/resource#az-resource-update) command to update the resource that controls the `scm` endpoint.

+```azure-cli

+az resource update --resource-group <RESOURCE_GROUP> --name scm --namespace Microsoft.Web --resource-type basicPublishingCredentialsPolicies --parent sites/<APP_NAME> --set properties.allow=true

+```

+In this command, replace the placeholders with your resource group name and app name.

+Azure Functions integrates well with [Azure Cosmos DB](../cosmos-db/introduction.md) for many [use cases](../cosmos-db/use-cases.md), including IoT, ecommerce, gaming, etc.

+For example, for [event sourcing](https://learn.microsoft.com/azure/architecture/patterns/event-sourcing), the two services are integrated to power event-driven architectures using Azure Cosmos DB's [change feed](../cosmos-db/change-feed.md) functionality. The change feed provides downstream microservices the ability to reliably and incrementally read inserts and updates (for example, order events). This functionality can be leveraged to provide a persistent event store as a message broker for state-changing events and drive order processing workflow between many microservices (which can be implemented as [serverless Azure Functions](https://azure.com/serverless)).

+To connect to Cosmos DB, first [create an account, database, and container](../cosmos-db/nosql/quickstart-portal.md). Then you may connect Functions to Cosmos DB using [trigger and bindings](functions-bindings-cosmosdb-v2.md), like this [example](functions-add-output-binding-cosmos-db-vs-code.md).

+To implement more complex app logic, you may also use the Python library for Cosmos DB. An aynchronous I/O implementation looks like this:

+pip install azure-cosmos

+pip install aiohttp

+from azure.cosmos.aio import CosmosClient

+from azure.cosmos import exceptions

+import asyncio

+# Singleton CosmosClient instance

+client = CosmosClient(endpoint, credential=key)

+# Helper function to get or create database and container

+async def get_or_create_container(client, database_id, container_id, partition_key):

+ database = await client.create_database_if_not_exists(id=database_id)

+ container = await database.create_container_if_not_exists(id=container_id, partition_key=PartitionKey(path=partition_key))

+ print(f'Container with id "{container_id}" created')

+

+ return container

+

+async def create_products():

+ container = await get_or_create_container(client, database_id, container_id, partition_key)

+ for i in range(10):

+ await container.upsert_item({

+ 'id': f'item{i}',

+ 'productName': 'Widget',

+ 'productModel': f'Model {i}'

+ })

+

+async def get_products():

+ items = []

+ container = await get_or_create_container(client, database_id, container_id, partition_key)

+ async for item in container.read_all_items():

+ items.append(item)

+ return items

+async def query_products(product_name):

+ container = await get_or_create_container(client, database_id, container_id, partition_key)

+ query = f"SELECT * FROM c WHERE c.productName = '{product_name}'"

+ items = []

+ async for item in container.query_items(query=query, enable_cross_partition_query=True):

+ items.append(item)

+ return items

+async def main():

+ await create_products()

+ all_products = await get_products()

+ print('All Products:', all_products)

+ queried_products = await query_products('Widget')

+ print('Queried Products:', queried_products)

+if __name__ == "__main__":

+ asyncio.run(main())

+8. Add mount entries to /etc/fstab

+/dev/mapper/prodvg-prod01 /prod01 xfs defaults 0 0

+/dev/mapper/jrnvg-jrn /jrn xfs defaults 0 0

+/dev/mapper/instvg-prd /prd xfs defaults 0 0

+Two [Kubernetes Services](../../articles/aks/concepts-network-services.md) are also created:

+This manifest also creates two [Kubernetes Services](../../articles/aks/concepts-network-services.md):

+Two [Kubernetes Services](../../articles/aks/concepts-network-services.md) are also created:

+This article covers where you can get help when developing your solutions with the Azure Linux Container Host.

+## Stay connected with Azure Linux

+We're hosting public community calls for Azure Linux users to get together and discuss new features, provide feedback, and learn more about how others use Azure Linux. In each session, we will feature a new demo.

+Azure Linux published a [feature roadmap](https://github.com/orgs/microsoft/projects/970/views/2) that contains features that are in development and available for GA and public preview. This feature roadmap will be reviewed in each community call. We welcome you to leave feedback or ask questions on feature items.

+The schedule for the upcoming community calls is as follows:

+[create an IoT hub]: ../iot/tutorial-send-telemetry-iot-hub.md?pivots=programming-language-csharp#create-an-iot-hub

+[Send telemetry from a device]: ../iot/tutorial-send-telemetry-iot-hub.md?pivots=programming-language-csharp

+| [Render] | Yes, except Get Copyright API, Get Attribution API and Terra maps (`MapTile.GetTerraTile` and `layer=terra`) which are nonbillable.|<ul><li>15 tiles = 1 transaction</li><li>One request for Get Copyright = 1 transaction</li><li>One request for Get Map Attribution = 1 transaction</li><li>One request for Get Static Map = 1 transaction</li><li>One request for Get Map Tileset = 1 transaction</li></ul> <br> For Creator related usage, see the [Creator table]. |<ul><li>Maps Base Map Tiles (Gen2 pricing)</li><li>Maps Imagery Tiles (Gen2 pricing)</li><li>Maps Static Map Images (Gen2 pricing)</li><li>Maps Weather Tiles (Gen2 pricing)</li><li>Standard Hybrid Aerial Imagery Transactions (Gen1 S0 pricing)</li><li>Standard Aerial Imagery Transactions (Gen1 S0 pricing)</li><li>Standard S1 Aerial Imagery Transactions (Gen1 S1 pricing)</li><li>Standard S1 Hybrid Aerial Imagery Transactions (Gen1 S1 pricing)</li><li>Standard S1 Rendering Transactions (Gen1 S1 pricing)</li><li>Standard S1 Tile Transactions (Gen1 S1 pricing)</li><li>Standard S1 Weather Tile Transactions (Gen1 S1 pricing)</li><li>Standard Tile Transactions (Gen1 S0 pricing)</li><li>Standard Weather Tile Transactions (Gen1 S0 pricing)</li><li>Maps Copyright (Gen2 pricing, Gen1 S0 pricing and Gen1 S1 pricing)</li></ul>|

+| 23 | :::image type="icon" source="./media/weather-services-concepts/mostly-cloudy-snow.png"::: | Yes | No | Mostly Cloudy with Snow|

+| 44 | :::image type="icon" source="./media/weather-services-concepts/mostly-cloudy-snow-night.png"::: | No | Yes | Mostly Cloudy with Snow|

+| Windows 11 Client and Pro | Γ£ô<sup>1</sup>, <sup>2</sup> | | |

+| Windows 10 1803 (RS4) and higher | Γ£ô<sup>1</sup> | | |

+<sup>1</sup> Using the Azure Monitor agent [client installer](./azure-monitor-agent-windows-client.md).<br>

+<sup>2</sup> Also supported on Arm64-based machines.

+#### 1. Assign the Monitored Objects Contributor role to the operator

+### What is the Application Insights pricing model?

+Application Insights is billed through the Log Analytics workspace into which its log data ingested.

+The default Pay-as-you-go Log Analytics pricing tier includes 5 GB per month of free data allowance per billing account.

+Learn more about [Azure Monitor logs pricing options](https://azure.microsoft.com/pricing/details/monitor/).

+

+### Are there data transfer charges between an Azure web app and Application Insights?

+* If your Azure web app is hosted in a datacenter where there's an Application Insights collection endpoint, there's no charge.

+* If there's no collection endpoint in your host datacenter, your app's telemetry incurs [Azure outgoing charges](https://azure.microsoft.com/pricing/details/bandwidth/).

+

+This answer depends on the distribution of our endpoints, *not* on where your Application Insights resource is hosted.

+### Do I incur network costs if my Application Insights resource is monitoring an Azure resource (that is, telemetry producer) in a different region?

+Yes, you may incur more network costs, which vary depending on the region the telemetry is coming from and where it's going.

+Refer to [Azure bandwidth pricing](https://azure.microsoft.com/pricing/details/bandwidth/) for details.

+- Have an Owner role to the resource group if you want to grant access by using [Azure built-in roles](../../role-based-access-control/built-in-roles.md).

+The following Software Development Kits (SDKs) and features are unsupported for use with Microsoft Entra authenticated ingestion:

+1. After disabling local authentication on your resource, you'll see the corresponding information in the **Overview** pane.

+The audience parameter, AADAudience, can vary depending on your specific environment.

+This error shows the resource is set for Microsoft Entra-only. You need to correctly configure the SDK because it's sending to the wrong API.

+This error means the SDK uses credentials without permission for the Application Insights resource or subscription.

+First, check the Application Insights resource's access control. You must configure the SDK with credentials that have the Monitoring Metrics Publisher role.

+Or add the following Java Virtual Machine (JVM) args while running your application: `-Djava.net.useSystemProxies=true -Dhttps.proxyHost=localhost -Dhttps.proxyPort=8888`

+If you see the message, `WARN c.m.a.TelemetryChannel - Failed to send telemetry with status code: 401, please check your credentials` in the log, it means the agent couldn't send telemetry. You likely didn't enable Microsoft Entra authentication on the agent, while your Application Insights resource has `DisableLocalAuth: true`. Ensure you pass a valid credential with access permission to your Application Insights resource.

+If you see the exception, `com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established` in the log file, it means the agent failed to acquire the access token. The likely cause is an invalid client ID in your User-Assigned Managed Identity configuration.

+If you see the message, `WARN c.m.a.TelemetryChannel - Failed to send telemetry with status code: 403, please check your credentials` in the log, it means the agent couldn't send telemetry. The likely reason is that the credentials used don't allow telemetry ingestion.

+Using Fiddler, you might notice the response `HTTP/1.1 403 Forbidden - provided credentials do not grant the access to ingest the telemetry into the component`.

+The issue could be due to:

+- Creating the resource with a system-assigned managed identity or associating a user-assigned identity without adding the Monitoring Metrics Publisher role to it.

+- Using the correct credentials for access tokens but linking them to the wrong Application Insights resource. Ensure your resource (virtual machine or app service) or user-assigned identity has Monitoring Metrics Publisher roles in your Application Insights resource.

+If the exception, `com.microsoft.aad.msal4j.MsalServiceException: Application with identifier <CLIENT_ID> was not found in the directory` in the log, it means the agent failed to get the access token. This exception likely happens because the client ID in your client secret configuration is invalid or incorrect.

+This issue occurs if the administrator doesn't install the application or no tenant user consents to it. It also happens if you send your authentication request to the wrong tenant.

+To instrument your Node.js application, use the [OpenTelemetry Distro](./opentelemetry-enable.md).

+To monitor Python apps, use the [OpenTelemetry Distro](./opentelemetry-enable.md).

+There's usually no difference, with two exceptions.

+- Application Insights resources that were receiving 1 GB per month free via legacy Application Insights pricing model will no longer receive the free data.

+- Application Insights resources that were in the basic pricing tier prior to April 2018 continue to be billed at the same non-regional price point as before April 2018. Application Insights resources created after that time, or those converted to be workspace-based, will receive the current regional pricing. For current prices in your currency and region, see [Application Insights pricing](https://azure.microsoft.com/pricing/details/monitor/).

+## Sampling overrides

+by configuring [sampling overrides](./java-standalone-config.md#sampling-overrides).

+See [sampling overrides](java-standalone-config.md#sampling-overrides) and [telemetry processors](java-standalone-telemetry-processors.md).

+- To provide the TLS config setting in a configmap, please create the self-signed certificate and key inside your mtls enabled app.

+- To provide the TLS config setting in a CRD, please create the self-signed certificate and key inside your mtls enabled app.

+Azure Monitor uses a consumption-based pricing (pay-as-you-go) billing model where you only pay for what you use. Features of Azure Monitor that are enabled by default don't incur any charge. This includes collection and alerting on the [Activity log](essentials/activity-log.md) and collection and analysis of [platform metrics](essentials/metrics-supported.md).

+| Logs |Ingestion, retention, and export of data in [Log Analytics workspaces](logs/log-analytics-workspace-overview.md) and [legacy Application insights resources](app/convert-classic-resource.md). Log data ingestion will typically be the largest component of Azure Monitor charges for most customers. There's no charge for querying this data except in the case of [Basic Logs](logs/basic-logs-configure.md) or [Archived Logs](logs/data-retention-archive.md).<br><br>Charges for Logs can vary significantly on the configuration that you choose. See [Azure Monitor Logs pricing details](logs/cost-logs.md) for details on how charges for Logs data are calculated and the different pricing tiers available. |

+| Platform Logs | Processing of [diagnostic and auditing information](essentials/resource-logs.md) is charged for [certain services](essentials/resource-logs-categories.md#costs) when sent to destinations other than a Log Analytics workspace. There's no direct charge when this data is sent to a Log Analytics workspace, but there's a charge for the workspace data ingestion and collection. |

+| Metrics | There's no charge for [standard metrics](essentials/metrics-supported.md) collected from Azure resources. There's a cost for collecting [custom metrics](essentials/metrics-custom-overview.md) and for retrieving metrics from the [REST API](essentials/rest-api-walkthrough.md#retrieve-metric-values). |

+| Alerts | Alerts are charged based on the type and number of [signals](alerts/alerts-overview.md) used by the alert rule, its frequency, and the type of [notification](alerts/action-groups.md) used in response. For [log search alerts](alerts/alerts-types.md#log-alerts) configured for [at scale monitoring](alerts/alerts-types.md#monitor-the-same-condition-on-multiple-resources-using-splitting-by-dimensions-1), the cost also depends on the number of time series created by the dimensions resulting from your query. |

+| Web tests | There's a cost for [standard web tests](app/availability-standard-tests.md) and [multi-step web tests](app/availability-multistep.md) in Application Insights. Multi-step web tests are deprecated.|

+There are two primary tools to view, analyze, and optimize your Azure Monitor costs. Each is described in detail in the following sections.

+To get started analyzing your Azure Monitor charges, open [Cost Management + Billing](../cost-management-billing/costs/quick-acm-cost-analysis.md?toc=/azure/billing/TOC.json) in the Azure portal. This tool includes several built-in dashboards for deep cost analysis like cost by resource and invoice details. Select **Cost Management** and then **Cost analysis**. Select your subscription or another [scope](../cost-management-billing/costs/understand-work-scopes.md).

+Other services such as Microsoft Defender for Cloud and Microsoft Sentinel also bill their usage against Log Analytics workspace resources. See [Common cost analysis uses](../cost-management-billing/costs/cost-analysis-common-uses.md) for details on using this view.

+- **Daily cost analysis emails.** After you configure your Cost Analysis view, you should click **Subscribe** at the top of the screen to receive regular email updates from Cost Analysis.

+- **Budget alerts.** To be notified if there are significant increases in your spending, create a [budget alerts](../cost-management-billing/costs/cost-mgt-alerts-monitor-usage-spending.md) for a single workspace or group of workspaces.

+These exports are in CSV format and contain a list of daily usage (billed quantity and cost) by resource, [billing meter](cost-meters.md), and several other fields such as [AdditionalInfo](../cost-management-billing/automate/understand-usage-details-fields.md#list-of-fields-and-descriptions). You can use Microsoft Excel to do rich analyses of your usage not possible in the **Cost Analytics** experiences in the portal.

+For example, usage from Log Analytics can be found by first filtering on the **Meter Category** column to show:

+There are several approaches to view the benefits a workspace receives from offers that are part of other products. These offers are:

+1. [Defender for Servers data allowance](logs/cost-logs.md#workspaces-with-microsoft-defender-for-cloud) and

+1. [Microsoft Sentinel benefit for Microsoft 365 E5, A5, F5, and G5 customers](https://azure.microsoft.com/offers/sentinel-microsoft-365-offer/).

+Since a usage export has both the number of units of usage and their cost, you can use this export to see the benefits you're receiving. In the usage export, to see the benefits, filter the *Instance ID* column to your workspace. (To select all of your workspaces in the spreadsheet, filter the *Instance ID* column to "contains /workspaces/".) Then filter on the Meter to either of the following 2 meters:

+- **Standard Data Included per Node**: this meter is under the service "Insight and Analytics" and tracks the benefits received when a workspace in either in Log Analytics [Per Node tier](logs/cost-logs.md#per-node-pricing-tier) data allowance and/or has [Defender for Servers](logs/cost-logs.md#workspaces-with-microsoft-defender-for-cloud) enabled. Each of these allowances provide a 500 MB/server/day data allowance.

+- **Free Benefit - M365 Defender Data Ingestion**: this meter, under the service "Azure Monitor", tracks the benefit from the [Microsoft Sentinel benefit for Microsoft 365 E5, A5, F5, and G5 customers](https://azure.microsoft.com/offers/sentinel-microsoft-365-offer/).

+You can also see these data benefits in the Log Analytics Usage and estimated costs page. If the workspace is receiving these benefits, there's a sentence below the cost estimate table that gives the data volume of the benefits used over the last 31 days.

+The [Operation](/azure/azure-monitor/reference/tables/operation) table contains daily events which given the amount of benefit used from the [Defender for Servers data allowance](logs/cost-logs.md#workspaces-with-microsoft-defender-for-cloud) and the [Microsoft Sentinel benefit for Microsoft 365 E5, A5, F5, and G5 customers](https://azure.microsoft.com/offers/sentinel-microsoft-365-offer/). The `Detail` column for these events is in the format `Benefit amount used 1.234 GB`, and the type of benefit is in the `OperationKey` column. Here's a query that charts the benefits used in the last 31-days:

+You can get more usage details about Log Analytics workspaces and Application Insights resources from the **Usage and Estimated Costs** option for each.

+This view includes the following sections:

+Depending on the number of nodes of the suite that your organization purchased, moving some subscriptions into a Per GB (pay-as-you-go) pricing tier might be advantageous, but this change in pricing tier requires careful consideration.

+## Azure Migrate data benefits

+Workspaces linked to [classic Azure Migrate](/azure/migrate/migrate-services-overview#azure-migrate-versions) receive free data benefits for the data tables related to Azure Migrate (`ServiceMapProcess_CL`, `ServiceMapComputer_CL`, `VMBoundPort`, `VMConnection`, `VMComputer`, `VMProcess`, `InsightsMetrics`). This version of Azure Migrate was retired in February 2024.

+Starting from 1 July 2024, the data benefit for Azure Migrate in Log Analytics will no longer be available. We suggest moving to the [Azure Migrate agentless dependency analysis](/azure/migrate/how-to-create-group-machine-dependencies-agentless). If you continue with agent-based dependency analysis, standard [Azure Monitor charges](https://azure.microsoft.com/pricing/details/monitor/) will apply for the data ingestion that enables dependency visualization.

+ Title: Azure Monitor data sources and data collection methods

+# Customer intent: As an Azure Monitor user, I want to understand the different types of data that can be collected in Azure Monitor and the method of data collection for each so that I can configure my environment to collect the data that I need.

+# Azure Monitor data sources and data collection methods

+Most resources in Azure generate the monitoring data described in the following table. Some services will also have other data that can be collected by enabling other features of Azure Monitor (described in other sections in this article). Regardless of the services that you're monitoring though, you should start by understanding and configuring collection of this data.

+|Activity log | The Activity log provides insight into subscription-level events for Azure services including service health records and configuration changes. | Collected automatically. View in the Azure portal or create a diagnostic setting to send it to other destinations. Can be collected in Log Analytics workspace at no charge. See [Azure Monitor activity log](essentials/activity-log.md). |

+| Platform metrics | Platform metrics are numerical values that are automatically collected at regular intervals for different aspects of a resource. The specific metrics vary for each type of resource. | Collected automatically and stored in [Azure Monitor Metrics](./essentials/data-platform-metrics.md). View in metrics explorer or create a diagnostic setting to send it to other destinations. See [Azure Monitor Metrics overview](essentials/data-platform-metrics.md) and [Supported metrics with Azure Monitor](/azure/azure-monitor/reference/supported-metrics/metrics-index) for a list of metrics for different services. |

+## Log data from Microsoft Entra ID

+Audit logs and sign in logs in Microsoft Entra ID are similar to the activity logs in Azure Monitor. Use diagnostic settings to send the activity log to a Log Analytics workspace, to archive it to a storage account, or to stream to an event hub to send it to services outside of Azure. See [Configure Microsoft Entra diagnostic settings for activity logs](/entra/identity/monitoring-health/howto-configure-diagnostic-settings).

+| Audit logs</br>Signin logs | Enable you to assess many aspects of your Microsoft Entra ID environment, including history of sign-in activity, audit trail of changes made within a particular tenant, and activities performed by the provisioning service. | Collected automatically. View in the Azure portal or create a diagnostic setting to send it to other destinations. |

+## Apps and workloads

+### Application data

+Application monitoring in Azure Monitor is done with [Application Insights](/azure/azure-monitor/app/app-insights-overview/), which collects data from applications running on various platforms in Azure, another cloud, or on-premises. When you enable Application Insights for an application, it collects metrics and logs related to the performance and operation of the application and stores it in the same Azure Monitor data platform used by other data sources.

+See [Application Insights overview](./app/app-insights-overview.md) for further details about the data that Application insights collected and links to articles on onboarding your application.

+| Data type | Description | Data collection method |

+|:|:|:|

+| Logs | Operational data about your application including page views, application requests, exceptions, and traces. Also includes dependency information between application components to support Application Map and data correlation. | Application logs are stored in a Log Analytics workspace that you select as part of the onboarding process. |

+| Metrics | Numeric data measuring the performance of your application and user requests measured over intervals of time. | Metric data is stored in both Azure Monitor Metrics and the Log Analytics workspace. |

+| Traces | Traces are a series of related events tracking end-to-end requests through the components of your application. | Traces are stored in the Log Analytics workspace for the app. |

+## Infrastructure

+### Virtual machine data

+| IIS logs | Logs created by Internet Information Service (IIS). | Deploy the Azure Monitor agent (AMA) and create a data collection rule (DCR) to send data to Log Analytics workspace. See [Collect IIS logs with Azure Monitor Agent](./agents/data-collection-iis.md). |

+### Kubernetes cluster data

+| Logs | Standard Kubernetes logs including events for the cluster, nodes, deployments, and workloads. | Enable Container insights for the cluster to send container logs to a Log Analytics workspace. See [Enable Container insights](./containers/kubernetes-monitoring-enable.md#enable-container-insights) for onboarding and [Configure data collection in Container insights using data collection rule](./containers/container-insights-data-collection-dcr.md) to configure which logs are collected. |

+While Code Optimizations incurs no extra costs.

+- [MDCFileIntegrityMonitoringEvents](/azure/azure-monitor/reference/tables/mdcfileintegritymonitoringevents)

+There are several types of tables in Azure Monitor Logs. You can delete any table that's not an Azure table, but what happens to the data when you delete the table is different for each type of table.

+For more information, see [What happens to data when you delete a table in a Log Analytics workspace](../logs/data-retention-archive.md#what-happens-to-data-when-you-delete-a-table-in-a-log-analytics-workspace).

+When you shorten an existing retention setting, Azure Monitor waits 30 days before removing the data, so you can revert the change and avoid data loss in the event of an error in configuration. You can [purge data](../logs/personal-data-mgmt.md#delete) immediately when required.

+### What happens to data when you delete a table in a Log Analytics workspace

+A Log Analytics workspace can contain several [types of tables](../logs/manage-logs-tables.md#table-type-and-schema). What happens when you delete the table is different for each:

+|Table type|Data retention|Recommendations|

+|-|-|-|

+|Azure table |An Azure table holds logs from an Azure resource or data required by an Azure service or solution and cannot be deleted. When you stop streaming data from the resource, service, or solution, data remains in the workspace until the end of the retention period defined for the table or for the default workspace retention, if you do not define table-level retention. |To minimize charges, set [table-level retention](#configure-retention-and-archive-at-the-table-level) to four days before you stop streaming logs to the table.|

+|[Restored table](./restore.md) `(table_RST`)| Deletes the hot cache provisioned for the restore, but source table data isn't deleted.||

+|[Search results table](./search-jobs.md) (`table_SRCH`)| Deletes the table and data immediately and permanently.||

+|[Custom log table](./create-custom-table.md#create-a-custom-table) (`table_CL`)| Soft deletes the table until the end of the table-level retention or default workspace retention period. During the soft delete period, you continue to pay for data retention and can recreate the table and access the data by setting up a table with the same name and schema. Fourteen days after you delete a custom table, Azure Monitor removes the table-level retention configuration and applies the default workspace retention.|To minimize charges, set [table-level retention](#configure-retention-and-archive-at-the-table-level) to four days before you delete the table.|

+> [!IMPORTANT]

+> Workspaces with a 30-day retention might keep data for 31 days. If you need to retain data for 30 days only to comply with a privacy policy, configure the default workspace retention to 30 days using the API and update the `immediatePurgeDataOn30Days` workspace property to `true`. This operation is currently only supported using the [Workspaces - Update API](/rest/api/loganalytics/workspaces/update).

+To set the retention and archive duration for a table, call the [Workspaces - Create Or Update API](/rest/api/loganalytics/workspaces/create-or-update):

+|`properties.retentionInDays` | integer | The workspace data retention in days. Allowed values are per pricing plan. See pricing tiers documentation for details. |

+|`location`|string| The geo-location of the resource.|

+|`immediatePurgeDataOn30Days`|boolean|Flag that indicates whether data is immediately removed after 30 days and is non-recoverable. Applicable only when workspace retention is set to 30 days.|

+This example sets the workspace's retention to the workspace default of 30 days and ensures that data is immediately removed after 30 days and is non-recoverable.

+PATCH https://management.azure.com/subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}?api-version=2023-09-01

+ "features": {"immediatePurgeDataOn30Days": true}

+ },

+"location": "australiasoutheast"

+ ...

+ "features": {

+ "legacy": 0,

+ "searchVersion": 1,

+ "immediatePurgeDataOn30Days": true,

+ ...

+ },

+ ...

+Learn more about:

+- [Managing personal data in Azure Monitor Logs](../logs/personal-data-mgmt.md)

+- [Creating a search job to retrieve archive data matching particular criteria](search-jobs.md)

+- **SkuCapacity**: You can set the commitment tier to 100, 200, 300, 400, 500, 1000, 2000, 5000, 10000, 25000, 50000 GB per day. The minimum commitment tier supported in CLI is 500 currently. Use REST to configure lower commitment tiers with minimum of 100. For more information on cluster costs, see [Dedicate clusters](./cost-logs.md#dedicated-clusters).

+- 404--Cluster not found, the cluster might have been deleted. If you try to create a cluster with that name and get conflict, the cluster is in deletion process.

+- 409--Can't delete a cluster while in provisioning state. Wait for the Async operation to complete and try again.

+ Title: Managing personal data in Azure Monitor Logs and Application Insights

+# Managing personal data in Azure Monitor Logs and Application Insights

+Azure Monitor's [Purge API](/rest/api/loganalytics/workspacepurge/purge) lets you delete personal data. Use the purge operation sparingly to avoid potential risks, performance impact, and the potential to skew all-up aggregations, measurements, and other aspects of your Log Analytics data. See the [Strategy for personal data handling](#strategy-for-personal-data-handling) section for alternative approaches to handling personal data.

+The [Logs Ingestion API](logs-ingestion-api-overview.md) in Azure Monitor allows you to send custom data to a Log Analytics workspace. This tutorial uses Azure Resource Manager templates (ARM templates) to walk through configuration of the components required to support the API and then provides a sample application using both the REST API and client libraries for [.NET](/dotnet/api/overview/azure/Monitor.Ingestion-readme), [Go](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/monitor/ingestion/azlogs), [Java](/java/api/overview/azure/monitor-ingestion-readme), [JavaScript](/javascript/api/overview/azure/monitor-ingestion-readme), and [Python](/python/api/overview/azure/monitor-ingestion-readme).

+> This tutorial uses the Azure portal to configure the components to support the Logs ingestion API. See [Tutorial: Send data to Azure Monitor using Logs ingestion API (Resource Manager templates)](tutorial-logs-ingestion-api.md) for a similar tutorial that uses Azure Resource Manager templates to configure these components and that has sample code for client libraries for [.NET](/dotnet/api/overview/azure/Monitor.Ingestion-readme), [Go](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/monitor/ingestion/azlogs), [Java](/java/api/overview/azure/monitor-ingestion-readme), [JavaScript](/javascript/api/overview/azure/monitor-ingestion-readme), and [Python](/python/api/overview/azure/monitor-ingestion-readme).

+ Title: Monitoring data reference for Azure Monitor

+description: This article contains important reference material you need when you monitor Azure Monitor.

+# Azure Monitor monitoring data reference

+See [Monitor Azure Monitor](monitor-azure-monitor.md) for details on the data you can collect for Azure Monitor and how to use it.

+<!-- ## Metrics. Required section. -->

+<!-- Repeat the following section for each resource type/namespace in your service. For each ### section, replace the <ResourceType/namespace> placeholder, add the metrics-tableheader #include, and add the table #include.

+To add the table #include, find the table(s) for the resource type in the Metrics column at https://review.learn.microsoft.com/en-us/azure/azure-monitor/reference/supported-metrics/metrics-index?branch=main#supported-metrics-and-log-categories-by-resource-type, which is autogenerated from underlying systems. -->

+### Supported metrics for Microsoft.Monitor/accounts

+The following table lists the metrics available for the Microsoft.Monitor/accounts resource type.

+### Supported metrics for microsoft.insights/autoscalesettings

+The following table lists the metrics available for the microsoft.insights/autoscalesettings resource type.

+### Supported metrics for microsoft.insights/components

+The following table lists the metrics available for the microsoft.insights/components resource type.

+### Supported metrics for Microsoft.Insights/datacollectionrules

+The following table lists the metrics available for the Microsoft.Insights/datacollectionrules resource type.

+### Supported metrics for Microsoft.operationalinsight/workspaces

+Azure Monitor Logs / Log Analytics workspaces

+<!-- ## Metric dimensions. Required section. -->

+Microsoft.Monitor/accounts:

+- `Stamp color`

+microsoft.insights/autoscalesettings:

+- `MetricTriggerRule`

+- `MetricTriggerSource`

+- `ScaleDirection`

+microsoft.insights/components:

+- `availabilityResult/name`

+- `availabilityResult/location`

+- `availabilityResult/success`

+- `dependency/type`

+- `dependency/performanceBucket`

+- `dependency/success`

+- `dependency/target`

+- `dependency/resultCode`

+- `operation/synthetic`

+- `cloud/roleInstance`

+- `cloud/roleName`

+- `client/isServer`

+- `client/type`

+Microsoft.Insights/datacollectionrules:

+- `InputStreamId`

+- `ResponseCode`

+- `ErrorType`

+### Supported resource logs for Microsoft.Monitor/accounts

+### Supported resource logs for microsoft.insights/autoscalesettings

+### Supported resource logs for microsoft.insights/components

+### Supported resource logs for Microsoft.Insights/datacollectionrules

+### Application Insights

+microsoft.insights/components

+- [AzureActivity](/azure/azure-monitor/reference/tables/AzureActivity#columns)

+- [AzureMetrics](/azure/azure-monitor/reference/tables/AzureMetrics#columns)

+- [AppAvailabilityResults](/azure/azure-monitor/reference/tables/AppAvailabilityResults#columns)

+- [AppBrowserTimings](/azure/azure-monitor/reference/tables/AutoscaleScaleActionsLog#columns)

+- [AppDependencies](/azure/azure-monitor/reference/tables/AppDependencies#columns)

+- [AppEvents](/azure/azure-monitor/reference/tables/AppEvents#columns)

+- [AppPageViews](/azure/azure-monitor/reference/tables/AppPageViews#columns)

+- [AppPerformanceCounters](/azure/azure-monitor/reference/tables/AppPerformanceCounters#columns)

+- [AppRequests](/azure/azure-monitor/reference/tables/AppRequests#columns)

+- [AppSystemEvents](/azure/azure-monitor/reference/tables/AppSystemEvents#columns)

+- [AppTraces](/azure/azure-monitor/reference/tables/AppTraces#columns)

+- [AppExceptions](/azure/azure-monitor/reference/tables/AppExceptions#columns)

+### Azure Monitor autoscale settings

+Microsoft.Insights/AutoscaleSettings

+- [AzureActivity](/azure/azure-monitor/reference/tables/AzureActivity#columns)

+- [AzureMetrics](/azure/azure-monitor/reference/tables/AzureMetrics#columns)

+- [AutoscaleEvaluationsLog](/azure/azure-monitor/reference/tables/AutoscaleEvaluationsLog#columns)

+- [AutoscaleScaleActionsLog](/azure/azure-monitor/reference/tables/AutoscaleScaleActionsLog#columns)

+### Azure Monitor Workspace

+Microsoft.Monitor/accounts

+- [AMWMetricsUsageDetails](/azure/azure-monitor/reference/tables/AMWMetricsUsageDetails#columns)

+### Data Collection Rules

+Microsoft.Insights/datacollectionrules

+- [DCRLogErrors](/azure/azure-monitor/reference/tables/DCRLogErrors#columns)

+### Workload Monitoring of Azure Monitor Insights

+Microsoft.Insights/WorkloadMonitoring

+- [InsightsMetrics](/azure/azure-monitor/reference/tables/InsightsMetrics#columns)

+- [Monitor resource provider operations](/azure/role-based-access-control/resource-provider-operations#monitor)

+## Related content

+- See [Monitor Azure Monitor](monitor-azure-monitor.md) for a description of monitoring Azure Monitor.

+- See [Monitor Azure resources with Azure Monitor](/azure/azure-monitor/essentials/monitor-azure-resource) for details on monitoring Azure resources.

+ Title: Monitor Azure Monitor

+description: Start here to learn how to monitor Azure Monitor.

+# Monitor Azure Monitor

+Azure Monitor has many separate larger components. Information on monitoring each of these components follows.

+## Azure Monitor core

+**Autoscale** - Azure Monitor Autoscale has a diagnostics feature that provides insights into the performance of your autoscale settings. For more information, see [Azure Monitor Autoscale diagnostics](autoscale/autoscale-diagnostics.md) and [Troubleshooting using autoscale metrics](autoscale/autoscale-troubleshoot.md#autoscale-metrics).

+**Agent Monitoring** - You can now monitor the health of your agents easily and seamlessly across Azure, on premises and other clouds using this interactive experience. For more information, see [Azure Monitor Agent Health](agents/azure-monitor-agent-health.md).

+**Data Collection Rules(DCRs)** - Use [detailed metrics and log](essentials/data-collection-monitor.md) to monitor the performance of your DCRs.

+## Azure Monitor Logs and Log Analytics

+**[Log Analytics Workspace Insights](logs/log-analytics-workspace-insights-overview.md)** provides a dashboard that shows you the volume of data going through your workspace(s). You can calculate the cost of your workspace based on the data volume.

+

+**[Log Analytics workspace health](logs/log-analytics-workspace-health.md)** provides a set of queries that you can use to monitor the health of your workspace.

+**Optimizing and troubleshooting log queries** - Sometimes Azure Monitor KQL Log queries can take more time to run than needed or never return at all. By monitoring the various aspects of the query, you can troubleshoot and optimize them. For more information, see [Audit queries in Azure Monitor Logs](logs/query-audit.md) and [Optimize log queries](logs/query-optimization.md).

+**Log Ingestion pipeline latency** - Azure Monitor provides a highly scalable log ingestion pipeline that can ingest logs from any source. You can monitor the latency of this pipeline using Kusto queries. For more information, see [Log data ingestion time in Azure Monitor](logs/data-ingestion-time.md#check-ingestion-time).

+**Log Analytics usage** - You can monitor the data ingestion for your Log Analytics workspace. For more information, see [Analyze usage in Log Analytics](logs/analyze-usage.md).

+## All resources

+**Health of any Azure resource** - Azure Monitor resources are tied into the resource health feature, which provides insights into the health of any Azure resource. For more information, see [Resource health](/azure/service-health/resource-health-overview/).

+For more information about the resource types for Azure Monitor, see [Azure Monitor monitoring data reference](monitor-azure-monitor-reference.md).

+For a list of available metrics for Azure Monitor, see [Azure Monitor monitoring data reference](monitor-azure-monitor-reference.md#metrics).

+For the available resource log categories, their associated Log Analytics tables, and the logs schemas for Azure Monitor, see [Azure Monitor monitoring data reference](monitor-azure-monitor-reference.md#resource-logs).

+Refer to the links in the beginning of this article for specific Kusto queries for each of the Azure Monitor components.

+## Related content

+- See [Azure Monitor monitoring data reference](monitor-azure-monitor-reference.md) for a reference of the metrics, logs, and other important values created for Azure Monitor.

+- See [Monitoring Azure resources with Azure Monitor](/azure/azure-monitor/essentials/monitor-azure-resource) for general details on monitoring Azure resources.

+Next, add a `SnapshotCollector` section to _appsettings.json_ where you can override the defaults. The following example shows a configuration equivalent to the default configuration:

+If you need to customize the Snapshot Collector's behavior manually, without using _appsettings.json_, use the overload of `AddSnapshotCollector` that takes a delegate. For example:

+using Microsoft.ApplicationInsights;

+using Microsoft.ApplicationInsights.DataContracts;

+using Microsoft.ApplicationInsights.Extensibility;

+internal class ExampleService

+ private readonly TelemetryClient _telemetryClient;

+ public ExampleService(TelemetryClient telemetryClient)

+ {

+ // Obtain the TelemetryClient via dependency injection.

+ _telemetryClient = telemetryClient;

+ }

+ public void HandleExampleRequest()

+ {

+ using IOperationHolder<RequestTelemetry> operation =

+ _telemetryClient.StartOperation<RequestTelemetry>("Example");

+ // TODO: Handle the request.

+ operation.Telemetry.Success = true;

+ // Report the exception to Application Insights.

+ operation.Telemetry.Success = false;

+ _telemetryClient.TrackException(ex);

+ // TODO: Rethrow the exception if desired.

+ }

+The following example uses `ILogger` instead of `TelemetryClient`. This example assumes you're using the [Application Insights Logger Provider](../app/ilogger.md#console-application). As the example shows, when handling an exception, be sure to pass the exception as the first parameter to `LogError`.

+```csharp

+using Microsoft.Extensions.Logging;

+internal class LoggerExample

+{

+ private readonly ILogger _logger;

+ public LoggerExample(ILogger<LoggerExample> logger)

+ {

+ _logger = logger;

+ }

+ public void HandleExampleRequest()

+ {

+ using IDisposable scope = _logger.BeginScope("Example");

+ try

+ {

+ // TODO: Handle the request

+ }

+ catch (Exception ex)

+ {

+ // Use the LogError overload with an Exception as the first parameter.

+ _logger.LogError(ex, "An error occurred.");

+ }

+ }

+}

+```

+> [!NOTE]

+> By default, the Application Insights Logger (`ApplicationInsightsLoggerProvider`) forwards exceptions to the Snapshot Debugger via `TelemetryClient.TrackException`. This behavior is controlled via the `TrackExceptionsAsExceptionTelemetry` property on the `ApplicationInsightsLoggerOptions` class. If you set `TrackExceptionsAsExceptionTelemetry` to `false` when configuring the Application Insights Logger, then the preceding example will not trigger the Snapshot Debugger. In this case, modify your code to call `TrackException` manually.

+- [Troubleshoot](snapshot-debugger-troubleshoot.md) Snapshot Debugger problems.

+## March 2024

+|Subservice | Article | Description |

+||||

+|Alerts|[Improve the reliability of your application by using Azure Advisor](../../articles/advisor/advisor-high-availability-recommendations.md)|WeΓÇÖve updated the alerts troubleshooting articles to remove out of date content and include common support issues.|

+|Application-Insights|[Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python, and Java applications](app/opentelemetry-enable.md)|OpenTelemetry sample applications are now provided in a centralized location.|

+|Application-Insights|[Migrate to workspace-based Application Insights resources](app/convert-classic-resource.md)|Classic Application Insights resources have been retired. For more information, see this article for migration information and frequently asked questions.|

+|Application-Insights|[Sampling overrides - Azure Monitor Application Insights for Java](app/java-standalone-sampling-overrides.md)|The sampling overrides feature has reached general availability (GA), starting from 3.5.0.|

+|Containers|[Configure data collection and cost optimization in Container insights using data collection rule](containers/container-insights-data-collection-dcr.md)|Updated to include new Logs and Events cost preset.|

+|Containers|[Enable private link with Container insights](containers/container-insights-private-link.md)|Updated with ARM templates.|

+|Essentials|[Data collection rules in Azure Monitor](essentials/data-collection-rule-overview.md)|Rewritten to consolidate previous data collection article.|

+|Essentials|[Workspace transformation data collection rule (DCR) in Azure Monitor](essentials/data-collection-transformations-workspace.md)|Content moved to a new article dedicated to workspace transformation DCR.|

+|Essentials|[Data collection transformations in Azure Monitor](essentials/data-collection-transformations.md)|Rewritten to remove redundancy and make the article more consistent with related articles.|

+|Essentials|[Create and edit data collection rules (DCRs) in Azure Monitor](essentials/data-collection-rule-create-edit.md)|Updated API version in REST API calls.|

+|Essentials|[Tutorial: Edit a data collection rule (DCR)](essentials/data-collection-rule-edit.md)|Updated API version in REST API calls.|

+|Essentials|[Monitor and troubleshoot DCR data collection in Azure Monitor](essentials/data-collection-monitor.md)|New article documenting new DCR monitoring feature.|

+|Logs|[Monitor Log Analytics workspace health](logs/log-analytics-workspace-health.md)|Added new metrics for monitoring data export from a Log Analytics workspace.|

+|Logs|[Set a table's log data plan to Basic or Analytics](logs/basic-logs-configure.md)|Azure Databricks logs tables now support the basic logs data plan.|

+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, and volumes. You can also select service and performance levels and manage data protection. You can create and manage high-performance, highly available, and scalable file shares by using the same protocols and tools that you're familiar with and rely on on-premises.

+The combination of the quota assigned to the volume and the selected service level determines the [throughput limit](azure-netapp-files-service-levels.md) for a volume with automatic QoS. For volumes with manual QoS, the throughput limit can be defined individually. When you make performance plans about Azure NetApp Files, you need to understand several considerations.

+The maximum empirical throughput that has been observed in testing is 4,500 MiB/s. At the Premium storage tier, an automatic QoS volume quota of 70.31 TiB provisions a throughput limit high enough to achieve this performance level.

+For automatic QoS volumes, if you're considering assigning volume quota amounts beyond 70.31 TiB, additional quota may be assigned to a volume for storing more data. However, the added quota doesn't result in a further increase in actual throughput.

+Learn about quota management and throughput for volumes with the automatic QoS type.

+If a workloadΓÇÖs performance is throughput-limit bound, it's possible to overprovision the automatic QoS volume quota to set a higher throughput level and achieve higher performance.

+For example, if an automatic QoS volume in the Premium storage tier has only 500 GiB of data but requires 128 MiB/s of throughput, you can set the quota to 2 TiB so the throughput level is set accordingly (64 MiB/s per TB * 2 TiB = 128 MiB/s).

+If you consistently overprovision a volume for achieving a higher throughput, consider using the manual QoS volumes or using a higher service level instead. In this example, you can achieve the same throughput limit with half the automatic QoS volume quota by using the Ultra storage tier instead (128 MiB/s per TiB * 1 TiB = 128 MiB/s).

+## Monitoring volumes for performance

+Azure NetApp Files volumes can be monitored using available [Performance metrics](azure-netapp-files-metrics.md#performance-metrics-for-volumes).

+When volume throughput reaches its maximum (as determined by the QoS setting), the volume response times (latency) increase. This effect can be incorrectly perceived as a performance issue caused by the storage. Increasing the volume QoS setting (manual QoS) or increasing the volume size (auto QoS) increases the allowable volume throughput.

+To check if the maximum throughput limit has been reached, monitor the metric [Throughput limit reached](azure-netapp-files-metrics.md#volumes). For more recommendations, see [Performance FAQs for Azure NetApp Files](faq-performance.md#what-should-i-do-to-optimize-or-tune-azure-netapp-files-performance).

+## How do I monitor Azure NetApp Files volume performance

+Azure NetApp Files volumes performance can be monitored through [available metrics](azure-netapp-files-metrics.md).

+NIC Teaming isn't supported in Azure. Although multiple network interfaces are supported on Azure virtual machines, they represent a logical rather than a physical construct. As such, they provide no fault tolerance. Also, the bandwidth available to an Azure virtual machine is calculated for the machine itself and not any individual network interface.

+Jumbo frames aren't supported with Azure virtual machines.

+> Your account must have the appropriate permissions in order to perform these tasks. For example, to invite a user to your tenant, you must have a role that includes this permission, such as [Guest Inviter](/entra/identity/role-based-access-control/permissions-reference) or [User Administrator](/entra/identity/role-based-access-control/permissions-reference).

+1. Search or scroll to find users you want to add to the group, then select one or more users by tapping the circle next to their name.

+1. Select **Add** in the top right corner to add the selected users to the group.

+1. Search or scroll to find groups to which this user should be added, then select one or more groups by tapping the circle next to the group name.

+1. Select **Add** in the top right corner to add the user to the selected groups.

+To [manage authentication methods](/entra/identity/authentication/concept-authentication-methods-manage) or [reset a user's password](/entra/fundamentals/users-reset-password-azure-portal):

+1. Select **Reset password** to assign a temporary password to the user, or **Authentication methods** to manage authentication methods for self-service password reset.

+## Investigate risky users and sign-ins

+[Microsoft Entra ID Protection](/entra/id-protection/overview-identity-protection) provides organizations with reporting they can use to [investigate identity risks in their environment](/entra/id-protection/howto-identity-protection-investigate-risk).

+If you have the [necessary permissions and license](/entra/id-protection/overview-identity-protection#required-roles), you'll see details in the **Risky users** and **Risky sign-ins** sections within **Microsoft Entra ID**. You can open these sections to view more information and perform some management tasks.

+### Manage risky users

+1. In **Microsoft Entra ID**, scroll down to the **Security** card and then select **Risky users**.

+1. Search or scroll to find and select a specific risky user.

+1. Review basic information for this user, a list of their risky sign-ins, and their risk history.

+1. To [take action on the user](/entra/id-protection/howto-identity-protection-investigate-risk), select the three dots near the top of the screen. You can:

+ * Reset the user's password

+ * Confirm user compromise

+ * Dismiss user risk

+ * Block the user from signing in (or unblock, if previously blocked)

+### Monitor risky sign-ins

+1. In **Microsoft Entra ID**, scroll down to the **Security** card and then select **Risky sign-ins**. It may take a minute or two for the list of all risky sign-ins to load.

+1. Search or scroll to find and select a specific risky sign-in.

+1. Review details about the risky sign-in.

+| `DeploymentScriptExistingStorageNotInSameSubscriptionAsDeploymentScript` | The existing storage provided in deployment is not found in the subscription where the script is being deployed. |

+> | licenses | **Yes** | **Yes** | No |

+> | privatelinkscopes | **Yes** | **Yes** | No |

+- Create a storage account with [`allowSharedKeyAccess`](/azure/templates/microsoft.storage/storageaccounts) set to `true` , and specify the deployment script to use the existing storage account. To specify an existing storage account, see [Use existing storage account](#use-existing-storage-account). Some additional configuration is required for the storage account.

+ "apiVersion": "2023-09-01",

+ },

+ "allowSharedKeyAccess": true

+ "apiVersion": "2023-07-31-preview",

+ "principalId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), '2023-07-31-preview').principalId]",

+| East US | AZ01 | AV36P | Yes |

+| East US | AZ02 | **AV36P** | Yes |

+| East US | AZ03 | AV36, AV36P, AV64 | Yes |

+- Australia East (on AV36P)

+- East US (on AV36P)

+## April 2024

+Azure VMware Solution Stretched Clusters is now generally available in the East US region. [Learn more](architecture-stretched-clusters.md)

+Azure VMware Service will become generally available on May 17, 2023, to US Federal and State and Local Government (US) customers and their partners, in the regions of Arizona and Virginia. With this release, we're combining world-class Azure infrastructure together with VMware technologies by offering Azure VMware Solutions on Azure Government, which is designed, built, and supported by Microsoft.

+| Standard (with large file shares enabled) | Supported |

+> [!NOTE]

+> Though the selected vault may have the *global-redundancy* setting, backup for AKS currently supports **Operational Tier** only. All backups are stored in your subscription in the same region as that of the AKS cluster, and they aren't copied to Backup vault storage.

+ > [!NOTE]

+ > The vault is created with only *Local Redundancy* and *Operational Data store* support.

+> [!IMPORTANT]

+> The time of the day indicates the backup start time and not the time when the backup completes. The time required for completing the backup operation is dependent on various factors, including number and size of the persistent volumes and churn rate between consecutive backups.

+ > [!NOTE]

+ > 1. The storage account and the AKS cluster should be in the same region and subscription.

+ > 2. The blob container shouldn't contain any previously created file systems (except created by backup for AKS).

+ > 3. If your source or target AKS cluster is in a private virtual network, then you need to create Private Endpoint to connect storage account with the AKS cluster.

+ For the Backup vault to connect with the AKS cluster, you must enable Trusted Access as it allows the Backup vault to have a direct line of sight to the AKS cluster. Learn [how to enable Trusted Access](azure-kubernetes-service-cluster-manage-backups.md#trusted-access-related-operations).

+> [!NOTE]

+> For Backup Extension installation and Trusted Access enablement, the commands are available in Azure CLI only.

+ Title: Create Recovery Services vaults using REST API for Azure Backup

+# Create Azure Recovery Services vault using REST API for Azure Backup

+This article describes how to create Azure Recovery Services vault using REST API. To create the vault using the Azure portal, see [this article](backup-create-recovery-services-vault.md#create-a-recovery-services-vault).

+A Recovery Services vault is a storage entity in Azure that houses data. The data is typically copies of data, or configuration information for virtual machines (VMs), workloads, servers, or workstations. You can use Recovery Services vaults to hold backup data for various Azure services such as IaaS VMs (Linux or Windows) and SQL Server in Azure VMs. Recovery Services vaults support System Center DPM, Windows Server, Azure Backup Server, and more. Recovery Services vaults make it easy to organize your backup data, while minimizing management overhead.

+## Before you start

+The creation of an Azure Recovery Services vault using REST API is outlined in [create vault REST API](/rest/api/recoveryservices/vaults/createorupdate) article. Let's use this article as a reference to create a vault named `testVault` in `West US`.

+To create or update an Azure Recovery Services vault, use the following *PUT* operation:

+The following example body is used to create a vault in `West US`. Specify the location. The SKU is always `Standard`.

+A condensed *201 Created* response from the previous example request body shows an *ID* has been assigned and the *provisioningState* is *Succeeded*:

+ Title: Manage the backup jobs using REST API in Azure Backup

+description: In this article, learn how to track and manage the backup and restore jobs of Azure Backup using REST API.

+# Track the backup and restore jobs using REST API in Azure Backup

+This article describes how to monitor the backup and restore jobs using REST API in Azure Backup.

+The Azure Backup service triggers jobs that run in background in various scenarios such as triggering backup, restore operations, disabling backup. You can track these jobs using their IDs.

+The `{jobName}` is "jobId" mentioned above. The response is always 200 OK with the "status" field indicating the current status of the job. Once it's *Completed* or *CompletedWithWarnings*, the 'extendedInfo' section reveals more details about the job.

+Once the *GET* URI submission is complete, a 200 (OK) response is returned.

+## Next steps

+[About Azure Backup](backup-overview.md).

+* Ensure that the file share is present in one of the supported storage account types. Review the [support matrix](azure-file-share-support-matrix.md).

+ :::image type="content" source="./media/backup-azure-troubleshoot-vm-backup-fails-snapshot-timeout/open-services-window.png" alt-text="Screenshot shows how to open Windows Services." lightbox="./media/backup-azure-troubleshoot-vm-backup-fails-snapshot-timeout/open-services-window.png":::

+ :::image type="content" source="./media/backup-azure-troubleshoot-vm-backup-fails-snapshot-timeout/windows-azure-guest-service-running.png" alt-text="Screenshot shows the Windows Azure Guest service is in running state." lightbox="./media/backup-azure-troubleshoot-vm-backup-fails-snapshot-timeout/windows-azure-guest-service-running.png":::

+ :::image type="content" source="./media/backup-azure-arm-vms-prepare/delete-lock.png" alt-text="Screenshot shows how to delete a lock." lightbox="./media/backup-azure-arm-vms-prepare/delete-lock.png":::

+After you remove the lock, the restore points have to be cleaned up.

+ :::image type="content" source="./media/backup-azure-arm-vms-prepare/resource-group.png" alt-text="Screenshot shows how to select the resource group." lightbox="./media/backup-azure-arm-vms-prepare/resource-group.png":::

+ :::image type="content" source="./media/backup-azure-arm-vms-prepare/restore-point-collection.png" alt-text="Screenshot shows how to select the restore point collection." lightbox="./media/backup-azure-arm-vms-prepare/restore-point-collection.png":::

+>- Restore of a file or folder with length *>2 KB* or with characters `xFFFF` or `xFFFE` isn't supported from snapshots.