-1. **Validation technical profiles**: A [self-asserted technical profile](self-asserted-technical-profile.md) can call [validation technical profiles](validation-technical-profile.md) to validate the data profiled by the user.

-|displayName |String|The display name for the user. Max length 256. \< \> characters aren't allowed. | Yes|Yes|Persisted, Output|

-The Document Intelligence [Layout model](concept-layout.md) is an advanced machine-learning based document analysis API. The Layout model offers a comprehensive solution for advanced content extraction and document structure analysis capabilities. With the Layout model, you can easily extract text and structural to divide large bodies of text into smaller, meaningful chunks based on semantic content rather than arbitrary splits. The extracted information can be conveniently outputted to Markdown format, enabling you to define your semantic chunking strategy based on the provided building blocks.

-* **Fixed-sized chunking**. Most chunking strategies used in RAG today are based on fix-sized text segments known as chunks. Fixed-sized chunking is quick, easy, and effective with text that doesn't have a strong semantic structure such as logs and data. However it isn't recommended for text that requires semantic understanding and precise context. The fixed-size nature of the window can result in severing words, sentences, or paragraphs impeding comprehension and disrupt the flow of information and understanding.

-* **Semantic chunking**. This method divides the text into chunks based on semantic understanding. Division boundaries are focused on sentence subject and use significant computational algorithmically complex resources. However, it has the distinct advantage of maintaining semantic consistency within each chunk. It's useful for text summarization, sentiment analysis, and document classification tasks.

-* **Scalability and AI quality**. The Layout model is highly scalable in Optical Character Recognition (OCR), table extraction, and [document structure analysis](concept-layout.md#document-layout-analysis). It supports [309 printed and 12 handwritten languages](language-support-ocr.md#model-id-prebuilt-layout) further ensuring high-quality results driven by AI capabilities.

-**Text image processed with Document Intelligence Studio and output to markdown using Layout model**

-* Azure AI Document Intelligence is now integrated with [LangChain](https://python.langchain.com/docs/integrations/document_loaders/azure_document_intelligence) as one of its document loaders. You can use it to easily load the data and output to Markdown format. This [notebook](https://github.com/microsoft/Form-Recognizer-Toolkit/blob/main/SampleCode/Python/sample_rag_langchain.ipynb) shows a simple demo for RAG pattern with Azure AI Document Intelligence as document loader and Azure Search as retriever in LangChain.

-* [GPT-4 Turbo with Vision API reference](https://aka.ms/gpt-v-api-ref)

- 1. **Name**. Enter the name you have chosen for your resource. The name you choose must be unique within Azure.

- 1. After your resource has successfully deployed, select **Go to resource**.

-1. If you've created a new resource, after it deploys, select **Go to resource**. If you have an existing Document Translation resource, navigate directly to your resource page.

-1. If you've created a new resource, after it deploys, select **Go to resource**. If you have an existing Document Translation resource, navigate directly to your resource page.

-* Your **source** container or blob must have designated **read** and **list** access.

-* Your **target** container or blob must have designated **write** and **list** access.

-* Your **glossary** blob must have designated **read** and **list** access.

- "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"

- "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",

-* If you aren't using a [**system-assigned managed identity**](create-use-managed-identities.md) for authentication, make sure you've created source URL & SAS token for the specific blob/document (not for the container)

-* Ensure you've specified the target filename as part of the target URL ΓÇô though the SAS token is still for the container.

- "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"

- "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",

- "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",

- "sourceUrl": "https://myblob.blob.core.windows.net/source"

- "targetUrl": "https://myblob.blob.core.windows.net/target",

- "glossaryUrl": "https:// myblob.blob.core.windows.net/glossary/en-es.xlf",

-Cancel currently processing or queued job. Only documents for which translation hasn't started are canceled.

-| 429 | Too Many Requests | You've exceeded the quota or rate of requests allowed for your subscription. |

-| 502 | Bad Gateway | Network or server-side issue. May also indicate invalid headers. |

-# Azure OpenAI GPT-4 Turbo with Vision tool (preview) in Azure AI studio

-Azure OpenAI GPT-4 Turbo with Vision tool enables you to leverage your AzureOpenAI GPT-4 Turbo with Vision model deployment to analyze images and provide textual responses to questions about them.

- In AI studio, select **Deployments** from the left navigation pane and create a deployment by selecting model name: `gpt-4v`.

-Setup connections to provisioned resources in prompt flow.

-| connection | AzureOpenAI | the AzureOpenAI connection to be used in the tool | Yes |

-| deployment\_name | string | the language model to use | Yes |

-| prompt | string | The text prompt that the language model will use to generate its response. | 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 | value that controls the model's behavior with regard to repeating phrases. Default is 0. | No |

-| frequency\_penalty | float | value that controls the model's behavior with regard to generating rare phrases. Default is 0. | No |

-| [Azure OpenAI GPT-4 Turbo with Vision (preview)](./azure-open-ai-gpt-4v-tool.md) | Use AzureOpenAI GPT-4 Turbo with Vision model deployment to analyze images and provide textual responses to questions about them. | Default | [promptflow-tools](https://pypi.org/project/promptflow-tools/) |

-When you integrate Microsoft Entra ID with your AKS cluster, you can use [Conditional Access][aad-conditional-access] or Privileged Identity Management (PIM) for just-in-time requests to control access to your cluster. This article shows you how to enable Conditional Access and PIM on your AKS clusters.

-> Microsoft Entra Conditional Access and Privileged Identity Management are Microsoft Entra ID P1 or P2 capabilities requiring a Premium P2 SKU. For more on Microsoft Entra ID SKUs, see the [pricing guide][aad-pricing].

- --query objectId -o tsv)

- --query objectId -o tsv)

- volumeMounts

- my-azurefile Bound pvc-8436e62e-a0d9-11e5-8521-5a8664dc0477 10Gi RWX my-azurefile 5m

-To allow access to your applications or between application components, Kubernetes provides an abstraction layer to virtual networking. Kubernetes nodes connect to a virtual network, providing inbound and outbound connectivity for pods. The *kube-proxy* component runs on each node to provide these network features.

-In Kubernetes:

-* *Services* logically group pods to allow for direct access on a specific port via an IP address or DNS name.

-* *ServiceTypes* allow you to specify what kind of Service you want.

-* You can distribute traffic using a *load balancer*.

-* Layer 7 routing of application traffic can also be achieved with *ingress controllers*.

-* You can *control outbound (egress) traffic* for cluster nodes.

-* Security and filtering of the network traffic for pods is possible with *network policies*.

-The Azure platform also simplifies virtual networking for AKS clusters. When you create a Kubernetes load balancer, you also create and configure the underlying Azure load balancer resource. As you open network ports to pods, the corresponding Azure network security group rules are configured. For HTTP application routing, Azure can also configure *external DNS* as new Ingress routes are configured.

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

-[network-security-group-rules-overview]: concepts-security.md#azure-network-security-groups

-| Prometheus metrics | When you [enable metric scraping](../azure-monitor/containers/prometheus-metrics-enable.md) for your cluster, [Prometheus metrics](../azure-monitor/containers/prometheus-metrics-scrape-default.md) are collected by [Azure Monitor managed service for Prometheus](../azure-monitor/essentials/prometheus-metrics-overview.md) and stored in an [Azure Monitor workspace](../azure-monitor/essentials/azure-monitor-workspace-overview.md). Analyze them with [prebuilt dashboards](../azure-monitor/visualize/grafana-plugin.md#use-out-of-the-box-dashboards) in [Azure Managed Grafana](../managed-grafan). |

-| [Container insights](../azure-monitor/containers/container-insights-overview.md) | Uses a containerized version of the [Azure Monitor agent](../azure-monitor/agents/agents-overview.md) to collect stdout/stderr logs, and Kubernetes events from each node in your cluster, supporting a [variety of monitoring scenarios for AKS clusters](../azure-monitor/containers/container-insights-overview.md#features-of-container-insights). You can enable monitoring for an AKS cluster when it's created by using [Azure CLI](../aks/learn/quick-kubernetes-deploy-cli.md), [Azure Policy](../azure-monitor/containers/container-insights-enable-aks-policy.md), Azure portal or Terraform. If you don't enable Container insights when you create your cluster, see [Enable Container insights for Azure Kubernetes Service (AKS) cluster](../azure-monitor/containers/container-insights-enable-aks.md) for other options to enable it.<br><br>Container insights store most of its data in a [Log Analytics workspace](../azure-monitor/logs/log-analytics-workspace-overview.md), and you'll typically use the same log analytics workspace as the [resource logs](monitor-aks-reference.md#resource-logs) for your cluster. See [Design a Log Analytics workspace architecture](../azure-monitor/logs/workspace-design.md) for guidance on how many workspaces you should use and where to locate them. |

-| [Azure Monitor managed service for Prometheus](../azure-monitor/essentials/prometheus-metrics-overview.md) | [Prometheus](https://prometheus.io/) is a cloud-native metrics solution from the Cloud Native Compute Foundation and the most common tool used for collecting and analyzing metric data from Kubernetes clusters. Azure Monitor managed service for Prometheus is a fully managed Prometheus-compatible monitoring solution in Azure. If you don't enable managed Prometheus when you create your cluster, see [Collect Prometheus metrics from an AKS cluster](../azure-monitor/essentials/prometheus-metrics-enable.md) for other options to enable it.<br><br>Azure Monitor managed service for Prometheus stores its data in an [Azure Monitor workspace](../azure-monitor/essentials/azure-monitor-workspace-overview.md), which is [linked to a Grafana workspace](../azure-monitor/essentials/azure-monitor-workspace-manage.md#link-a-grafana-workspace) so that you can analyze the data with Azure Managed Grafana. |

-Metrics play an important role in cluster monitoring, identifying issues, and optimizing performance in the AKS clusters. Platform metrics are captured using the out of the box metrics server installed in kube-system namespace, which periodically scrapes metrics from all Kubernetes nodes served by Kubelet. You should also enable Azure Managed Prometheus metrics to collect container metrics and Kubernetes object metrics, such as object state of Deployments. See [Collect Prometheus metrics from an AKS cluster](../azure-monitor/containers/prometheus-metrics-enable.md) to send data to Azure Managed service for Prometheus.

-ContainerLogV2 is the recommended approach and is the default schema for customers onboarding container insights with Managed Identity Auth using ARM, Bicep, Terraform, Policy, and Azure portal. For more information about how to enable ContainerLogV2 through either the cluster's Data Collection Rule (DCR) or ConfigMap, see [Enable the ContainerLogV2 schema](../azure-monitor/containers/container-insights-logging-v2.md?tabs=configure-portal#enable-the-containerlogv2-schema-1).

-Throughout the lifecycle of your Azure Kubernetes Service (AKS) cluster, you might need to access an AKS node. This access could be for maintenance, log collection, or troubleshooting operations. You can securely authenticate against AKS Linux and Windows nodes using SSH, and you can also [connect to Windows Server nodes using remote desktop protocol (RDP)][aks-windows-rdp]. For security reasons, the AKS nodes aren't exposed to the internet. To connect to the AKS nodes, you use `kubectl debug` or the private IP address.

-This article shows you how to create a connection to an AKS node and update the SSH key on an existing AKS cluster.

-This article assumes you have an SSH key. If not, you can create an SSH key using [macOS or Linux][ssh-nix] or [Windows][ssh-windows], to know more refer [Manage SSH configuration][manage-ssh-node-access]. Make sure you save the key pair in an OpenSSH format, other formats like .ppk aren't supported.

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

-## Create an interactive shell connection to a Linux node using kubectl

-To create an interactive shell connection to a Linux node, use the `kubectl debug` command to run a privileged container on your node.

-

- The following example resembles output from the command:

-

-2. Use the `kubectl debug` command to run a container image on the node to connect to it. The following command starts a privileged container on your node and connects to it.

- The following example resembles output from the command:

-

- This privileged container gives access to the node.

-

-### Remove Linux node access

-When you're done with a debugging pod, enter the `exit` command to end the interactive shell session. After the interactive container session closes, delete the pod used for access with `kubectl delete pod`.

-## Create an interactive shell connection to a node using private IP

-If you don't have access to the Kubernetes API, you can get access to properties such as ```Node IP``` and ```Node Name``` through the AKS Agentpool Preview API(preview version 07-02-2023 or above) to troubleshoot node-specific issues in your AKS node pools. For convenience, we also expose the public IP if the node has a public IP assigned. However in order to SSH into the node, you need to be in the cluster's virtual network.

-1. To get the private IP via CLI, use az cli version 2.53 or above with aks-preview extension installed.

-```bash

- az aks machine list --resource-group myResourceGroup --cluster-name myAKSCluster --nodepool-name nodepool1 -o table

-

- ```

-The following example resembles output from the command:

- ```output

- Name Ip

- --

-aks-nodepool1-33555069-vmss000000 10.224.0.5,family:IPv4;

-aks-nodepool1-33555069-vmss000001 10.224.0.6,family:IPv4;

-aks-nodepool1-33555069-vmss000002 10.224.0.4,family:IPv4;

-```

-To target a specific node inside the nodepool, use this command:

-```bash

- az aks machine show --cluster-name myAKScluster --nodepool-name nodepool1 -g myResourceGroup --machine-name aks-nodepool1-33555069-vmss000000 -o table

-

- ```

- The following example resembles output from the command:

-```output

- Name Ip

- --

-aks-nodepool1-33555069-vmss000000 10.224.0.5,family:IPv4;

- ```

-2. Use the private IP to SSH into the node. [Azure Bastion][azure-bastion] also provides you with information for securely connecting to virtual machines via private IP address. Make sure that you configure an Azure Bastion host for the virtual network in which the VM resides.

-```bash

-ssh azureuser@10.224.0.33

-```

-## Create the SSH connection to a Windows node

-At this time, you can't connect to a Windows Server node directly by using `kubectl debug`. Instead, you need to first connect to another node in the cluster, then connect to the Windows Server node from that node using SSH. Alternatively, you can [connect to Windows Server nodes using remote desktop protocol (RDP) connections][aks-windows-rdp] instead of using SSH or use SSH with 'machines API' presented at the start of this document.

-To connect to another node in the cluster, use the `kubectl debug` command. For more information, see the Linux section.

-To create the SSH connection to the Windows Server node from another node, use the SSH keys provided when you created the AKS cluster and the internal IP address of the Windows Server node.

-> The following steps for creating the SSH connection to the Windows Server node from another node can only be used if you created your AKS cluster using the Azure CLI and the `--generate-ssh-keys` parameter. AKS Update command can also be used to manage, create SSH keys on an existing AKS cluster. For more information refer [Manage SSH configuration][manage-ssh-node-access].

- The following example resembles output from the command:

- In the previous example, *node-debugger-aks-nodepool1-37663765-vmss000000-bkmmx* is the name of the pod started by `kubectl debug`.

- The following example resembles output from the command:

- The following example resembles output from the command:

- The following example resembles output from the command:

-

- [...]

-

- Microsoft Windows [Version 10.0.17763.1935]

- (c) 2018 Microsoft Corporation. All rights reserved.

-

- azureuser@aksnpwin000000 C:\Users\azureuser>

-If you need more troubleshooting data, you can [view the kubelet logs][view-kubelet-logs] or [view the Kubernetes master node logs][view-master-logs].

-See [Manage SSH configuration][manage-ssh-node-access] to learn about managing the SSH key on an AKS cluster or node pools.

-[view-master-logs]: monitor-aks-reference.md#resource-logs

-[agentpool-rest-api]: /rest/api/aks/agent-pools/get#agentpool

-AKS intiated maintenance refers to the AKS releases. These releases are weekly rounds of fixes and feature and component updates that affect your clusters. The type of maintenance that you initiate regularly are [cluster auto-upgrades][aks-upgrade] and [Node OS automatic security updates][node-image-auto-upgrade].

-| 1.28 | Azure policy 1.2.1<br>Metrics-Server 0.6.3<br>KEDA 2.11.2<br>Open Service Mesh 1.2.7<br>Core DNS V1.9.4<br>0.12.0</br>Overlay VPA 0.13.0<br>Azure-Keyvault-SecretsProvider 1.4.1<br>Application Gateway Ingress Controller (AGIC) 1.7.2<br>Image Cleaner v1.2.2<br>Azure Workload identity v2.0.0<br>MDC Defender Security Publisher 1.0.68<br>MDC Defender Old File Cleaner 1.3.68<br>MDC Defender Pod Collector 1.0.78<br>MDC Defender Low Level Collector 1.3.81<br>Azure Active Directory Pod Identity 1.8.13.6<br>GitOps 1.8.1|Cilium 1.13.5<br>CNI v1.4.43.1 (Default)/v1.5.11 (Azure CNI Overlay)<br> Cluster Autoscaler 1.27.3<br> | OS Image Ubuntu 22.04 Cgroups V2 <br>ContainerD 1.7.5 for Linux and 1.7.1 for Windows<br>Azure Linux 2.0<br>Cgroups V1<br>ContainerD 1.6<br>|No breaking changes|None

-> [Tutorial: Import and publish your first API](import-and-publish.md)

-description: Learn best practices and the common troubleshooting scenarios for your app running in Azure App Service.

-# Best Practices for Azure App Service

-This article summarizes best practices for using [Azure App Service](./overview.md).

-When Azure resources composing a solution such as a web app and a database are located in different regions, it can have the following effects:

-* Monetary charges for outbound data transfer cross-region as noted on the [Azure pricing page](https://azure.microsoft.com/pricing/details/data-transfers).

-Colocation in the same region is best for Azure resources composing a solution such as a web app and a database or storage account used to hold content or data. When creating resources, make sure they are in the same Azure region unless you have specific business or design reason for them not to be. You can move an App Service app to the same region as your database by using the [App Service cloning feature](app-service-web-app-cloning.md) currently available for Premium App Service Plan apps.

-## <a name ="certificatepinning"></a>Certificate Pinning

-Applications should never have a hard dependency or pin to the default \*.azurewebsites.net TLS certificate because the \*.azurewebsites.net TLS certificate could be rotated anytime given the nature of App Service as a Platform as a Service (PaaS). Certificate pinning is a practice where an application only allows a specific list of acceptable Certificate Authorities (CAs), public keys, thumbprints, or any part of the certificate hierarchy. In the event that the service rotates the App Service default wildcard TLS certificate, certificate pinned applications will break and disrupt the connectivity for applications that are hardcoded to a specific set of certificate attributes. The periodicity with which the \*.azurewebsites.net TLS certificate is rotated is also not guaranteed since the rotation frequency can change at any time.

-Note that applications which rely on certificate pinning should also not have a hard dependency on an App Service Managed Certificate. App Service Managed Certificates could be rotated anytime, leading to similar problems for applications that rely on stable certificate properties. It is best practice to provide a custom TLS certificate for applications that rely on certificate pinning.

-If an application needs to rely on certificate pinning behavior, it is recommended to add a custom domain to a web app and provide a custom TLS certificate for the domain which can then be relied on for certificate pinning.

-## <a name="memoryresources"></a>When apps consume more memory than expected

-When you notice an app consumes more memory than expected as indicated via monitoring or service recommendations, consider the [App Service Auto-Healing feature](https://azure.microsoft.com/blog/auto-healing-windows-azure-web-sites). One of the options for the Auto-Healing feature is taking custom actions based on a memory threshold. Actions span the spectrum from email notifications to investigation via memory dump to on-the-spot mitigation by recycling the worker process. Auto-healing can be configured via web.config and via a friendly user interface as described at in this blog post for the App Service Support Site Extension.

-## <a name="CPUresources"></a>When apps consume more CPU than expected

-When you notice an app consumes more CPU than expected or experiences repeated CPU spikes as indicated via monitoring or service recommendations, consider scaling up or scaling out the App Service plan. If your application is stateful, scaling up is the only option, while if your application is stateless, scaling out gives you more flexibility and higher scale potential.

-For more information about App Service scaling and autoscaling options, see [Scale a Web App in Azure App Service](manage-scale-up.md).

-## <a name="socketresources"></a>When socket resources are exhausted

-A common reason for exhausting outbound TCP connections is the use of client libraries, which are not implemented to reuse TCP connections, or when a higher-level protocol such as HTTP - Keep-Alive is not used. Review the documentation for each of the libraries referenced by the apps in your App Service Plan to ensure they are configured or accessed in your code for efficient reuse of outbound connections. Also follow the library documentation guidance for proper creation and release or cleanup to avoid leaking connections. While such client libraries investigations are in progress, impact may be mitigated by scaling out to multiple instances.

-### Node.js and outgoing http requests

-When working with Node.js and many outgoing http requests, dealing with HTTP - Keep-Alive is important. You can use the [agentkeepalive](https://www.npmjs.com/package/agentkeepalive) `npm` package to make it easier in your code.

-Always handle the `http` response, even if you do nothing in the handler. If you don't handle the response properly, your application gets stuck eventually because no more sockets are available.

-For example, when working with the `http` or `https` package:

-If you are running on App Service on Linux on a machine with multiple cores, another best practice is to use PM2 to start multiple Node.js processes to execute your application. You can do it by specifying a startup command to your container.

-For example, to start four instances:

-## <a name="appbackup"></a>When your app backup starts failing

-The two most common reasons why app backup fails are: invalid storage settings and invalid database configuration. These failures typically happen when there are changes to storage or database resources, or changes for how to access these resources (for example, credentials updated for the database selected in the backup settings). Backups typically run on a schedule and require access to storage (for outputting the backed-up files) and databases (for copying and reading contents to be included in the backup). The result of failing to access either of these resources would be consistent backup failure.

-When backup failures happen, review most recent results to understand which type of failure is happening. For storage access failures, review and update the storage settings used in the backup configuration. For database access failures, review and update your connections strings as part of app settings; then proceed to update your backup configuration to properly include the required databases. For more information on app backups, see [Back up a web app in Azure App Service](manage-backup.md).

-## <a name="nodejs"></a>When new Node.js apps are deployed to Azure App Service

-Azure App Service default configuration for Node.js apps is intended to best suit the needs of most common apps. If configuration for your Node.js app would benefit from personalized tuning to improve performance or optimize resource usage for CPU/memory/network resources, see [Best practices and troubleshooting guide for Node applications on Azure App Service](app-service-web-nodejs-best-practices-and-troubleshoot-guide.md). This article describes the iisnode settings you may need to configure for your Node.js app, describes the various scenarios or issues that your app may be facing, and shows how to address these issues.

-## <a name=""></a>When Internet of Things (IoT) devices are connected to apps on App Service

-There are a few scenarios where you can improve your environment when running Internet of Things (IoT) devices that are connected to App Service. One very common practice with IoT devices is "certificate pinning". To avoid any unforeseen downtime due to changes in the service's managed certificates, you should never pin certificates to the default \*.azurewebsites.net certificate nor to an App Service Managed Certificate. If your system needs to rely on certificate pinning behavior, it is recommended to add a custom domain to a web app and provide a custom TLS certificate for the domain which can then be relied on for certificate pinning. You can refer to the [certificate pinning](#certificatepinning) section of this article for more information.

-To increase resiliency in your environment, you should not rely on a single endpoint for all your devices. You should at least host your web apps in two different regions to avoid a single point of failure and be ready to failover traffic. On App Service, you can add identical custom domain to different web apps as long as these web apps are hosted in different regions. This ensures that if you need to pin certificates, you can also pin on the custom TLS certificate that you provided. Another option would be to use a load balancer in front of the web apps, such as Azure Front Door or Traffic Manager, to ensure high availability for your web apps. You can refer to [Quickstart: Create a Front Door for a highly available global web application](../frontdoor/quickstart-create-front-door.md) or [Controlling Azure App Service traffic with Azure Traffic Manager](./web-sites-traffic-manager.md) for more information.

-## Next Steps

-For more information on best practices, visit [App Service Diagnostics](./overview-diagnostics.md) to find out actionable best practices specific to your resource.

-You can also use this link to directly open App Service Diagnostics for your resource: `https://portal.azure.com/?websitesextension_ext=asd.featurePath%3Ddetectors%2FParentAvailabilityAndPerformance#@microsoft.onmicrosoft.com/resource/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{siteName}/troubleshoot`.

-description: Learn about the OS functionality in Azure App Service on Windows. Find out what types of file, network, and registry access your app gets.

-# Operating system functionality on Azure App Service

-This article describes the common baseline operating system functionality that is available to all Windows apps running on [Azure App Service](./overview.md). This functionality includes file, network, and registry access, and diagnostics logs and events.

-> [!NOTE]

-> [Linux apps](overview.md#app-service-on-linux) in App Service run in their own containers. You have root access to the container but no access to the host operating system is allowed. Likewise, for [apps running in Windows containers](quickstart-custom-container.md?pivots=container-windows), you have administrative access to the container but no access to the host operating system.

->

-App Service runs customer apps in a multi-tenant hosting environment. Apps deployed in the **Free** and **Shared** tiers run in worker processes on shared virtual machines, while apps deployed in the **Standard** and **Premium** tiers run on virtual machine(s) dedicated specifically for the apps associated with a single customer.

-Because App Service supports a seamless scaling experience between different tiers, the security configuration enforced for App Service apps remains the same. This ensures that apps don't suddenly behave differently, failing in unexpected ways, when an App Service plan switches from one tier to another.

-App Service supports a variety of development frameworks, including ASP.NET, classic ASP, Node.js, PHP, and Python.

-In order to simplify and normalize security configuration, App Service apps typically run the various development frameworks with their default settings. The frameworks and runtime components provided by the platform are updated regularly to satisfy security and compliance requirements, for this reason we don't guarantee specific minor/patch versions and recommend customers target major version as needed.

-At its core, App Service is a service running on top of the Azure PaaS (platform as a service) infrastructure. As a result, the local drives that are "attached" to a virtual machine are the same drive types available to any worker role running in Azure. This includes:

-A best practice is to always use the environment variables `%SystemDrive%` and `%ResourceDrive%` instead of hard-coded file paths. The root path returned from these two environment variables has shifted over time from `d:\` to `c:\`. However, older applications hard-coded with file path references to `d:\` will continue to work because the App Service platform automatically remaps `d:\` to instead point at `c:\`. As noted above, it's highly recommended to always use the environment variables when building file paths and avoid confusion over platform changes to the default root file path.

-It's important to monitor your disk utilization as your application grows. If the disk quota is reached, it can have adverse effects to your application. For example:

-One of the unique aspects of App Service that makes app deployment and maintenance straightforward is that all content shares are stored on a set of UNC shares. This model maps well to the common pattern of content storage used by on-premises web hosting environments that have multiple load-balanced servers.

-Within App Service, there is a number of UNC shares created in each data center. A percentage of the user content for all customers in each data center is allocated to each UNC share. Each customer's subscription has a reserved directory structure on a specific UNC share within a data center. A customer may have multiple apps created within a specific data center, so all of the directories belonging to a single customer subscription are created on the same UNC share.

-Due to how Azure services work, the specific virtual machine responsible for hosting a UNC share will change over time. It is guaranteed that UNC shares will be mounted by different virtual machines as they're brought up and down during the normal course of Azure operations. For this reason, apps should never make hard-coded assumptions that the machine information in a UNC file path will remain stable over time. Instead, they should use the convenient *faux* absolute path `%HOME%\site` that App Service provides. This faux absolute path provides a portable, app-and-user-agnostic method for referring to one's own app. By using `%HOME%\site`, one can transfer shared files from app to app without having to configure a new absolute path for each transfer.

-The `%HOME%` directory in an app maps to a content share in Azure Storage dedicated for that app, and its size is defined by your [pricing tier](https://azure.microsoft.com/pricing/details/app-service/). It may include directories such as those for content, error and diagnostic logs, and earlier versions of the app created by source control. These directories are available to the app's application code at runtime for read and write access. Because the files aren't stored locally, they're persistent across app restarts.

-On the system drive, App Service reserves `%SystemDrive%\local` for app-specific temporary local storage. Changes to files in this directory are *not* persistent across app restarts. Although an app has full read/write access to its own temporary local storage, that storage really isn't intended to be used directly by the application code. Rather, the intent is to provide temporary file storage for IIS and web application frameworks. App Service also limits the amount of storage in `%SystemDrive%\local` for each app to prevent individual apps from consuming excessive amounts of local file storage. For **Free**, **Shared**, and **Consumption** (Azure Functions) tiers, the limit is 500 MB. See the following table for other tiers:

-| SKU | Local file storage |

-| B1/S1/P1 | 11GB |

-| B2/S2/P2 | 15GB |

-| B3/S3/P3 | 58GB |

-| P0v3 | 11GB |

-| P1v2/P1v3/P1mv3/Isolated1/Isolated1v2 | 21GB |

-| P2v2/P2v3/P2mv3/Isolated2/Isolated2v2 | 61GB |

-| P3v2/P3v3/P3mv3/Isolated3/Isolated3v2 | 140GB |

-| Isolated4v2 | 276GB|

-| P4mv3 | 280GB |

-| Isolated5v2 | 552GB|

-| P5mv3 | 560GB |

-| Isolated6v2 | 1104GB|

-Two examples of how App Service uses temporary local storage are the directory for temporary ASP.NET files and the directory for IIS compressed files. The ASP.NET compilation system uses the `%SystemDrive%\local\Temporary ASP.NET Files` directory as a temporary compilation cache location. IIS uses the `%SystemDrive%\local\IIS Temporary Compressed Files` directory to store compressed response output. Both of these types of file usage (as well as others) are remapped in App Service to per-app temporary local storage. This remapping ensures that functionality continues as expected.

-Each app in App Service runs as a random unique low-privileged worker process identity called the "application pool identity", described further in the IIS [Application Pool Identities](/iis/manage/configuring-security/application-pool-identities) documentation. Application code uses this identity for basic read-only access to the operating system drive. This means application code can list common directory structures and read common files on operating system drive. Although this might appear to be a somewhat broad level of access, the same directories and files are accessible when you provision a worker role in an Azure hosted service and read the drive contents.

-The content share (`%HOME%`) directory contains an app's content, and application code can write to it. If an app runs on multiple instances, the `%HOME%` directory is shared among all instances so that all instances see the same directory. So, for example, if an app saves uploaded files to the `%HOME%` directory, those files are immediately available to all instances.

-The temporary local storage (`%SystemDrive%\local`) directory is not shared between instances, neither is it shared between the app and its [Kudu app](resources-kudu.md).

-Application code can use TCP/IP and UDP-based protocols to make outbound network connections to Internet accessible endpoints that expose external services. Apps can use these same protocols to connect to services within Azure, for example, by establishing HTTPS connections to SQL Database.

-There's also a limited capability for apps to establish one local loopback connection, and have an app listen on that local loopback socket. This feature exists primarily to enable apps that listen on local loopback sockets as part of their functionality. Each app sees a "private" loopback connection. App "A" cannot listen to a local loopback socket established by app "B".

-Named pipes are also supported as an inter-process communication (IPC) mechanism between different processes that collectively run an app. For example, the IIS FastCGI module relies on named pipes to coordinate the individual processes that run PHP pages.

-As noted earlier, apps run inside of low-privileged worker processes using a random application pool identity. Application code has access to the memory space associated with the worker process, as well as any child processes that may be spawned by CGI processes or other applications. However, one app cannot access the memory or data of another app even if it's on the same virtual machine.

-Apps can run scripts or pages written with supported web development frameworks. App Service doesn't configure any web framework settings to more restricted modes. For example, ASP.NET apps running on App Service run in "full" trust as opposed to a more restricted trust mode. Web frameworks, including both classic ASP and ASP.NET, can call in-process COM components (but not out of process COM components) like ADO (ActiveX Data Objects) that are registered by default on the Windows operating system.

-Apps can spawn and run arbitrary code. It's allowable for an app to do things like spawn a command shell or run a PowerShell script. However, even though arbitrary code and processes can be spawned from an app, executable programs and scripts are still restricted to the privileges granted to the parent application pool. For example, an app can spawn an executable that makes an outbound HTTP call, but that same executable cannot attempt to unbind the IP address of a virtual machine from its NIC. Making an outbound network call is allowed to low-privileged code, but attempting to reconfigure network settings on a virtual machine requires administrative privileges.

-Log information is another set of data that some apps attempt to access. The types of log information available to code running in App Service includes diagnostic and log information generated by an app that is also easily accessible to the app.

-For example, W3C HTTP logs generated by an active app are available either on a log directory in the network share location created for the app, or available in blob storage if a customer has set up W3C logging to storage. The latter option enables large quantities of logs to be gathered without the risk of exceeding the file storage limits associated with a network share.

-In a similar vein, real-time diagnostics information from .NET apps can also be logged using the .NET tracing and diagnostics infrastructure, with options to write the trace information to either the app's network share, or alternatively to a blob storage location.

-Areas of diagnostics logging and tracing that aren't available to apps are Windows ETW events and common Windows event logs (for example, System, Application, and Security event logs). Since ETW trace information can potentially be viewable machine-wide (with the right ACLs), read and write access to ETW events are blocked. Developers might notice that API calls to read and write ETW events and common Windows event logs appear to work, but that is because App Service is "faking" the calls so that they appear to succeed. In reality, the application code has no access to this event data.

-Apps have read-only access to much (though not all) of the registry of the virtual machine they're running on. In practice, this means registry keys that allow read-only access to the local Users group are accessible by apps. One area of the registry that is currently not supported for either read or write access is the HKEY\_CURRENT\_USER hive.

-Write-access to the registry is blocked, including access to any per-user registry keys. From the app's perspective, write access to the registry should never be relied upon in the Azure environment since apps can (and do) get migrated across different virtual machines. The only persistent writeable storage that can be depended on by an app is the per-app content directory structure stored on the App Service UNC shares.

-[Azure App Service sandbox](https://github.com/projectkudu/kudu/wiki/Azure-Web-App-sandbox) - The most up-to-date information about the execution environment of App Service. This page is

-maintained directly by the App Service development team.

-Kudu is the engine behind a number of features in [Azure App Service](overview.md) related to source control based deployment, and other deployment methods like Dropbox and OneDrive sync.

-Anytime you create an app, App Service creates a companion app for it that's secured by HTTPS. This Kudu app is accessible at:

-For more information, see [Accessing the kudu service](https://github.com/projectkudu/kudu/wiki/Accessing-the-kudu-service).

-It also provides other features, such as:

-To access Kudu in the browser with Microsoft Entra authentication, you need to be a member of a built-in or custom role.

-## More Resources

-Kudu is an [open source project](https://github.com/projectkudu/kudu), and has its documentation at [Kudu Wiki](https://github.com/projectkudu/kudu/wiki).

-description: Learn more about the routine, planned maintenance to keep the App Service platform up-to-date and secure.

-# Routine (planned) maintenance for App Service

-Routine maintenance covers behind the scenes updates to the Azure App Service platform. Types of maintenance can be performance improvements, bug fixes,

-new features, or security updates. App Service maintenance can be on App Service itself or the underlying operating system.

->[!IMPORTANT]

->A breaking change or deprecation of functionality is not a part of routine maintenance (see [Modern Lifecycle Policy - Microsoft Lifecycle | Microsoft Learn](/lifecycle/policies/modern) for deprecation topic for details).

->

-Our service quality and uptime guarantees continue to apply during maintenance periods. Maintenance periods are mentioned to help customers to get visibility into platform changes.

-Like security updates on personal computers, mobile phones and other devices, even machines in the cloud need the latest updates. Unlike physical devices, cloud solutions like Azure App Service provide ways to overcome these routines with more ease. There's no need to "stop working" for a certain period and wait until patches are installed. Any workload can be shifted to different hardware in a matter of seconds and while updates are installed. The updates are made monthly, but can vary on the needs and other factors.

-Since a typical cloud solution consists of multiple applications, databases, storage accounts, functions, and other resources, various parts of your solutions can be undergoing maintenance at different times. Some of this coordination is related to geography, region, data centers, and availability zones. It can also be due to the cloud where not everything is touched simultaneously.

-[Safe deployment practices - Azure DevOps | Microsoft Learn](/devops/operate/safe-deployment-practices)

-In order from top to bottom we see:

-## Frequently Asked Questions

-The maintenance fundamentally represents delivering latest updates to the platform and service. It's difficult to predict when individual apps would be affected down to a specific time, so more generic notifications are sent out. The time ranges in those notifications don't reflect the experiences at the app level, but the overall operation across all resources. Apps which undergo maintenance instantly restart on freshly updated machines and continue working. There's no downtime when requests/traffic aren't served.

-A typical scenario is that customers have multiple applications, and they are upgraded at different times. To avoid sending notifications for each of them, a more generic notification is sent that captures multiple resources. The notification is sent at the beginning and throughout the maintenance window. Due to the time window being longer, you can receive multiple reminders for the same rollout so you can easier correlate any restart/interruption/issue in case it is needed.

-Platform maintenance isn't expected to impact application uptime or availability. Applications continue to stay online while platform maintenance occurs. Platform maintenance may cause applications to be cold started on new virtual machines, which can lead to cold start delays. An application is still considered to be online, even while cold-starting. For best practices to minimize/avoid cold starts, consider using [local cache for Windows apps](overview-local-cache.md) as well as [Health check](monitor-instances-health-check.md). It's not expected that sites would incur any SLA violation during maintenance windows.

-### How does the upgrade work how does it ensure the smooth operation of my apps?

-Azure App Service represents a fleet of scale units, which provide hosting of web applications/solutions to the customers. Each scale unit is further divided into smaller pieces and sliced into a concept of upgrade domains and availability zones. This is to optimize placements of bigger App Service Plans and smooth deployments since not all machines in each scale unit are updated at once. Fleet upgrades machines iteratively while monitoring the health of the fleet so any time there is an issue, the system can stop the rollout. This process is described in detail at [Demystifying the magic behind App Service OS updates - Azure App Service](https://azure.github.io/AppService/2018/01/18/Demystifying-the-magic-behind-App-Service-OS-updates.html).

-Maintenance operations are optimized to start outside standard business hours (9-5pm) as statistically that is a better timing for any interruptions and restarts of workloads as there is a less stress on the system (in customer applications and transitively also on the platform itself). For App Service Plan and App Service Environment v2, maintenance can continue into business hours during longer maintenance events.

-If you run your workloads in Isolated SKU via App Service Environment v3, you can also schedule the upgrades when needed. This is described with details at Control and automate planned maintenance for App Service Environment v3 - Azure App Service.

-If your applications need extra time during restarts to come online (a typical pattern would be heavy dependency on external resources during application warm-up/start-up), consider using [Health Check](monitor-instances-health-check.md). You can use this to communicate with the platform that your application is not ready to receive requests yet and the system can use that information to route requests to other instances in your App Service Plan. For such case, it's recommended to have at least two instances in the plan.

-### My applications have been online, but since these notifications started showing up things are worse. What changed?

-Updates and maintenance events have been happening to the platform since its inception. The frequency of updates decreased over time, so the number of interruptions also decreased and uptime increases. However, there is an increased level of visibility into all changes which can cause the perception that more changes are being made.

-## Next steps

-[Control and automate planned maintenance for App Service Environment v3 - Azure App Service](https://azure.github.io/AppService/2022/09/15/Configure-automation-for-upgrade-preferences-in-App-Service-Environment.html)

-[Demystifying the magic behind App Service OS updates - Azure App Service](https://azure.github.io/AppService/2018/01/18/Demystifying-the-magic-behind-App-Service-OS-updates.html)

-[Routine Planned Maintenance Notifications for Azure App Service - Azure App Service](https://azure.github.io/AppService/2022/02/01/App-Service-Planned-Notification-Feature.html)

-| AZ_ACR_NAME | (your Azure Container Registry instance, for example. azurearctest.azurecr.io) |

- [ActivityTrigger] (string Major, int UniversityYear) inputs, FunctionContext executionContext)

-The following example shows a [C# function](functions-dotnet-class-library.md) that retrieves a single record. The function is triggered by an HTTP request that uses a query string to specify the ID. That ID is used to retrieve a `ToDoItem` record with the specified query.

-The following example shows a [C# function](functions-dotnet-class-library.md) that retrieves documents returned by the query. The function is triggered by an HTTP request that uses route data to specify the value of a query parameter. That parameter is used to filter the `ToDoItem` records in the specified query.

-The following example shows a [C# function](functions-dotnet-class-library.md) that retrieves a single record. The function is triggered by an HTTP request that uses a query string to specify the ID. That ID is used to retrieve a `ToDoItem` record with the specified query.

-The following example shows a [C# function](functions-dotnet-class-library.md) that retrieves documents returned by the query. The function is triggered by an HTTP request that uses route data to specify the value of a query parameter. That parameter is used to filter the `ToDoItem` records in the specified query.

-The following example shows a SQL input binding in a Java function that reads from a query and returns the results in the HTTP response.

-The following example shows a SQL input binding in a Java function that reads from a query filtered by a parameter from the query string and returns the row in the HTTP response.

-The following example shows a SQL input binding in a Java function that executes a stored procedure with input from the HTTP request query parameter.

-The following example shows a SQL input binding that reads from a query and returns the results in the HTTP response.

-The following example shows a SQL input binding that reads from a query filtered by a parameter from the query string and returns the row in the HTTP response.

-The following example shows a SQL input binding that executes a stored procedure with input from the HTTP request query parameter.

-The following example shows a SQL input binding in a function.json file and a PowerShell function that reads from a query and returns the results in the HTTP response.

-The following example shows a SQL input binding in a PowerShell function that reads from a query filtered by a parameter from the query string and returns the row in the HTTP response.

-The following example shows a SQL input binding in a function.json file and a PowerShell function that executes a stored procedure with input from the HTTP request query parameter.

-The following example shows a SQL input binding in a function.json file and a Python function that reads from a query and returns the results in the HTTP response.

-The following example shows a SQL input binding in a Python function that reads from a query filtered by a parameter from the query string and returns the row in the HTTP response.

-The following example shows a SQL input binding in a function.json file and a Python function that executes a stored procedure with input from the HTTP request query parameter.

-If you're configuring `AzureWebJobsStorage` using a storage account that uses the default DNS suffix and service name for global Azure, following the `https://<accountName>.blob/queue/file/table.core.windows.net` format, you can instead set `AzureWebJobsStorage__accountName` to the name of your storage account. The endpoints for each storage service are inferred for this account. This doesn't work when the storage account is in a sovereign cloud or has a custom DNS.

-In addition to Azure Functions hosting, you can also host containerized function apps in containers can also be deployed to Kubernetes clusters and to Azure Container Apps. If you choose to host your functions in a Kubernetes cluster, consider using an [Azure Arc-enabled Kubernetes cluster](../azure-arc/kubernetes/overview.md). To learn more about deploying custom container apps, see [Azure Container Apps hosting of Azure Functions](./functions-container-apps-hosting.md).

- if ($App.ApplicationSettings["FUNCTIONS_WORKER_RUNTIME"] -eq 'dotnet')

- $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_WORKER_RUNTIME"])

-description: This article describes how you can configure the Container insights agent to control stdout/stderr and environment variables log collection.

-# Configure agent data collection for Container insights

-Container insights collects stdout, stderr, and environmental variables from container workloads deployed to managed Kubernetes clusters from the containerized agent. You can configure agent data collection settings by creating a custom Kubernetes ConfigMap to control this experience.

-This article demonstrates how to create ConfigMaps and configure data collection based on your requirements.

-## ConfigMap file settings overview

-A template ConfigMap file is provided so that you can easily edit it with your customizations without having to create it from scratch. Before you start, review the Kubernetes documentation about [ConfigMaps](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/). Familiarize yourself with how to create, configure, and deploy ConfigMaps. You need to know how to filter stderr and stdout per namespace or across the entire cluster. You also need to know how to filter environment variables for any container running across all pods/nodes in the cluster.

->[!IMPORTANT]

->The minimum agent version supported to collect stdout, stderr, and environmental variables from container workloads is **ciprod06142019** or later. To verify your agent version, on the **Node** tab, select a node. On the **Properties** pane, note the value of the **Agent Image Tag** property. For more information about the agent versions and what's included in each release, see [Agent release notes](https://github.com/microsoft/Docker-Provider/tree/ci_feature_prod).

-### Data collection settings

-The following table describes the settings you can configure to control data collection.

->[!NOTE]

->For clusters enabling container insights using Azure CLI version 2.54.0 or greater, the default setting for `[log_collection_settings.schema]` will be set to "v2"

-| Key | Data type | Value | Description |

-|--|--|--|--|

-| `schema-version` | String (case sensitive) | v1 | This schema version is used by the agent<br> when parsing this ConfigMap.<br> Currently supported schema-version is v1.<br> Modifying this value isn't supported and will be<br> rejected when the ConfigMap is evaluated. |

-| `config-version` | String | | Supports the ability to keep track of this config file's version in your source control system/repository.<br> Maximum allowed characters are 10, and all other characters are truncated. |

-| `[log_collection_settings.stdout] enabled =` | Boolean | True or false | Controls if stdout container log collection is enabled. When set to `true` and no namespaces are excluded for stdout log collection<br> (`log_collection_settings.stdout.exclude_namespaces` setting), stdout logs will be collected from all containers across all pods/nodes in the cluster. If not specified in the ConfigMap,<br> the default value is `enabled = true`. |

-| `[log_collection_settings.stdout] exclude_namespaces =` | String | Comma-separated array | Array of Kubernetes namespaces for which stdout logs won't be collected. This setting is effective only if<br> `log_collection_settings.stdout.enabled`<br> is set to `true`.<br> If not specified in the ConfigMap, the default value is<br> `exclude_namespaces = ["kube-system","gatekeeper-system"]`. |

-| `[log_collection_settings.stderr] enabled =` | Boolean | True or false | Controls if stderr container log collection is enabled.<br> When set to `true` and no namespaces are excluded for stdout log collection<br> (`log_collection_settings.stderr.exclude_namespaces` setting), stderr logs will be collected from all containers across all pods/nodes in the cluster.<br> If not specified in the ConfigMap, the default value is<br> `enabled = true`. |

-| `[log_collection_settings.stderr] exclude_namespaces =` | String | Comma-separated array | Array of Kubernetes namespaces for which stderr logs won't be collected.<br> This setting is effective only if<br> `log_collection_settings.stdout.enabled` is set to `true`.<br> If not specified in the ConfigMap, the default value is<br> `exclude_namespaces = ["kube-system","gatekeeper-system"]`. |

-| `[log_collection_settings.env_var] enabled =` | Boolean | True or false | This setting controls environment variable collection<br> across all pods/nodes in the cluster<br> and defaults to `enabled = true` when not specified<br> in the ConfigMap.<br> If collection of environment variables is globally enabled, you can disable it for a specific container<br> by setting the environment variable<br> `AZMON_COLLECT_ENV` to `False` either with a Dockerfile setting or in the [configuration file for the Pod](https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/) under the `env:` section.<br> If collection of environment variables is globally disabled, you can't enable collection for a specific container. The only override that can be applied at the container level is to disable collection when it's already enabled globally. |

-| `[log_collection_settings.enrich_container_logs] enabled =` | Boolean | True or false | This setting controls container log enrichment to populate the `Name` and `Image` property values<br> for every log record written to the **ContainerLog** table for all container logs in the cluster.<br> It defaults to `enabled = false` when not specified in the ConfigMap. |

-| `[log_collection_settings.collect_all_kube_events] enabled =` | Boolean | True or false | This setting allows the collection of Kube events of all types.<br> By default, the Kube events with type **Normal** aren't collected. When this setting is set to `true`, the **Normal** events are no longer filtered, and all events are collected.<br> It defaults to `enabled = false` when not specified in the ConfigMap. |

-| `[log_collection_settings.schema] enabled =` | String (case sensitive) | v2 or v1 [(retired)](./container-insights-v2-migration.md) | This setting sets the log ingestion format to ContainerLogV2 |

-| `[log_collection_settings.enable_multiline_logs] enabled =` | Boolean | True or False | This setting controls whether multiline container logs are enabled. They are disabled by default. See [Multi-line logging in Container Insights](./container-insights-logging-v2.md) to learn more. |

-### Metric collection settings

-The following table describes the settings you can configure to control metric collection.

-| Key | Data type | Value | Description |

-|--|--|--|--|

-| `[metric_collection_settings.collect_kube_system_pv_metrics] enabled =` | Boolean | True or false | This setting allows persistent volume (PV) usage metrics to be collected in the kube-system namespace. By default, usage metrics for persistent volumes with persistent volume claims in the kube-system namespace aren't collected. When this setting is set to `true`, PV usage metrics for all namespaces are collected. By default, this setting is set to `false`. |

-ConfigMap is a global list and there can be only one ConfigMap applied to the agent. You can't have another ConfigMap overruling the collections.

-### Agent settings for outbound proxy with Azure Monitor Private Link Scope (AMPLS)

-| Key | Data type | Value | Description |

-|--|--|--|--|

-| `[agent_settings.proxy_config] ignore_proxy_settings =` | Boolean | True or false | Set this value to true to ignore proxy settings. On both AKS & Arc K8s environments, if your cluster is configured with forward proxy, then proxy settings are automatically applied and used for the agent. For certain configurations, such as, with AMPLS + Proxy, you might with for the proxy config to be ignored. . By default, this setting is set to `false`. |

-## Configure and deploy ConfigMaps

-To configure and deploy your ConfigMap configuration file to your cluster:

-1. Download the [template ConfigMap YAML file](https://aka.ms/container-azm-ms-agentconfig) and save it as *container-azm-ms-agentconfig.yaml*.

-1. Edit the ConfigMap YAML file with your customizations to collect stdout, stderr, and environmental variables:

- - To exclude specific namespaces for stdout log collection, configure the key/value by using the following example:

- `[log_collection_settings.stdout] enabled = true exclude_namespaces = ["my-namespace-1", "my-namespace-2"]`.

- - To disable environment variable collection for a specific container, set the key/value `[log_collection_settings.env_var] enabled = true` to enable variable collection globally. Then follow the steps [here](container-insights-manage-agent.md#disable-environment-variable-collection-on-a-container) to complete configuration for the specific container.

- - To disable stderr log collection cluster-wide, configure the key/value by using the following example: `[log_collection_settings.stderr] enabled = false`.

-

- Save your changes in the editor.

-1. Create a ConfigMap by running the following kubectl command: `kubectl apply -f <configmap_yaml_file.yaml>`.

-

- Example: `kubectl apply -f container-azm-ms-agentconfig.yaml`

-The configuration change can take a few minutes to finish before taking effect. Then all Azure Monitor Agent pods in the cluster will restart. The restart is a rolling restart for all Azure Monitor Agent pods, so not all of them restart at the same time. When the restarts are finished, a message similar to this example includes the following result: `configmap "container-azm-ms-agentconfig" created`.

-## Verify configuration

-To verify the configuration was successfully applied to a cluster, use the following command to review the logs from an agent pod: `kubectl logs ama-logs-fdf58 -n kube-system`. If there are configuration errors from the Azure Monitor Agent pods, the output will show errors similar to the following example:

-```

-***************Start Config Processing********************

-config::unsupported/missing config schema version - 'v21' , using defaults

-```

-Errors related to applying configuration changes are also available for review. The following options are available to perform more troubleshooting of configuration changes:

- ```

- config::error::Exception while parsing config map for log collection/env variable settings: \nparse error on value \"$\" ($end), using defaults, please check config map for errors

- ```

-After you correct the errors in the ConfigMap, save the YAML file and apply the updated ConfigMap by running the following command: `kubectl apply -f <configmap_yaml_file.yaml`.

-## Apply updated ConfigMap

-If you've already deployed a ConfigMap on clusters and you want to update it with a newer configuration, you can edit the ConfigMap file you've previously used. Then you can apply it by using the same command as before: `kubectl apply -f <configmap_yaml_file.yaml`.

-The configuration change can take a few minutes to finish before taking effect. Then all Azure Monitor Agent pods in the cluster will restart. The restart is a rolling restart for all Azure Monitor Agent pods, so not all of them restart at the same time. When the restarts are finished, a message similar to this example includes the following result: `configmap "container-azm-ms-agentconfig" updated`.

-## Verify schema version

-Supported config schema versions are available as pod annotation (schema-versions) on the Azure Monitor Agent pod. You can see them with the following kubectl command: `kubectl describe pod ama-logs-fdf58 -n=kube-system`.

-Output similar to the following example appears with the annotation schema-versions:

-```

- Name: ama-logs-fdf58

- Namespace: kube-system

- Node: aks-agentpool-95673144-0/10.240.0.4

- Start Time: Mon, 10 Jun 2019 15:01:03 -0700

- Labels: controller-revision-hash=589cc7785d

- dsName=ama-logs-ds

- pod-template-generation=1

- Annotations: agentVersion=1.10.0.1

- dockerProviderVersion=5.0.0-0

- schema-versions=v1

-```

-## Frequently asked questions

-This section provides answers to common questions.

-### How do I enable log collection for containers in the kube-system namespace through Helm?

-The log collection from containers in the kube-system namespace is disabled by default. You can enable log collection by setting an environment variable on Azure Monitor Agent. See the [Container insights](https://aka.ms/azuremonitor-containers-helm-chart) GitHub page.

-

-## Next steps

-The main differences in monitoring a Windows Server cluster with Container insights compared to a Linux cluster are described in [Features of Container insights](container-insights-overview.md#features-of-container-insights) in the overview article.

-After you finish your analysis to determine which sources are generating the data that's exceeding your requirements, you can reconfigure data collection. For more information on configuring collection of stdout, stderr, and environmental variables, see [Configure agent data collection settings](container-insights-agent-config.md).

-You must be on the ContainerLogV2 schema to configure Basic Logs. For more information, see [Enable the ContainerLogV2 schema (preview)](container-insights-logging-v2.md).

-> This section describes [collection of Prometheus metrics in your Log Analytics workspace](container-insights-prometheus-logs.md). This information does not apply if you're using [Managed Prometheus to scrape your Prometheus metrics](prometheus-metrics-enable.md).

-description: This article describes how to enable the AKS Monitoring Add-on by using a custom Azure policy.

-# Enable the AKS Monitoring Add-on by using Azure Policy

-This article describes how to enable the Azure Kubernetes Service (AKS) Monitoring Add-on by using a custom Azure policy.

-## Permissions required

-The AKS Monitoring Add-on requires the following roles on the managed identity used by Azure Policy:

-The AKS Monitoring Add-on custom policy can be assigned at either the subscription or resource group scope. If the Log Analytics workspace and AKS cluster are in different subscriptions, the managed identity used by the policy assignment must have the required role permissions on both the subscriptions or on the Log Analytics workspace resource. Similarly, if the policy is scoped to the resource group, the managed identity should have the required role permissions on the Log Analytics workspace if the workspace isn't in the selected resource group scope.

-## Create and assign a policy definition by using the Azure portal

-Use the Azure portal to create and assign a policy definition.

-### Create a policy definition

-1. Download the Azure custom policy definition to enable the AKS Monitoring Add-on.

- ``` sh

- curl -o azurepolicy.json -L https://aka.ms/aks-enable-monitoring-custom-policy

- ```

-1. Go to the [Azure Policy Definitions](https://portal.azure.com/#blade/Microsoft_Azure_Policy/PolicyMenuBlade/Definitions) page. Create a policy definition with the following details on the **Policy definition** page:

- - **Definition location**: Select the Azure subscription where the policy definition should be stored.

- - **Name**: *(Preview)AKS-Monitoring-Addon*

- - **Description**: *Azure custom policy to enable the Monitoring Add-on onto Azure Kubernetes clusters in a specified scope*

- - **Category**: Select **Use existing** and select **Kubernetes** from the dropdown list.

- - **Policy rule**: Remove the existing sample rules and copy the contents of `azurepolicy.json` downloaded in step 1.

-### Assign a policy definition to a specified scope

-> [!NOTE]

-> A managed identity will be created automatically and assigned specified roles in the policy definition.

-1. Select the policy definition **(Preview) AKS Monitoring Addon** that you created.

-1. Select **Assign** and specify a **Scope** of where the policy should be assigned.

-1. Select **Next** and provide the resource ID of the Log Analytics workspace. The resource ID should be in the format `/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.OperationalInsights/workspaces/<workspaceName>`.

-1. Create a remediation task if you want to apply the policy to existing AKS clusters in the selected scope.

-1. Select **Review + create** to create the policy assignment.

-## Create and assign a policy definition by using the Azure CLI

-Use the Azure CLI to create and assign a policy definition.

-### Create a policy definition

-1. Download the Azure custom policy definition rules and parameter files with the following commands:

- ``` sh

- curl -o azurepolicy.rules.json -L https://aka.ms/aks-enable-monitoring-custom-policy-rules

- curl -o azurepolicy.parameters.json -L https://aka.ms/aks-enable-monitoring-custom-policy-parameters

- ```

-1. Create the policy definition with the following command:

- ```azurecli

- az cloud set -n <AzureCloud | AzureChinaCloud | AzureUSGovernment> # set the Azure cloud

- az login # login to cloud environment

- az account set -s <subscriptionId>

- az policy definition create --name "(Preview)AKS-Monitoring-Addon" --display-name "(Preview)AKS-Monitoring-Addon" --mode Indexed --metadata version=1.0.0 category=Kubernetes --rules azurepolicy.rules.json --params azurepolicy.parameters.json

- ```

-### Assign a policy definition to a specified scope

-Create the policy assignment with the following command:

-```azurecli

-az policy assignment create --name aks-monitoring-addon --policy "(Preview)AKS-Monitoring-Addon" --assign-identity --identity-scope /subscriptions/<subscriptionId> --role Contributor --scope /subscriptions/<subscriptionId> --location <locatio> --role Contributor --scope /subscriptions/<subscriptionId> -p "{ \"workspaceResourceId\": { \"value\": \"/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/microsoft.operationalinsights/workspaces/<workspaceName>\" } }"

-```

-## Next steps

-description: Learn how to enable Container insights on an Azure Kubernetes Service (AKS) cluster.

-# Enable Container insights for Azure Kubernetes Service (AKS) cluster

-This article describes how to enable Container insights on a managed Kubernetes cluster hosted on an [Azure Kubernetes Service (AKS)](../../aks/index.yml) cluster.

-## Prerequisites

-## Enable monitoring

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

-There are multiple options to enable Prometheus metrics on your cluster from the Azure portal.

-### New cluster

-When you create a new AKS cluster in the Azure portal, you can enable Prometheus, Container insights, and Grafana from the **Integrations** tab. In the Azure Monitor section, select either **Default configuration** or **Custom configuration** if you want to specify which workspaces to use. You can perform additional configuration once the cluster is created.

-### From existing cluster

-This option enables Container insights on a cluster and gives you the option of also enabling [Managed Prometheus and Managed Grafana](./prometheus-metrics-enable.md) for the cluster.

-> [!NOTE]

-> If you want to enabled Managed Prometheus without Container insights, then [enable it from the Azure Monitor workspace](./prometheus-metrics-enable.md).

-1. Open the cluster's menu in the Azure portal and select **Insights**.

- 1. If Container insights isn't enabled for the cluster, then you're presented with a screen identifying which of the features have been enabled. Click **Configure monitoring**.

- :::image type="content" source="media/aks-onboard/configure-monitoring-screen.png" lightbox="media/aks-onboard/configure-monitoring-screen.png" alt-text="Screenshot that shows the configuration screen for a cluster.":::

- 2. If Container insights has already been enabled on the cluster, select the **Monitoring Settings** button to modify the configuration.

- :::image type="content" source="media/aks-onboard/monitor-settings-button.png" lightbox="media/aks-onboard/monitor-settings-button.png" alt-text="Screenshot that shows the monitoring settings button for a cluster.":::

-2. The **Container insights** will be enabled. **Select** the checkboxes for **Enable Prometheus metrics** and **Enable Grafana** if you also want to enable them for the cluster. If you have existing Azure Monitor workspace and Grafana workspace, then they're selected for you.

- :::image type="content" source="media/prometheus-metrics-enable/configure-container-insights.png" lightbox="media/prometheus-metrics-enable/configure-container-insights.png" alt-text="Screenshot that shows the dialog box to configure Container insights with Prometheus and Grafana.":::

-3. Click **Advanced settings** to select alternate workspaces or create new ones. The **Cost presets** setting allows you to modify the default collection details to reduce your monitoring costs. See [Enable cost optimization settings in Container insights](./container-insights-cost-config.md) for details.

- :::image type="content" source="media/aks-onboard/advanced-settings.png" lightbox="media/aks-onboard/advanced-settings.png" alt-text="Screenshot that shows the advanced settings dialog box.":::

-4. Click **Configure** to save the configuration.

-### From Container insights

-From the Container insights menu, you can view all of your clusters, quickly identify which aren't monitored, and launch the same configuration experience as described in [From existing cluster](#from-existing-cluster).

-1. Open the **Monitor** menu in the Azure portal and select **Insights**.

-3. The **Unmonitored clusters** tab lists clusters that don't have Container insights enabled. Click **Enable** next to a cluster and follow the guidance in [Existing cluster](#existing-cluster).

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

-> [!NOTE]

-> Managed identity authentication will be default in CLI version 2.49.0 or higher. If you need to use legacy/non-managed identity authentication, use CLI version < 2.49.0. For CLI version 2.54.0 or higher the logging schema will be configured to [ContainerLogV2](container-insights-logging-v2.md) via the ConfigMap

-### Use a default Log Analytics workspace

-Use the following command to enable monitoring of your AKS cluster by using a default Log Analytics workspace for the resource group. If a default workspace doesn't already exist in the cluster's region, one will be created with a name in the format *DefaultWorkspace-\<GUID>-\<Region>*.

-```azurecli

-az aks enable-addons -a monitoring -n <cluster-name> -g <cluster-resource-group-name>

-```

-The output will resemble the following example:

-```output

-provisioningState : Succeeded

-```

-### Specify a Log Analytics workspace

-Use the following command to enable monitoring of your AKS cluster on a specific Log Analytics workspace. The resource ID of the workspace will be in the form `"/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroupName>/providers/Microsoft.OperationalInsights/workspaces/<WorkspaceName>"`.

-```azurecli

-az aks enable-addons -a monitoring -n <cluster-name> -g <cluster-resource-group-name> --workspace-resource-id <workspace-resource-id>

-```

-**Example**

-```azurecli

-az aks enable-addons -a monitoring -n <cluster-name> -g <cluster-resource-group-name> --workspace-resource-id "/subscriptions/my-subscription/resourceGroups/my-resource-group/providers/Microsoft.OperationalInsights/workspaces/my-workspace"

-```

-## [Resource Manager template](#tab/arm)

->[!NOTE]

->The template must be deployed in the same resource group as the cluster.

-1. Download the template and parameter file.

- - Template file: [https://aka.ms/aks-enable-monitoring-msi-onboarding-template-file](https://aka.ms/aks-enable-monitoring-msi-onboarding-template-file)

- - Parameter file: [https://aka.ms/aks-enable-monitoring-msi-onboarding-template-parameter-file](https://aka.ms/aks-enable-monitoring-msi-onboarding-template-parameter-file)

-2. Edit the following values in the parameter file:

- | Parameter | Description |

- |:|:|

- | `aksResourceId` | Use the values on the **AKS Overview** page for the AKS cluster. |

- | `aksResourceLocation` | Use the values on the **AKS Overview** page for the AKS cluster. |

- | `workspaceResourceId` | Use the resource ID of your Log Analytics workspace. |

- | `resourceTagValues` | Match the existing tag values specified for the existing Container insights extension data collection rule (DCR) of the cluster and the name of the DCR. The name will be *MSCI-\<clusterName\>-\<clusterRegion\>* and this resource created in an AKS clusters resource group. If this is the first time onboarding, you can set the arbitrary tag values. |

-3. Deploy the template with the parameter file by using any valid method for deploying Resource Manager templates. For examples of different methods, see [Deploy the sample templates](../resource-manager-samples.md#deploy-the-sample-templates).

-## [Bicep](#tab/bicep)

-### Existing cluster

-1. Download Bicep templates and parameter files depending on whether you want to enable Syslog collection.

- **Syslog**

- - Template file: [Template with Syslog](https://aka.ms/enable-monitoring-msi-syslog-bicep-template)

- - Parameter file: [Parameter with Syslog](https://aka.ms/enable-monitoring-msi-syslog-bicep-parameters)

- **No Syslog**

- - Template file: [Template without Syslog](https://aka.ms/enable-monitoring-msi-bicep-template)

- - Parameter file: [Parameter without Syslog](https://aka.ms/enable-monitoring-msi-bicep-parameters)

-2. Edit the following values in the parameter file:

-

- | Parameter | Description |

- |:|:|

- | `aksResourceId` | Use the values on the AKS Overview page for the AKS cluster. |

- | `aksResourceLocation` | Use the values on the AKS Overview page for the AKS cluster. |

- | `workspaceResourceId` | Use the resource ID of your Log Analytics workspace. |

- | `workspaceRegion` | Use the location of your Log Analytics workspace. |

- | `resourceTagValues` | Match the existing tag values specified for the existing Container insights extension data collection rule (DCR) of the cluster and the name of the DCR. The name will match `MSCI-<clusterName>-<clusterRegion>` and this resource is created in the same resource group as the AKS clusters. For first time onboarding, you can set the arbitrary tag values. |

- | `enabledContainerLogV2` | Set this parameter value to be true to use the default recommended ContainerLogV2 schema

- | Cost optimization parameters | Refer to [Data collection parameters](container-insights-cost-config.md#data-collection-parameters) |

-3. Deploy the template with the parameter file by using any valid method for deploying Resource Manager templates. For examples of different methods, see [Deploy the sample templates](../resource-manager-samples.md#deploy-the-sample-templates).

-### New cluster

-Replace and use the managed cluster resources in [Deploy an Azure Kubernetes Service (AKS) cluster using Bicep](../../aks/learn/quick-kubernetes-deploy-bicep.md).

-## [Terraform](#tab/terraform)

-### New AKS cluster

-1. Download Terraform template file depending on whether you want to enable Syslog collection.

- **Syslog**

- - [https://aka.ms/enable-monitoring-msi-syslog-terraform](https://aka.ms/enable-monitoring-msi-syslog-terraform)

- **No Syslog**

- - [https://aka.ms/enable-monitoring-msi-terraform](https://aka.ms/enable-monitoring-msi-terraform)

-2. Adjust the `azurerm_kubernetes_cluster` resource in *main.tf* based on what cluster settings you're going to have.

-3. Update parameters in *variables.tf* to replace values in "<>"

- | Parameter | Description |

- |:|:|

- | `aks_resource_group_name` | Use the values on the AKS Overview page for the resource group. |

- | `resource_group_location` | Use the values on the AKS Overview page for the resource group. |

- | `cluster_name` | Define the cluster name that you would like to create. |

- | `workspace_resource_id` | Use the resource ID of your Log Analytics workspace. |

- | `workspace_region` | Use the location of your Log Analytics workspace. |

- | `resource_tag_values` | Match the existing tag values specified for the existing Container insights extension data collection rule (DCR) of the cluster and the name of the DCR. The name will match `MSCI-<clusterName>-<clusterRegion>` and this resource is created in the same resource group as the AKS clusters. For first time onboarding, you can set the arbitrary tag values. |

- | `enabledContainerLogV2` | Set this parameter value to be true to use the default recommended ContainerLogV2. |

- | Cost optimization parameters | Refer to [Data collection parameters](container-insights-cost-config.md#data-collection-parameters) |

-4. Run `terraform init -upgrade` to initialize the Terraform deployment.

-5. Run `terraform plan -out main.tfplan` to initialize the Terraform deployment.

-6. Run `terraform apply main.tfplan` to apply the execution plan to your cloud infrastructure.

-### Existing AKS cluster

-1. Import the existing cluster resource first with the command: ` terraform import azurerm_kubernetes_cluster.k8s <aksResourceId>`

-2. Add the oms_agent add-on profile to the existing azurerm_kubernetes_cluster resource.

- ```

- oms_agent {

- log_analytics_workspace_id = var.workspace_resource_id

- msi_auth_for_monitoring_enabled = true

- }

- ```

-3. Copy the DCR and DCRA resources from the Terraform templates

-4. Run `terraform plan -out main.tfplan` and make sure the change is adding the oms_agent property. Note: If the `azurerm_kubernetes_cluster` resource defined is different during terraform plan, the existing cluster will get destroyed and recreated.

-5. Run `terraform apply main.tfplan` to apply the execution plan to your cloud infrastructure.

-> [!TIP]

-> - Edit the `main.tf` file appropriately before running the terraform template

-> - Data will start flowing after 10 minutes since the cluster needs to be ready first

-> - WorkspaceID needs to match the format `/subscriptions/12345678-1234-9876-4563-123456789012/resourceGroups/example-resource-group/providers/Microsoft.OperationalInsights/workspaces/workspaceValue`

-> - If resource group already exists, run `terraform import azurerm_resource_group.rg /subscriptions/<Subscription_ID>/resourceGroups/<Resource_Group_Name>` before terraform plan

-### [Azure Policy](#tab/policy)

-1. Download Azure Policy template and parameter files depending on whether you want to enable Syslog collection.

- - Template file: [https://aka.ms/enable-monitoring-msi-azure-policy-template](https://aka.ms/enable-monitoring-msi-azure-policy-template)

- - Parameter file: [https://aka.ms/enable-monitoring-msi-azure-policy-parameters](https://aka.ms/enable-monitoring-msi-azure-policy-parameters)

-2. Create the policy definition using the following command:

- ```

- az policy definition create --name "AKS-Monitoring-Addon-MSI" --display-name "AKS-Monitoring-Addon-MSI" --mode Indexed --metadata version=1.0.0 category=Kubernetes --rules azure-policy.rules.json --params azure-policy.parameters.json

- ```

-3. Create the policy assignment using the following CLI command or any [other available method](../../governance/policy/assign-policy-portal.md).

- ```

- az policy assignment create --name aks-monitoring-addon --policy "AKS-Monitoring-Addon-MSI" --assign-identity --identity-scope /subscriptions/<subscriptionId> --role Contributor --scope /subscriptions/<subscriptionId> --location <location> --role Contributor --scope /subscriptions/<subscriptionId> -p "{ \"workspaceResourceId\": { \"value\": \"/subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/microsoft.operationalinsights/workspaces/<workspaceName>\" } }"

- ```

-> [!TIP]

-> - Make sure when performing remediation task, the policy assignment has access to workspace you specified.

-> - Download all files under *AddonPolicyTemplate* folder before running the policy template.

-## Verify agent and solution deployment

-You can verify that the agent is deployed properly using the [kubectl command line tool](../../aks/learn/quick-kubernetes-deploy-cli.md#connect-to-the-cluster).

-```

-kubectl get ds ama-logs --namespace=kube-system

-```

-The output should resemble the following example, which indicates that it was deployed properly:

-```output

-User@aksuser:~$ kubectl get ds ama-logs --namespace=kube-system

-NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE

-ama-logs 2 2 2 2 2 beta.kubernetes.io/os=linux 1d

-```

-If there are Windows Server nodes on the cluster, run the following command to verify that the agent is deployed successfully:

-```

-kubectl get ds ama-logs-windows --namespace=kube-system

-```

-The output should resemble the following example, which indicates that it was deployed properly:

-```output

-User@aksuser:~$ kubectl get ds ama-logs-windows --namespace=kube-system

-NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE

-ama-logs-windows 2 2 2 2 2 beta.kubernetes.io/os=windows 1d

-```

-To verify deployment of the solution, run the following command:

-```

-kubectl get deployment ama-logs-rs -n=kube-system

-```

-The output should resemble the following example, which indicates that it was deployed properly:

-```output

-User@aksuser:~$ kubectl get deployment ama-logs-rs -n=kube-system

-NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE

-ama-logs-rs 1 1 1 1 3h

-```

-## View configuration with CLI

-Use the `aks show` command to find out whether the solution is enabled or not, what the Log Analytics workspace resource ID is, and summary information about the cluster.

-```azurecli

-az aks show -g <resourceGroupofAKSCluster> -n <nameofAksCluster>

-```

-The command will return JSON-formatted information about the solution. The `addonProfiles` section should include information on the `omsagent` as in the following example:

-```output

-"addonProfiles": {

- "omsagent": {

- "config": {

- "logAnalyticsWorkspaceResourceID": "/subscriptions/<WorkspaceSubscription>/resourceGroups/<DefaultWorkspaceRG>/providers/Microsoft.OperationalInsights/workspaces/<defaultWorkspaceName>"

- },

- "enabled": true

- }

- }

-```

-## Limitations

-## Next steps

-* If you experience issues while you attempt to onboard the solution, review the [Troubleshooting guide](container-insights-troubleshoot.md).

-* With monitoring enabled to collect health and resource utilization of your AKS cluster and workloads running on them, learn [how to use](container-insights-analyze.md) Container insights.

-description: Collect metrics and logs of Azure Arc-enabled Kubernetes clusters using Azure Monitor.

-# Azure Monitor Container Insights for Azure Arc-enabled Kubernetes clusters

-[Azure Monitor Container Insights](container-insights-overview.md) provides rich monitoring experience for Azure Arc-enabled Kubernetes clusters.

-## Supported configurations

->[!NOTE]

->If you are migrating from Container Insights on Azure Red Hat OpenShift v4.x, please also ensure that you have [disabled monitoring](./container-insights-optout-hybrid.md) before proceeding with configuring Container Insights on Azure Arc enabled Kubernetes to prevent any installation issues.

->

-## Prerequisites

-### Identify workspace resource ID

-Run the following commands to locate the full Azure Resource Manager identifier of the Log Analytics workspace.

-1. List all the subscriptions that you have access to using the following command:

- ```azurecli

- az account list --all -o table

- ```

-2. Switch to the subscription hosting the Log Analytics workspace using the following command:

- ```azurecli

- az account set -s <subscriptionId of the workspace>

- ```

-3. The following example displays the list of workspaces in your subscriptions in the default JSON format.

- ```azurecli

- az resource list --resource-type Microsoft.OperationalInsights/workspaces -o json

- ```

- In the output, find the workspace name of interest. The `id` field of that represents the Azure Resource Manager identifier of that Log Analytics workspace.

- >[!TIP]

- > This `id` can also be found in the *Overview* pane of the Log Analytics workspace through the Azure portal.

-## Create extension instance

-## [CLI](#tab/create-cli)

-### Option 1 - With default values

-This option uses the following defaults:

->[!NOTE]

-> Managed identity authentication is the default in k8s-extension version 1.43.0 or higher.

-```azurecli

-az k8s-extension create --name azuremonitor-containers --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type connectedClusters --extension-type Microsoft.AzureMonitor.Containers

-```

-To use [managed identity authentication](container-insights-onboard.md#authentication), add the `configuration-settings` parameter as in the following:

-```azurecli

-az k8s-extension create --name azuremonitor-containers --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type connectedClusters --extension-type Microsoft.AzureMonitor.Containers --configuration-settings amalogs.useAADAuth=true

-```

->[!NOTE]

-> Managed identity authentication is not supported for Arc-enabled Kubernetes clusters with ARO (Azure Red Hat Openshift) or Windows nodes.

->

-To use legacy/non-managed identity authentication to create an extension instance on **Arc K8S connected clusters with ARO**, use the commands below that don't use managed identity. Non-cli onboarding is not supported for Arc-enabled Kubernetes clusters with **ARO**.

-Install the extension with **amalogs.useAADAuth=false**.

-```azurecli

-az k8s-extension create --name azuremonitor-containers --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type connectedClusters --extension-type Microsoft.AzureMonitor.Containers --configuration-settings amalogs.useAADAuth=false

-```

-### Option 2 - With existing Azure Log Analytics workspace

-You can use an existing Azure Log Analytics workspace in any subscription on which you have *Contributor* or a more permissive role assignment.

-```azurecli

-az k8s-extension create --name azuremonitor-containers --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type connectedClusters --extension-type Microsoft.AzureMonitor.Containers --configuration-settings logAnalyticsWorkspaceResourceID=<armResourceIdOfExistingWorkspace>

-```

-### Option 3 - With advanced configuration

-If you want to tweak the default resource requests and limits, you can use the advanced configurations settings:

-```azurecli

-az k8s-extension create --name azuremonitor-containers --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type connectedClusters --extension-type Microsoft.AzureMonitor.Containers --configuration-settings amalogs.resources.daemonset.limits.cpu=150m amalogs.resources.daemonset.limits.memory=600Mi amalogs.resources.deployment.limits.cpu=1 amalogs.resources.deployment.limits.memory=750Mi

-```

-Check out the [resource requests and limits section of Helm chart](https://github.com/microsoft/Docker-Provider/blob/ci_prod/charts/azuremonitor-containers/values.yaml) for the available configuration settings.

-### Option 4 - On Azure Stack Edge

-If the Azure Arc-enabled Kubernetes cluster is on Azure Stack Edge, then a custom mount path `/home/data/docker` needs to be used.

-```azurecli

-az k8s-extension create --name azuremonitor-containers --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type connectedClusters --extension-type Microsoft.AzureMonitor.Containers --configuration-settings amalogs.logsettings.custommountpath=/home/data/docker

-```

-### Option 5 - With Azure Monitor Private Link Scope (AMPLS) + Proxy

-If the cluster is configured with a forward proxy, then proxy settings are automatically applied to the extension. In the case of a cluster with AMPLS + proxy, proxy config should be ignored. Onboard the extension with the configuration setting `amalogs.ignoreExtensionProxySettings=true`.

-```azurecli

-az k8s-extension create --name azuremonitor-containers --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type connectedClusters --extension-type Microsoft.AzureMonitor.Containers --configuration-settings amalogs.ignoreExtensionProxySettings=true

-```

->[!NOTE]

-> If you are explicitly specifying the version of the extension to be installed in the create command, then ensure that the version specified is >= 2.8.2.

-## [Azure portal](#tab/create-portal)

->[!IMPORTANT]

-> If you are deploying Azure Monitor on a Kubernetes cluster running on top of Azure Stack Edge, then the Azure CLI option needs to be followed instead of the Azure portal option as a custom mount path needs to be set for these clusters.

-### Onboarding from the Azure Arc-enabled Kubernetes resource pane

-1. In the Azure portal, select the Azure Arc-enabled Kubernetes cluster that you wish to monitor.

-2. From the resource pane on the left, select the 'Insights' item under the 'Monitoring' section.

-3. On the onboarding page, select the 'Configure Azure Monitor' button

-4. You can now choose the [Log Analytics workspace](../logs/quick-create-workspace.md) to send your metrics and logs data to.

-5. To use managed identity authentication, select the *Use managed identity* checkbox.

-6. Select the 'Configure' button to deploy the Azure Monitor Container Insights cluster extension.

-### Onboarding from Azure Monitor pane

-1. In the Azure portal, navigate to the 'Monitor' pane, and select the 'Containers' option under the 'Insights' menu.

-2. Select the 'Unmonitored clusters' tab to view the Azure Arc-enabled Kubernetes clusters that you can enable monitoring for.

-3. Click on the 'Enable' link next to the cluster that you want to enable monitoring for.

-4. Choose the Log Analytics workspace.

-5. To use managed identity authentication, select the *Use managed identity* checkbox.

-6. Select the 'Configure' button to continue.

-## [ARM](#tab/create-arm)

-This sections has instructions for onboarding with legacy authentication. For MSI based onboarding, see next tab.

-1. Download Azure Resource Manager template and parameter:

- ```console

- curl -L https://aka.ms/arc-k8s-azmon-extension-arm-template -o arc-k8s-azmon-extension-arm-template.json

- curl -L https://aka.ms/arc-k8s-azmon-extension-arm-template-params -o arc-k8s-azmon-extension-arm-template-params.json

- ```

-2. Update parameter values in arc-k8s-azmon-extension-arm-template-params.json file. For Azure public cloud, `opinsights.azure.com` needs to be used as the value of workspaceDomain and for AzureUSGovernment, `opinsights.azure.us` needs to be used as the value of workspaceDomain.

-3. Deploy the template to create Azure Monitor Container Insights extension

- ```azurecli

- az login

- az account set --subscription "Subscription Name"

- az deployment group create --resource-group <resource-group> --template-file ./arc-k8s-azmon-extension-arm-template.json --parameters @./arc-k8s-azmon-extension-arm-template-params.json

- ```

-## [ARM (with MSI)](#tab/create-arm-msi)

-Onboard using an ARM template with MSI based authentication enabled

-1. Download Azure Resource Manager template and parameter:

- ```console

- curl -L https://aka.ms/arc-k8s-azmon-extension-msi-arm-template -o arc-k8s-azmon-extension-arm-template.json

- curl -L https://aka.ms/arc-k8s-azmon-extension-msi-arm-template-params -o arc-k8s-azmon-extension-arm-template-params.json

- ```

-2. Update parameter values in arc-k8s-azmon-extension-arm-template-params.json file. For Azure public cloud, `opinsights.azure.com` needs to be used as the value of workspaceDomain and for AzureUSGovernment, `opinsights.azure.us` needs to be used as the value of workspaceDomain.

-3. Deploy the template to create Azure Monitor Container Insights extension

- ```azurecli

- az login

- az account set --subscription "Subscription Name"

- az deployment group create --resource-group <resource-group> --template-file ./arc-k8s-azmon-extension-arm-template.json --parameters @./arc-k8s-azmon-extension-arm-template-params.json

- ```

-## Verify extension installation status

-Once you have successfully created the Azure Monitor extension for your Azure Arc-enabled Kubernetes cluster, you can additionally check the status of installation using the Azure portal or CLI. Successful installations should show the status as 'Installed'. If your status is showing 'Failed' or remains in the 'Pending' state for long periods of time, proceed to the Troubleshooting section below.

-### [Azure portal](#tab/verify-portal)

-1. In the Azure portal, select the Azure Arc-enabled Kubernetes cluster with the extension installing

-2. From the resource pane on the left, select the 'Extensions' item under the 'Settings' section.

-3. You should see an extension with the name 'azuremonitor-containers' listed, with the listed status in the 'Install status' column

-### [CLI](#tab/verify-cli)

-Run the following command to show the latest status of the `Microsoft.AzureMonitor.Containers` extension

-```azurecli

-az k8s-extension show --name azuremonitor-containers --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type connectedClusters -n azuremonitor-containers

-```

-## Delete extension instance

-The following command only deletes the extension instance, but doesn't delete the Log Analytics workspace. The data within the Log Analytics resource is left intact.

-```azurecli

-az k8s-extension delete --name azuremonitor-containers --cluster-type connectedClusters --cluster-name <cluster-name> --resource-group <resource-group>

-```

-## Disconnected cluster

-If your cluster is disconnected from Azure for > 48 hours, then Azure Resource Graph won't have information about your cluster. As a result the Insights pane may display incorrect information about your cluster state.

-## Troubleshooting

-For issues with enabling monitoring, we have provided a [troubleshooting script](https://aka.ms/azmon-ci-troubleshooting) to help diagnose any problems.

-## Next steps

-description: Collect metrics and logs of AKS hybrid clusters using Azure Monitor.

-# Azure Monitor container insights for Azure Kubernetes Service (AKS) hybrid clusters (preview)

->[!NOTE]

->Support for monitoring AKS hybrid clusters is currently in preview. We recommend only using preview features in safe testing environments.

-[Azure Monitor container insights](./container-insights-overview.md) provides a rich monitoring experience for [AKS hybrid clusters (preview)](/azure/aks/hybrid/aks-hybrid-options-overview). This article describes how to set up Container insights to monitor an AKS hybrid cluster.

-## Supported configurations

-## Prerequisites

-## Onboarding

-## [CLI](#tab/create-cli)

-```acli

-az login

-az account set --subscription <cluster-subscription-name>

-az k8s-extension create --name azuremonitor-containers --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type provisionedclusters --cluster-resource-provider "microsoft.hybridcontainerservice" --extension-type Microsoft.AzureMonitor.Containers --configuration-settings amalogs.useAADAuth=true

-```

-## [Azure portal](#tab/create-portal)

-### Onboarding from the AKS hybrid resource pane

-1. In the Azure portal, select the AKS hybrid cluster that you wish to monitor.

-2. From the resource pane on the left, select the 'Insights' item under the 'Monitoring' section.

-3. On the onboarding page, select the 'Configure Azure Monitor' button

-4. You can now choose the [Log Analytics workspace](../logs/quick-create-workspace.md) to send your metrics and logs data to.

-5. Select the 'Configure' button to deploy the Azure Monitor Container Insights cluster extension.

-### Onboarding from Azure Monitor pane

-1. In the Azure portal, navigate to the 'Monitor' pane, and select the 'Containers' option under the 'Insights' menu.

-2. Select the 'Unmonitored clusters' tab to view the AKS hybrid clusters that you can enable monitoring for.

-3. Click on the 'Enable' link next to the cluster that you want to enable monitoring for.

-4. Choose the Log Analytics workspace.

-5. Select the 'Configure' button to continue.

-## [Resource Manager](#tab/create-arm)

-1. Download the Azure Resource Manager Template and Parameter files

-```bash

-curl -L https://aka.ms/existingClusterOnboarding.json -o existingClusterOnboarding.json

-```

-```bash

-curl -L https://aka.ms/existingClusterParam.json -o existingClusterParam.json

-```

-2. Edit the values in the parameter file.

- - For clusterResourceId and clusterRegion, use the values on the Overview page for the LCM cluster

- - For workspaceResourceId, use the resource ID of your Log Analytics workspace

- - For workspaceRegion, use the Location of your Log Analytics workspace

- - For workspaceDomain, use the workspace domain value as ΓÇ£opinsights.azure.comΓÇ¥ for public cloud and for Microsoft Azure operated by 21Vianet cloud as ΓÇ£opinsights.azure.cnΓÇ¥

- - For resourceTagValues, leave as empty if not specific

-3. Deploy the ARM template

-```azurecli

-az login

-az account set --subscription <cluster-subscription-name>

-az deployment group create --resource-group <resource-group> --template-file ./existingClusterOnboarding.json --parameters existingClusterParam.json

-```

-## Validation

-### Extension details

-Showing the extension details:

-```azcli

-az k8s-extension list --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type provisionedclusters --cluster-resource-provider "microsoft.hybridcontainerservice"

-```

-## Delete extension

-The command for deleting the extension:

-```azcli

-az k8s-extension delete --cluster-name <cluster-name> --resource-group <resource-group> --cluster-type provisionedclusters --cluster-resource-provider "microsoft.hybridcontainerservice" --name azuremonitor-containers --yes

-```

-## Known Issues/Limitations

-Starting with chart version 1.0.0, the agent data collection settings are controlled from the ConfigMap. For more information on agent data collection settings, see [Configure agent data collection for Container insights](container-insights-agent-config.md).

-> By default, Normal event types aren't collected, so you won't see them when you query the KubeEvents table unless the *collect_all_kube_events* ConfigMap setting is enabled. If you need to collect Normal events, enable *collect_all_kube_events setting* in the *container-azm-ms-agentconfig* ConfigMap. See [Configure agent data collection for Container insights](./container-insights-agent-config.md) for information on how to configure the ConfigMap.

-Container logs for AKS are stored in [the ContainerLogV2 table](./container-insights-logging-v2.md). You can run the following sample queries to look for the stderr/stdout log output from target pods, deployments, or namespaces.

-description: Switch your ContainerLog table to the ContainerLogV2 schema.

-# Enable the ContainerLogV2 schema

-Azure Monitor Container insights offers a schema for container logs, called ContainerLogV2. As part of this schema, there are fields to make common queries to view Azure Kubernetes Service (AKS) and Azure Arc-enabled Kubernetes data. In addition, this schema is compatible with [Basic Logs](../logs/basic-logs-configure.md), which offers a low-cost alternative to standard analytics logs.

->[!NOTE]

-> ContainerLogV2 will be the default schema via the ConfigMap for CLI version 2.54.0 and greater. ContainerLogV2 will be default ingestion format for customers who will be onboarding container insights with Managed Identity Auth using ARM, Bicep, Terraform, Policy and Portal onboarding. ContainerLogV2 can be explicitly enabled through CLI version 2.51.0 or higher using Data collection settings.

-The new fields are:

-* `ContainerName`

-* `PodName`

-* `PodNamespace`

-## ContainerLogV2 schema

-```kusto

- Computer: string,

- ContainerId: string,

- ContainerName: string,

- PodName: string,

- PodNamespace: string,

- LogMessage: dynamic,

- LogSource: string,

- TimeGenerated: datetime

-```

->[!NOTE]

-> [Export](../logs/logs-data-export.md) to Event Hub and Storage Account is not supported if the incoming LogMessage is not a valid JSON. For best performance, we recommend emitting container logs in JSON format.

-## Enable the ContainerLogV2 schema

-Customers can enable the ContainerLogV2 schema at the cluster level through either the cluster's Data Collection Rule (DCR) or ConfigMap. To enable the ContainerLogV2 schema, configure the cluster's ConfigMap. Learn more about ConfigMap in [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) and in [Azure Monitor documentation](./container-insights-agent-config.md#configmap-file-settings-overview).

-Follow the instructions to configure an existing ConfigMap or to use a new one.

->[!NOTE]

-> Because ContainerLogV2 can be enabled through either the DCR and ConfigMap, when both are enabled the ContainerLogV2 setting of the ConfigMap will take precedence. Stdout and stderr logs will only be ingested to the ContainerLog table when both the DCR and ConfigMap are explicitly set to off.

-### Configure via an existing Data Collection Rule (DCR)

-## [Azure portal](#tab/configure-portal)

->[!NOTE]

-> DCR based configuration is not supported for service principal based clusters. Please [migrate your clusters with service principal to managed identity](./container-insights-authentication.md) to use this experience.

-1. In the Insights section of your Kubernetes cluster, select the **Monitoring Settings** button from the top toolbar

-2. Select **Edit collection settings** to open the advanced settings

-3. Select the checkbox with **Enable ContainerLogV2** and choose the **Save** button below

-4. The summary section should display the message "ContainerLogV2 enabled", click the **Configure** button to complete your configuration change

-## [CLI](#tab/configure-CLI)

-1. For configuring via CLI, use the corresponding [config file](./container-insights-cost-config.md#enable-cost-settings), update the `enableContainerLogV2` field in the config file to be true.

-

-### Configure an existing ConfigMap

-This applies to the scenario where you have already enabled container insights for your AKS cluster and have [configured agent data collection settings](./container-insights-agent-config.md#configure-and-deploy-configmaps) using ConfigMap "_container-azm-ms-agentconfig.yaml_". If this ConfigMap doesn't yet have the `log_collection_settings.schema` field, you'll need to append the following section in this existing ConfigMap .yaml file:

-```yaml

-[log_collection_settings.schema]

- # In the absence of this ConfigMap, the default value for containerlog_schema_version is "v1"

- # Supported values for this setting are "v1","v2"

- # See documentation at https://aka.ms/ContainerLogv2 for benefits of v2 schema over v1 schema before opting for "v2" schema

- containerlog_schema_version = "v2"

-```

-### Configure a new ConfigMap

-1. [Download the new ConfigMap](https://aka.ms/container-azm-ms-agentconfig). For the newly downloaded ConfigMap, the default value for `containerlog_schema_version` is `"v2"`.

-1. Ensure that the `containerlog_schema_version` to `"v2"` and the `[log_collection_settings.schema]` is also uncommented by removing the `#` preceding it:

- ```yaml

- [log_collection_settings.schema]

- # In the absence of this ConfigMap, the default value for containerlog_schema_version is "v1"

- # Supported values for this setting are "v1","v2"

- # See documentation at https://aka.ms/ContainerLogv2 for benefits of v2 schema over v1 schema before opting for "v2" schema

- containerlog_schema_version = "v2"

- ```

-3. After you finish configuring the ConfigMap, run the following kubectl command: `kubectl apply -f <configname>`.

- Example: `kubectl apply -f container-azm-ms-agentconfig.yaml`

->[!NOTE]

->* The configuration change can take a few minutes to complete before it takes effect. All ama-logs pods in the cluster will restart.

->* The restart is a rolling restart for all ama-logs pods. It won't restart all of them at the same time.

-## Multi-line logging in Container Insights

-Azure Monitor container insights now supports multiline logging. With this feature enabled, previously split container logs are stitched together and sent as single entries to the ContainerLogV2 table. Customers are able see container log lines upto to 64 KB (up from the existing 16 KB limit). If the stitched log line is larger than 64 KB, it gets truncated due to Log Analytics limits.

-Additionally, the feature also adds support for .NET, Go, Python and Java stack traces, which appear as single entries instead of being split into multiple entries in ContainerLogV2 table.

-Below are two screenshots which demonstrate Multi-line logging at work for Go exception stack trace:

-Multi-line logging disabled scenario:

-<!-- convertborder later -->

-Multi-line logging enabled scenario:

-<!-- convertborder later -->

-Similarly, below screenshots depict Multi-line logging enabled scenarios for Java and Python stack traces:

-For Java:

-For Python:

-### Pre-requisites

-Customers must [enable ContainerLogV2](./container-insights-logging-v2.md#enable-the-containerlogv2-schema) for multi-line logging to work.

-### How to enable

-Multi-line logging feature can be enabled by setting **enabled** flag to "true" under the `[log_collection_settings.enable_multiline_logs]` section in the [config map](https://github.com/microsoft/Docker-Provider/blob/ci_prod/kubernetes/container-azm-ms-agentconfig.yaml)

-```yaml

-[log_collection_settings.enable_multiline_logs]

-# fluent-bit based multiline log collection for go (stacktrace), dotnet (stacktrace)

-# if enabled will also stitch together container logs split by docker/cri due to size limits(16KB per log line)

- enabled = "true"

-```

-## Next steps

-* Configure [Basic Logs](../logs/basic-logs-configure.md) for ContainerLogv2.

-* Learn how [query data](./container-insights-log-query.md#container-logs) from ContainerLogV2

-description: This article describes how to manage the most common maintenance tasks with the containerized Log Analytics agent used by Container insights.

->[!NOTE]

->The Container Insights agent name has changed from OMSAgent to Azure Monitor Agent, along with a few other resource names. This article reflects the new name. Update your commands, alerts, and scripts that reference the old name. Read more about the name change in [our blog post](https://techcommunity.microsoft.com/t5/azure-monitor-status-archive/name-update-for-agent-and-associated-resources-in-azure-monitor/ba-p/3576810).

->

-The process to upgrade the agent on an AKS cluster consists of two steps. The first step is to disable monitoring with Container insights by using the Azure CLI. Follow the steps described in the [Disable monitoring](container-insights-optout.md?#azure-cli) article. By using the Azure CLI, you can remove the agent from the nodes in the cluster without affecting the solution and the corresponding data that's stored in the workspace.

-Container Insights has shifted the image version and naming convention to [semver format] (https://semver.org/). SemVer helps developers keep track of every change made to a software during its development phase and ensures that the software versioning is consistent and meaningful. The old version was in format of ciprod\<timestamp\>-\<commitId\> and win-ciprod\<timestamp\>-\<commitId\>, our first image versions using the Semver format are 3.1.4 for Linux and win-3.1.4 for Windows.

-Customers who manually enable Container Insights using custom methods prior to October 2022 can end up with multiple versions of our agent running together. To clear this duplication, customers are recommended to follow the steps below:

-### Migration guidelines for AKS clusters

-1. Get details of customer's custom settings, such as memory and CPU limits on omsagent containers.

-2. Review Resource Limits:

-Current ama-logs default limit are below

-| OS | Controller Name | Default Limits |

-||||

-| Linux | ds-cpu-limit-linux | 500m |

-| Linux | ds-memory-limit-linux | 750Mi |

-| Linux | rs-cpu-limit | 1 |

-| Linux | rs-memory-limit | 1.5Gi |

-| Windows | ds-cpu-limit-windows | 500m |

-| Windows | ds-memory-limit-windows | 1Gi |

-Validate whether the current default settings and limits meet the customer's needs. And if not, create support tickets under containerinsights agent to help investigate and toggle memory/cpu limits for the customer. Through doing this, it can help address the scale limitations issues that some customers encountered previously that resulted in OOMKilled exceptions.

-3. Fetch current Azure analytic workspace ID since we're going to re-onboard the container insights.

-```console

-az aks show -g $resourceGroupNameofCluster -n $nameofTheCluster | grep logAnalyticsWorkspaceResourceID`

-```

-**For customers that previously onboarded to containerinsights through helm chart** :

-ΓÇó List all releases across namespaces with command:

-```console

- helm list --all-namespaces

-```

-ΓÇó Clean the chart installed for containerinsights (or azure-monitor-containers) with command:

-```console

-helm uninstall <releaseName> --namespace <Namespace>

-```

-

-**For customers that previously onboarded to containerinsights through yaml deployment** :

-ΓÇó Download previous custom deployment yaml file:

-```console

-curl -LO raw.githubusercontent.com/microsoft/Docker-Provider/ci_dev/kubernetes/omsagent.yaml

-```

-ΓÇó Clean the old omsagent chart:

-```console

-kubectl delete -f omsagent.yaml

-```

-5. Disable container insights to clean all related resources with aks command: [Disable Container insights on your Azure Kubernetes Service (AKS) cluster - Azure Monitor | Microsoft Learn](https://learn.microsoft.com/azure/azure-monitor/containers/container-insights-optout)

-```console

-az aks disable-addons -a monitoring -n MyExistingManagedCluster -g MyExistingManagedClusterRG

-```

-6. Re-onboard to containerinsights with the workspace fetched from step 3 using [the steps outlined here](https://learn.microsoft.com/azure/azure-monitor/containers/container-insights-enable-aks?tabs=azure-cli#specify-a-log-analytics-workspace)

-# Metric alert rules in Container insights (preview)

-description: This article describes how to enable and configure Container insights so that you can understand how your container is performing and what performance-related issues have been identified.

-# Enable Container insights

-This article provides an overview of the requirements and options that are available for enabling [Container insights](../containers/container-insights-overview.md) on your Kubernetes clusters. You can enable Container insights for a new deployment or for one or more existing deployments of Kubernetes by using several supported methods.

-## Supported configurations

-Container insights supports the following environments:

- - AKS on Azure Stack HCI

- - AKS Edge Essentials

- - Canonical

- - Cluster API Provider on Azure

- - K8s on Azure Stack Edge

- - Red Hat OpenShift version 4.x

- - SUSE Rancher (Rancher Kubernetes engine)

- - SUSE Rancher K3s

- - VMware (ie. TKG)

-> [!NOTE]

-> Container insights supports ARM64 nodes on AKS. See [Cluster requirements](../../azure-arc/kubernetes/system-requirements.md#cluster-requirements) for the details of Azure Arc-enabled clusters that support ARM64 nodes.

-## Prerequisites

- - To enable Container insights, you require must have at least [Contributor](../../role-based-access-control/built-in-roles.md#contributor) access to the AKS cluster.

- - To view data after container monitoring is enabled, you must have [Monitoring Reader](../roles-permissions-security.md#monitoring-reader) or [Monitoring Contributor](../roles-permissions-security.md#monitoring-contributor) role.

-## Authentication

-Container insights uses managed identity authentication. This authentication model has a monitoring agent that uses the cluster's managed identity to send data to Azure Monitor. Read more in [Authentication for Container Insights](container-insights-authentication.md) including guidance on migrating from legacy authentication models.

-> [!Note]

-> [ContainerLogV2](container-insights-logging-v2.md) is the default schema when you onboard Container insights with using ARM, Bicep, Terraform, Policy and Portal onboarding. ContainerLogV2 can be explicitly enabled through CLI version 2.51.0 or higher using Data collection settings.

-## Agent

-Container insights relies on a containerized [Azure Monitor agent](../agents/agents-overview.md) for Linux. This specialized agent collects performance and event data from all nodes in the cluster and sends it to a Log Analytics workspace. The agent is automatically deployed and registered with the specified Log Analytics workspace during deployment.

-### Data collection rule

-[Data collection rules (DCR)](../essentials/data-collection-rule-overview.md) contain the definition of data that should be collected by Azure Monitor agent. When you enable Container insights on a cluster, a DCR is created with the name *MSCI-\<cluster-region\>-<\cluster-name\>*. Currently, this name can't be modified.

-Since March 1, 2023 Container insights uses a semver compliant agent version. The agent version is *mcr.microsoft.com/azuremonitor/containerinsights/ciprod:3.1.4* or later. It's represented by the format mcr.microsoft.com/azuremonitor/containerinsights/ciprod:\<semver compatible version\>. When a new version of the agent is released, it's automatically upgraded on your managed Kubernetes clusters that are hosted on AKS. To track which versions are released, see [Agent release announcements](https://github.com/microsoft/Docker-Provider/blob/ci_prod/ReleaseNotes.md).

-> [!NOTE]

-> Ingestion Transformations are not currently supported with the [Container insights DCR](../essentials/data-collection-transformations.md).

-### Log Analytics agent

-When Container insights doesn't use managed identity authentication, it relies on a containerized [Log Analytics agent for Linux](../agents/log-analytics-agent.md). The agent version is *microsoft/oms:ciprod04202018* or later. It's represented by a date in the following format: *mmddyyyy*. When a new version of the agent is released, it's automatically upgraded on your managed Kubernetes clusters that are hosted on AKS. To track which versions are released, see [Agent release announcements](https://github.com/microsoft/docker-provider/tree/ci_feature_prod).

-With the general availability of Windows Server support for AKS, an AKS cluster with Windows Server nodes has a preview agent installed as a daemon set pod on each individual Windows Server node to collect logs and forward them to Log Analytics. For performance metrics, a Linux node that's automatically deployed in the cluster as part of the standard deployment collects and forwards the data to Azure Monitor for all Windows nodes in the cluster.

-> [!NOTE]

-> If you've already deployed an AKS cluster and enabled monitoring by using either the Azure CLI or a Resource Manager template, you can't use `kubectl` to upgrade, delete, redeploy, or deploy the agent. The template needs to be deployed in the same resource group as the cluster.

-## Differences between Windows and Linux clusters

-The main differences in monitoring a Windows Server cluster compared to a Linux cluster include:

->[!NOTE]

-> Container insights support for the Windows Server 2022 operating system is in preview.

-The containerized Linux agent (replicaset pod) makes API calls to all the Windows nodes on Kubelet secure port (10250) within the cluster to collect node and container performance-related metrics. Kubelet secure port (:10250) should be opened in the cluster's virtual network for both inbound and outbound for Windows node and container performance-related metrics collection to work.

-If you have a Kubernetes cluster with Windows nodes, review and configure the network security group and network policies to make sure the Kubelet secure port (:10250) is open for both inbound and outbound in the cluster's virtual network.

-## Network firewall requirements

-The following table lists the proxy and firewall configuration information required for the containerized agent to communicate with Container insights. All network traffic from the agent is outbound to Azure Monitor.

-**Azure public cloud**

-| Endpoint |Port |

-|--||

-| `*.ods.opinsights.azure.com` | 443 |

-| `*.oms.opinsights.azure.com` | 443 |

-| `dc.services.visualstudio.com` | 443 |

-| `*.monitoring.azure.com` | 443 |

-| `login.microsoftonline.com` | 443 |

-The following table lists the extra firewall configuration required for managed identity authentication.

-|Agent resource| Purpose | Port |

-|--|||

-| `global.handler.control.monitor.azure.com` | Access control service | 443 |

-| `<cluster-region-name>.ingest.monitor.azure.com` | Azure monitor managed service for Prometheus - metrics ingestion endpoint (DCE) | 443 |

-| `<cluster-region-name>.handler.control.monitor.azure.com` | Fetch data collection rules for specific AKS cluster | 443 |

-**Microsoft Azure operated by 21Vianet cloud**

-The following table lists the proxy and firewall configuration information for Azure operated by 21Vianet.

-|Agent resource| Purpose | Port |

-|--||-|

-| `*.ods.opinsights.azure.cn` | Data ingestion | 443 |

-| `*.oms.opinsights.azure.cn` | OMS onboarding | 443 |

-| `dc.services.visualstudio.com` | For agent telemetry that uses Azure Public Cloud Application Insights | 443 |

-The following table lists the extra firewall configuration required for managed identity authentication.

-|Agent resource| Purpose | Port |

-|--|||

-| `global.handler.control.monitor.azure.cn` | Access control service | 443 |

-| `<cluster-region-name>.handler.control.monitor.azure.cn` | Fetch data collection rules for specific AKS cluster | 443 |

-**Azure Government cloud**

-The following table lists the proxy and firewall configuration information for Azure US Government.

-| Endpoint | Purpose | Port |

-|--||-|

-| `*.ods.opinsights.azure.us` | Data ingestion | 443 |

-| `*.oms.opinsights.azure.us` | OMS onboarding | 443 |

-| `dc.services.visualstudio.com` | For agent telemetry that uses Azure Public Cloud Application Insights | 443 |

-The following table lists the extra firewall configuration required for managed identity authentication.

-|Agent resource| Purpose | Port |

-|--|||

-| `global.handler.control.monitor.azure.us` | Access control service | 443 |

-| `<cluster-region-name>.handler.control.monitor.azure.us` | Fetch data collection rules for specific AKS cluster | 443 |

-## Troubleshooting

-If you registered your cluster and/or configured HCI Insights before November 2023, features that use the AMA agent on HCI, such as Arc for Servers Insights, VM Insights, Container Insights, Defender for Cloud or Sentinel might not be collecting logs and event data properly. See [Repair AMA agent for HCI](/azure-stack/hci/manage/monitor-hci-single?tabs=22h2-and-later) for steps to reconfigure the AMA agent and HCI Insights.

-## Next steps

-After you've enabled monitoring, you can begin analyzing the performance of your Kubernetes clusters that are hosted on AKS, Azure Stack, or another environment.

-To learn how to use Container insights, see [View Kubernetes cluster performance](container-insights-analyze.md).

-description: This article describes how you can stop monitoring of your hybrid Kubernetes cluster with Container insights.

-# Disable Container insights on your hybrid Kubernetes cluster

-This article shows how to disable Container insights for the following Kubernetes environments:

-## How to stop monitoring using Helm

-The following steps apply to the following environments:

-1. To first identify the Container insights helm chart release installed on your cluster, run the following helm command.

- ```

- helm list

- ```

- The output resembles the following:

- ```

- NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION

- azmon-containers-release-1 default 3 2020-04-21 15:27:24.1201959 -0700 PDT deployed azuremonitor-containers-2.7.0 7.0.0-1

- ```

- *azmon-containers-release-1* represents the helm chart release for Container insights.

-2. To delete the chart release, run the following helm command.

- `helm delete <releaseName>`

- Example:

- `helm delete azmon-containers-release-1`

- This removes the release from the cluster. You can verify by running the `helm list` command:

- ```

- NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION

- ```

-The configuration change can take a few minutes to complete. Because Helm tracks your releases even after youΓÇÖve deleted them, you can audit a clusterΓÇÖs history, and even undelete a release with `helm rollback`.

-## How to stop monitoring on Azure Arc-enabled Kubernetes

-### Using PowerShell

-1. Download and save the script to a local folder that configures your cluster with the monitoring add-on using the following commands:

- ```powershell

- wget https://aka.ms/disable-monitoring-powershell-script -OutFile disable-monitoring.ps1

- ```

-2. Configure the `$azureArcClusterResourceId` variable by setting the corresponding values for `subscriptionId`, `resourceGroupName` and `clusterName` representing the resource ID of your Azure Arc-enabled Kubernetes cluster resource.

- ```powershell

- $azureArcClusterResourceId = "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Kubernetes/connectedClusters/<clusterName>"

- ```

-3. Configure the `$kubeContext` variable with the **kube-context** of your cluster by running the command `kubectl config get-contexts`. If you want to use the current context, set the value to `""`.

- ```powershell

- $kubeContext = "<kubeContext name of your k8s cluster>"

- ```

-4. Run the following command to stop monitoring the cluster.

- ```powershell

- .\disable-monitoring.ps1 -clusterResourceId $azureArcClusterResourceId -kubeContext $kubeContext

- ```

-#### Using service principal

-The script *disable-monitoring.ps1* uses the interactive device login. If you prefer non-interactive login, you can use an existing service principal or create a new one that has the required permissions as described in [Prerequisites](container-insights-enable-arc-enabled-clusters.md#prerequisites). To use service principal, you have to pass $servicePrincipalClientId, $servicePrincipalClientSecret and $tenantId parameters with values of service principal you have intended to use to enable-monitoring.ps1 script.

-```powershell

-$subscriptionId = "<subscription Id of the Azure Arc-connected cluster resource>"

-$servicePrincipal = New-AzADServicePrincipal -Role Contributor -Scope "/subscriptions/$subscriptionId"

-$servicePrincipalClientId = $servicePrincipal.ApplicationId.ToString()

-$servicePrincipalClientSecret = [System.Net.NetworkCredential]::new("", $servicePrincipal.Secret).Password

-$tenantId = (Get-AzSubscription -SubscriptionId $subscriptionId).TenantId

-```

-For example:

-```powershell

-\disable-monitoring.ps1 -clusterResourceId $azureArcClusterResourceId -kubeContext $kubeContext -servicePrincipalClientId $servicePrincipalClientId -servicePrincipalClientSecret $servicePrincipalClientSecret -tenantId $tenantId

-```

-### Using bash

-1. Download and save the script to a local folder that configures your cluster with the monitoring add-on using the following commands:

- ```bash

- curl -o disable-monitoring.sh -L https://aka.ms/disable-monitoring-bash-script

- ```

-2. Configure the `azureArcClusterResourceId` variable by setting the corresponding values for `subscriptionId`, `resourceGroupName` and `clusterName` representing the resource ID of your Azure Arc-enabled Kubernetes cluster resource.

- ```bash

- export AZUREARCCLUSTERRESOURCEID="/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Kubernetes/connectedClusters/<clusterName>"

- ```

-3. Configure the `kubeContext` variable with the **kube-context** of your cluster by running the command `kubectl config get-contexts`.

- ```bash

- export KUBECONTEXT="<kubeContext name of your k8s cluster>"

- ```

-4. To stop monitoring your cluster, there are different commands provided based on your deployment scenario.

- Run the following command to stop monitoring the cluster using the current context.

- ```bash

- bash disable-monitoring.sh --resource-id $AZUREARCCLUSTERRESOURCEID

- ```

- Run the following command to stop monitoring the cluster by specifying a context

- ```bash

- bash disable-monitoring.sh --resource-id $AZUREARCCLUSTERRESOURCEID --kube-context $KUBECONTEXT

- ```

-#### Using service principal

-The bash script *disable-monitoring.sh* uses the interactive device login. If you prefer non-interactive login, you can use an existing service principal or create a new one that has the required permissions as described in [Prerequisites](container-insights-enable-arc-enabled-clusters.md#prerequisites). To use service principal, you have to pass --client-id, --client-secret and --tenant-id values of service principal you have intended to use to *enable-monitoring.sh* bash script.

-```bash

-SUBSCRIPTIONID="<subscription Id of the Azure Arc-connected cluster resource>"

-SERVICEPRINCIPAL=$(az ad sp create-for-rbac --role="Contributor" --scopes="/subscriptions/${SUBSCRIPTIONID}")

-SERVICEPRINCIPALCLIENTID=$(echo $SERVICEPRINCIPAL | jq -r '.appId')

-SERVICEPRINCIPALCLIENTSECRET=$(echo $SERVICEPRINCIPAL | jq -r '.password')

-TENANTID=$(echo $SERVICEPRINCIPAL | jq -r '.tenant')

-```

-For example:

-```bash

-bash disable-monitoring.sh --resource-id $AZUREARCCLUSTERRESOURCEID --kube-context $KUBECONTEXT --client-id $SERVICEPRINCIPALCLIENTID --client-secret $SERVICEPRINCIPALCLIENTSECRET --tenant-id $TENANTID

-```

-## Next steps

-If the Log Analytics workspace was created only to support monitoring the cluster and it's no longer needed, you have to manually delete it. If you are not familiar with how to delete a workspace, see [Delete an Azure Log Analytics workspace](../logs/delete-workspace.md).

-description: This article describes how you can discontinue monitoring of your Azure AKS cluster with Container insights.

-# Disable Container insights on your Azure Kubernetes Service (AKS) cluster

-After you enable monitoring of your Azure Kubernetes Service (AKS) cluster, you can stop monitoring the cluster if you decide you no longer want to monitor it. This article shows you how to do this task by using the Azure CLI or the provided Azure Resource Manager templates (ARM templates).

-## Azure CLI

-Use the [az aks disable-addons](/cli/azure/aks#az-aks-disable-addons) command to disable Container insights. The command removes the agent from the cluster nodes. It doesn't remove the solution or the data already collected and stored in your Azure Monitor resource.

-```azurecli

-az aks disable-addons -a monitoring -n MyExistingManagedCluster -g MyExistingManagedClusterRG

-```

-To reenable monitoring for your cluster, see [Enable monitoring by using the Azure CLI](container-insights-enable-new-cluster.md#enable-using-azure-cli).

-## Azure Resource Manager template

-Two ARM templates are provided to support removing the solution resources consistently and repeatedly in your resource group. One is a JSON template that specifies the configuration to stop monitoring. The other template contains parameter values that you configure to specify the AKS cluster resource ID and resource group in which the cluster is deployed.

-If you're unfamiliar with the concept of deploying resources by using a template, see:

-* [Deploy resources with ARM templates and Azure PowerShell](../../azure-resource-manager/templates/deploy-powershell.md)

-* [Deploy resources with ARM templates and the Azure CLI](../../azure-resource-manager/templates/deploy-cli.md)

->[!NOTE]

->The template must be deployed in the same resource group of the cluster. If you omit any other properties or add-ons when you use this template, they might be removed from the cluster. Examples are `enableRBAC` for Kubernetes RBAC policies implemented in your cluster, or `aksResourceTagValues`, if tags are specified for the AKS cluster.

->

-If you choose to use the Azure CLI, you must install and use the CLI locally. You must be running the Azure CLI version 2.0.27 or later. To identify your version, run `az --version`. If you need to install or upgrade the Azure CLI, see [Install the Azure CLI](/cli/azure/install-azure-cli).

-### Create a template

-1. Copy and paste the following JSON syntax into your file:

- ```json

- {

- "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",

- "contentVersion": "1.0.0.0",

- "parameters": {

- "aksResourceId": {

- "type": "string",

- "metadata": {

- "description": "AKS Cluster Resource ID"

- }

- },

- "aksResourceLocation": {

- "type": "string",

- "metadata": {

- "description": "Location of the AKS resource e.g. \"East US\""

- }

- },

- "aksResourceTagValues": {

- "type": "object",

- "metadata": {

- "description": "Existing all tags on AKS Cluster Resource"

- }

- }

- },

- "resources": [

- {

- "name": "[split(parameters('aksResourceId'),'/')[8]]",

- "type": "Microsoft.ContainerService/managedClusters",

- "location": "[parameters('aksResourceLocation')]",

- "tags": "[parameters('aksResourceTagValues')]",

- "apiVersion": "2018-03-31",

- "properties": {

- "mode": "Incremental",

- "id": "[parameters('aksResourceId')]",

- "addonProfiles": {

- "omsagent": {

- "enabled": false,

- "config": null

- }

- }

- }

- }

- ]

- }

- ```

-1. Save this file as **OptOutTemplate.json** to a local folder.

-1. Paste the following JSON syntax into your file:

- ```json

- {

- "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",

- "contentVersion": "1.0.0.0",

- "parameters": {

- "aksResourceId": {

- "value": "/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroup>/providers/Microsoft.ContainerService/managedClusters/<ResourceName>"

- },

- "aksResourceLocation": {

- "value": "<aksClusterRegion>"

- },

- "aksResourceTagValues": {

- "value": {

- "<existing-tag-name1>": "<existing-tag-value1>",

- "<existing-tag-name2>": "<existing-tag-value2>",

- "<existing-tag-nameN>": "<existing-tag-valueN>"

- }

- }

- }

- }

- ```

-1. Edit the values for **aksResourceId** and **aksResourceLocation** by using the values of the AKS cluster, which you can find on the **Properties** page for the selected cluster.

- <!-- convertborder later -->

- :::image type="content" source="media/container-insights-optout/container-properties-page.png" lightbox="media/container-insights-optout/container-properties-page.png" alt-text="Screenshot that shows the Container properties page." border="false":::

- While you're on the **Properties** page, also copy the **Workspace Resource ID**. This value is required if you decide you want to delete the Log Analytics workspace later. Deleting the Log Analytics workspace isn't performed as part of this process.

- Edit the values for **aksResourceTagValues** to match the existing tag values specified for the AKS cluster.

-1. Save this file as **OptOutParam.json** to a local folder.

-Now you're ready to deploy this template.

-### Remove the solution by using the Azure CLI

-To remove the solution and clean up the configuration on your AKS cluster, run the following command with the Azure CLI on Linux:

-```azurecli

-az login

-az account set --subscription "Subscription Name"

-az deployment group create --resource-group <ResourceGroupName> --template-file ./OptOutTemplate.json --parameters ./OptOutParam.json

-```

-The configuration change can take a few minutes to finish. The result is returned in a message similar to the following example:

-```output

-ProvisioningState : Succeeded

-```

-### Remove the solution by using PowerShell

-To remove the solution and clean up the configuration from your AKS cluster, run the following PowerShell commands in the folder that contains the template:

-```powershell

-Connect-AzAccount

-Select-AzSubscription -SubscriptionName <yourSubscriptionName>

-New-AzResourceGroupDeployment -Name opt-out -ResourceGroupName <ResourceGroupName> -TemplateFile .\OptOutTemplate.json -TemplateParameterFile .\OptOutParam.json

-```

-The configuration change can take a few minutes to finish. The result is returned in a message similar to the following example:

-```output

-ProvisioningState : Succeeded

-```

-## Next steps

-If the workspace was created only to support monitoring the cluster and it's no longer needed, you must delete it manually. If you aren't familiar with how to delete a workspace, see [Delete an Azure Log Analytics workspace with the Azure portal](../logs/delete-workspace.md). Don't forget about the **Workspace Resource ID** copied earlier in step 4. You'll need that information.

-# Container insights overview

-Container insights is a feature of Azure Monitor that monitors the performance and health of container workloads deployed to [Azure](../../aks/intro-kubernetes.md) or that are managed by [Azure Arc-enabled Kubernetes](../../azure-arc/kubernetes/overview.md). It collects memory and processor metrics from controllers, nodes, and containers in addition to gathering container logs. You can analyze the collected data for the different components in your cluster with a collection of [views](container-insights-analyze.md) and pre-built [workbooks](container-insights-reports.md).

-The following video provides an intermediate-level deep dive to help you learn about monitoring your AKS cluster with Container insights. The video refers to *Azure Monitor for Containers*, which is the previous name for *Container insights*.

-> [!VIDEO https://www.youtube.com/embed/XEdwGvS2AwA]

-## Features of Container insights

-Container insights includes the following features to provide to understand the performance and health of your Kubernetes cluster and container workloads:

-Access Container insights in the Azure portal from **Containers** in the **Monitor** menu or directly from the selected AKS cluster by selecting **Insights**. The Azure Monitor menu gives you the global perspective of all the containers that are deployed and monitored. This information allows you to search and filter across your subscriptions and resource groups. You can then drill into Container insights from the selected container. Access Container insights for a particular AKS container directly from the AKS page.

-Container insights sends data to [Logs](../logs/data-platform-logs.md) and [Metrics](../essentials/data-platform-metrics.md) where you can analyze it using different features of Azure Monitor. It works with other Azure services such as [Azure Monitor managed service for Prometheus](../essentials/prometheus-metrics-overview.md) and [Managed Grafana](../../managed-grafan#monitoring-data).

-Container insights supports the following configurations:

-Container insights supports clusters running the Linux and Windows Server 2019 operating system. The container runtimes it supports are Moby and any CRI-compatible runtime such as CRI-O and ContainerD. Docker is no longer supported as a container runtime as of September 2022. For more information about this deprecation, see the [AKS release notes][aks-release-notes].

-### Is there support for collecting Kubernetes audit logs for ARO clusters?

-### Does Container Insights support pod sandboxing?

-Yes, Container Insights supports pod sandboxing through support for Kata Containers. For more details on pod sandboxing in AKS, [refer to the AKS docs](/azure/aks/use-pod-sandboxing).

-To learn more about how to configure collected PV metrics, see [Configure agent data collection for Container insights](./container-insights-agent-config.md).

-To learn more about collected PV metrics, see [Configure agent data collection for Container insights](./container-insights-agent-config.md).

-| Error message "Error retrieving data" | While an AKS cluster is setting up for health and performance monitoring, a connection is established between the cluster and a Log Analytics workspace. A Log Analytics workspace is used to store all monitoring data for your cluster. This error might occur when your Log Analytics workspace has been deleted. Check if the workspace was deleted. If it was, reenable monitoring of your cluster with Container insights. Then specify an existing workspace or create a new one. To reenable, [disable](container-insights-optout.md) monitoring for the cluster and [enable](container-insights-enable-new-cluster.md) Container insights again. |

-If the first option isn't convenient because of query changes involved, you can reenable collecting these fields. Enable the setting `log_collection_settings.enrich_container_logs` in the agent config map as described in the [data collection configuration settings](./container-insights-agent-config.md).

-description: This article describes the transition plan from the ContainerLog to ContainerLogV2 table

-# Migrate from ContainerLog to ContainerLogV2

-With the upgraded offering of ContainerLogV2 becoming generally available, on 30th September 2026, the ContainerLog table will be retired. If you currently ingest container insights data to the ContainerLog table, transition to using ContainerLogV2 prior to that date.

->[!NOTE]

-> Support for ingesting the ContainerLog table will be **retired on 30th September 2026**.

-## Steps to complete the transition

-To transition to ContainerLogV2, we recommend the following approach.

-1. Learn about the feature differences between ContainerLog and ContainerLogV2

-2. Assess the impact migrating to ContainerLogV2 might have on your existing queries, alerts, or dashboards

-3. [Enable the ContainerLogV2 schema](container-insights-logging-v2.md) through either the container insights data collection rules (DCRs) or ConfigMap

-4. Validate that you're now ingesting ContainerLogV2 to your Log Analytics workspace.

-## ContainerLog vs ContainerLogV2 schema

-The following table highlights the key differences between using ContainerLog and ContainerLogV2 schema.

->[!NOTE]

-> DCR based configuration is not supported for service principal based clusters. [Migrate your clusters with service principal to managed identity](./container-insights-authentication.md) to use this experience.

-| Feature differences | ContainerLog | ContainerLogV2 |

-| - | -- | - |

-| Onboarding | Only configurable through the ConfigMap | Configurable through both the ConfigMap and DCR\* |

-| Pricing | Only compatible with full-priced analytics logs | Supports the low cost basic logs tier in addition to analytics logs |

-| Querying | Requires multiple join operations with inventory tables for standard queries | Includes additional pod and container metadata to reduce query complexity and join operations |

-| Multiline | Not supported, multiline entries are split into multiple rows | Support for multiline logging to allow consolidated, single entries for multiline output |

-\* DCR enablement is not supported for service principal based clusters, must be enabled through the ConfigMap

-## Assess the impact on existing alerts

-If you're currently using ContainerLog in your alerts, then migrating to ContainerLogV2 requires updates to your alert queries for them to continue functioning as expected.

-To scan for alerts that might be referencing the ContainerLog table, run the following Azure Resource Graph query:

-```Kusto

-resources

-| where type in~ ('microsoft.insights/scheduledqueryrules') and ['kind'] !in~ ('LogToMetric')

-| extend severity = strcat("Sev", properties["severity"])

-| extend enabled = tobool(properties["enabled"])

-| where enabled in~ ('true')

-| where tolower(properties["targetResourceTypes"]) matches regex 'microsoft.operationalinsights/workspaces($|/.*)?' or tolower(properties["targetResourceType"]) matches regex 'microsoft.operationalinsights/workspaces($|/.*)?' or tolower(properties["scopes"]) matches regex 'providers/microsoft.operationalinsights/workspaces($|/.*)?'

-| where properties contains "ContainerLog"

-| project id,name,type,properties,enabled,severity,subscriptionId

-| order by tolower(name) asc

-```

-## Next steps

-description: Disable the collection of Prometheus metrics from an Azure Kubernetes Service cluster and remove the agent from the cluster nodes.

-# Disable Prometheus metrics collection from an AKS cluster

-Currently, the Azure CLI is the only option to remove the metrics add-on from your AKS cluster, and stop sending Prometheus metrics to Azure Monitor managed service for Prometheus.

-The `az aks update --disable-azure-monitor-metrics` command:

-+ Removes the ama-metrics agent from the cluster nodes.

-+ Deletes the recording rules created for that cluster.

-+ Deletes the data collection endpoint (DCE).

-+ Deletes the data collection rule (DCR).

-+ Deletes the DCRA and recording rules groups created as part of onboarding.

-> [!NOTE]

-> This action doesn't remove any existing data stored in your Azure Monitor workspace.

-```azurecli

-az aks update --disable-azure-monitor-metrics -n <cluster-name> -g <cluster-resource-group>

-```

-## Next steps

-description: Enable Azure Monitor managed service for Prometheus and configure data collection from your Azure Kubernetes Service (AKS) cluster.

-# Collect Prometheus metrics from an AKS cluster

-This article describes how to configure your Azure Kubernetes Service (AKS) cluster to send data to Azure Monitor managed service for Prometheus. When you perform this configuration, a containerized version of the [Azure Monitor agent](../agents/agents-overview.md) is installed with a metrics extension. This sends data to the Azure Monitor workspace that you specify.

-> [!NOTE]

-> The process described here doesn't enable [Container insights](../containers/container-insights-overview.md) on the cluster. However, both processes use the Azure Monitor agent. For different methods to enable Container insights on your cluster, see [Enable Container insights](../containers/container-insights-onboard.md)..

-The Azure Monitor metrics agent's architecture utilizes a ReplicaSet and a DaemonSet. The ReplicaSet pod scrapes cluster-wide targets such as `kube-state-metrics` and custom application targets that are specified. The DaemonSet pods scrape targets solely on the node that the respective pod is deployed on, such as `node-exporter`. This is so that the agent can scale as the number of nodes and pods on a cluster increases.

-## Prerequisites

- - Microsoft.ContainerService

- - Microsoft.Insights

- - Microsoft.AlertsManagement

-> [!NOTE]

-> `Contributor` permission is enough for enabling the addon to send data to the Azure Monitor workspace. You will need `Owner` level permission in case you're trying to link your Azure Monitor Workspace to view metrics in Azure Managed Grafana. This is required because the user executing the onboarding step, needs to be able to give the Azure Managed Grafana System Identity `Monitoring Reader` role on the Azure Monitor Workspace to query the metrics.

-## Enable Prometheus metric collection

-Use any of the following methods to install the Azure Monitor agent on your AKS cluster and send Prometheus metrics to your Azure Monitor workspace.

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

-There are multiple options to enable Prometheus metrics on your cluster from the Azure portal.

-#### New cluster

-When you create a new AKS cluster in the Azure portal, you can enable Prometheus, Container insights, and Grafana from the **Integrations** tab.

-#### From the Azure Monitor workspace

-This option enables Prometheus metrics on a cluster without enabling Container insights.

-1. Open the **Azure Monitor workspaces** menu in the Azure portal and select your workspace.

-1. Select **Monitored clusters** in the **Managed Prometheus** section to display a list of AKS clusters.

-1. Select **Configure** next to the cluster you want to enable.

- :::image type="content" source="media/prometheus-metrics-enable/azure-monitor-workspace-configure-prometheus.png" lightbox="media/prometheus-metrics-enable/azure-monitor-workspace-configure-prometheus.png" alt-text="Screenshot that shows an Azure Monitor workspace with a Prometheus configuration.":::

-#### From an existing cluster monitored with Container insights

-This option adds Prometheus metrics to a cluster already enabled for Container insights.

-1. Open the **Kubernetes services** menu in the Azure portal and select your AKS cluster.

-2. Click **Insights**.

-3. Click **Monitor settings**.

- :::image type="content" source="media/prometheus-metrics-enable/aks-cluster-monitor-settings.png" lightbox="media/prometheus-metrics-enable/aks-cluster-monitor-settings.png" alt-text="Screenshot of button for monitor settings for an AKS cluster.":::

-4. Click the checkbox for **Enable Prometheus metrics** and select your Azure Monitor workspace.

-5. To send the collected metrics to Grafana, select a Grafana workspace. See [Create an Azure Managed Grafana instance](../../managed-grafan) for details on creating a Grafana workspace.

- :::image type="content" source="media/prometheus-metrics-enable/aks-cluster-monitor-settings-details.png" lightbox="media/prometheus-metrics-enable/aks-cluster-monitor-settings-details.png" alt-text="Screenshot of monitor settings for an AKS cluster.":::

-6. Click **Configure** to complete the configuration.

-See [Collect Prometheus metrics from AKS cluster (preview)](../essentials/prometheus-metrics-enable.md) for details on [verifying your deployment](../essentials/prometheus-metrics-enable.md#verify-deployment) and [limitations](../essentials/prometheus-metrics-enable.md#limitations-during-enablementdeployment)

-#### From an existing cluster

-This option enables Prometheus, Grafana, and Container insights on a cluster.

-1. Open the clusters menu in the Azure portal and select **Insights**.

-3. Select **Configure monitoring**.

-4. Container insights is already enabled. Select the checkboxes for **Enable Prometheus metrics** and **Enable Grafana**. If you have existing Azure Monitor workspace and Grafana workspace, then they're selected for you. Click **Advanced settings** to select alternate workspaces or create new ones.

- :::image type="content" source="media/prometheus-metrics-enable/configure-container-insights.png" lightbox="media/prometheus-metrics-enable/configure-container-insights.png" alt-text="Screenshot that shows that show the dialog box to configure Container insights with Prometheus and Grafana.":::

-5. Click **Configure** to save the configuration.

-### [CLI](#tab/cli)

-#### Prerequisites

-#### Install the metrics add-on

-Use `az aks create` or `az aks update` with the `-enable-azure-monitor-metrics` option to install the metrics add-on. Depending on the Azure Monitor workspace and Grafana workspace you want to use, choose one of the following options:

-If no Azure Monitor workspace is specified, a default Azure Monitor workspace is created in a resource group with the name `DefaultRG-<cluster_region>` and is named `DefaultAzureMonitorWorkspace-<mapped_region>`.

- ```azurecli

- az aks create/update --enable-azure-monitor-metrics -n <cluster-name> -g <cluster-resource-group>

- ```

-If the existing Azure Monitor workspace is already linked to one or more Grafana workspaces, data is available in that Grafana workspace.

- ```azurecli

- az aks create/update --enable-azure-monitor-metrics -n <cluster-name> -g <cluster-resource-group> --azure-monitor-workspace-resource-id <workspace-name-resource-id>

- ```

-This option creates a link between the Azure Monitor workspace and the Grafana workspace.

- ```azurecli

- az aks create/update --enable-azure-monitor-metrics -n <cluster-name> -g <cluster-resource-group> --azure-monitor-workspace-resource-id <azure-monitor-workspace-name-resource-id> --grafana-resource-id <grafana-workspace-name-resource-id>

- ```

-The output for each command looks similar to the following example:

-```json

-"azureMonitorProfile": {

- "metrics": {

- "enabled": true,

- "kubeStateMetrics": {

- "metricAnnotationsAllowList": "",

- "metricLabelsAllowlist": ""

- }

- }

-}

-```

-#### Optional parameters

-You can use the following optional parameters with the previous commands:

-| Parameter | Description |

-|:|:|

-| `--ksm-metric-annotations-allow-list` | Comma-separated list of Kubernetes annotations keys used in the resource's kube_resource_annotations metric. For example, kube_pod_annotations is the annotations metric for the pods resource. By default, this metric contains only name and namespace labels. To include more annotations, provide a list of resource names in their plural form and Kubernetes annotation keys that you want to allow for them. A single `*` can be provided for each resource to allow any annotations, but this has severe performance implications. For example, `pods=[kubernetes.io/team,...],namespaces=[kubernetes.io/team],...`. |

-| `--ksm-metric-labels-allow-list` | Comma-separated list of more Kubernetes label keys that is used in the resource's kube_resource_labels metric kube_resource_labels metric. For example, kube_pod_labels is the labels metric for the pods resource. By default this metric contains only name and namespace labels. To include more labels, provide a list of resource names in their plural form and Kubernetes label keys that you want to allow for them A single `*` can be provided for each resource to allow any labels, but i this has severe performance implications. For example, `pods=[app],namespaces=[k8s-label-1,k8s-label-n,...],...`. |

-| `--enable-windows-recording-rules` | lets you enable the recording rule groups required for proper functioning of the Windows dashboards. |

-**Use annotations and labels.**

-```azurecli

-az aks create/update --enable-azure-monitor-metrics -n <cluster-name> -g <cluster-resource-group> --ksm-metric-labels-allow-list "namespaces=[k8s-label-1,k8s-label-n]" --ksm-metric-annotations-allow-list "pods=[k8s-annotation-1,k8s-annotation-n]"

-```

-The output is similar to the following example:

-```json

- "azureMonitorProfile": {

- "metrics": {

- "enabled": true,

- "kubeStateMetrics": {

- "metricAnnotationsAllowList": "pods=[k8s-annotation-1,k8s-annotation-n]",

- "metricLabelsAllowlist": "namespaces=[k8s-label-1,k8s-label-n]"

- }

- }

- }

-```

-## [Azure Resource Manager](#tab/resource-manager)

-### Prerequisites

-### Retrieve required values for Grafana resource

-On the **Overview** page for the Azure Managed Grafana instance in the Azure portal, select **JSON view**.

-If you're using an existing Azure Managed Grafana instance that's already linked to an Azure Monitor workspace, the list of already existing Grafana integrations is needed. Copy the value of the `azureMonitorWorkspaceIntegrations` field. If it doesn't exist, then the instance hasn't been linked with any Azure Monitor workspace.

-```json

-"properties": {

- "grafanaIntegrations": {

- "azureMonitorWorkspaceIntegrations": [

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_1"

- },

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_2"

- }

- ]

- }

-}

-```

-### Download and edit the template and the parameter file

-1. Download the template at [https://aka.ms/azureprometheus-enable-arm-template](https://aka.ms/azureprometheus-enable-arm-template) and save it as **existingClusterOnboarding.json**.

-1. Download the parameter file at [https://aka.ms/azureprometheus-enable-arm-template-parameterss](https://aka.ms/azureprometheus-enable-arm-template-parameters) and save it as **existingClusterParam.json**.

-1. Edit the values in the parameter file.

- | Parameter | Value |

- |:|:|

- | `azureMonitorWorkspaceResourceId` | Resource ID for the Azure Monitor workspace. Retrieve from the **JSON view** on the **Overview** page for the Azure Monitor workspace. |

- | `azureMonitorWorkspaceLocation` | Location of the Azure Monitor workspace. Retrieve from the **JSON view** on the **Overview** page for the Azure Monitor workspace. |

- | `clusterResourceId` | Resource ID for the AKS cluster. Retrieve from the **JSON view** on the **Overview** page for the cluster. |

- | `clusterLocation` | Location of the AKS cluster. Retrieve from the **JSON view** on the **Overview** page for the cluster. |

- | `metricLabelsAllowlist` | Comma-separated list of Kubernetes labels keys to be used in the resource's labels metric. |

- | `metricAnnotationsAllowList` | Comma-separated list of more Kubernetes label keys to be used in the resource's annotations metric. |

- | `grafanaResourceId` | Resource ID for the managed Grafana instance. Retrieve from the **JSON view** on the **Overview** page for the Grafana instance. |

- | `grafanaLocation` | Location for the managed Grafana instance. Retrieve from the **JSON view** on the **Overview** page for the Grafana instance. |

- | `grafanaSku` | SKU for the managed Grafana instance. Retrieve from the **JSON view** on the **Overview** page for the Grafana instance. Use the **sku.name**. |

-1. Open the template file and update the `grafanaIntegrations` property at the end of the file with the values that you retrieved from the Grafana instance. The following example is similar:

- ```json

- {

- "type": "Microsoft.Dashboard/grafana",

- "apiVersion": "2022-08-01",

- "name": "[split(parameters('grafanaResourceId'),'/')[8]]",

- "sku": {

- "name": "[parameters('grafanaSku')]"

- },

- "location": "[parameters('grafanaLocation')]",

- "properties": {

- "grafanaIntegrations": {

- "azureMonitorWorkspaceIntegrations": [

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_1"

- },

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_2"

- },

- {

- "azureMonitorWorkspaceResourceId": "[parameters('azureMonitorWorkspaceResourceId')]"

- }

- ]

- }

- }

- ```

-In this JSON, `full_resource_id_1` and `full_resource_id_2` were already in the Azure Managed Grafana resource JSON. They're added here to the Azure Resource Manager template (ARM template). If you have no existing Grafana integrations, don't include these entries for `full_resource_id_1` and `full_resource_id_2`.

-The final `azureMonitorWorkspaceResourceId` entry is already in the template and is used to link to the Azure Monitor workspace resource ID provided in the parameters file.

-## [Bicep](#tab/bicep)

-### Prerequisites

-### Limitation with Bicep deployment

-Currently in Bicep, there's no way to explicitly scope the `Monitoring Reader` role assignment on a string parameter "resource ID" for an Azure Monitor workspace (like in an ARM template). Bicep expects a value of type `resource | tenant`. There also is no REST API [spec](https://github.com/Azure/azure-rest-api-specs) for an Azure Monitor workspace.

-Therefore, the default scoping for the `Monitoring Reader` role is on the resource group. The role is applied on the same Azure Monitor workspace (by inheritance), which is the expected behavior. After you deploy this Bicep template, the Grafana instance is given `Monitoring Reader` permissions for all the Azure Monitor workspaces in that resource group.

-### Retrieve required values for a Grafana resource

-On the **Overview** page for the Azure Managed Grafana instance in the Azure portal, select **JSON view**.

-If you're using an existing Azure Managed Grafana instance that's already linked to an Azure Monitor workspace, the list of already existing Grafana integrations is needed. Copy the value of the `azureMonitorWorkspaceIntegrations` field. If it doesn't exist, then the instance hasn't been linked with any Azure Monitor workspace.

-```json

-"properties": {

- "grafanaIntegrations": {

- "azureMonitorWorkspaceIntegrations": [

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_1"

- },

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_2"

- }

- ]

- }

-}

-```

-### Download and edit templates and the parameter file

-1. Download the [main Bicep template](https://aka.ms/azureprometheus-enable-bicep-template). Save it as **FullAzureMonitorMetricsProfile.bicep**.

-2. Download the [parameter file](https://aka.ms/azureprometheus-enable-bicep-template-parameters) and save it as **FullAzureMonitorMetricsProfileParameters.json** in the same directory as the main Bicep template.

-3. Download the [nested_azuremonitormetrics_dcra_clusterResourceId.bicep](https://aka.ms/nested_azuremonitormetrics_dcra_clusterResourceId) and [nested_azuremonitormetrics_profile_clusterResourceId.bicep](https://aka.ms/nested_azuremonitormetrics_profile_clusterResourceId) files into the same directory as the main Bicep template.

-4. Edit the values in the parameter file.

-5. The main Bicep template creates all the required resources. It uses two modules for creating the Data Collection Rule Associations (DCRA) and Azure Monitor metrics profile resources from the other two Bicep files.

- | Parameter | Value |

- |:|:|

- | `azureMonitorWorkspaceResourceId` | Resource ID for the Azure Monitor workspace. Retrieve from the **JSON view** on the **Overview** page for the Azure Monitor workspace. |

- | `azureMonitorWorkspaceLocation` | Location of the Azure Monitor workspace. Retrieve from the **JSON view** on the **Overview** page for the Azure Monitor workspace. |

- | `clusterResourceId` | Resource ID for the AKS cluster. Retrieve from the **JSON view** on the **Overview** page for the cluster. |

- | `clusterLocation` | Location of the AKS cluster. Retrieve from the **JSON view** on the **Overview** page for the cluster. |

- | `metricLabelsAllowlist` | Comma-separated list of Kubernetes labels keys used in the resource's labels metric. |

- | `metricAnnotationsAllowList` | Comma-separated list of more Kubernetes label keys used in the resource's annotations metric. |

- | `grafanaResourceId` | Resource ID for the managed Grafana instance. Retrieve from the **JSON view** on the **Overview** page for the Grafana instance. |

- | `grafanaLocation` | Location for the managed Grafana instance. Retrieve from the **JSON view** on the **Overview** page for the Grafana instance. |

- | `grafanaSku` | SKU for the managed Grafana instance. Retrieve from the **JSON view** on the **Overview** page for the Grafana instance. Use the **sku.name**. |

-1. Open the template file and update the `grafanaIntegrations` property at the end of the file with the values that you retrieved from the Grafana instance. The following example is similar:

- ```json

- {

- "type": "Microsoft.Dashboard/grafana",

- "apiVersion": "2022-08-01",

- "name": "[split(parameters('grafanaResourceId'),'/')[8]]",

- "sku": {

- "name": "[parameters('grafanaSku')]"

- },

- "location": "[parameters('grafanaLocation')]",

- "properties": {

- "grafanaIntegrations": {

- "azureMonitorWorkspaceIntegrations": [

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_1"

- },

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_2"

- },

- {

- "azureMonitorWorkspaceResourceId": "[parameters('azureMonitorWorkspaceResourceId')]"

- }

- ]

- }

- }

- ```

-In this JSON, `full_resource_id_1` and `full_resource_id_2` were already in the Azure Managed Grafana resource JSON. They're added here to the ARM template. If you have no existing Grafana integrations, don't include these entries for `full_resource_id_1` and `full_resource_id_2`.

-The final `azureMonitorWorkspaceResourceId` entry is already in the template and is used to link to the Azure Monitor workspace resource ID provided in the parameters file.

-## [Terraform](#tab/terraform)

-### Prerequisites

-### Retrieve required values for a Grafana resource

-On the **Overview** page for the Azure Managed Grafana instance in the Azure portal, select **JSON view**.

-If you're using an existing Azure Managed Grafana instance that's already linked to an Azure Monitor workspace, you need the list of Grafana integrations. Copy the value of the `azureMonitorWorkspaceIntegrations` field. If it doesn't exist, the instance hasn't been linked with any Azure Monitor workspace. Update the azure_monitor_workspace_integrations block(shown here) in main.tf with the list of grafana integrations.

-```.tf

- azure_monitor_workspace_integrations {

- resource_id = var.monitor_workspace_id[var.monitor_workspace_id1, var.monitor_workspace_id2]

- }

-```

-### Download and edit the templates

-If you're deploying a new AKS cluster using Terraform with managed Prometheus addon enabled, follow these steps:

-1. Download all files under [AddonTerraformTemplate](https://aka.ms/AAkm357).

-2. Edit the variables in variables.tf file with the correct parameter values.

-3. Run `terraform init -upgrade` to initialize the Terraform deployment.

-4. Run `terraform plan -out main.tfplan` to initialize the Terraform deployment.

-5. Run `terraform apply main.tfplan` to apply the execution plan to your cloud infrastructure.

-Note: Pass the variables for `annotations_allowed` and `labels_allowed` keys in main.tf only when those values exist. These are optional blocks.

-> [!NOTE]

-> Edit the main.tf file appropriately before running the terraform template. Add in any existing azure_monitor_workspace_integrations values to the grafana resource before running the template. Else, older values gets deleted and replaced with what is there in the template during deployment. Users with 'User Access Administrator' role in the subscription of the AKS cluster can enable 'Monitoring Reader' role directly by deploying the template. Edit the grafanaSku parameter if you're using a nonstandard SKU and finally run this template in the Grafana Resource's resource group.

-## [Azure Policy](#tab/azurepolicy)

-### Prerequisites

-### Download Azure Policy rules and parameters and deploy

-1. Download the main [Azure Policy rules template](https://aka.ms/AddonPolicyMetricsProfile). Save it as **AddonPolicyMetricsProfile.rules.json**.

-1. Download the [parameter file](https://aka.ms/AddonPolicyMetricsProfile.parameters). Save it as **AddonPolicyMetricsProfile.parameters.json** in the same directory as the rules template.

-1. Create the policy definition using the following command:

- `az policy definition create --name "(Preview) Prometheus Metrics addon" --display-name "(Preview) Prometheus Metrics addon" --mode Indexed --metadata version=1.0.0 category=Kubernetes --rules AddonPolicyMetricsProfile.rules.json --params AddonPolicyMetricsProfile.parameters.json`

-1. After you create the policy definition, in the Azure portal, select **Policy** > **Definitions**. Select the policy definition you created.

-1. Select **Assign**, go to the **Parameters** tab, and fill in the details. Select **Review + Create**.

-1. After the policy is assigned to the subscription, whenever you create a new cluster without Prometheus enabled, the policy will run and deploy to enable Prometheus monitoring. If you want to apply the policy to an existing AKS cluster, create a **Remediation task** for that AKS cluster resource after you go to the **Policy Assignment**.

-1. Now you should see metrics flowing in the existing Azure Managed Grafana instance, which is linked with the corresponding Azure Monitor workspace.

-Afterwards, if you create a new Managed Grafana instance, you can link it with the corresponding Azure Monitor workspace from the **Linked Grafana Workspaces** tab of the relevant **Azure Monitor Workspace** page. The `Monitoring Reader` role must be assigned to the managed identity of the Managed Grafana instance with the scope as the Azure Monitor workspace, so that Grafana has access to query the metrics. Use the following instructions to do so:

-1. On the **Overview** page for the Azure Managed Grafana instance in the Azure portal, select **JSON view**.

-1. Copy the value of the `principalId` field for the `SystemAssigned` identity.

- ```json

- "identity": {

- "principalId": "00000000-0000-0000-0000-000000000000",

- "tenantId": "00000000-0000-0000-0000-000000000000",

- "type": "SystemAssigned"

- },

- ```

-1. On the **Access control (IAM)** page for the Azure Managed Grafana instance in the Azure portal, select **Add** > **Add role assignment**.

-1. Select `Monitoring Reader`.

-1. Select **Managed identity** > **Select members**.

-1. Select the **system-assigned managed identity** with the `principalId` from the Grafana resource.

-1. Choose **Select** > **Review+assign**.

-### Deploy the template

-Deploy the template with the parameter file by using any valid method for deploying ARM templates. For examples of different methods, see [Deploy the sample templates](../resource-manager-samples.md#deploy-the-sample-templates).

-### Limitations during enablement/deployment

-## Enable Windows metrics collection (preview)

-> [!NOTE]

-> There is no CPU/Memory limit in windows-exporter-daemonset.yaml so it may over-provision the Windows nodes

-> For more details see [Resource reservation](https://kubernetes.io/docs/concepts/configuration/windows-resource-management/#resource-reservation)

->

-> As you deploy workloads, set resource memory and CPU limits on containers. This also subtracts from NodeAllocatable and helps the cluster-wide scheduler in determining which pods to place on which nodes.

-> Scheduling pods without limits may over-provision the Windows nodes and in extreme cases can cause the nodes to become unhealthy.

-As of version 6.4.0-main-02-22-2023-3ee44b9e of the Managed Prometheus addon container (prometheus_collector), Windows metric collection has been enabled for the AKS clusters. Onboarding to the Azure Monitor Metrics add-on enables the Windows DaemonSet pods to start running on your node pools. Both Windows Server 2019 and Windows Server 2022 are supported. Follow these steps to enable the pods to collect metrics from your Windows node pools.

-1. Manually install windows-exporter on AKS nodes to access Windows metrics.

- Enable the following collectors:

- * `[defaults]`

- * `container`

- * `memory`

- * `process`

- * `cpu_info`

- Deploy the [windows-exporter-daemonset YAML](https://github.com/prometheus-community/windows_exporter/blob/master/kubernetes/windows-exporter-daemonset.yaml) file:

- ```

- kubectl apply -f windows-exporter-daemonset.yaml

- ```

-1. Apply the [ama-metrics-settings-configmap](https://github.com/Azure/prometheus-collector/blob/main/otelcollector/configmaps/ama-metrics-settings-configmap.yaml) to your cluster. Set the `windowsexporter` and `windowskubeproxy` Booleans to `true`. For more information, see [Metrics add-on settings configmap](./prometheus-metrics-scrape-configuration.md#metrics-add-on-settings-configmap).

-1. Enable the recording rules that are required for the out-of-the-box dashboards:

- * If onboarding using the CLI, include the option `--enable-windows-recording-rules`.

- * If onboarding using an ARM template, Bicep, or Azure Policy, set `enableWindowsRecordingRules` to `true` in the parameters file.

-## Verify deployment

-1. Run the following command to verify that the DaemonSet was deployed properly on the Linux node pools:

- ```

- kubectl get ds ama-metrics-node --namespace=kube-system

- ```

- The number of pods should be equal to the number of Linux nodes on the cluster. The output should resemble the following example:

- ```

- User@aksuser:~$ kubectl get ds ama-metrics-node --namespace=kube-system

- NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE

- ama-metrics-node 1 1 1 1 1 <none> 10h

- ```

-1. Run the following command to verify that the DaemonSet was deployed properly on the Windows node pools:

- ```

- kubectl get ds ama-metrics-win-node --namespace=kube-system

- ```

- The number of pods should be equal to the number of Windows nodes on the cluster. The output should resemble the following example:

- ```

- User@aksuser:~$ kubectl get ds ama-metrics-node --namespace=kube-system

- NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE

- ama-metrics-win-node 3 3 3 3 3 <none> 10h

- ```

-1. Run the following command to verify that the two ReplicaSets were deployed properly:

- ```

- kubectl get rs --namespace=kube-system

- ```

- The output should resemble the following example:

- ```

- User@aksuser:~$kubectl get rs --namespace=kube-system

- NAME DESIRED CURRENT READY AGE

- ama-metrics-5c974985b8 1 1 1 11h

- ama-metrics-ksm-5fcf8dffcd 1 1 1 11h

- ```

-## Artifacts/Resources provisioned/created as a result of metrics addon enablement for an AKS cluster

-When you enable metrics addon, the following resources are provisioned:

-| Resource Name | Resource Type | Resource Group | Region/Location | Description |

- |:|:|:|:|:|

- | `MSPROM-<aksclusterregion>-<clustername>` | **Data Collection Rule** | Same Resource group as AKS cluster resource | Same region as Azure Monitor Workspace | This data collection rule is for prometheus metrics collection by metrics addon, which has the chosen Azure monitor workspace as destination, and also it is associated to the AKS cluster resource |

- | `MSPROM-<aksclusterregion>-<clustername>` | **Data Collection endpoint** | Same Resource group as AKS cluster resource | Same region as Azure Monitor Workspace | This data collection endpoint is used by the above data collection rule for ingesting Prometheus metrics from the metrics addon|

-

-When you create a new Azure Monitor workspace, the following additional resources are created as part of it

-| Resource Name | Resource Type | Resource Group | Region/Location | Description |

- |:|:|:|:|:|

- | `<azuremonitor-workspace-name>` | **System Data Collection Rule** | MA_\<azuremonitor-workspace-name>_\<azuremonitor-workspace-region>_managed | Same region as Azure Monitor Workspace | This is **system** data collection rule that customers can use when they use OSS Prometheus server to Remote Write to Azure Monitor Workspace |

- | `<azuremonitor-workspace-name>` | **System Data Collection endpoint** | MA_\<azuremonitor-workspace-name>_\<azuremonitor-workspace-region>_managed | Same region as Azure Monitor Workspace | This is **system** data collection endpoint that customers can use when they use OSS Prometheus server to Remote Write to Azure Monitor Workspace |

-

-## HTTP Proxy

-Azure Monitor metrics addon supports HTTP Proxy and uses the same settings as the HTTP Proxy settings for the AKS cluster configured with [these instructions](../../../articles/aks/http-proxy.md).

-## Network firewall requirements

-**Azure public cloud**

-The following table lists the firewall configuration required for Azure monitor Prometheus metrics ingestion for Azure Public cloud. All network traffic from the agent is outbound to Azure Monitor.

-|Agent resource| Purpose | Port |

-|--|||

-| `global.handler.control.monitor.azure.com` | Access control service/ Azure Monitor control plane service | 443 |

-| `*.ingest.monitor.azure.com` | Azure monitor managed service for Prometheus - metrics ingestion endpoint (DCE) | 443 |

-| `*.handler.control.monitor.azure.com` | For querying data collection rules | 443 |

-**Azure US Government cloud**

-The following table lists the firewall configuration required for Azure monitor Prometheus metrics ingestion for Azure US Government cloud. All network traffic from the agent is outbound to Azure Monitor.

-|Agent resource| Purpose | Port |

-|--|||

-| `global.handler.control.monitor.azure.us` | Access control service/ Azure Monitor control plane service | 443 |

-| `*.ingest.monitor.azure.us` | Azure monitor managed service for Prometheus - metrics ingestion endpoint (DCE) | 443 |

-| `*.handler.control.monitor.azure.us` | For querying data collection rules | 443 |

-## Uninstall the metrics add-on

-To uninstall the metrics add-on, see [Disable Prometheus metrics collection on an AKS cluster.](./prometheus-metrics-disable.md)

-## Supported regions

-The list of regions Azure Monitor Metrics and Azure Monitor Workspace is supported in can be found [here](https://aka.ms/ama-metrics-supported-regions) under the Managed Prometheus tag.

-## Frequently asked questions

-This section provides answers to common questions.

-### Does enabling managed service for Prometheus on my Azure Kubernetes Service cluster also enable Container insights?

-You have options for how you can collect your Prometheus metrics. If you use the Azure portal and enable Prometheus metrics collection and install the Azure Kubernetes Service (AKS) add-on from the Azure Monitor workspace UX, it won't enable Container insights and collection of log data. When you go to the Insights page on your AKS cluster, you're prompted to enable Container insights to collect log data.<br>

-

-If you use the Azure portal and enable Prometheus metrics collection and install the AKS add-on from the Insights page of your AKS cluster, it enables log collection into a Log Analytics workspace. and Prometheus metrics collection into an Azure Monitor workspace.

-## Next steps

-description: How to configure your Azure Arc-enabled Kubernetes cluster (preview) to send data to Azure Monitor managed service for Prometheus.

-# Collect Prometheus metrics from an Arc-enabled Kubernetes cluster (preview)

-This article describes how to configure your Azure Arc-enabled Kubernetes cluster (preview) to send data to Azure Monitor managed service for Prometheus. When you configure your Azure Arc-enabled Kubernetes cluster to send data to Azure Monitor managed service for Prometheus, a containerized version of the Azure Monitor agent is installed with a metrics extension. You then specify the Azure Monitor workspace where the data should be sent.

-> [!NOTE]

-> The process described here doesn't enable [Container insights](../containers/container-insights-overview.md) on the cluster even though the Azure Monitor agent installed in this process is the same agent used by Container insights.

-> For different methods to enable Container insights on your cluster, see [Enable Container insights](../containers/container-insights-onboard.md). For details on adding Prometheus collection to a cluster that already has Container insights enabled, see [Collect Prometheus metrics with Container insights](../containers/container-insights-prometheus.md).

-## Supported configurations

-The following configurations are supported:

-+ Azure Monitor Managed Prometheus supports monitoring Azure Arc-enabled Kubernetes. For more information, see [Azure Monitor managed service for Prometheus](../essentials/prometheus-metrics-overview.md).

-+ Docker

-+ Moby

-+ CRI compatible container runtimes such CRI-O

-The following configurations are not supported:

-+ Windows

-+ Azure Red Hat OpenShift 4

-## Prerequisites

-+ Prerequisites listed in [Deploy and manage Azure Arc-enabled Kubernetes cluster extensions](../../azure-arc/kubernetes/extensions.md#prerequisites)

-+ An Azure Monitor workspace. To create new workspace, see [Manage an Azure Monitor workspace ](../essentials/azure-monitor-workspace-manage.md).

-+ The cluster must use [managed identity authentication](../../aks/use-managed-identity.md).

-+ The following resource providers must be registered in the subscription of the Arc-enabled Kubernetes cluster and the Azure Monitor workspace:

- + Microsoft.Kubernetes

- + Microsoft.Insights

- + Microsoft.AlertsManagement

-+ The following endpoints must be enabled for outbound access in addition to the [Azure Arc-enabled Kubernetes network requirements](../../azure-arc/kubernetes/network-requirements.md?tabs=azure-cloud):

- **Azure public cloud**

- |Endpoint|Port|

- ||--|

- |*.ods.opinsights.azure.com |443 |

- |*.oms.opinsights.azure.com |443 |

- |dc.services.visualstudio.com |443 |

- |*.monitoring.azure.com |443 |

- |login.microsoftonline.com |443 |

- |global.handler.control.monitor.azure.com |443 |

- | \<cluster-region-name\>.handler.control.monitor.azure.com |443 |

-## Create an extension instance

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

-### Onboard from Azure Monitor workspace

-1. Open the **Azure Monitor workspaces** menu in the Azure portal and select your cluster.

-1. Select **Managed Prometheus** to display a list of AKS and Arc clusters.

-1. Select **Configure** for the cluster you want to enable.

-### Onboard from Container insights

-1. In the Azure portal, select the Azure Arc-enabled Kubernetes cluster that you wish to monitor.

-1. From the resource pane on the left, select **Insights** under the **Monitoring** section.

-1. On the onboarding page, select **Configure monitoring**.

-1. On the **Configure Container insights** page, select the **Enable Prometheus metrics** checkbox.

-1. Select **Configure**.

-### [CLI](#tab/cli)

-### Prerequisites

-+ The k8s-extension extension must be installed. Install the extension using the command `az extension add --name k8s-extension`.

-+ The k8s-extension version 1.4.1 or higher is required. Check the k8s-extension version by using the `az version` command.

-### Create an extension with default values

-+ A default Azure Monitor workspace is created in the DefaultRG-<cluster_region> following the format `DefaultAzureMonitorWorkspace-<mapped_region>`.

-+ Auto-upgrade is enabled for the extension.

-```azurecli

-az k8s-extension create \

-```

-### Create an extension with an existing Azure Monitor workspace

-If the Azure Monitor workspace is already linked to one or more Grafana workspaces, the data is available in Grafana.

-```azurecli

-az k8s-extension create\

-```

-### Create an extension with an existing Azure Monitor workspace and link with an existing Grafana workspace

-This option creates a link between the Azure Monitor workspace and the Grafana workspace.

-```azurecli

-az k8s-extension create\

-grafana-resource-id=<grafana-workspace-name-resource-id>

-```

-### Create an extension with optional parameters

-You can use the following optional parameters with the previous commands:

-`--configurationsettings.AzureMonitorMetrics.KubeStateMetrics.MetricsLabelsAllowlist` is a comma-separated list of Kubernetes label keys that will be used in the resource' labels metric. By default the metric contains only name and namespace labels. To include additional labels, provide a list of resource names in their plural form and Kubernetes label keys you would like to allow for them. For example, `=namespaces=[kubernetes.io/team,...],pods=[kubernetes.io/team],...`

-`--configurationSettings.AzureMonitorMetrics.KubeStateMetrics.MetricAnnotationsAllowList` is a comma-separated list of Kubernetes annotations keys that will be used in the resource' labels metric. By default the metric contains only name and namespace labels. To include additional annotations, provide a list of resource names in their plural form and Kubernetes annotation keys you would like to allow for them. For example, `=namespaces=[kubernetes.io/team,...],pods=[kubernetes.io/team],...`.

-> [!NOTE]

-> A single `*`, for example `'=pods=[*]'` can be provided per resource to allow any labels, however, this has severe performance implications.

-```azurecli

-az k8s-extension create\

-grafana-resource-id=<grafana-workspace-name-resource-id> \

-AzureMonitorMetrics.KubeStateMetrics.MetricAnnotationsAllowList="pods=[k8s-annotation-1,k8s-annotation-n]" \

-AzureMonitorMetrics.KubeStateMetrics.MetricsLabelsAllowlist "namespaces=[k8s-label-1,k8s-label-n]"

-```

-### [Resource Manager](#tab/resource-manager)

-### Prerequisites

-+ If the Azure Managed Grafana instance is in a subscription other than the Azure Monitor Workspaces subscription, register the Azure Monitor Workspace subscription with the `Microsoft.Dashboard` resource provider by following the steps in the [Register resource provider](../../azure-resource-manager/management/resource-providers-and-types.md#register-resource-provider) section of the Azure resource providers and types article.

-+ The Azure Monitor workspace and Azure Managed Grafana workspace must already exist.

-+ The template must be deployed in the same resource group as the Azure Managed Grafana workspace.

-+ Users with the User Access Administrator role in the subscription of the AKS cluster can enable the Monitoring Data Reader role directly by deploying the template.

-### Create an extension

-1. Retrieve required values for the Grafana resource

- > [!NOTE]

- > Azure Managed Grafana is not currently available in the Azure US Government cloud.

- On the Overview page for the Azure Managed Grafana instance in the Azure portal, select **JSON view**.

- If you're using an existing Azure Managed Grafana instance that's already linked to an Azure Monitor workspace, you need the list of already existing Grafana integrations. Copy the value of the `azureMonitorWorkspaceIntegrations` field. If the field doesn't exist, the instance hasn't been linked with any Azure Monitor workspace.

- ```json

- "properties": {

- "grafanaIntegrations": {

- "azureMonitorWorkspaceIntegrations": [

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_1"

- },

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_2"

- }

- ]

- }

- }

- ```

-1. Download and edit the template and the parameter file

- 1. Download the template at https://aka.ms/azureprometheus-arc-arm-template and save it as *existingClusterOnboarding.json*.

- 1. Download the parameter file at https://aka.ms/azureprometheus-arc-arm-template-parameters and save it as *existingClusterParam.json*.

-1. Edit the following fields' values in the parameter file.

- |Parameter|Value |

- |||

- |`azureMonitorWorkspaceResourceId` |Resource ID for the Azure Monitor workspace. Retrieve from the **JSON view** on the Overview page for the Azure Monitor workspace. |

- |`azureMonitorWorkspaceLocation`|Location of the Azure Monitor workspace. Retrieve from the JSON view on the Overview page for the Azure Monitor workspace. |

- |`clusterResourceId` |Resource ID for the Arc cluster. Retrieve from the **JSON view** on the Overview page for the cluster. |

- |`clusterLocation` |Location of the Arc cluster. Retrieve from the **JSON view** on the Overview page for the cluster. |

- |`metricLabelsAllowlist` |Comma-separated list of Kubernetes labels keys to be used in the resource's labels metric.|

- |`metricAnnotationsAllowList` |Comma-separated list of more Kubernetes label keys to be used in the resource's labels metric. |

- |`grafanaResourceId` |Resource ID for the managed Grafana instance. Retrieve from the **JSON view** on the Overview page for the Grafana instance. |

- |`grafanaLocation` |Location for the managed Grafana instance. Retrieve from the **JSON view** on the Overview page for the Grafana instance. |

- |`grafanaSku` |SKU for the managed Grafana instance. Retrieve from the **JSON view** on the Overview page for the Grafana instance. Use the `sku.name`. |

-1. Open the template file and update the `grafanaIntegrations` property at the end of the file with the values that you retrieved from the Grafana instance. For example:

- ```json

- {

- "type": "Microsoft.Dashboard/grafana",

- "apiVersion": "2022-08-01",

- "name": "[split(parameters('grafanaResourceId'),'/')[8]]",

- "sku": {

- "name": "[parameters('grafanaSku')]"

- },

- "location": "[parameters('grafanaLocation')]",

- "properties": {

- "grafanaIntegrations": {

- "azureMonitorWorkspaceIntegrations": [

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_1"

- },

- {

- "azureMonitorWorkspaceResourceId": "full_resource_id_2"

- },

- {

- "azureMonitorWorkspaceResourceId": "[parameters ('azureMonitorWorkspaceResourceId')]"

- }

- ]

- }

- }

- }

- ```

- In the example JSON above, `full_resource_id_1` and `full_resource_id_2` are already in the Azure Managed Grafana resource JSON. They're added here to the Azure Resource Manager template (ARM template). If you don't have any existing Grafana integrations, don't include these entries.

- The final `azureMonitorWorkspaceResourceId` entry is in the template by default and is used to link to the Azure Monitor workspace resource ID provided in the parameters file.

-### Verify extension installation status

-Once you have successfully created the Azure Monitor extension for your Azure Arc-enabled Kubernetes cluster, you can check the status of the installation using the Azure portal or CLI. Successful installations show the status as `Installed`.

-#### Azure portal

-1. In the Azure portal, select the Azure Arc-enabled Kubernetes cluster with the extension installation.

-1. From the resource pane on the left, select the **Extensions** item under the **Setting**' section.

-1. An extension with the name **azuremonitor-metrics** is listed, with the current status in the **Install status** column.

-#### Azure CLI

-Run the following command to show the latest status of the` Microsoft.AzureMonitor.Containers.Metrics` extension.

-```azurecli

-az k8s-extension show \

-```

-### Delete the extension instance

-To delete the extension instance, use the following CLI command:

-```azurecli

-az k8s-extension delete --name azuremonitor-metrics -g <cluster_resource_group> -c<cluster_name> -t connectedClusters

-```

-The command only deletes the extension instance. The Azure Monitor workspace and its data are not deleted.

-## Disconnected clusters

-If your cluster is disconnected from Azure for more than 48 hours, Azure Resource Graph won't have information about your cluster. As a result, your Azure Monitor Workspace may have incorrect information about your cluster state.

-## Troubleshooting

-For issues with the extension, see the [Troubleshooting Guide](./prometheus-metrics-troubleshoot.md).

-## Next Steps

-+ [Default Prometheus metrics configuration in Azure Monitor ](prometheus-metrics-scrape-default.md)

-+ [Customize scraping of Prometheus metrics in Azure Monitor](prometheus-metrics-scrape-configuration.md)

-+ [Use Azure Monitor managed service for Prometheus as data source for Grafana using managed system identity](../essentials/prometheus-grafana.md)

-+ [Configure self-managed Grafana to use Azure Monitor managed service for Prometheus with Microsoft Entra ID](../essentials/prometheus-self-managed-grafana-azure-active-directory.md)

-You can create multiple Data Collection Rules that point to the same Data Collection Endpoint for metrics to be sent to additional Azure Monitor workspaces from the same Kubernetes cluster. In case you have a very high volume of metrics, a new Data Collection Endpoint can be created as well. Please refer to the service limits [document](../service-limits.md) regarding ingestion limits. Currently, this is only available through onboarding through Resource Manager templates. You can follow the [regular onboarding process](prometheus-metrics-enable.md) and then edit the same Resource Manager templates to add additional DCRs and DCEs (if applicable) for your additional Azure Monitor workspaces. You'll need to edit the template to add an additional parameters for every additional Azure Monitor workspace, add another DCR for every additional Azure Monitor workspace, add another DCE (if applicable), add the Monitor Reader Role for the new Azure Monitor workspace and add an additional Azure Monitor workspace integration for Grafana.

-description: Describes minimal ingestion profile in Azure Monitor managed service for Prometheus and how you can configure it collect more data.

-This article provides instructions on customizing metrics scraping for a Kubernetes cluster with the [metrics addon](prometheus-metrics-enable.md) in Azure Monitor.

-To override the cluster label in the time series scraped, update the setting `cluster_alias` to any string under `prometheus-collector-settings` in the [configmap](https://aka.ms/azureprometheus-addon-settings-configmap) `ama-metrics-settings-configmap`. You can create this configmap if it doesn't exist in the cluster or you can edit the existing one if its already exists in your cluster.

-This article lists the default targets, dashboards, and recording rules when you [configure Prometheus metrics to be scraped from an Azure Kubernetes Service (AKS) cluster](prometheus-metrics-enable.md) for any AKS cluster.

-> This requires applying or updating the `ama-metrics-settings-configmap` configmap and installing `windows-exporter` on all Windows nodes. For more information, see the [enablement document](./prometheus-metrics-enable.md#enable-prometheus-metric-collection).

-* [Collect Prometheus metrics from an AKS cluster](../containers/prometheus-metrics-enable.md)

-| Prometheus Metrics | Pricing for [Azure Monitor managed service for Prometheus](essentials/prometheus-metrics-overview.md) is based on [data samples ingested](essentials/prometheus-metrics-enable.md) and [query samples processed](essentials/azure-monitor-workspace-manage.md#link-a-grafana-workspace). Data is retained for 18 months at no extra charge. |

-To connect your Azure Monitor managed service for Prometheus to your Azure Monitor workspace, see [Collect Prometheus metrics from AKS cluster](./prometheus-metrics-enable.md)

-To set up an Azure monitor workspace as a data source for Grafana using a Resource Manager template, see [Collect Prometheus metrics from AKS cluster](prometheus-metrics-enable.md?tabs=resource-manager#enable-prometheus-metric-collection)

-| Container insights | [Enable Container insights](../containers/prometheus-metrics-enable.md) | When you enable Container insights on a Kubernetes cluster, a containerized version of the Azure Monitor agent is installed, and a DCR is created that collects data according to the configuration you selected. You may need to modify this DCR to add a transformation. |

-* [Collect Prometheus metrics from AKS cluster](./prometheus-metrics-enable.md)

-[Get started with Azure Workbooks](workbooks-getting-started.md)

-description: Simplify complex reporting with prebuilt and custom parameterized workbooks.

-# Workbook configuration options

-You can configure workbooks to suit your needs by using the settings in the **Settings** tab. If query or metrics steps display time-based data, more settings are available on the **Advanced settings** tab.

-## Workbook settings

-Workbook settings have these tabs to help you configure your workbook.

-|Settings tab |Description |

-|||

-|Resources|This tab contains the resources that appear as default selections in this workbook.<br>The resource marked as the **Owner** is where the workbook will be saved and the location of the workbooks and templates you'll see when you're browsing. The owner resource can't be removed.<br> You can add a default resource by selecting **Add Resources**. You can remove resources by selecting a resource or several resources and selecting **Remove Selected Resources**. When you're finished adding and removing resources, select **Apply Changes**.|

-|Versions| This tab contains a list of all the available versions of this workbook. Select a version and use the toolbar to compare, view, or restore versions. Previous workbook versions are available for 90 days.<br><ul><li>**Compare**: Compares the JSON of the previous workbook to the most recently saved version.</li><li>**View**: Opens the selected version of the workbook in a context pane.</li><li>**Restore**: Saves a new copy of the workbook with the contents of the selected version and overwrites any existing current content. You'll be prompted to confirm this action.</li></ul><br>|

-|Style |On this tab, you can set a padding and spacing style for the whole workbook. The possible options are **Wide**, **Standard**, **Narrow**, and **None**. The default style setting is **Standard**.|

-|Pin |While in pin mode, you can select **Pin Workbook** to pin a component from this workbook to a dashboard. Select **Link to Workbook** to pin a static link to this workbook on your dashboard. You can choose a specific component in your workbook to pin.|

-|Trusted hosts |On this tab, you can enable a trusted source or mark this workbook as trusted in this browser. For more information, see [Trusted hosts](#trusted-hosts). |

-> [!NOTE]

-> Version history isn't available for [bring-your-own-storage](workbooks-bring-your-own-storage.md) workbooks.

-#### Versions tab

-#### Compare versions

-### Trusted hosts

-Enable a trusted source or mark this workbook as trusted in this browser.

-| Control | Definition |

-| -- | -- |

-| Mark workbook as trusted | If enabled, this workbook can call any endpoint, whether the host is marked as trusted or not. A workbook is trusted if it's a new workbook, an existing workbook that's saved, or is explicitly marked as a trusted workbook. |

-| URL grid | A grid to explicitly add trusted hosts. |

-## Time brushing

-Time range brushing allows a user to "brush" or "scrub" a range on a chart and have that range output as a parameter value.

-You can also choose to only export a parameter when a range is explicitly brushed:

-### Brushing in a metrics chart

-When you enable time brushing on a metrics chart, you can "brush" a time by dragging the mouse on the time chart.

-After the brush has stopped, the metrics chart zooms in to that range and exports the range as a time range parameter.

-An icon on the toolbar in the upper-right corner is active to reset the time range back to its original, unzoomed time range.

-### Brushing in a query chart

-When you enable time brushing on a query chart, indicators appear that you can drag, or you can brush a range on the time chart.

-After the brush has stopped, the query chart shows that range as a time range parameter but won't zoom in. This behavior is different than the behavior of metrics charts. Because of the complexity of user-written queries, it might not be possible for workbooks to correctly update the range used by the query in the query content directly. If the query is using a time range parameter, it's possible to get this behavior by using a [global parameter](workbooks-parameters.md#global-parameters) instead.

-An icon on the toolbar in the upper-right corner is active to reset the time range back to its original, unzoomed time range.

-## Interactivity

-There are several ways that you can create interactive reports and experiences in workbooks:

-### Set up a grid row click

-1. Make sure you're in edit mode by selecting **Edit**.

-1. Select **Add query** to add a log query control to the workbook.

-1. Select the log query type, the resource type, and the target resources.

-1. Use the query editor to enter the KQL for your analysis:

- ```kusto

- requests

- | summarize AllRequests = count(), FailedRequests = countif(success == false) by Request = name

- | order by AllRequests desc

- ```

-1. Select **Run query** to see the results.

-1. Select **Advanced Settings** to open the **Advanced Settings** pane.

-1. Select the **When an item is selected, export a parameter** checkbox.

-1. Select **Add Parameter** and fill in the following information:

- - **Field to export**: `Request`

- - **Parameter name**: `SelectedRequest`

- - **Default value**: `All requests`

-

- :::image type="content" source="media/workbooks-configurations/workbooks-export-parameters-add.png" alt-text="Screenshot that shows the Advanced Settings workbook editor with settings for exporting fields as parameters.":::

-1. Optional. If you want to export the entire contents of the selected row instead of a specific column, leave **Field to export** unset. The entire row's contents are exported as JSON to the parameter. On the referencing KQL control, use the `todynamic` function to parse the JSON and access the individual columns.

-1. Select **Save**.

-1. Select **Done Editing**.

-1. Add another query control as in the preceding steps.

-1. Use the query editor to enter the KQL for your analysis.

- ```kusto

- requests

- | where name == '{SelectedRequest}' or 'All Requests' == '{SelectedRequest}'

- | summarize ['{SelectedRequest}'] = count() by bin(timestamp, 1h)

- ```

-1. Select **Run query** to see the results.

-1. Change **Visualization** to **Area chart**.

-1. Choose a row to select in the first grid. Note how the area chart below filters to the selected request.

-The resulting report looks like this example in edit mode:

-

- :::image type="content" source="media/workbooks-configurations/workbooks-interactivity-grid-create.png" alt-text="Screenshot that shows workbooks with the first two queries in edit mode.":::

-The following image shows a more elaborate interactive report in read mode based on the same principles. The report uses grid clicks to export parameters, which in turn are used in two charts and a text block.

- :::image type="content" source="media/workbooks-configurations/workbooks-interactivity-grid-read.png" alt-text="Screenshot that shows a workbook report using grid clicks.":::

-### Set up grid cell clicks

-1. Make sure you're in edit mode by selecting **Edit**.

-1. Select **Add query** to add a log query control to the workbook.

-1. Select the log query type, resource type, and target resources.

-1. Use the query editor to enter the KQL for your analysis:

- ```kusto

- requests

- | summarize Count = count(), Sample = any(pack_all()) by Request = name

- | order by Count desc

- ```

-1. Select **Run query** to see the results.

-1. Select **Column Settings** to open the settings pane.

-1. In the **Columns** section, set:

- - **Sample**

- - **Column renderer**: `Link`

- - **View to open**: `Cell Details`

- - **Link label**: `Sample`

- - **Count**

- - **Column renderer**: `Bar`

- - **Color palette**: `Blue`

- - **Minimum value**: `0`

- - **Request**

- - **Column renderer**: `Automatic`

-1. Select **Save and Close** to apply changes.

- :::image type="content" source="media/workbooks-configurations/workbooks-column-settings.png" alt-text="Screenshot that shows the Edit column settings pane.":::

-1. Select a **Sample** link in the grid to open a pane with the details of a sampled request.

- :::image type="content" source="media/workbooks-configurations/workbooks-grid-link-details.png" alt-text="Screenshot that shows the Details pane of the sample request.":::

-### Link renderer actions

-Learn about how [link actions](workbooks-link-actions.md) work to enhance workbook interactivity.

-### Set conditional visibility

-1. Follow the steps in the [Set up a grid row click](#set-up-a-grid-row-click) section to set up two interactive controls.

-1. Add a new parameter with these values:

- - **Parameter name**: `ShowDetails`

- - **Parameter type**: `Drop down`

- - **Required**: `checked`

- - **Get data from**: `JSON`

- - **JSON Input**: `["Yes", "No"]`

-1. Select **Save** to commit changes.

- :::image type="content" source="media/workbooks-configurations/workbooks-edit-parameter.png" alt-text="Screenshot that shows editing an interactive parameter in workbooks.":::

-1. Set the parameter value to `Yes`.

-

- :::image type="content" source="media/workbooks-configurations/workbooks-set-parameter.png" alt-text="Screenshot that shows setting an interactive parameter value in a workbook.":::

-1. In the query control with the area chart, select **Advanced Settings** (the gear icon).

-1. If **ShowDetails** is set to `Yes`, select **Make this item conditionally visible**.

-1. Select **Done Editing** to commit the changes.

-1. On the workbook toolbar, select **Done Editing**.

-1. Switch the value of **ShowDetails** to `No`. Notice that the chart below disappears.

-The following image shows the case where **ShowDetails** is `Yes`:

- :::image type="content" source="media/workbooks-configurations/workbooks-conditional-visibility-visible.png" alt-text="Screenshot that shows a workbook with a conditional component that's visible.":::

-The following image shows the hidden case where **ShowDetails** is `No`:

-### Set up multi-selects in grids and charts

-Query and metrics components can export parameters when a row or multiple rows are selected.

-1. In the query component that displays the grid, select **Advanced settings**.

-1. Select the **When items are selected, export parameters** checkbox.

-1. Select the **Allow selection of multiple values** checkbox.

- - The displayed visualization allows multi-selecting and the exported parameter's values will be arrays of values, like when using multi-select dropdown parameters.

- - If cleared, the display visualization only captures the last selected item and exports only a single value at a time.

-1. Use **Add Parameter** for each parameter you want to export. A pop-up window appears with the settings for the parameter to be exported.

-When you enable single selection, you can specify which field of the original data to export. Fields include parameter name, parameter type, and default value to use if nothing is selected.

-When you enable multi-selection, you specify which field of the original data to export. Fields include parameter name, parameter type, quote with, and delimiter. The quote with and delimiter values are used when turning arrow values into text when they're being replaced in a query. In multi-selection, if no values are selected, the default value is an empty array.

-> [!NOTE]

-> For multi-selection, only unique values are exported. For example, you won't see output array values like "1,1,2,1". The array output will be "1,2".

-If you leave the **Field to export** setting empty in the export settings, all the available fields in the data will be exported as a stringified JSON object of key:value pairs. For grids and titles, the string includes the fields in the grid. For charts, the available fields are x,y,series, and label, depending on the type of chart.

-While the default behavior is to export a parameter as text, if you know the field is a subscription or resource ID, use that information as the export parameter type. Then the parameter can be used downstream in places that require those types of parameters.

-# Creating an Azure Workbook

-Workbooks allow authors to include text blocks in their workbooks. The text can be human analysis of the telemetry, information to help users interpret the data, section headings, etc.

-

-Text is added through a markdown control into which an author can add their content. An author can use the full formatting capabilities of markdown. These include different heading and font styles, hyperlinks, tables, etc. Markdown allows authors to create rich Word- or Portal-like reports or analytic narratives. Text can contain parameter values in the markdown text, and those parameter references will be updated as the parameters change.

-

-1. Use the **Preview** tab to see how your content will look. The preview shows the content inside a scrollable area to limit its size, but when displayed at runtime, the markdown content will expand to fill whatever space it needs, without a scrollbar.

-

-Azure Workbooks allow you to query any of the supported workbook [data sources](workbooks-data-sources.md).

-### Best practices for querying logs

- union isfuzzy=true MissingTable, (AzureDiagnostics | getschema | summarize c=count() | project isMissing=iff(c > 0, 0, 1))

- This query returns a **1** if the **AzureDiagnostics** table doesn't exist in the workspace. If the real table doesn't exist, the fake row of the **MissingTable** will be returned. If any columns exist in the schema for the **AzureDiagnostics** table, a **0** is returned. You could use this as a parameter value, and conditionally hide your query steps unless the parameter value is 0. You could also use conditional visibility to show text that says that the current workspace does not have the missing table, and send the user to documentation on how to onboard.

-

-Uses dynamic scopes for more efficient querying. The snippet below uses this heuristc:

-| join kind = inner (Resources

-| project x, label = 'x',

- x in ('microsoft.compute/virtualmachinescalesets', 'microsoft.compute/virtualmachines') and resourceCount <= 5, true,

- x == 'microsoft.resources/resourcegroups' and resourceGroups <= 3 and resourceCount > 5, true,

- x == 'microsoft.resources/subscriptions' and resourceGroups > 3 and resourceCount > 5, true,

-| where type =~ 'microsoft.compute/virtualmachines' or type =~ 'microsoft.compute/virtualmachinescalesets'

-| where resourceGroup in~({ResourceGroups})

-| project value = id, label = id, selected = false,

- group = iff(type =~ 'microsoft.compute/virtualmachines', 'Virtual machines', 'Virtual machine scale sets')

-Workbooks allow you to control how your parameter controls are presented to consumers ΓÇô text box vs. drop down, single- vs. multi-select, values from text, JSON, KQL, or Azure Resource Graph, etc.

- - Parameter type:

- - Required:

-

-Most Azure resources emit metric data about state and health such as CPU utilization, storage availability, count of database transactions, failing app requests, etc. Using workbooks, you can create visualizations of the metric data as time-series charts.

-The example below shows the number of transactions in a storage account over the prior hour. This allows the storage owner to see the transaction trend and look for anomalies in behavior.

-

-## Add links

-You can use links to create links to other views, workbooks, other items inside a workbook, or to create tabbed views within a workbook. The links can be styled as hyperlinks, buttons, and tabs.

-|Scroll to a step| When selecting a link, the workbook will move focus and scroll to make another step visible. This action can be used to create a "table of contents", or a "go back to the top" style experience. |

-Most of the time, tab links are combined with the **Set a parameter value** action. Here's an example showing the links step configured to create 2 tabs, where selecting either tab will set a **selectedTab** parameter to a different value (the example shows a third tab being edited to show the parameter name and parameter value placeholders):

-The first tab is selected by default, initially setting **selectedTab** to 1, and making that step visible. Selecting the second tab will change the value of the parameter to "2", and different content will be displayed:

-

-If any required parameters are used in button text, tooltip text, or value fields, and the required parameter is unset, the toolbar button will be disabled. For example, this can be used to disable toolbar buttons when no value is selected in another parameter/control.

- This is a group in read mode with two items inside: a text item and a query item.

-In this mode, a button is displayed where the group would be, and no content is retrieved or created until the user explicitly clicks the button to load the content. This is useful in scenarios where the content might be expensive to compute or rarely used. The author can specify the text to appear on the button.

-

-When a group is configured to load from a template, by default, that content will be loaded in lazy mode, and it will only load when the group is visible.

-When a template is loaded into a group, the workbook attempts to merge any parameters declared in the template with parameters that already exist in the group. Any parameters that already exist in the workbook with identical names will be merged out of the template being loaded. If all parameters in a parameter step are merged out, the entire parameters step will disappear.

-To improve performance, it's helpful to break up a large template into multiple smaller templates that loads some content in lazy mode or on demand by the user. This makes the initial load faster since the top-level template can be much smaller.

-

-1. If the individual steps moved in step 3 had conditional visibilities, that will become the visibility of the outer group (like used in tabs). Remove them from the items inside the group and add that visibility setting to the group itself. Save here to avoid losing changes and/or export and save a copy of the json content.

-1. If you want that group to be loaded from a template, you can use the **Edit** toolbar button in the group. This will open just the content of that group as a workbook in a new window. You can then save it as appropriate and close this workbook view (don't close the browser, just that view to go back to the previous workbook you were editing).

-description: Simplify complex reporting with prebuilt and custom parameterized workbooks containing dropdown parameters.

-[Getting started with Azure Workbooks](workbooks-getting-started.md)

-description: Learn how to perform the commonly used tasks in workbooks.

-# Get started with Azure Workbooks

-This article describes how to access Azure Workbooks and the common tasks used to work with workbooks.

-You can access Azure Workbooks in a few ways:

- :::image type="content" source="./media/workbooks-overview/workbooks-menu.png" alt-text="Screenshot that shows Workbooks in the menu.":::

- :::image type="content" source="media/workbooks-overview/workbooks-log-analytics-icon.png" alt-text="Screenshot of Workbooks on the Log Analytics workspaces page.":::

-When the gallery opens, select a saved workbook or a template. You can also search for a name in the search box.

-## Save a workbook

-To save a workbook, save the report with a specific title, subscription, resource group, and location.

-By default, the workbook is auto-filled with the same settings as the LA workspace, with the same subscription and resource group. Workbooks are saved to 'My Reports' by default, and are only accessible by the individual user, but they can be saved directly to shared reports or shared later on. Workbooks are shared resources and they require write access to the parent resource group to be saved.

-## Share a workbook

-When you want to share a workbook or template, keep in mind that the person you want to share with must have permissions to access the workbook. They must have an Azure account, and **Monitoring Reader** permissions.

-To share a workbook or workbook template:

-1. In the Azure portal, select the workbook or template you want to share.

-1. Select the **Share** icon from the top toolbar.

-1. The **Share workbook** or **Share template** window opens with a URL to use for sharing the workbook.

-1. Copy the link to share the workbook, or select **Share link via email** to open your default mail app.

-## Pin a visualization

-You can pin text, query, or metrics components in a workbook by using the **Pin** button on those items while the workbook is in pin mode. Or you can use the **Pin** button if the workbook author has enabled settings for that element to make it visible.

-To access pin mode, select **Edit** to enter editing mode. Select **Pin** on the top bar. An individual **Pin** then appears above each corresponding workbook part's **Edit** button on the right side of the screen.

-> [!NOTE]

-> The state of the workbook is saved at the time of the pin. Pinned workbooks on a dashboard won't update if the underlying workbook is modified. To update a pinned workbook part, you must delete and re-pin that part.

-### Time ranges for pinned queries

-Pinned workbook query parts will respect the dashboard's time range if the pinned item is configured to use a *TimeRange* parameter. The dashboard's time range value will be used as the time range parameter's value. Any change of the dashboard time range will cause the pinned item to update. If a pinned part is using the dashboard's time range, you'll see the subtitle of the pinned part update to show the dashboard's time range whenever the time range changes.

-Pinned workbook parts using a time range parameter will auto-refresh at a rate determined by the dashboard's time range. The last time the query ran will appear in the subtitle of the pinned part.

-If a pinned component has an explicitly set time range and doesn't use a time range parameter, that time range will always be used for the dashboard, regardless of the dashboard's settings. The subtitle of the pinned part won't show the dashboard's time range. The query won't auto-refresh on the dashboard. The subtitle will show the last time the query executed.

-> [!NOTE]

-> Queries that use the *merge* data source aren't currently supported when pinning to dashboards.

-## Auto refresh

-Select **Auto refresh** to open a list of intervals that you can use to select the interval. The workbook will keep refreshing after the selected time interval.

-* **Auto refresh** only refreshes when the workbook is in read mode. If a user sets an interval of 5 minutes and after 4 minutes switches to edit mode, refreshing doesn't occur if the user is still in edit mode. But if the user returns to read mode, the interval of 5 minutes resets and the workbook will be refreshed after 5 minutes.

-* Selecting **Auto refresh** in read mode also resets the interval. If a user sets the interval to 5 minutes and after 3 minutes the user selects **Auto refresh** to manually refresh the workbook, the **Auto refresh** interval resets and the workbook will be auto-refreshed after 5 minutes.

-* This setting isn't saved with the workbook. Every time a user opens a workbook, **Auto refresh** is **Off** and needs to be set again.

-* Switching workbooks and going out of the gallery clears the **Auto refresh** interval.

-## Next steps

-[Azure Workbooks data sources](workbooks-data-sources.md)

-| Link action | Action on click |

-| Link action | Action on click |

-| Link action | Action on click |

-|Resource Overview| Opens the resource's view in the portal based on the resource ID value in the cell. You can also optionally set a submenu value that will open a specific menu item in the resource view. |

-|Resource group id comes from| The resource ID is used to manage deployed resources. The subscription is used to manage deployed resources and costs. The resource groups are used like folders to organize and manage all your resources. If this value isn't specified, the deployment will fail. Select from **Cell**, **Column**, **Parameter**, and **Static Value** in [Link sources](#link-sources).|

-|ARM template URI from| The URI to the ARM template itself. The template URI needs to be accessible to the users who will deploy the template. Select from **Cell**, **Column**, **Parameter**, and **Static Value** in [Link sources](#link-sources). For more information, see [Azure quickstart templates](https://azure.microsoft.com/resources/templates/).|

-|ARM Template Parameters|Defines the template parameters used for the template URI defined earlier. These parameters are used to deploy the template on the run page. The grid contains an **Expand** toolbar button to help fill the parameters by using the names defined in the template URI and set to static empty values. This option can only be used when there are no parameters in the grid and the template URI has been set. The lower section is a preview of what the parameter output looks like. Select **Refresh** to update the preview with current changes. Parameters are typically values. References are something that could point to key vault secrets that the user has access to. <br/><br/> **Template Viewer pane limitation** doesn't render reference parameters correctly and will show up as null/value. As a result, users won't be able to correctly deploy reference parameters from the **Template Viewer** tab.|

-This section configures what you'll see before you run the Resource Manager deployment.

-|Run button text from| Label used on the run (execute) button to deploy the ARM template. Users will select this button to start deploying the ARM template.|

-Use this setting to open **Custom Views** in the Azure portal. Verify the configuration and settings. Incorrect values will cause errors in the portal or fail to open the views correctly. There are two ways to configure the settings: via the form or URL.

-|Workbook owner Resource Id comes from| This value is the Resource ID of the Azure resource that "owns" the workbook. Commonly, it's an Application Insights resource or a Log Analytics workspace. Inside of Azure Monitor, this value might also be the literal string `"Azure Monitor"`. When the workbook is saved, this value is what the workbook is linked to. |

-|Template Id comes from| Specify the ID of the template to be opened. A community template from the gallery is the most common case. Prefix the path to the template with `Community-`, like `Community-Workbooks/Performance/Apdex` for the `Workbooks/Performance/Apdex` template. If it's a link to a saved workbook or template, use the full Azure resource ID of that item. |

-|Location comes from| The location field should be specified if you're opening a specific workbook resource. If location isn't specified, finding the workbook content is much slower. If you know the location, specify it. If you don't know the location or are opening a template with no specific location, leave this field as `Default`.|

-For each of the preceding settings, you must choose where the value in the linked workbook will come from. See [Link sources](#link-sources).

-|Static Value| When selected, a field appears where you can enter a static value that's used in the linked workbook. This value is commonly used when all the rows in the grid will use the same value for a field. |

-[Get started with Azure Workbooks](workbooks-getting-started.md)

-[Getting started with Azure Workbooks](workbooks-getting-started.md)

-description: Learn how to retrieve deprecated legacy and private Azure workbooks.

-# Retrieve legacy Application Insights workbooks

-Private and legacy workbooks have been deprecated and aren't accessible from the Azure portal. If you're looking for the deprecated workbook that you forgot to convert before the deadline, you can use this process to retrieve the content of your old workbook and load it into a new workbook. This tool will only be available for a limited time.

-Application Insights Workbooks, also known as "Legacy Workbooks", are stored as a different Azure resource type than all other Azure Workbooks. These different Azure resource types are now being merged one single standard type so that you can take advantage of all the existing and new functionality available in standard Azure Workbooks. For example:

-* Converted legacy workbooks can be queried via Azure Resource Graph (ARG), and show up in other standard Azure views of resources in a resource group or subscription.

-* Converted legacy workbooks can support top level ARM template features like other resource types, including, but not limited to:

- * Tags

- * Policies

- * Activity Log / Change Tracking

- * Resource locks

-* Converted legacy workbooks can support [ARM templates](workbooks-automate.md).

-* Converted legacy workbooks can support the [BYOS](workbooks-bring-your-own-storage.md) feature.

-* Converted legacy workbooks can be saved in region of your choice.

-The legacy workbook deprecation doesn't change where you find your workbooks in the Azure portal. The legacy workbooks are still visible in the Workbooks section of Application Insights. The deprecation won't affect the content of your workbook.

-> [!NOTE]

->

-> - After April 15 2021, you will not be able to save legacy workbooks.

-> - Use `Save as` on a legacy workbook to create a standard Azure workbook.

-> - Any new workbook you create will be a standard workbook.

-## Why isn't there an automatic conversion?

-For these reasons, we suggest that users manually migrate the workbooks they want to keep.

-## Convert a legacy Application Insights workbook

-1. Identify legacy workbooks. In the gallery view, legacy workbooks have a warning icon. When you open a legacy workbook, there's a banner.

- :::image type="content" source="media/workbooks-retrieve-legacy-workbooks/workbooks-legacy-warning.png" alt-text="Screenshot of the warning symbol on a deprecated workbook.":::

- :::image type="content" source="media/workbooks-retrieve-legacy-workbooks/workbooks-legacy-banner.png" alt-text="Screenshot of the banner at the top of a deprecated workbook.":::

-1. Convert the legacy workbooks. For any legacy workbook you want to keep after June 30 2021:

- 1. Open the workbook, and then from the toolbar, select **Edit**, then **Save As**.

- 1. Enter the workbook name.

- 1. Select a subscription, resource group, and region where you have write access.

- 1. If the Legacy Workbook uses links to other Legacy Workbooks, or loading workbook content in groups, those items will need to be updated to point to the newly saved workbook.

- 1. After you have saved the workbook, you can delete the legacy Workbook, or update its contents to be a link to the newly saved workbook.

-1. Verify permissions. For legacy workbooks, permissions were based on the Application Insights specific roles, like Application Insights Contributor. Verify that users of the new workbook have the appropriate standard Monitoring Reader/Contributor or Workbook Reader/Contributor roles so that they can see and create Workbooks in the appropriate resource groups.

-For more information, see [access control](workbooks-overview.md#access-control).

-After deprecation of the legacy workbooks, you'll still be able to retrieve the content of Legacy Workbooks for a limited time by using Azure CLI or PowerShell tools, to query `microsoft.insights/components/[name]/favorites` for the specific resource using `api-version=2015-05-01`.

-## Convert a private workbook

-1. Open a new or empty workbook.

-1. In the toolbar, select **Edit** and then navigate to the advanced editor.

- :::image type="content" source="media/workbooks-retrieve-legacy-workbooks/workbooks-retrieve-deprecated-advanced-editor.png" alt-text="Screenshot of the advanced editor used to retrieve deprecated workbooks.":::

-1. Copy the [workbook json](#json-for-private-workbook-conversion) and paste it into your open advanced editor.

-1. Select **Apply** at the top right.

-1. Select the subscription and resource group and category of the workbook you'd like to retrieve.

-1. The grid at the bottom of this workbook lists all the private workbooks in the selected subscription or resource group.

-1. Select one of the workbooks in the grid. Your workbook should look something like this:

- :::image type="content" source="media/workbooks-retrieve-legacy-workbooks/workbooks-retrieve-deprecated-private.png" alt-text="Screenshot of a deprecated private workbook converted to a standard workbook." lightbox="media//workbooks-retrieve-legacy-workbooks/workbooks-retrieve-deprecated-private.png":::

-1. Select **Open Content as Workbook** at the bottom of the workbook.

-1. A new workbook appears with the content of the old private workbook that you selected. Save the workbook as a standard workbook.

-1. You have to re-create links to the deprecated workbook or its contents, including dashboard pins and URL links.

-## Convert a favorites-based (legacy) workbook

-

-1. Navigate to your Application Insights Resource > Workbooks gallery.

-1. Open a new or empty workbook.

-1. Select Edit in the toolbar and navigate to the advanced editor.

- :::image type="content" source="media/workbooks-retrieve-legacy-workbooks/workbooks-retrieve-deprecated-advanced-editor.png" alt-text="Screenshot of the advanced editor used to retrieve deprecated workbooks.":::

-1. Copy the [workbook json](#json-for-private-workbook-conversion) and paste it into your open advanced editor.

-1. Select **Apply**.

-1. The grid at the bottom of this workbook lists all the legacy workbooks within the current AppInsights resource.

-1. Select one of the workbooks in the grid. Your workbook should now look something like this:

- :::image type="content" source="media/workbooks-retrieve-legacy-workbooks/workbooks-retrieve-deprecated-legacy.png" alt-text="Screenshot of a deprecated legacy workbook converted to a standard workbook." lightbox="media/workbooks-retrieve-legacy-workbooks/workbooks-retrieve-deprecated-legacy.png":::

-1. Select **Open Content as Workbook** at the bottom of the workbook.

-1. A new workbook appears with the content of the old private workbook that you selected. Save the workbook as a standard workbook.

-1. You have to re-create links to the deprecated workbook or its contents, including dashboard pins and URL links.

-## JSON for legacy workbook conversion

-```json

-{

- "version": "Notebook/1.0",

- "items": [

- {

- "type": 9,

- "content": {

- "version": "KqlParameterItem/1.0",

- "parameters": [

- {

- "id": "876235fc-ef67-418d-87f5-69f496be171b",

- "version": "KqlParameterItem/1.0",

- "name": "resource",

- "type": 5,

- "typeSettings": {

- "additionalResourceOptions": [

- "value::1"

- ],

- "componentIdOnly": true

- },

- "timeContext": {

- "durationMs": 86400000

- },

- "defaultValue": "value::1"

- }

- ],

- "style": "pills",

- "queryType": 0,

- "resourceType": "microsoft.insights/components"

- },

- "conditionalVisibility": {

- "parameterName": "debug",

- "comparison": "isNotEqualTo"

- },

- "name": "resource selection"

- },

- {

- "type": 1,

- "content": {

- "json": "# Legacy (Favorites based) Workbook Conversion\r\n\r\nThis workbook shows favorite based (legacy) workbooks in this Application Insights resource: \r\n\r\n{resource:grid}\r\n\r\nThe grid below will show the favorite workbooks found, and allows you to copy the contents, or open them as a full Azure Workbook where they can be saved."

- },

- "name": "text - 5"

- },

- {

- "type": 3,

- "content": {

- "version": "KqlItem/1.0",

- "query": "{\"version\":\"ARMEndpoint/1.0\",\"data\":null,\"headers\":[],\"method\":\"GETARRAY\",\"path\":\"{resource}/favorites\",\"urlParams\":[{\"key\":\"api-version\",\"value\":\"2015-05-01\"},{\"key\":\"sourceType\",\"value\":\"notebook\"},{\"key\":\"canFetchContent\",\"value\":\"false\"}],\"batchDisabled\":false,\"transformers\":[{\"type\":\"jsonpath\",\"settings\":{\"columns\":[{\"path\":\"$.Name\",\"columnid\":\"name\"},{\"path\":\"$.FavoriteId\",\"columnid\":\"id\"},{\"path\":\"$.TimeModified\",\"columnid\":\"modified\",\"columnType\":\"datetime\"},{\"path\":\"$.FavoriteType\",\"columnid\":\"type\"}]}}]}",

- "size": 0,

- "title": "Legacy Workbooks (Select an item to see contents)",

- "noDataMessage": "No legacy workbooks found",

- "noDataMessageStyle": 3,

- "exportedParameters": [

- {

- "fieldName": "id",

- "parameterName": "favoriteId"

- },

- {

- "fieldName": "name",

- "parameterName": "name",

- "parameterType": 1

- }

- ],

- "queryType": 12,

- "gridSettings": {

- "rowLimit": 1000,

- "filter": true

- }

- },

- "name": "list favorites"

- },

- {

- "type": 9,

- "content": {

- "version": "KqlParameterItem/1.0",

- "parameters": [

- {

- "id": "8d78556d-a4f3-4868-bf06-9e0980246d31",

- "version": "KqlParameterItem/1.0",

- "name": "config",

- "type": 1,

- "query": "{\"version\":\"ARMEndpoint/1.0\",\"data\":null,\"headers\":[],\"method\":\"GET\",\"path\":\"{resource}/favorites/{favoriteId}\",\"urlParams\":[{\"key\":\"api-version\",\"value\":\"2015-05-01\"},{\"key\":\"sourceType\",\"value\":\"notebook\"},{\"key\":\"canFetchContent\",\"value\":\"true\"}],\"batchDisabled\":false,\"transformers\":[{\"type\":\"jsonpath\",\"settings\":{\"columns\":[{\"path\":\"$.Config\",\"columnid\":\"Content\"}]}}]}",

- "timeContext": {

- "durationMs": 86400000

- },

- "queryType": 12

- }

- ],

- "style": "pills",

- "queryType": 12

- },

- "conditionalVisibility": {

- "parameterName": "debug",

- "comparison": "isNotEqualTo"

- },

- "name": "turn response into param"

- },

- {

- "type": 11,

- "content": {

- "version": "LinkItem/1.0",

- "style": "list",

- "links": [

- {

- "id": "fc93ee9e-d5b2-41de-b74a-1fb62f0df49e",

- "linkTarget": "OpenBlade",

- "linkLabel": "Open Content as Workbook",

- "style": "primary",

- "bladeOpenContext": {

- "bladeName": "UsageNotebookBlade",

- "extensionName": "AppInsightsExtension",

- "bladeParameters": [

- {

- "name": "ComponentId",

- "source": "parameter",

- "value": "resource"

- },

- {

- "name": "NewNotebookData",

- "source": "parameter",

- "value": "config"

- }

- ]

- }

- }

- ]

- },

- "conditionalVisibility": {

- "parameterName": "config",

- "comparison": "isNotEqualTo"

- },

- "name": "links - 4"

- }

- ],

- "$schema": "https://github.com/Microsoft/Application-Insights-Workbooks/blob/master/schema/workbook.json"

-}

-```

-## JSON for private workbook conversion

-```json

-{

- "version": "Notebook/1.0",

- "items": [

- {

- "type": 9,

- "content": {

- "version": "KqlParameterItem/1.0",

- "crossComponentResources": [

- "{Subscription}"

- ],

- "parameters": [

- {

- "id": "1f74ed9a-e3ed-498d-bd5b-f68f3836a117",

- "version": "KqlParameterItem/1.0",

- "name": "Subscription",

- "type": 6,

- "isRequired": true,

- "typeSettings": {

- "additionalResourceOptions": [

- "value::1"

- ],

- "includeAll": false,

- "showDefault": false

- }

- },

- {

- "id": "b616a3a3-4271-4208-b1a9-a92a78efed08",

- "version": "KqlParameterItem/1.0",

- "name": "ResourceGroup",

- "label": "Resource group",

- "type": 2,

- "isRequired": true,

- "query": "Resources\r\n| summarize by resourceGroup\r\n| order by resourceGroup asc\r\n| project id=resourceGroup, resourceGroup",

- "crossComponentResources": [

- "{Subscription}"

- ],

- "typeSettings": {

- "additionalResourceOptions": [

- "value::1"

- ],

- "showDefault": false

- },

- "queryType": 1,

- "resourceType": "microsoft.resourcegraph/resources"

- },

- {

- "id": "3872fc90-1467-4b01-81ef-d82d90665d72",

- "version": "KqlParameterItem/1.0",

- "name": "Category",

- "type": 2,

- "description": "Workbook Category",

- "isRequired": true,

- "typeSettings": {

- "additionalResourceOptions": [],

- "showDefault": false

- },

- "jsonData": "[\"workbook\",\"sentinel\",\"usage\",\"tsg\",\"usageMetrics\",\"workItems\",\"performance-websites\",\"performance-appinsights\",\"performance-documentdb\",\"performance-storage\",\"performance-storageclassic\",\"performance-vm\",\"performance-vmclassic\",\"performance-sqlserverdatabases\",\"performance-virtualnetwork\",\"performance-virtualmachinescalesets\",\"performance-computedisks\",\"performance-networkinterfaces\",\"performance-logicworkflows\",\"performance-appserviceplans\",\"performance-applicationgateway\",\"performance-runbooks\",\"performance-servicebusqueues\",\"performance-iothubs\",\"performance-networkroutetables\",\"performance-cognitiveserviceaccounts\",\"performance-containerservicemanagedclusters\",\"performance-servicefabricclusters\",\"performance-cacheredis\",\"performance-eventhubnamespaces\",\"performance-hdinsightclusters\",\"failure-websites\",\"failure-appinsights\",\"failure-documentdb\",\"failure-storage\",\"failure-storageclassic\",\"failure-vm\",\"failure-vmclassic\",\"failure-sqlserverdatabases\",\"failure-virtualnetwork\",\"failure-virtualmachinescalesets\",\"failure-computedisks\",\"failure-networkinterfaces\",\"failure-logicworkflows\",\"failure-appserviceplans\",\"failure-applicationgateway\",\"failure-runbooks\",\"failure-servicebusqueues\",\"failure-iothubs\",\"failure-networkroutetables\",\"failure-cognitiveserviceaccounts\",\"failure-containerservicemanagedclusters\",\"failure-servicefabricclusters\",\"failure-cacheredis\",\"failure-eventhubnamespaces\",\"failure-hdinsightclusters\",\"storage-insights\",\"cosmosdb-insights\",\"vm-insights\",\"container-insights\",\"keyvaults-insights\",\"backup-insights\",\"rediscache-insights\",\"servicebus-insights\",\"eventhub-insights\",\"workload-insights\",\"adxcluster-insights\",\"wvd-insights\",\"activitylog-insights\",\"hdicluster-insights\",\"laws-insights\",\"hci-insights\"]",

- "defaultValue": "workbook"

- }

- ],

- "queryType": 1,

- "resourceType": "microsoft.resourcegraph/resources"

- },

- "name": "resource selection"

- },

- {

- "type": 1,

- "content": {

- "json": "# Private Workbook Conversion\r\n\r\nThis workbook shows private workbooks within the current subscription / resource group: \r\n\r\n| Subscription | Resource Group | \r\n|--|-|\r\n|{Subscription}|{ResourceGroup} |\r\n\r\nThe grid below will show the private workbooks found, and allows you to copy the contents, or open them as a full Azure Workbook where they can be saved.\r\n\r\nUse the button below to load the selected private workbook content into a new workbook. From there you can save it as a new workbook."

- },

- "name": "text - 5"

- },

- {

- "type": 3,

- "content": {

- "version": "KqlItem/1.0",

- "query": "{\"version\":\"ARMEndpoint/1.0\",\"data\":null,\"headers\":[],\"method\":\"GETARRAY\",\"path\":\"/{Subscription}/resourceGroups/{ResourceGroup}/providers/microsoft.insights/myworkbooks\",\"urlParams\":[{\"key\":\"api-version\",\"value\":\"2020-10-20\"},{\"key\":\"category\",\"value\":\"{Category}\"}],\"batchDisabled\":false,\"transformers\":[{\"type\":\"jsonpath\",\"settings\":{\"tablePath\":\"$..[?(@.kind == \\\"user\\\")]\",\"columns\":[{\"path\":\"$.properties.displayName\",\"columnid\":\"name\"},{\"path\":\"$.name\",\"columnid\":\"id\"},{\"path\":\"$.kind\",\"columnid\":\"type\",\"columnType\":\"string\"},{\"path\":\"$.properties.timeModified\",\"columnid\":\"modified\",\"columnType\":\"datetime\"},{\"path\":\"$.properties.sourceId\",\"columnid\":\"resource\",\"columnType\":\"string\"}]}}]}",

- "size": 1,

- "title": "Private Workbooks",

- "noDataMessage": "No private workbooks found",

- "noDataMessageStyle": 3,

- "exportedParameters": [

- {

- "fieldName": "id",

- "parameterName": "id"

- },

- {

- "fieldName": "name",

- "parameterName": "name",

- "parameterType": 1

- },

- {

- "fieldName": "resource",

- "parameterName": "resource",

- "parameterType": 1

- }

- ],

- "queryType": 12,

- "gridSettings": {

- "formatters": [

- {

- "columnMatch": "resource",

- "formatter": 13,

- "formatOptions": {

- "linkTarget": null,

- "showIcon": true

- }

- }

- ],

- "rowLimit": 1000,

- "filter": true,

- "labelSettings": [

- {

- "columnId": "resource",

- "label": "Linked To"

- }

- ]

- },

- "sortBy": []

- },

- "name": "list private workbooks"

- },

- {

- "type": 9,

- "content": {

- "version": "KqlParameterItem/1.0",

- "parameters": [

- {

- "id": "8d78556d-a4f3-4868-bf06-9e0980246d31",

- "version": "KqlParameterItem/1.0",

- "name": "config",

- "type": 1,

- "query": "{\"version\":\"ARMEndpoint/1.0\",\"data\":null,\"headers\":[],\"method\":\"GET\",\"path\":\"{Subscription}/resourceGroups/{ResourceGroup}/providers/microsoft.insights/myworkbooks/{id}\",\"urlParams\":[{\"key\":\"api-version\",\"value\":\"2020-10-20\"},{\"key\":\"sourceType\",\"value\":\"notebook\"},{\"key\":\"canFetchContent\",\"value\":\"true\"}],\"batchDisabled\":false,\"transformers\":[{\"type\":\"jsonpath\",\"settings\":{\"columns\":[{\"path\":\"$..serializedData\",\"columnid\":\"Content\"}]}}]}",

- "timeContext": {

- "durationMs": 86400000

- },

- "queryType": 12

- }

- ],

- "style": "pills",

- "queryType": 12

- },

- "conditionalVisibility": {

- "parameterName": "debug",

- "comparison": "isNotEqualTo"

- },

- "name": "turn response into param"

- },

- {

- "type": 11,

- "content": {

- "version": "LinkItem/1.0",

- "style": "list",

- "links": [

- {

- "id": "fc93ee9e-d5b2-41de-b74a-1fb62f0df49e",

- "linkTarget": "OpenBlade",

- "linkLabel": "Open Content as Workbook",

- "style": "primary",

- "bladeOpenContext": {

- "bladeName": "UsageNotebookBlade",

- "extensionName": "AppInsightsExtension",

- "bladeParameters": [

- {

- "name": "ComponentId",

- "source": "parameter",

- "value": "resource"

- },

- {

- "name": "NewNotebookData",

- "source": "parameter",

- "value": "config"

- }

- ]

- }

- }

- ]

- },

- "conditionalVisibility": {

- "parameterName": "config",

- "comparison": "isNotEqualTo"

- },

- "name": "links - 4"

- }

- ],

- "$schema": "https://github.com/Microsoft/Application-Insights-Workbooks/blob/master/schema/workbook.json"

-}

-```

-[Get started with Azure Workbooks](workbooks-getting-started.md)

-[Get started with Azure Workbooks](workbooks-getting-started.md)

-Application-Insights|[Migrate to workspace-based Application Insights resources](app/convert-classic-resource.md)|We confirmed that migrating from classic to workspace-based resources doesn't introduce application downtime or restarts, and it does not change your existing instrumentation key or connection string.|"

-Essentials|[Collect Prometheus metrics from an AKS cluster](containers/prometheus-metrics-enable.md)|Updated to include additional onboarding methods.|

-Logs|[Enable the ContainerLogV2 schema](containers/container-insights-logging-v2.md)|Updated configuration section.|

-Essentials|[Collect Prometheus metrics from an AKS cluster (preview)](essentials/prometheus-metrics-enable.md)|Enabled Windows metric collection metrics add-on.|

-Essentials|[Collect Prometheus metrics from AKS cluster (preview)](essentials/prometheus-metrics-enable.md)|Added enabling Prometheus metric collection by using Azure Policy and Bicep.|

-Containers|[Azure Monitor container insights for Azure Kubernetes Service hybrid clusters (preview)](containers/container-insights-enable-provisioned-clusters.md)|New article.|

-Essentials Prometheus|<ul> <li> [Azure Monitor workspace overview (preview)](essentials/azure-monitor-workspace-overview.md?tabs=azure-portal) </li><li> [Overview of Azure Monitor managed service for Prometheus (preview)](essentials/prometheus-metrics-overview.md) </li><li>[Rule groups in Azure Monitor managed service for Prometheus (preview)](essentials/prometheus-rule-groups.md)</li><li>[Remote-write in Azure Monitor managed service for Prometheus (preview)](essentials/prometheus-remote-write-managed-identity.md) </li><li>[Use Azure Monitor managed service for Prometheus (preview) as data source for Grafana](essentials/prometheus-grafana.md)</li><li>[Troubleshoot collection of Prometheus metrics in Azure Monitor (preview)](essentials/prometheus-metrics-troubleshoot.md)</li><li>[Default Prometheus metrics configuration in Azure Monitor (preview)](essentials/prometheus-metrics-scrape-default.md)</li><li>[Scrape Prometheus metrics at scale in Azure Monitor (preview)](essentials/prometheus-metrics-scrape-scale.md)</li><li>[Customize scraping of Prometheus metrics in Azure Monitor (preview)](essentials/prometheus-metrics-scrape-configuration.md)</li><li>[Create, validate, and troubleshoot custom configuration file for Prometheus metrics in Azure Monitor (preview)](essentials/prometheus-metrics-scrape-validate.md)</li><li>[Minimal Prometheus ingestion profile in Azure Monitor (preview)](essentials/prometheus-metrics-scrape-configuration-minimal.md)</li><li>[Collect Prometheus metrics from AKS cluster (preview)](essentials/prometheus-metrics-enable.md)</li><li>[Send Prometheus metrics to multiple Azure Monitor workspaces (preview)](essentials/prometheus-metrics-multiple-workspaces.md) </li></ul> |New articles: Public preview of Azure Monitor managed service for Prometheus.|

-| [Configure ContainerLogv2 schema (preview) for Container insights](containers/container-insights-logging-v2.md) | New article: Describes new schema for container logs. |

-# What is Azure NetApp Files

-Azure NetApp Files is an Azure native, first-party, enterprise-class, high-performance file storage service. It provides NAS volumes as a service for which you can create NetApp accounts, capacity pools, select service and performance levels, create volumes, and manage data protection. It allows you to create and manage high-performance, highly available, and scalable file shares, using the same protocols and tools that you're familiar with and enterprise applications rely on on-premises. Azure NetApp Files supports SMB and NFS protocols and can be used for various use cases such as file sharing, home directories, databases, high-performance computing and more. Additionally, it also provides built-in availability, data protection and disaster recovery capabilities.

-* [Managing Azure NetApp Files preview features with Terraform Cloud and AzAPI Provider](https://techcommunity.microsoft.com/t5/azure-architecture-blog/managing-azure-netapp-files-preview-features-with-terraform/ba-p/3657714)

-## Backup and restoration

-Private cloud vCenter Server and NSX-T Data Center configurations are on an hourly backup schedule. Backups are kept for three days. If you need to restore from a backup, open a [support request](https://rc.portal.azure.com/#create/Microsoft.Support) in the Azure portal to request restoration.

-You can connect a private cloud to multiple private clouds, and the connections are nontransitive. For example, if _private cloud 1_ is connected to _private cloud 2_, and _private cloud 2_ is connected to _private cloud 3_, private clouds 1 and 3 wouldn't communicate until they were directly connected.

->The **AVS interconnect** feature doesn't check for overlapping IP space the way native Azure vNet peering does before creating the peering. Therefore, it's your responsibility to ensure that there isn't overlap between the private clouds.

->In Azure VMware Solution environments, it's possible to configure non-routed, overlapping IP deployments on NSX segments that aren't routed to Azure. These don't cause issues with the AVS Interconnect feature, as it only routes between the NSX-T Data Center T0 gateway on each private cloud.

-The placement policy feature is available in all Azure VMware Solution regions.

-Placement policies let you control the placement of virtual machines (VMs) on hosts within a cluster through the Azure portal.

-When you create a placement policy, it includes a DRS rule in the specified vSphere cluster.

-It also includes other logic for interoperability with Azure VMware Solution operations.

-### Cluster scale in

-

-### As this is an existing functionality available in vCenter, why can't I use it directly?

-Azure VMware Solution provides a VMware private cloud in Azure. In this managed VMware infrastructure, Microsoft manages the clusters, hosts, datastores, and distributed virtual switches in the private cloud. At the same time, the tenant is responsible for managing the workloads deployed on the private cloud. As a result, the tenant administering the private cloud doesn't have the [same set of privileges](concepts-identity.md) as available to the VMware administrator in an on-premises deployment.

-Further, the lack of the desired granularity in the vSphere privileges presents some challenges when managing the placement of the workloads on the private cloud. For example, vSphere DRS rules commonly used on-premises to define affinity and anti-affinity rules can't be used as-is in an Azure VMware Solution environment, as some of those rules can block day-to-day operation the private cloud. Placement Policies provides a way to define those rules using the Azure VMware Solution portal, thereby circumventing the need to use DRS rules. Coupled with a simplified experience, Placement Policies ensure the rules don't impact the day-to-day infrastructure maintenance and operation activities.

-Azure Database for PostgreSQL server backup is available in the following regions:

-East US, East US 2, Central US, South Central US, West US, West US 2, West Central US, Brazil South, Canada Central, North Europe, West Europe, UK South, UK West, Germany West Central, Switzerland North, Switzerland West, East Asia, Southeast Asia, Japan East, Japan West, Korea Central, Korea South, India Central, Australia East, Australia Central, Australia Central 2, UAE North

-Azure Content Delivery Network (CDN) includes four products:

-Azure Container Apps Health probes are based on [Kubernetes health probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/). These probes allow the Container Apps runtime to regularly inspect the status of your container apps.

-> [Conditional Access policy components](../active-directory/conditional-access/concept-conditional-access-policies.md).

-* [Geo-replicationin Azure Container Registry](container-registry-geo-replication.md)

-To estimate the minimum throughput required of a container with manual throughput, find the maximum of:

-To estimate the minimum throughput required of a shared throughput database with manual throughput, find the maximum of:

-For example, you have a database provisioned with 400 RU/s, 15 GB of storage, and 10 containers. The minimum RU/s is `MAX(400, 15 * 1 RU/s per GB, 400 / 100, 400 + 0 )` = 400 RU/s. If there were 30 containers in the database, the minimum RU/s would be `400 + MAX(30 - 25, 0) * 100 RU/s` = 900 RU/s.

-In summary, here are the minimum provisioned RU limits when using manual throughput.

-| Resource | Limit |

-| | |

-| Minimum RUs per container ([dedicated throughput provisioned mode with manual throughput](./resource-model.md#azure-cosmos-db-containers)) | 400 |

-| Minimum RUs per database ([shared throughput provisioned mode with manual throughput](./resource-model.md#azure-cosmos-db-containers)) | 400 RU/s for first 25 containers. |

-> [Download latest version (``2.14.12``)](https://aka.ms/cosmosdb-emulator)

-## Latest version ``2.14.12``

-> *Released March 20, 2023*

- - ignite-2023

-* Create an Azure Cosmos DB for NoSQL account by using the steps described in the [create database account](quickstart-java.md#create-a-database-account) section of the Java quickstart article.

- >!Note

- The list of capabilities must always specify all capabilities that you want to enable, inclusively. This includes capabilities that are already enabled for the account that you want to keep.

-description: Deploy a .NET web application to manage Azure Cosmos DB for NoSQL account resources in this quickstart.

-zone_pivot_groups: azure-cosmos-db-quickstart-path

-# CustomerIntent: As a developer, I want to learn the basics of the .NET client library so that I can build applications with Azure Cosmos DB for NoSQL.

-# Quickstart: Azure Cosmos DB for NoSQL client library for .NET

-Get started with the Azure Cosmos DB client library for .NET to create databases, containers, and items within your account. Follow these steps to deploy a sample application and explore the code. In this quickstart, you use the Azure Developer CLI (`azd`) and the `Microsoft.Azure.Cosmos` library to connect to a newly created Azure Cosmos DB for NoSQL account.

- - No Azure subscription? You can [try Azure Cosmos DB free](../try-free.md) with no credit card required.

-## Deploy the Azure Developer CLI template

-Use the Azure Developer CLI (`azd`) to create an Azure Cosmos DB for NoSQL account and set up an Azure Container Apps web application. The sample application uses the client library for .NET to manage resources.

-1. Start in an empty directory in the Azure Cloud Shell.

- > [!TIP]

- > We recommend creating a new uniquely named directory within the fileshare folder (`~/clouddrive`).

- >

- > For example, this command will create a new directory and navigate to that directory:

- >

- > ```azurecli-interactive

- > mkdir ~/clouddrive/cosmos-db-nosql-dotnet-quickstart

- >

- > cd ~/clouddrive/cosmos-db-nosql-dotnet-quickstart

- > ```

-1. Initialize the Azure Developer CLI using `azd init` and the `cosmos-db-nosql-dotnet-quickstart` template.

- ```azurecli-interactive

- azd init --template cosmos-db-nosql-dotnet-quickstart

- ```

-1. During initialization, configure a unique environment name.

- > [!NOTE]

- > The environment name will also be used as the target resource group name.

-1. Deploy the Azure Cosmos DB account and other resources for this quickstart with `azd provision`.

- ```azurecli-interactive

- azd provision

- ```

-1. During the provisioning process, select your subscription and desired location. Wait for the provisioning process to complete. The process can take **approximately five minutes**.

-1. Once the provisioning of your Azure resources is done, a link to the running web application is included in the output.

- ```output

- View the running web application in Azure Container Apps:

- <https://container-app-39423723798.redforest-xz89v7c.eastus.azurecontainerapps.io>

-

- SUCCESS: Your application was provisioned in Azure in 5 minutes 0 seconds.

- ```

-1. Use the link in the console to navigate to your web application in the browser.

- :::image type="content" source="media/quickstart-dotnet/web-application.png" alt-text="Screenshot of the running web application.":::

-## Get the application code

-Use the Azure Developer CLI (`azd`) to get the application code. The sample application uses the client library for .NET to manage resources.

-1. Start in an empty directory.

-1. Initialize the Azure Developer CLI using `azd init` and the `cosmos-db-nosql-dotnet-quickstart` template.

- ```azurecli

- azd init --template cosmos-db-nosql-dotnet-quickstart

- ```

-1. During initialization, configure a unique environment name.

- > [!NOTE]

- > If you decide to deploy this application to Azure in the future, the environment name will also be used as the target resource group name.

-## Create the API for NoSQL account

-Use the Azure CLI (`az`) to create an API for NoSQL account. You can choose to create an account in your existing subscription, or try a free Azure Cosmos DB account.

-### [Try Azure Cosmos DB free](#tab/try-free)

-1. Navigate to the **Try Azure Cosmos DB free** homepage: <https://cosmos.azure.com/try/>

-1. Sign-in using your Microsoft account.

-1. In the list of APIs, select the **Create** button for the **API for NoSQL**.

-1. Navigate to the newly created account by selecting **Open in portal**.

-1. Record the account and resource group names for the API for NoSQL account. You use these values in later steps.

-> [!IMPORTANT]

-> If you are using a free account, you might need to change the default subscription in Azure CLI to the subscription ID used for the free account.

->

-> ```azurecli

-> az account set --subscription <subscription-id>

-> ```

-### [Azure subscription](#tab/azure-subscription)

-1. If you haven't already, sign in to the Azure CLI using the `az login` command.

-1. Use `az group create` to create a new resource group in your subscription.

- ```azurecli

- az group create \

- --name <resource-group-name> \

- --location <location>

- ```

-1. Use the `az cosmosdb create` command to create a new API for NoSQL account with default settings.

- ```azurecli

- az cosmosdb create \

- --resource-group <resource-group-name> \

- --name <account-name> \

- --locations regionName=<location>

- ```

-## Create the database and container

-Use the Azure CLI to create the `cosmicworks` database and `products` container for the quickstart.

-1. Create a new database with `az cosmosdb sql database create`. Set the name of the database to `comsicworks` and use autoscale throughput with a maximum of **1,000** RU/s.

- ```azurecli

- az cosmosdb sql database create \

- --resource-group <resource-group-name> \

- --account-name <account-name> \

- --name "cosmicworks" \

- --max-throughput 1000

- ```

-1. Create a container named `products` within the `cosmicworks` database using `az cosmosdb sql container create`. Set the partition key path to `/category`.

- ```azurecli

- az cosmosdb sql container create \

- --resource-group <resource-group-name> \

- --account-name <account-name> \

- --database-name "cosmicworks" \

- --name "products" \

- --partition-key-path "/category"

- ```

-## Configure passwordless authentication

-When developing locally with passwordless authentication, make sure the user account that connects to Cosmos DB is assigned a role with the correct permissions to perform data operations. Currently, Azure Cosmos DB for NoSQL doesn't include built-in roles for data operations, but you can create your own using the Azure CLI or PowerShell.

-1. Get the API for NoSQL endpoint for the account using `az cosmosdb show`. You'll use this value in the next step.

- ```azurecli

- az cosmosdb show \

- --resource-group <resource-group-name> \

- --name <account-name> \

- --query "documentEndpoint"

- ```

-1. Set the `AZURE_COSMOS_DB_NOSQL_ENDPOINT` environment variable using the .NET secret manager (`dotnet user-secrets`). Set the value to the API for NoSQL account endpoint recorded in the previous step.

- dotnet user-secrets set "AZURE_COSMOS_DB_NOSQL_ENDPOINT" "<cosmos-db-nosql-endpoint>" --project ./src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj

- ```

-1. Create a JSON file named `role-definition.json`. Use this content to configure the role with the following permissions:

- - `Microsoft.DocumentDB/databaseAccounts/readMetadata`

- - `Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*`

- - `Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*`

- ```json

- {

- "RoleName": "Write to Azure Cosmos DB for NoSQL data plane",

- "Type": "CustomRole",

- "AssignableScopes": [

- "/"

- ],

- "Permissions": [

- {

- "DataActions": [

- "Microsoft.DocumentDB/databaseAccounts/readMetadata",

- "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",

- "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"

- ]

- }

- ]

- }

- ```

-1. Create a role using the `az role definition create` command. Name the role `Write to Azure Cosmos DB for NoSQL data plane` and ensure the role is scoped to the account level using `/`. Use the `role-definition.json` file you created in the previous step.

- ```azurecli

- az cosmosdb sql role definition create \

- --resource-group <resource-group-name> \

- --account-name <account-name> \

- --body @role-definition.json

- ```

-1. When the command is finished, it outputs an object that includes an `id` field. Record the value from the `id` field. You use this value in an upcoming step.

- > [!TIP]

- > If you need to get the `id` again, you can use the `az cosmosdb sql role definition list` command:

- >

- > ```azurecli

- > az cosmosdb sql role definition list \

- > --resource-group <resource-group-name> \

- > --account-name <account-name> \

- > --query "[?roleName == 'Write to Azure Cosmos DB for NoSQL data plane'].id"

- > ```

- >

-1. For local development, get your currently logged in **service principal id**. Record this value as you'll also use this value in the next step.

- ```azurecli

- az ad signed-in-user show --query id

-1. Assign the role definition to your currently logged in user using `az cosmosdb sql role assignment create`.

- ```azurecli

- az cosmosdb sql role assignment create \

- --resource-group <resource-group-name> \

- --account-name <account-name> \

- --scope "/" \

- --role-definition-id "<your-custom-role-definition-id>" \

- --principal-id "<your-service-principal-id>"

-1. Run the .NET web application.

- dotnet run --project ./src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj

-1. Use the link in the console to navigate to your web application in the browser.

- :::image type="content" source="media/quickstart-dotnet/web-application.png" alt-text="Screenshot of the running web application.":::

-## Walk through the .NET library code

-The sample code in the Azure Develop CLI template creates a database named `cosmicworks` with a container named `products`. The `products` container is designed to contain product details such as name, category, quantity, and a sale indicator. Each product also contains a unique identifier.

-For this sample, the container uses the `/category` property as a logical partition key.

-The code blocks used to perform these operations in this sample are included in this section. You can also [browse the entire template's source](https://vscode.dev/github/azure-samples/cosmos-db-nosql-dotnet-quickstart) using Visual Studio Code for the Web.

-Application requests to most Azure services must be authorized. Using the <xref:Azure.Identity.DefaultAzureCredential> class provided by the <xref:Azure.Identity> client library and namespace is the recommended approach for implementing passwordless connections to Azure services in your code.

-> [!IMPORTANT]

-> You can also authorize requests to Azure services using passwords, connection strings, or other credentials directly. However, this approach should be used with caution. Developers must be diligent to never expose these secrets in an unsecure location. Anyone who gains access to the password or secret key is able to authenticate. `DefaultAzureCredential` offers improved management and security benefits over the account key to allow passwordless authentication.

-`DefaultAzureCredential` supports multiple authentication methods and determines which method should be used at runtime.

-The client authentication code for this project is in the `src/web/Program.cs` file.

-For example, your app can authenticate using your Visual Studio sign-in credentials when developing locally, and then use a system-assigned managed identity once it has been deployed to Azure. No code changes are required for this transition between environments.

-Alternatively, your app can specify a `clientId` with the <xref:Azure.Identity.DefaultAzureCredentialOptions> class to use a user-assigned managed identity locally or in Azure.

-The code to access database resources is in the `GenerateQueryDataAsync` method of the `src/web/Pages/Index.razor` file.

-Use the <xref:Microsoft.Azure.Cosmos.CosmosClient.GetDatabase%2A> method to return a reference to the specified database.

-The code to access container resources is also in the `GenerateQueryDataAsync` method.

-The <xref:Microsoft.Azure.Cosmos.Database.GetContainer%2A> returns a reference to the specified container.

-The easiest way to create a new item in a container is to first build a C# class or record type with all of the members you want to serialize into JSON. In this example, the C# record has a unique identifier, a `category` field for the partition key, name, quantity, price, and clearance fields.

-In the `GenerateQueryDataAsync` method, create an item in the container by calling <xref:Microsoft.Azure.Cosmos.Container.UpsertItemAsync%2A>.

-In Azure Cosmos DB, you can perform a point read operation by using both the unique identifier (`id`) and partition key fields. In the SDK, call <xref:Microsoft.Azure.Cosmos.Container.ReadItemAsync%2A> passing in both values to return a deserialized instance of your C# type.

-Still in the `GenerateQueryDataAsync` method, use `ReadItemAsync<Product>` to serialize the item using the `Product` type.

-After you insert an item, you can run a query to get all items that match a specific filter. This example runs the SQL query: `SELECT * FROM products p WHERE p.category = "gear-surf-surfboards"`. This example uses the QueryDefinition type and a parameterized query expression for the partition key filter. Once the query is defined, call <xref:Microsoft.Azure.Cosmos.Container.GetItemQueryIterator%2A> to get a result iterator that manages the pages of results. In the example, the query logic is also in the `GenerateQueryDataAsync` method.

-Then, use a combination of `while` and `foreach` loops to retrieve pages of results and then iterate over the individual items.

-## Clean up resources

-When you no longer need the sample application or resources, remove the corresponding deployment and all resources.

-```azurecli-interactive

-azd down

-### [Try Azure Cosmos DB free](#tab/try-free)

-1. Navigate to the **Try Azure Cosmos DB free** homepage again: <https://cosmos.azure.com/try/>

-1. Sign-in using your Microsoft account.

-1. Select **Delete your account**.

-### [Azure subscription](#tab/azure-subscription)

-When you no longer need the API for NoSQL account, you can delete the corresponding resource group. Use the `az group delete` command to delete the resource group.

-```azurecli

-az group delete --name <resource-group-name>

-```

-> [Tutorial: Develop a .NET console application with Azure Cosmos DB for NoSQL](tutorial-dotnet-console-app.md)

-description: Gives a Go code sample you can use to connect to and query the Azure Cosmos DB for NoSQL

-# Quickstart: Build a Go application using an Azure Cosmos DB for NoSQL account

-> [!div class="op_single_selector"]

->

-> * [.NET](quickstart-dotnet.md)

-> * [Node.js](quickstart-nodejs.md)

-> * [Java](quickstart-java.md)

-> * [Spring Data](quickstart-java-spring-data.md)

-> * [Python](quickstart-python.md)

-> * [Spark v3](quickstart-spark.md)

-> * [Go](quickstart-go.md)

->

-> [!IMPORTANT]

-> The Go SDK for Azure Cosmos DB is currently in beta. This beta is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities.

->

-> For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-In this quickstart, you'll build a sample Go application that uses the Azure SDK for Go to manage an Azure Cosmos DB for NoSQL account. Without a credit card or an Azure subscription, you can set up a free [Try Azure Cosmos DB account](https://aka.ms/trycosmosdb)

-Azure Cosmos DB is a multi-model database service that lets you quickly create and query document, table, key-value, and graph databases with global distribution and horizontal scale capabilities.

-To learn more about Azure Cosmos DB, go to [Azure Cosmos DB](../introduction.md).

-## Prerequisites

- - No Azure subscription? You can [try Azure Cosmos DB free](../try-free.md) with no credit card required.

-## Getting started

-For this quickstart, you'll need to create an Azure resource group and an Azure Cosmos DB account.

-Run the following commands to create an Azure resource group:

-```azurecli

-az group create --name myResourceGroup --location eastus

-```

-Next create an Azure Cosmos DB account by running the following command:

-```

-az cosmosdb create --name my-cosmosdb-account --resource-group myResourceGroup

-```

-### Install the package

-Use the `go get` command to install the [azcosmos](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos) package.

-```bash

-go get github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos

-```

-## Key concepts

-* A `Client` is a connection to an Azure Cosmos DB account.

-* Azure Cosmos DB accounts can have multiple `databases`. A `DatabaseClient` allows you to create, read, and delete databases.

-* Database within an Azure Cosmos DB Account can have multiple `containers`. A `ContainerClient` allows you to create, read, update, and delete containers, and to modify throughput provision.

-* Information is stored as items inside containers. And the client allows you to create, read, update, and delete items in containers.

-**Authenticate the client**

-```go

-var endpoint = "<azure_cosmos_uri>"

-var key = "<azure_cosmos_primary_key"

-cred, err := azcosmos.NewKeyCredential(key)

-if err != nil {

- log.Fatal("Failed to create a credential: ", err)

-}

-// Create a CosmosDB client

-client, err := azcosmos.NewClientWithKey(endpoint, cred, nil)

-if err != nil {

- log.Fatal("Failed to create Azure Cosmos DB client: ", err)

-}

-// Create database client

-databaseClient, err := client.NewDatabase("<databaseName>")

-if err != nil {

- log.Fatal("Failed to create database client:", err)

-}

-// Create container client

-containerClient, err := client.NewContainer("<databaseName>", "<containerName>")

-if err != nil {

- log.Fatal("Failed to create a container client:", err)

-}

-```

-**Create an Azure Cosmos DB database**

-```go

-import (

- "context"

- "log"

- "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"

-)

-func createDatabase (client *azcosmos.Client, databaseName string) error {

-// databaseName := "adventureworks"

- // sets the name of the database

- databaseProperties := azcosmos.DatabaseProperties{ID: databaseName}

- // creating the database

- ctx := context.TODO()

- databaseResp, err := client.CreateDatabase(ctx, databaseProperties, nil)

- if err != nil {

- log.Fatal(err)

- }

- return nil

-}

-```

-**Create a container**

-```go

-import (

- "context"

- "log"

- "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"

-)

-func createContainer (client *azcosmos.Client, databaseName, containerName, partitionKey string) error {

-// databaseName = "adventureworks"

-// containerName = "customer"

-// partitionKey = "/customerId"

-

- databaseClient, err := client.NewDatabase(databaseName) // returns a struct that represents a database

- if err != nil {

- log.Fatal("Failed to create a database client:", err)

- }

- // Setting container properties

- containerProperties := azcosmos.ContainerProperties{

- ID: containerName,

- PartitionKeyDefinition: azcosmos.PartitionKeyDefinition{

- Paths: []string{partitionKey},

- },

- }

- // Setting container options

- throughputProperties := azcosmos.NewManualThroughputProperties(400) //defaults to 400 if not set

- options := &azcosmos.CreateContainerOptions{

- ThroughputProperties: &throughputProperties,

- }

- ctx := context.TODO()

- containerResponse, err := databaseClient.CreateContainer(ctx, containerProperties, options)

- if err != nil {

- log.Fatal(err)

- }

- log.Printf("Container [%v] created. ActivityId %s\n", containerName, containerResponse.ActivityID)

-

- return nil

-}

-```

-**Create an item**

-```go

-import (

- "context"

- "log"

- "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"

-)

-func createItem(client *azcosmos.Client, databaseName, containerName, partitionKey string, item any) error {

-// databaseName = "adventureworks"

-// containerName = "customer"

-// partitionKey = "1"

-/*

- item = struct {

- ID string `json:"id"`

- CustomerId string `json:"customerId"`

- Title string

- FirstName string

- LastName string

- EmailAddress string

- PhoneNumber string

- CreationDate string

- }{

- ID: "1",

- CustomerId: "1",

- Title: "Mr",

- FirstName: "Luke",

- LastName: "Hayes",

- EmailAddress: "luke12@adventure-works.com",

- PhoneNumber: "879-555-0197",

- }

-*/

- // Create container client

- containerClient, err := client.NewContainer(databaseName, containerName)

- if err != nil {

- return fmt.Errorf("failed to create a container client: %s", err)

- }

- // Specifies the value of the partiton key

- pk := azcosmos.NewPartitionKeyString(partitionKey)

- b, err := json.Marshal(item)

- if err != nil {

- return err

- }

- // setting item options upon creating ie. consistency level

- itemOptions := azcosmos.ItemOptions{

- ConsistencyLevel: azcosmos.ConsistencyLevelSession.ToPtr(),

- }

- ctx := context.TODO()

- itemResponse, err := containerClient.CreateItem(ctx, pk, b, &itemOptions)

- if err != nil {

- return err

- }

- log.Printf("Status %d. Item %v created. ActivityId %s. Consuming %v Request Units.\n", itemResponse.RawResponse.StatusCode, pk, itemResponse.ActivityID, itemResponse.RequestCharge)

- return nil

-}

-```

-**Read an item**

-```go

-import (

- "context"

- "log"

- "fmt"

- "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"

-)

-func readItem(client *azcosmos.Client, databaseName, containerName, partitionKey, itemId string) error {

-// databaseName = "adventureworks"

-// containerName = "customer"

-// partitionKey = "1"

-// itemId = "1"

- // Create container client

- containerClient, err := client.NewContainer(databaseName, containerName)

- if err != nil {

- return fmt.Errorf("Failed to create a container client: %s", err)

- }

- // Specifies the value of the partiton key

- pk := azcosmos.NewPartitionKeyString(partitionKey)

- // Read an item

- ctx := context.TODO()

- itemResponse, err := containerClient.ReadItem(ctx, pk, itemId, nil)

- if err != nil {

- return err

- }

- itemResponseBody := struct {

- ID string `json:"id"`

- CustomerId string `json:"customerId"`

- Title string

- FirstName string

- LastName string

- EmailAddress string

- PhoneNumber string

- CreationDate string

- }{}

- err = json.Unmarshal(itemResponse.Value, &itemResponseBody)

- if err != nil {

- return err

- }

- b, err := json.MarshalIndent(itemResponseBody, "", " ")

- if err != nil {

- return err

- }

- fmt.Printf("Read item with customerId %s\n", itemResponseBody.CustomerId)

- fmt.Printf("%s\n", b)

- log.Printf("Status %d. Item %v read. ActivityId %s. Consuming %v Request Units.\n", itemResponse.RawResponse.StatusCode, pk, itemResponse.ActivityID, itemResponse.RequestCharge)

- return nil

-}

-```

-**Delete an item**

-```go

-import (

- "context"

- "log"

- "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"

-)

-func deleteItem(client *azcosmos.Client, databaseName, containerName, partitionKey, itemId string) error {

-// databaseName = "adventureworks"

-// containerName = "customer"

-// partitionKey = "1"

-// itemId = "1"

- // Create container client

- containerClient, err := client.NewContainer(databaseName, containerName)

- if err != nil {

- return fmt.Errorf("Failed to create a container client: %s", err)

- }

- // Specifies the value of the partiton key

- pk := azcosmos.NewPartitionKeyString(partitionKey)

- // Delete an item

- ctx := context.TODO()

- res, err := containerClient.DeleteItem(ctx, pk, itemId, nil)

- if err != nil {

- return err

- }

- log.Printf("Status %d. Item %v deleted. ActivityId %s. Consuming %v Request Units.\n", res.RawResponse.StatusCode, pk, res.ActivityID, res.RequestCharge)

- return nil

-}

-```

-## Run the code

-To authenticate, you need to pass the Azure Cosmos DB account credentials to the application.

-Get your Azure Cosmos DB account credentials by following these steps:

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

-1. Navigate to your Azure Cosmos DB account.

-1. Open the **Keys** pane and copy the **URI** and **PRIMARY KEY** of your account. You'll add the URI and keys values to an environment variable in the next step.

-After you've copied the **URI** and **PRIMARY KEY** of your account, save them to a new environment variable on the local machine running the application.

-Use the values copied from the Azure portal to set the following environment variables:

-# [Bash](#tab/bash)

-```bash

-export AZURE_COSMOS_ENPOINT=<Your_AZURE_COSMOS_URI>

-export AZURE_COSMOS_KEY=<Your_COSMOS_PRIMARY_KEY>

-```

-# [PowerShell](#tab/powershell)

-```powershell

-$env:AZURE_COSMOS_ENDPOINT=<Your_AZURE_COSMOS_URI>

-$env:AZURE_COSMOS_KEY=<Your_AZURE_COSMOS_URI>

-```

-Create a new Go module by running the following command:

-```bash

-go mod init azcosmos

-```

-```go

-package main

-import (

- "context"

- "encoding/json"

- "errors"

- "fmt"

- "log"

- "os"

- "github.com/Azure/azure-sdk-for-go/sdk/azcore"

- "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"

-)

-func main() {

- endpoint := os.Getenv("AZURE_COSMOS_ENDPOINT")

- if endpoint == "" {

- log.Fatal("AZURE_COSMOS_ENDPOINT could not be found")

- }

- key := os.Getenv("AZURE_COSMOS_KEY")

- if key == "" {

- log.Fatal("AZURE_COSMOS_KEY could not be found")

- }

- var databaseName = "adventureworks"

- var containerName = "customer"

- var partitionKey = "/customerId"

- item := struct {

- ID string `json:"id"`

- CustomerId string `json:"customerId"`

- Title string

- FirstName string

- LastName string

- EmailAddress string

- PhoneNumber string

- CreationDate string

- }{

- ID: "1",

- CustomerId: "1",

- Title: "Mr",

- FirstName: "Luke",

- LastName: "Hayes",

- EmailAddress: "luke12@adventure-works.com",

- PhoneNumber: "879-555-0197",

- }

- cred, err := azcosmos.NewKeyCredential(key)

- if err != nil {

- log.Fatal("Failed to create a credential: ", err)

- }

- // Create a CosmosDB client

- client, err := azcosmos.NewClientWithKey(endpoint, cred, nil)

- if err != nil {

- log.Fatal("Failed to create Azure Cosmos DB db client: ", err)

- }

-

- err = createDatabase(client, databaseName)

- if err != nil {

- log.Printf("createDatabase failed: %s\n", err)

- }

- err = createContainer(client, databaseName, containerName, partitionKey)

- if err != nil {

- log.Printf("createContainer failed: %s\n", err)

- }

- err = createItem(client, databaseName, containerName, item.CustomerId, item)

- if err != nil {

- log.Printf("createItem failed: %s\n", err)

- }

- err = readItem(client, databaseName, containerName, item.CustomerId, item.ID)

- if err != nil {

- log.Printf("readItem failed: %s\n", err)

- }

-

- err = deleteItem(client, databaseName, containerName, item.CustomerId, item.ID)

- if err != nil {

- log.Printf("deleteItem failed: %s\n", err)

- }

-}

-func createDatabase(client *azcosmos.Client, databaseName string) error {

-// databaseName := "adventureworks"

- databaseProperties := azcosmos.DatabaseProperties{ID: databaseName}

- // This is a helper function that swallows 409 errors

- errorIs409 := func(err error) bool {

- var responseErr *azcore.ResponseError

- return err != nil && errors.As(err, &responseErr) && responseErr.StatusCode == 409

- }

- ctx := context.TODO()

- databaseResp, err := client.CreateDatabase(ctx, databaseProperties, nil)

- switch {

- case errorIs409(err):

- log.Printf("Database [%s] already exists\n", databaseName)

- case err != nil:

- return err

- default:

- log.Printf("Database [%v] created. ActivityId %s\n", databaseName, databaseResp.ActivityID)

- }

- return nil

-}

-func createContainer(client *azcosmos.Client, databaseName, containerName, partitionKey string) error {

-// databaseName = adventureworks

-// containerName = customer

-// partitionKey = "/customerId"

- databaseClient, err := client.NewDatabase(databaseName)

- if err != nil {

- return err

- }

- // creating a container

- containerProperties := azcosmos.ContainerProperties{

- ID: containerName,

- PartitionKeyDefinition: azcosmos.PartitionKeyDefinition{

- Paths: []string{partitionKey},

- },

- }

- // this is a helper function that swallows 409 errors

- errorIs409 := func(err error) bool {

- var responseErr *azcore.ResponseError

- return err != nil && errors.As(err, &responseErr) && responseErr.StatusCode == 409

- }

- // setting options upon container creation

- throughputProperties := azcosmos.NewManualThroughputProperties(400) //defaults to 400 if not set

- options := &azcosmos.CreateContainerOptions{

- ThroughputProperties: &throughputProperties,

- }

- ctx := context.TODO()

- containerResponse, err := databaseClient.CreateContainer(ctx, containerProperties, options)

-

- switch {

- case errorIs409(err):

- log.Printf("Container [%s] already exists\n", containerName)

- case err != nil:

- return err

- default:

- log.Printf("Container [%s] created. ActivityId %s\n", containerName, containerResponse.ActivityID)

- }

- return nil

-}

-func createItem(client *azcosmos.Client, databaseName, containerName, partitionKey string, item any) error {

-// databaseName = "adventureworks"

-// containerName = "customer"

-// partitionKey = "1"

-/* item = struct {

- ID string `json:"id"`

- CustomerId string `json:"customerId"`

- Title string

- FirstName string

- LastName string

- EmailAddress string

- PhoneNumber string

- CreationDate string

- }{

- ID: "1",

- CustomerId: "1",

- Title: "Mr",

- FirstName: "Luke",

- LastName: "Hayes",

- EmailAddress: "luke12@adventure-works.com",

- PhoneNumber: "879-555-0197",

- CreationDate: "2014-02-25T00:00:00",

- }

-*/

- // create container client

- containerClient, err := client.NewContainer(databaseName, containerName)

- if err != nil {

- return fmt.Errorf("failed to create a container client: %s", err)

- }

- // specifies the value of the partiton key

- pk := azcosmos.NewPartitionKeyString(partitionKey)

- b, err := json.Marshal(item)

- if err != nil {

- return err

- }

- // setting the item options upon creating ie. consistency level

- itemOptions := azcosmos.ItemOptions{

- ConsistencyLevel: azcosmos.ConsistencyLevelSession.ToPtr(),

- }

- // this is a helper function that swallows 409 errors

- errorIs409 := func(err error) bool {

- var responseErr *azcore.ResponseError

- return err != nil && errors.As(err, &responseErr) && responseErr.StatusCode == 409

- }

- ctx := context.TODO()

- itemResponse, err := containerClient.CreateItem(ctx, pk, b, &itemOptions)

-

- switch {

- case errorIs409(err):

- log.Printf("Item with partitionkey value %s already exists\n", pk)

- case err != nil:

- return err

- default:

- log.Printf("Status %d. Item %v created. ActivityId %s. Consuming %v Request Units.\n", itemResponse.RawResponse.StatusCode, pk, itemResponse.ActivityID, itemResponse.RequestCharge)

- }

-

- return nil

-}

-func readItem(client *azcosmos.Client, databaseName, containerName, partitionKey, itemId string) error {

-// databaseName = "adventureworks"

-// containerName = "customer"

-// partitionKey = "1"

-// itemId = "1"

- // Create container client

- containerClient, err := client.NewContainer(databaseName, containerName)

- if err != nil {

- return fmt.Errorf("failed to create a container client: %s", err)

- }

- // Specifies the value of the partiton key

- pk := azcosmos.NewPartitionKeyString(partitionKey)

- // Read an item

- ctx := context.TODO()

- itemResponse, err := containerClient.ReadItem(ctx, pk, itemId, nil)

- if err != nil {

- return err

- }

- itemResponseBody := struct {

- ID string `json:"id"`

- CustomerId string `json:"customerId"`

- Title string

- FirstName string

- LastName string

- EmailAddress string

- PhoneNumber string

- CreationDate string

- }{}

- err = json.Unmarshal(itemResponse.Value, &itemResponseBody)

- if err != nil {

- return err

- }

- b, err := json.MarshalIndent(itemResponseBody, "", " ")

- if err != nil {

- return err

- }

- fmt.Printf("Read item with customerId %s\n", itemResponseBody.CustomerId)

- fmt.Printf("%s\n", b)

- log.Printf("Status %d. Item %v read. ActivityId %s. Consuming %v Request Units.\n", itemResponse.RawResponse.StatusCode, pk, itemResponse.ActivityID, itemResponse.RequestCharge)

- return nil

-}

-func deleteItem(client *azcosmos.Client, databaseName, containerName, partitionKey, itemId string) error {

-// databaseName = "adventureworks"

-// containerName = "customer"

-// partitionKey = "1"

-// itemId = "1"

- // Create container client

- containerClient, err := client.NewContainer(databaseName, containerName)

- if err != nil {

- return fmt.Errorf("failed to create a container client:: %s", err)

- }

- // Specifies the value of the partiton key

- pk := azcosmos.NewPartitionKeyString(partitionKey)

- // Delete an item

- ctx := context.TODO()

- res, err := containerClient.DeleteItem(ctx, pk, itemId, nil)

- if err != nil {

- return err

- }

- log.Printf("Status %d. Item %v deleted. ActivityId %s. Consuming %v Request Units.\n", res.RawResponse.StatusCode, pk, res.ActivityID, res.RequestCharge)

- return nil

-}

-Create a new file named `main.go` and copy the code from the sample section above.

-Run the following command to execute the app:

-```bash

-go run main.go

-```

-## Next steps

-In this quickstart, you've learned how to create an Azure Cosmos DB account, create a database, container, and an item entry. Now import more data to your Azure Cosmos DB account.

-Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.

-* If all you know is the number of vcores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md)

-* If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md)

-description: This quickstart presents a Spring Data Azure Cosmos DB v3 code sample you can use to connect to and query the Azure Cosmos DB for NoSQL

-# Quickstart: Build a Spring Data Azure Cosmos DB v3 app to manage Azure Cosmos DB for NoSQL data

-> [!div class="op_single_selector"]

->

-> * [.NET](quickstart-dotnet.md)

-> * [Node.js](quickstart-nodejs.md)

-> * [Java](quickstart-java.md)

-> * [Spring Data](quickstart-java-spring-data.md)

-> * [Python](quickstart-python.md)

-> * [Spark v3](quickstart-spark.md)

-> * [Go](quickstart-go.md)

-In this quickstart, you create and manage an Azure Cosmos DB for NoSQL account from the Azure portal, and by using a Spring Data Azure Cosmos DB v3 app cloned from GitHub.

-First, you create an Azure Cosmos DB for NoSQL account using the Azure portal. Alternately, without a credit card or an Azure subscription, you can set up a free [Try Azure Cosmos DB account](https://aka.ms/trycosmosdb). You can then create a Spring Boot app using the Spring Data Azure Cosmos DB v3 connector, and then add resources to your Azure Cosmos DB account by using the Spring Boot application.

-Azure Cosmos DB is a multi-model database service that lets you quickly create and query document, table, key-value, and graph databases with global distribution and horizontal scale capabilities.

-> [!IMPORTANT]

-> These release notes are for version 3 of Spring Data Azure Cosmos DB. You can find release notes for version 2 at [Spring Data Azure Cosmos DB v2 for API for NoSQL (legacy): Release notes and resources](sdk-java-spring-data-v2.md).

->

-> Spring Data Azure Cosmos DB supports only the API for NoSQL.

->

-> See the following articles for information about Spring Data on other Azure Cosmos DB APIs:

->

-> * [Spring Data for Apache Cassandra with Azure Cosmos DB](/azure/developer/java/spring-framework/configure-spring-data-apache-cassandra-with-cosmos-db)

-> * [Spring Data MongoDB with Azure Cosmos DB](/azure/developer/java/spring-framework/configure-spring-data-mongodb-with-cosmos-db)

-## Prerequisites

-* An Azure account with an active subscription.

- * No Azure subscription? You can [try Azure Cosmos DB free](../try-free.md) with no credit card required.

-* [Java Development Kit (JDK) 8](/java/openjdk/download#openjdk-8). Set the `JAVA_HOME` environment variable to the JDK install folder.

-* A [Maven binary archive](https://maven.apache.org/download.cgi). On Ubuntu, run `apt-get install maven` to install Maven.

-* [Git](https://www.git-scm.com/downloads). On Ubuntu, run `sudo apt-get install git` to install Git.

-## Introductory notes

-*The structure of an Azure Cosmos DB account.* Irrespective of API or programming language, an Azure Cosmos DB *account* contains zero or more *databases*, a *database* (DB) contains zero or more *containers*, and a *container* contains zero or more items, as shown in the following diagram:

-For more information about databases, containers, and items, see [Azure Cosmos DB resource model](../resource-model.md). A few important properties are defined at the level of the container, among them *provisioned throughput* and *partition key*.

-The provisioned throughput is measured in Request Units (*RUs*) which have a monetary price and are a substantial determining factor in the operating cost of the account. You can select provisioned throughput at per-container granularity or per-database granularity. However, you should prefer container-level throughput specification. For more information, see [Introduction to provisioned throughput in Azure Cosmos DB](../set-throughput.md).

-As items are inserted into an Azure Cosmos DB container, the database grows horizontally by adding more storage and compute to handle requests. Storage and compute capacity are added in discrete units known as *partitions*. You must choose one field in your documents to be the partition key, which maps each document to a partition.

-The way partitions are managed is that each partition is assigned a roughly equal slice out of the range of partition key values. For this reason, you should choose a partition key that's relatively random or evenly distributed. Otherwise, you get *hot partitions* and *cold partitions*, which see substantially more or fewer requests. For information on avoiding this condition, see [Partitioning and horizontal scaling in Azure Cosmos DB](../partitioning-overview.md).

-## Create a database account

-Before you can create a document database, you need to create an API for NoSQL account with Azure Cosmos DB.

-## Add a container

-<a id="add-sample-data"></a>

-## Add sample data

-## Query your data

-## Clone the sample application

-Now let's switch to working with code. Let's clone an API for NoSQL app from GitHub, set the connection string, and run it.

-Run the following command to clone the sample repository. This command creates a copy of the sample app on your computer.

-```bash

-git clone https://github.com/Azure-Samples/azure-spring-boot-samples.git

-```

-## Review the code

-This step is optional. If you're interested in learning how the database resources are created in the code, you can review the following snippets. Otherwise, you can skip ahead to [Run the app](#run-the-app).

-### [Passwordless (Recommended)](#tab/passwordless)

-In this section, the configurations and the code don't have any authentication operations. However, connecting to Azure service requires authentication. To complete the authentication, you need to use Azure Identity. Spring Cloud Azure uses `DefaultAzureCredential`, which Azure Identity provides to help you get credentials without any code changes.

-`DefaultAzureCredential` supports multiple authentication methods and determines which method to use at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code. For more information, see the [Default Azure credential](/azure/developer/java/sdk/identity-azure-hosted-auth#default-azure-credential) section of [Authenticate Azure-hosted Java applications](/azure/developer/java/sdk/identity-azure-hosted-auth).

-### Authenticate using DefaultAzureCredential

-You can authenticate to Cosmos DB for NoSQL using `DefaultAzureCredential` by adding the `azure-identity` [dependency](https://mvnrepository.com/artifact/com.azure/azure-identity) to your application. `DefaultAzureCredential` automatically discovers and uses the account you signed in with in the previous step.

-### Application configuration file

-Configure the Azure Database for MySQL credentials in the *application.yml* configuration file in the *cosmos/spring-cloud-azure-starter-data-cosmos/spring-cloud-azure-data-cosmos-sample* directory. Replace the values of `${AZURE_COSMOS_ENDPOINT}` and `${COSMOS_DATABASE}`.

-```yaml

-spring:

- cloud:

- azure:

- cosmos:

- endpoint: ${AZURE_COSMOS_ENDPOINT}

- database: ${COSMOS_DATABASE}

-```

-After Spring Boot and Spring Data create the Azure Cosmos DB account, database, and container, they connect to the database and container for `delete`, `add`, and `find` operations.

-### [Password](#tab/password)

-### Application configuration file

-The following section shows how Spring Boot and Spring Data use configuration instead of code to establish an Azure Cosmos DB client and connect to Azure Cosmos DB resources. At application startup Spring Boot handles all of this boilerplate using the following settings in *application.yml*:

-```yaml

-spring:

- cloud:

- azure:

- cosmos:

- key: ${AZURE_COSMOS_KEY}

- endpoint: ${AZURE_COSMOS_ENDPOINT}

- database: ${COSMOS_DATABASE}

-```

-Once you create an Azure Cosmos DB account, database, and container, just fill-in-the-blanks in the config file and Spring Boot/Spring Data does the following: (1) creates an underlying Java SDK `CosmosClient` instance with the URI and key, and (2) connects to the database and container. You're all set - no more resource management code!

-### Java source

-Spring Data provides a simple, clean, standardized, and platform-independent interface for operating on datastores, as shown in the following examples. These CRUD and query examples enable you to manipulate Azure Cosmos DB documents by using Spring Data Azure Cosmos DB. These examples build on the Spring Data GitHub sample linked to earlier in this article.

-* Item creation and updates by using the `save` method.

- ```java

- // Save the User class to Azure Cosmos DB database.

- final Mono<User> saveUserMono = repository.save(testUser);

- ```

-* Point-reads using the derived query method defined in the repository. The `findById` performs point-reads for `repository`. The fields mentioned in the method name cause Spring Data to execute a point-read defined by the `id` field:

- ```java

- // Nothing happens until we subscribe to these Monos.

- // findById will not return the user as user is not present.

- final Mono<User> findByIdMono = repository.findById(testUser.getId());

- final User findByIdUser = findByIdMono.block();

- Assert.isNull(findByIdUser, "User must be null");

- ```

-* Item deletes using `deleteAll`:

- ```java

- repository.deleteAll().block();

- LOGGER.info("Deleted all data in container.");

- ```

-* Derived query based on repository method name. Spring Data implements the `repository` `findByFirstName` method as a Java SDK SQL query on the `firstName` field. You can't implement this query as a point-read.

- ```java

- final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");

- ```

-## Run the app

-Now go back to the Azure portal to get your connection string information. Then, use the following steps to launch the app with your endpoint information so your app can communicate with your hosted database.

-1. In the Git terminal window, `cd` to the sample code folder.

- ```bash

- cd azure-spring-boot-samples/cosmos/spring-cloud-azure-starter-data-cosmos/spring-cloud-azure-data-cosmos-sample

- ```

-1. In the Git terminal window, use the following command to install the required Spring Data Azure Cosmos DB packages.

- ```bash

- mvn clean package

- ```

-1. In the Git terminal window, use the following command to start the Spring Data Azure Cosmos DB application:

- ```bash

- mvn spring-boot:run

- ```

-1. The app loads *application.yml* and connects the resources in your Azure Cosmos DB account.

-1. The app performs point CRUD operations described previously.

-1. The app performs a derived query.

-1. The app doesn't delete your resources. Switch back to the portal to [clean up the resources](#clean-up-resources) from your account if you want to avoid incurring charges.

-## Review SLAs in the Azure portal

-## Clean up resources

-## Next steps

-In this quickstart, you learned how to create an Azure Cosmos DB for NoSQL account and create a document database and container using the Data Explorer. You then ran a Spring Data app to do the same thing programmatically. You can now import more data into your Azure Cosmos DB account.

-Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.

-* If all you know is the number of vCores and servers in your existing database cluster, read about [estimating request units using vCores or vCPUs](../convert-vcore-to-request-unit.md)

-* If you know typical request rates for your current database workload, read about [estimating request units using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md)

-description: Use a Java code sample from GitHub to learn how to build an app to connect to and query Azure Cosmos DB for NoSQL.

-# Quickstart: Build a Java app to manage Azure Cosmos DB for NoSQL data

-> [!div class="op_single_selector"]

->

-> * [.NET](quickstart-dotnet.md)

-> * [Node.js](quickstart-nodejs.md)

-> * [Java](quickstart-java.md)

-> * [Spring Data](quickstart-java-spring-data.md)

-> * [Python](quickstart-python.md)

-> * [Spark v3](quickstart-spark.md)

-> * [Go](quickstart-go.md)

->

-This quickstart guide explains how to build a Java app to manage an Azure Cosmos DB for NoSQL account. You create the Java app using the SQL Java SDK, and add resources to your Azure Cosmos DB account by using the Java application.

-First, create an Azure Cosmos DB for NoSQL account using the Azure portal. Azure Cosmos DB is a multi-model database service that lets you quickly create and query document, table, key-value, and graph databases with global distribution and horizontal scale capabilities. You can [try Azure Cosmos DB account](https://aka.ms/trycosmosdb) for free without a credit card or an Azure subscription.

-> [!IMPORTANT]

-> This quickstart is for Azure Cosmos DB Java SDK v4 only. For more information, see the [release notes](sdk-java-v4.md), [Maven repository](https://mvnrepository.com/artifact/com.azure/azure-cosmos), [performance tips](performance-tips-java-sdk-v4.md), and [troubleshooting guide](troubleshoot-java-sdk-v4.md). If you currently use an older version than v4, see the [Migrate to Azure Cosmos DB Java SDK v4](migrate-java-v4-sdk.md) guide for help upgrading to v4.

-> [!TIP]

-> If you work with Azure Cosmos DB resources in a Spring application, consider using [Spring Cloud Azure](/azure/developer/java/spring-framework/) as an alternative. Spring Cloud Azure is an open-source project that provides seamless Spring integration with Azure services. To learn more about Spring Cloud Azure, and to see an example using Cosmos DB, see [Access data with Azure Cosmos DB NoSQL API](/azure/developer/java/spring-framework/configure-spring-boot-starter-java-app-with-cosmos-db).

-## Introductory notes

-**The structure of an Azure Cosmos DB account:** For any API or programming language, an Azure Cosmos DB *account* contains zero or more *databases*, a *database* (DB) contains zero or more *containers*, and a *container* contains zero or more items, as shown in the following diagram:

-For more information, see [Databases, containers, and items in Azure Cosmos DB](../resource-model.md).

-A few important properties are defined at the level of the container, including *provisioned throughput* and *partition key*. The provisioned throughput is measured in request units (RUs), which have a monetary price and are a substantial determining factor in the operating cost of the account. Provisioned throughput can be selected at per-container granularity or per-database granularity, however container-level throughput specification is typically preferred. To learn more about throughput provisioning, see [Introduction to provisioned throughput in Azure Cosmos DB](../set-throughput.md).

-As items are inserted into an Azure Cosmos DB container, the database grows horizontally by adding more storage and compute to handle requests. Storage and compute capacity are added in discrete units known as *partitions*, and you must choose one field in your documents to be the partition key that maps each document to a partition. Partitions are managed such that each partition is assigned a roughly equal slice out of the range of partition key values. Therefore, you're advised to choose a partition key that's relatively random or evenly distributed. Otherwise, some partitions see substantially more requests (*hot partition*) while other partitions see substantially fewer requests (*cold partition*). To learn more, see [Partitioning and horizontal scaling in Azure Cosmos DB](../partitioning-overview.md).

-## Create a database account

-Before you can create a document database, you need to create an API for NoSQL account with Azure Cosmos DB.

-## Add a container

-<a id="add-sample-data"></a>

-## Add sample data

-## Query your data

-## Clone the sample application

-Now let's switch to working with code. Clone an API for NoSQL app from GitHub, set the connection string, and run it. You can see how easy it is to work with data programmatically.

-Run the following command to clone the sample repository. This command creates a copy of the sample app on your computer.

-```bash

-git clone https://github.com/Azure-Samples/azure-cosmos-java-getting-started.git

-```

-## Review the code

-This step is optional. If you're interested in learning how the database resources are created in the code, you can review the following snippets. Otherwise, you can skip ahead to [Run the app](#run-the-app).

-## [Passwordless Sync API (Recommended)](#tab/passwordlesssync)

-## Authenticate using DefaultAzureCredential

-You can authenticate to Cosmos DB for NoSQL using `DefaultAzureCredential` by adding the `azure-identity` [dependency](https://mvnrepository.com/artifact/com.azure/azure-identity) to your application. `DefaultAzureCredential` automatically discovers and uses the account you signed into in the previous step.

-### Manage database resources using the synchronous (sync) API

-* `CosmosClient` initialization: The `CosmosClient` provides client-side logical representation for the Azure Cosmos DB database service. This client is used to configure and execute requests against the service.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncPasswordlessMain.java?name=CreatePasswordlessSyncClient)]

-* Use the [az cosmosdb sql database create](/cli/azure/cosmosdb/sql/database#az-cosmosdb-sql-database-create) and [az cosmosdb sql container create](/cli/azure/cosmosdb/sql/container#az-cosmosdb-sql-container-create) commands to create a Cosmos DB NoSQL database and container.

- ```azurecli-interactive

- # Create a SQL API database

- az cosmosdb sql database create \

- --account-name msdocs-cosmos-nosql \

- --resource-group msdocs \

- --name AzureSampleFamilyDB

- ```

-

- ```azurecli-interactive

- # Create a SQL API container

- az cosmosdb sql container create \

- --account-name msdocs-cosmos-nosql \

- --resource-group msdocs \

- --database-name AzureSampleFamilyDB \

- --name FamilyContainer \

- --partition-key-path '/lastName'

- ```

-* Item creation by using the `createItem` method.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncPasswordlessMain.java?name=CreateItem)]

-* Point reads are performed using `readItem` method.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncPasswordlessMain.java?name=ReadItem)]

-* SQL queries over JSON are performed using the `queryItems` method.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncPasswordlessMain.java?name=QueryItems)]

-## Run the app

-Now go back to the Azure portal to get your connection string information and launch the app with your endpoint information. This enables your app to communicate with your hosted database.

-1. In the git terminal window, `cd` to the sample code folder.

- ```bash

- cd azure-cosmos-java-getting-started

- ```

-2. In the git terminal window, use the following command to install the required Java packages.

- ```bash

- mvn package

- ```

-3. In the git terminal window, use the following command to start the Java application. Replace SYNCASYNCMODE with `sync-passwordless` or `async-passwordless`, depending on which sample code you'd like to run. Replace YOUR_COSMOS_DB_HOSTNAME with the quoted URI value from the portal, and replace YOUR_COSMOS_DB_MASTER_KEY with the quoted primary key from portal.

- ```bash

- mvn exec:java@SYNCASYNCMODE -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEY

- The terminal window displays a notification that the `FamilyDB` database was created.

-4. The app references the database and container you created via Azure CLI earlier.

-5. The app performs point reads using object IDs and partition key value (which is `lastName` in our sample).

-6. The app queries items to retrieve all families with last name (*Andersen*, *Wakefield*, *Johnson*).

-7. The app doesn't delete the created resources. Switch back to the portal to [clean up the resources](#clean-up-resources) from your account so that you don't incur charges.

-## [Passwordless Async API](#tab/passwordlessasync)

-## Authenticate using DefaultAzureCredential

-You can authenticate to Cosmos DB for NoSQL using `DefaultAzureCredential` by adding the [azure-identity dependency](https://mvnrepository.com/artifact/com.azure/azure-identity) to your application. `DefaultAzureCredential` automatically discovers and uses the account you signed-in with in the previous step.

-### Managing database resources using the asynchronous (async) API

-* Async API calls return immediately, without waiting for a response from the server. The following code snippets show proper design patterns for accomplishing all of the preceding management tasks using async API.

-* `CosmosAsyncClient` initialization. The `CosmosAsyncClient` provides client-side logical representation for the Azure Cosmos DB database service. This client is used to configure and execute asynchronous requests against the service.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/async/AsyncPasswordlessMain.java?name=CreatePasswordlessAsyncClient)]

-* Use the [az cosmosdb sql database create](/cli/azure/cosmosdb/sql/database#az-cosmosdb-sql-database-create) and [az cosmosdb sql container create](/cli/azure/cosmosdb/sql/container#az-cosmosdb-sql-container-create) commands to create a Cosmos DB NoSQL database and container.

- ```azurecli-interactive

- # Create a SQL API database

- az cosmosdb sql database create \

- --account-name msdocs-cosmos-nosql \

- --resource-group msdocs \

- --name AzureSampleFamilyDB

- ```

-

- ```azurecli-interactive

- # Create a SQL API container

- az cosmosdb sql container create \

- --account-name msdocs-cosmos-nosql \

- --resource-group msdocs \

- --database-name AzureSampleFamilyDB \

- --name FamilyContainer \

- --partition-key-path '/lastName'

-* As with the sync API, item creation is accomplished using the `createItem` method. This example shows how to efficiently issue numerous async `createItem` requests by subscribing to a Reactive Stream that issues the requests and prints notifications. Since this simple example runs to completion and terminates, `CountDownLatch` instances are used to ensure the program doesn't terminate during item creation. **The proper asynchronous programming practice is not to block on async calls. In realistic use cases, requests are generated from a main() loop that executes indefinitely, eliminating the need to latch on async calls.**

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/async/AsyncPasswordlessMain.java?name=CreateItem)]

-

-* As with the sync API, point reads are performed using `readItem` method.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/async/AsyncPasswordlessMain.java?name=ReadItem)]

-* As with the sync API, SQL queries over JSON are performed using the `queryItems` method.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/async/AsyncPasswordlessMain.java?name=QueryItems)]

-## Run the app

-Now go back to the Azure portal to get your connection string information and launch the app with your endpoint information. This enables your app to communicate with your hosted database.

-1. In the git terminal window, `cd` to the sample code folder.

- ```bash

- cd azure-cosmos-java-getting-started

- ```

-2. In the git terminal window, use the following command to install the required Java packages.

- ```bash

- mvn package

- ```

-3. In the git terminal window, use the following command to start the Java application. Replace SYNCASYNCMODE with `sync-passwordless` or `async-passwordless` depending on which sample code you would like to run, replace YOUR_COSMOS_DB_HOSTNAME with the quoted URI value from the portal, and replace YOUR_COSMOS_DB_MASTER_KEY with the quoted primary key from portal.

- ```bash

- mvn exec:java@SYNCASYNCMODE -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEY

- ```

- The terminal window displays a notification that the `AzureSampleFamilyDB` database was created.

-4. The app references the database and container you created via Azure CLI earlier.

-5. The app performs point reads using object IDs and partition key value (which is `lastName` in our sample).

-6. The app queries items to retrieve all families with last name (*Andersen*, *Wakefield*, *Johnson*).

-7. The app doesn't delete the created resources. Switch back to the portal to [clean up the resources](#clean-up-resources) from your account so that you don't incur charges.

-## [Sync API](#tab/sync)

-### Managing database resources using the synchronous (sync) API

-* `CosmosClient` initialization. The `CosmosClient` provides client-side logical representation for the Azure Cosmos DB database service. This client is used to configure and execute requests against the service.

-

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncMain.java?name=CreateSyncClient)]

-* `CosmosDatabase` creation.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncMain.java?name=CreateDatabaseIfNotExists)]

-* `CosmosContainer` creation.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncMain.java?name=CreateContainerIfNotExists)]

-* Item creation by using the `createItem` method.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncMain.java?name=CreateItem)]

-

-* Point reads are performed using `readItem` method.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncMain.java?name=ReadItem)]

-* SQL queries over JSON are performed using the `queryItems` method.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncMain.java?name=QueryItems)]

-## Run the app

-Now go back to the Azure portal to get your connection string information and launch the app with your endpoint information. This enables your app to communicate with your hosted database.

-1. In the git terminal window, `cd` to the sample code folder.

- ```bash

- cd azure-cosmos-java-getting-started

- ```

-2. In the git terminal window, use the following command to install the required Java packages.

- ```bash

- mvn package

- ```

-3. In the git terminal window, use the following command to start the Java application. Replace SYNCASYNCMODE with `sync` or `async` depending on which sample code you would like to run, replace YOUR_COSMOS_DB_HOSTNAME with the quoted URI value from the portal, and replace YOUR_COSMOS_DB_MASTER_KEY with the quoted primary key from portal.

- ```bash

- mvn exec:java@SYNCASYNCMODE -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEY

- ```

- The terminal window displays a notification that the FamilyDB database was created.

-4. The app creates a database with the name `AzureSampleFamilyDB`.

-5. The app creates a container with the name `FamilyContainer`.

-6. The app performs point reads using object IDs and partition key value (which is `lastName` in our sample).

-7. The app queries items to retrieve all families with last name (*Andersen*, *Wakefield*, *Johnson*).

-8. The app doesn't delete the created resources. Return to the Azure portal to [clean up the resources](#clean-up-resources) from your account so you don't incur charges.

-## [Async API](#tab/async)

-### Managing database resources using the asynchronous (async) API

-* Async API calls return immediately, without waiting for a response from the server. The following code snippets show proper design patterns for accomplishing all of the preceding management tasks using async API.

-* `CosmosAsyncClient` initialization. The `CosmosAsyncClient` provides client-side logical representation for the Azure Cosmos DB database service. This client is used to configure and execute asynchronous requests against the service.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/async/AsyncMain.java?name=CreateAsyncClient)]

-* `CosmosAsyncDatabase` creation.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncMain.java?name=CreateDatabaseIfNotExists)]

-* `CosmosAsyncContainer` creation.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/sync/SyncMain.java?name=CreateContainerIfNotExists)]

-* As with the sync API, item creation is accomplished using the `createItem` method. This example shows how to efficiently issue numerous async `createItem` requests by subscribing to a Reactive Stream that issues the requests and prints notifications. Since this simple example runs to completion and terminates, `CountDownLatch` instances are used to ensure the program doesn't terminate during item creation. **The proper asynchronous programming practice is not to block on async calls. In realistic use cases, requests are generated from a main() loop that executes indefinitely, eliminating the need to latch on async calls.**

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/async/AsyncMain.java?name=CreateItem)]

-

-* As with the sync API, point reads are performed by using `readItem` method.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/async/AsyncMain.java?name=ReadItem)]

-* As with the sync API, SQL queries over JSON are performed by using the `queryItems` method.

- [!code-java[](~/azure-cosmosdb-java-v4-getting-started/src/main/java/com/azure/cosmos/sample/async/AsyncMain.java?name=QueryItems)]

-## Run the app

-Now go back to the Azure portal to get your connection string information and launch the app with your endpoint information. This enables your app to communicate with your hosted database.

-1. In the git terminal window, `cd` to the sample code folder.

- ```bash

- cd azure-cosmos-java-getting-started

- ```

-2. In the git terminal window, use the following command to install the required Java packages.

- ```bash

- mvn package

- ```

-3. In the git terminal window, use the following command to start the Java application. Replace SYNCASYNCMODE with `sync` or `async` depending on which sample code you would like to run, replace YOUR_COSMOS_DB_HOSTNAME with the quoted URI value from the portal, and replace YOUR_COSMOS_DB_MASTER_KEY with the quoted primary key from portal.

- ```bash

- mvn exec:java@SYNCASYNCMODE -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEY

- ```

- The terminal window displays a notification that the `FamilyDB` database was created.

-4. The app creates a database with the name `AzureSampleFamilyDB`.

-5. The app creates a container with the name `FamilyContainer`.

-6. The app performs point reads using object IDs and partition key value (which is `lastName` in our sample).

-7. The app queries items to retrieve all families with last name (*Andersen*, *Wakefield*, *Johnson*).

-8. The app doesn't delete the created resources. Return to the Azure portal to [clean up the resources](#clean-up-resources) from your account so you don't incur charges.

-## Use Throughput Control

-Having throughput control helps to isolate the performance needs of applications running against a container, by limiting the amount of [request units](../request-units.md) that can be consumed by a given Java SDK client.

-There are several advanced scenarios that benefit from client-side throughput control:

-> [!WARNING]

-> Please note that throughput control is not yet supported for gateway mode.

-> Currently, for [serverless Azure Cosmos DB accounts](../serverless.md), attempting to use `targetThroughputThreshold` to define a percentage will result in failure. You can only provide an absolute value for target throughput/RU using `targetThroughput`.

-### Global throughput control

-Global throughput control in the Java SDK is configured by first creating a container that will define throughput control metadata. This container must have a partition key of `groupId`, and `ttl` enabled. Assuming you already have objects for client, database, and container as defined in the examples above, you can create this container as below. Here we name the container `ThroughputControl`:

-## [Sync API](#tab/sync-throughput)

-```java

- CosmosContainerProperties throughputContainerProperties = new CosmosContainerProperties("ThroughputControl", "/groupId").setDefaultTimeToLiveInSeconds(-1);

- ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);

- database.createContainerIfNotExists(throughputContainerProperties, throughputProperties);

-```

-## [Async API](#tab/async-throughput)

-```java

- CosmosContainerProperties throughputContainerProperties = new CosmosContainerProperties("ThroughputControl", "/groupId").setDefaultTimeToLiveInSeconds(-1);

- ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);

- database.createContainerIfNotExists(throughputContainerProperties, throughputProperties).block();

-```

-> [!NOTE]

-> The throughput control container must be created with a partition key `/groupId` and must have `ttl` value set, or throughput control will not function correctly.

-Then, to enable the container object used by the current client to use a shared global control group, we need to create two sets of config. The first is to define the control `groupName`, and the `targetThroughputThreshold` or `targetThroughput` for that group. If the group does not already exist, an entry for it will be created in the throughput control container:

-```java

- ThroughputControlGroupConfig groupConfig =

- new ThroughputControlGroupConfigBuilder()

- .groupName("globalControlGroup")

- .targetThroughputThreshold(0.25)

- .targetThroughput(100)

- .build();

-```

-> [!NOTE]

-> In the above, we define a `targetThroughput` value of `100`, meaning that only a maximum of 100 RUs of the container's provisioned throughput can be used by all clients consuming the throughput control group, before the SDK will attempt to rate limit clients. You can also define `targetThroughputThreshold` to provide a percentage of the container's throughput as the threshold instead (the example above defines a threshold of 25%). Defining a value for both with not cause an error, but the SDK will apply the one with the lower value. For example, if the container in the above example has 1000 RUs provisioned, the value of `targetThroughputThreshold(0.25)` will be 250 RUs, so the lower value of `targetThroughput(100)` will be used as the threshold.

-> [!IMPORTANT]

-> If you reference a `groupName` that already exists, but define `targetThroughputThreshold` or `targetThroughput` values to be different than what was originally defined for the group, this will be treated as a different group (even though it has the same name). To make sure all clients use the same group, make sure they all have the same settings for both `groupName` **and** `targetThroughputThreshold` (or `targetThroughput`). You also need to restart all applications after making any such changes, to ensure they all consume the new threshold or target throughput properly.

-The second config you need to create will reference the throughput container you created earlier, and define some behaviours for it using two parameters:

-```java

- GlobalThroughputControlConfig globalControlConfig =

- this.client.createGlobalThroughputControlConfigBuilder("ThroughputControlDatabase", "ThroughputControl")

- .setControlItemRenewInterval(Duration.ofSeconds(5))

- .setControlItemExpireInterval(Duration.ofSeconds(11))

- .build();

-```

-Now we're ready to enable global throughput control for this container object. Other Cosmos clients running in other JVMs can share the same throughput control group, and as long as they are referencing the same throughput control metadata container, and reference the same throughput control group name.

-```java

- container.enableGlobalThroughputControlGroup(groupConfig, globalControlConfig);

-```

-Finally, you must set the group name in request options for the given operation:

-```java

- CosmosItemRequestOptions options = new CosmosItemRequestOptions();

- options.setThroughputControlGroupName("globalControlGroup");

- container.createItem(family, options).block();

-```

-For [bulk operations](bulk-executor-java.md), this would look like the below:

-```java

- Flux<Family> families = Flux.range(0, 1000).map(i -> {

- Family family = new Family();

- family.setId(UUID.randomUUID().toString());

- family.setLastName("Andersen-" + i);

- return family;

- });

- CosmosBulkExecutionOptions bulkExecutionOptions = new CosmosBulkExecutionOptions();

- bulkExecutionOptions.setThroughputControlGroupName("globalControlGroup")

- Flux<CosmosItemOperation> cosmosItemOperations = families.map(family -> CosmosBulkOperations.getCreateItemOperation(family, new PartitionKey(family.getLastName())));

- container.executeBulkOperations(cosmosItemOperations, bulkExecutionOptions).blockLast();

-```

-> [!NOTE]

-> Throughput control does not do RU pre-calculation of each operation. Instead, it tracks the RU usages *after* the operation based on the response header. As such, throughput control is based on an approximation - and **does not guarantee** that amount of throughput will be available for the group at any given time. This means that if the configured RU is so low that a single operation can use it all, then throughput control cannot avoid the RU exceeding the configured limit. Therefore, throughput control works best when the configured limit is higher than any single operation that can be executed by a client in the given control group. With that in mind, when reading via query or change feed, you should configure the [page size](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/blob/a9460846d144fb87ae4e3d2168f63a9f2201c5ed/src/main/java/com/azure/cosmos/examples/queries/async/QueriesQuickstartAsync.java#L255) to be a modest amount, so that client throughput control can be re-calculated with higher frequency, and therefore reflected more accurately at any given time. However, when using throughput control for a write-job using bulk, the number of documents executed in a single request will automatically be tuned based on the throttling rate to allow the throughput control to kick-in as early as possible.

-### Local throughput control

-You can also use local throughput control, without defining a shared control group that multiple clients will use. However, with this approach, each client will be unaware of how much throughput other clients are consuming from the total available throughput in the container, while global throughput control attempts to load balance the consumption of each client.

-```java

- ThroughputControlGroupConfig groupConfig =

- new ThroughputControlGroupConfigBuilder()

- .groupName("localControlGroup")

- .targetThroughputThreshold(0.1)

- .build();

- container.enableLocalThroughputControlGroup(groupConfig);

-```

-As with global throughput control, remember to set the group name in request options for the given operation:

-```java

- CosmosItemRequestOptions options = new CosmosItemRequestOptions();

- options.setThroughputControlGroupName("localControlGroup");

- container.createItem(family, options).block();

-```

-For [bulk operations](bulk-executor-java.md), this would look like the below:

-```java

- Flux<Family> families = Flux.range(0, 1000).map(i -> {

- Family family = new Family();

- family.setId(UUID.randomUUID().toString());

- family.setLastName("Andersen-" + i);

- return family;

- });

- CosmosBulkExecutionOptions bulkExecutionOptions = new CosmosBulkExecutionOptions();

- bulkExecutionOptions.setThroughputControlGroupName("localControlGroup")

- Flux<CosmosItemOperation> cosmosItemOperations = families.map(family -> CosmosBulkOperations.getCreateItemOperation(family, new PartitionKey(family.getLastName())));

- container.executeBulkOperations(cosmosItemOperations, bulkExecutionOptions).blockLast();

-## Review SLAs in the Azure portal

-## Clean up resources

-## Next steps

-In this quickstart, you learned how to create an Azure Cosmos DB for NoSQL account, create a document database and container using Data Explorer, and run a Java app to do the same thing programmatically. You can now import additional data into your Azure Cosmos DB account.

-Are you capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.

-* If all you know is the number of vcores and servers in your existing database cluster, read about [estimating RUs using vCores or vCPUs](../convert-vcore-to-request-unit.md).

-* If you know typical request rates for your current database workload, learn how to [estimate RUs using Azure Cosmos DB capacity planner](estimate-ru-with-capacity-planner.md).

-description: Learn how to build a Node.js app to manage Azure Cosmos DB for NoSQL account resources in this quickstart.

-# Quickstart - Azure Cosmos DB for NoSQL client library for Node.js

-Get started with the Azure Cosmos DB client library for JavaScript to create databases, containers, and items within your account. Follow these steps to install the package and try out example code for basic tasks.

-> [!NOTE]

-> The [example code snippets](https://github.com/Azure-Samples/cosmos-db-sql-api-javascript-samples) are available on GitHub as a Node.js project.

- - No Azure subscription? You can [try Azure Cosmos DB free](../try-free.md) with no credit card required.

-### Prerequisite check

-This section walks you through creating an Azure Cosmos account and setting up a project that uses Azure Cosmos DB SQL API client library for JavaScript to manage resources.

-### <a id="create-account"></a>Create an Azure Cosmos DB account

-> [!TIP]

-> No Azure subscription? You can [try Azure Cosmos DB free](../try-free.md) with no credit card required. If you create an account using the free trial, you can safely skip ahead to the [Create a new JavaScript project](#create-a-new-javascript-project) section.

-### Create a new JavaScript project

-1. Create a new Node.js application in an empty folder using your preferred terminal.

- ```bash

- npm init -y

- ```

-2. Edit the `package.json` file to use ES6 modules by adding the `"type": "module",` entry. This setting allows your code to use modern async/await syntax.

- :::code language="javascript" source="~/cosmos-db-sql-api-javascript-samples/001-quickstart/package.json" highlight="6":::

-### Install packages

-### [Passwordless (Recommended)](#tab/passwordless)

-1. Add the [@azure/cosmos](https://www.npmjs.com/package/@azure/cosmos) and [@azure/identity](https://www.npmjs.com/package/@azure/identity) npm packages to the Node.js project.

- ```bash

- npm install @azure/cosmos

- npm install @azure/identity

- ```

-1. Add the [dotenv](https://www.npmjs.com/package/dotenv) npm package to read environment variables from a `.env` file.

- npm install dotenv

-### [Connection String](#tab/connection-string)

-1. Add the [@azure/cosmos](https://www.npmjs.com/package/@azure/cosmos) npm package to the Node.js project.

- npm install @azure/cosmos

-1. Add the [dotenv](https://www.npmjs.com/package/dotenv) npm package to read environment variables from a `.env` file.

- npm install dotenv

-### Configure environment variables

-You'll use the following JavaScript classes to interact with these resources:

-The sample code described in this article creates a database named ``cosmicworks`` with a container named ``products``. The ``products`` table is designed to contain product details such as name, category, quantity, and a sale indicator. Each product also contains a unique identifier.

-For this sample code, the container will use the category as a logical partition key.

-## [Passwordless (Recommended)](#tab/passwordless)

-#### Authenticate using DefaultAzureCredential

-From the project directory, open the *index.js* file. In your editor, add npm packages to work with Cosmos DB and authenticate to Azure. You'll authenticate to Cosmos DB for NoSQL using `DefaultAzureCredential` from the [`@azure/identity`](https://www.npmjs.com/package/@azure/identity) package. `DefaultAzureCredential` will automatically discover and use the account you signed-in with previously.

-Create an environment variable that specifies your Cosmos DB endpoint.

-Create constants for the database and container names.

-Create a new client instance of the [`CosmosClient`](/javascript/api/@azure/cosmos/cosmosclient) class constructor with the `DefaultAzureCredential` object and the endpoint.

-## [Connection String](#tab/connection-string)

-From the project directory, open the *index.js* file. In your editor, import [@azure/cosmos](https://www.npmjs.com/package/@azure/cosmos) package to work with Cosmos DB and authenticate to Azure using the endpoint and key.

-Create environment variables that specify your Cosmos DB endpoint and key.

-Create constants for the database and container names.

-Create a new client instance of the [`CosmosClient`](/javascript/api/@azure/cosmos/cosmosclient) class constructor with the endpoint and key.

-### <a id="create-and-query-the-database"></a>

-### Create a database

-## [Passwordless (Recommended)](#tab/passwordless)

-The `@azure/cosmos` client library enables you to perform *data* operations using [Azure RBAC](../role-based-access-control.md). However, to authenticate *management* operations, such as creating and deleting databases, you must use RBAC through one of the following options:

-> - [Azure CLI scripts](manage-with-cli.md)

-> - [Azure PowerShell scripts](manage-with-powershell.md)

-> - [Azure Resource Manager templates (ARM templates)](manage-with-templates.md)

-> - [Azure Resource Manager JavaScript client library](https://www.npmjs.com/package/@azure/arm-cosmosdb)

-The Azure CLI approach is used in for this quickstart and passwordless access. Use the [`az cosmosdb sql database create`](/cli/azure/cosmosdb/sql/database#az-cosmosdb-sql-database-create) command to create a Cosmos DB for NoSQL database.

-```azurecli

-# Create a SQL API database `

-az cosmosdb sql database create `

- --account-name <cosmos-db-account-name> `

- --resource-group <resource-group-name> `

- --name cosmicworks

-```

-The command line to create a database is for PowerShell, shown on multiple lines for clarity. For other shell types, change the line continuation characters as appropriate. For example, for Bash, use backslash ("\\"). Or, remove the continuation characters and enter the command on one line.

-## [Connection String](#tab/connection-string)

-Add the following code to use the [``CosmosClient.Databases.createDatabaseIfNotExists``](/javascript/api/@azure/cosmos/databases#@azure-cosmos-databases-createifnotexists) method to create a new database if it doesn't already exist. This method returns a reference to the existing or newly created database.

-### Create a container

-## [Passwordless (Recommended)](#tab/passwordless)

-The `Microsoft.Azure.Cosmos` client library enables you to perform *data* operations using [Azure RBAC](../role-based-access-control.md). However, to authenticate *management* operations such as creating and deleting databases you must use RBAC through one of the following options:

-> - [Azure CLI scripts](manage-with-cli.md)

-> - [Azure PowerShell scripts](manage-with-powershell.md)

-> - [Azure Resource Manager templates (ARM templates)](manage-with-templates.md)

-> - [Azure Resource Manager JavaScript client library](https://www.npmjs.com/package/@azure/arm-cosmosdb)

-The Azure CLI approach is used in this example. Use the [`az cosmosdb sql container create`](/cli/azure/cosmosdb/sql/container#az-cosmosdb-sql-container-create) command to create a Cosmos DB container.

-```azurecli

-# Create a SQL API container

-az cosmosdb sql container create `

- --account-name <cosmos-db-account-name> `

- --resource-group <resource-group-name> `

- --database-name cosmicworks `

- --partition-key-path "/categoryId" `

- --name products

-```

-The command line to create a container is for PowerShell, on multiple lines for clarity. For other shell types, change the line continuation characters as appropriate. For example, for Bash, use backslash ("\\"). Or, remove the continuation characters and enter the command on one line. For Bash, you'll also need to add `MSYS_NO_PATHCONV=1` before the command so that Bash deals with the partition key parameter correctly.

-After the resources have been created, use classes from the `Microsoft.Azure.Cosmos` client libraries to connect to and query the database.

-## [Connection String](#tab/connection-string)

-Add the following code to create a container with the [``Database.Containers.createContainerIfNotExistsAsync``](/javascript/api/@azure/cosmos/containers#@azure-cosmos-containers-createifnotexists) method. The method returns a reference to the container.

-Add the following code to provide your data set. Each _product_ has a unique ID, name, category id (used as partition key) and other fields.

-Create a few items in the container by calling [``Container.Items.create``](/javascript/api/@azure/cosmos/items#@azure-cosmos-items-create) in a loop.

-### Get an item

-In Azure Cosmos DB, you can perform a point read operation by using both the unique identifier (``id``) and partition key fields. In the SDK, call [``Container.item().read``](/javascript/api/@azure/cosmos/item#@azure-cosmos-item-read) passing in both values to return an item.

-The partition key is specific to a container. In this Contoso Products container, the category id, `categoryId`, is used as the partition key.

-Add the following code to query for all items that match a specific filter. Create a [parameterized query expression](/javascript/api/@azure/cosmos/sqlqueryspec) then call the [``Container.Items.query``](/javascript/api/@azure/cosmos/items#@azure-cosmos-items-query) method. This method returns a [``QueryIterator``](/javascript/api/@azure/cosmos/queryiterator) that manages the pages of results. Then, use a combination of ``while`` and ``for`` loops to [``fetchNext``](/javascript/api/@azure/cosmos/queryiterator#@azure-cosmos-queryiterator-fetchnext) page of results as a [``FeedResponse``](/javascript/api/@azure/cosmos/feedresponse) and then iterate over the individual data objects.

-The query is programmatically composed to `SELECT * FROM todo t WHERE t.partitionKey = 'Bikes, Touring Bikes'`.

-If you want to use this data returned from the FeedResponse as an _item_, you need to create an [``Item``](/javascript/api/@azure/cosmos/item), using the [``Container.Items.read``](#get-an-item) method.

-### Delete an item

-Add the following code to delete an item you need to use the ID and partition key to get the item, then delete it. This example uses the [``Container.Item.delete``](/javascript/api/@azure/cosmos/item#@azure-cosmos-item-delete) method to delete the item.

-## Run the code

-This app creates an Azure Cosmos DB SQL API database and container. The example then creates items and then reads one item back. Finally, the example issues a query that should only return items matching a specific category. With each step, the example outputs metadata to the console about the steps it has performed.

-To run the app, use a terminal to navigate to the application directory and run the application.

-```bash