[ACR] Troubleshooting guide (Azure#22926)

Author: timovv

sdk/containerregistry/container-registry/README.md

@@ -56,14 +56,14 @@ The [Azure Identity library][identity] provides easy Azure Active Directory supp
 ```javascript
 const {
   ContainerRegistryClient,
-  KnownContainerRegistryAudience
+  KnownContainerRegistryAudience,
 } = require("@azure/container-registry");
 const { DefaultAzureCredential } = require("@azure/identity");
 
 const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT;
 // Create a ContainerRegistryClient that will authenticate through Active Directory
 const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(), {
-  audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud
+  audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud,
 });
 ```
 
@@ -79,7 +79,7 @@ To authenticate with a registry in a [National Cloud](https://docs.microsoft.com
 ```javascript
 const {
   ContainerRegistryClient,
-  KnownContainerRegistryAudience
+  KnownContainerRegistryAudience,
 } = require("@azure/container-registry");
 const { DefaultAzureCredential, AzureAuthorityHosts } = require("@azure/identity");
 
@@ -89,7 +89,7 @@ const client = new ContainerRegistryClient(
   endpoint,
   new DefaultAzureCredential({ authorityHost: AzureAuthorityHosts.AzureChina }),
   {
-    audience: KnownContainerRegistryAudience.AzureResourceManagerChina
+    audience: KnownContainerRegistryAudience.AzureResourceManagerChina,
   }
 );
 ```
@@ -111,7 +111,7 @@ Iterate through the collection of repositories in the registry.
 ```javascript
 const {
   ContainerRegistryClient,
-  KnownContainerRegistryAudience
+  KnownContainerRegistryAudience,
 } = require("@azure/container-registry");
 const { DefaultAzureCredential } = require("@azure/identity");
 
@@ -120,7 +120,7 @@ async function main() {
   // where "myregistryname" is the actual name of your registry
   const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
   const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(), {
-    audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud
+    audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud,
   });
 
   console.log("Listing repositories");
@@ -140,7 +140,7 @@ main().catch((err) => {
 ```javascript
 const {
   ContainerRegistryClient,
-  KnownContainerRegistryAudience
+  KnownContainerRegistryAudience,
 } = require("@azure/container-registry");
 
 async function main() {
@@ -149,7 +149,7 @@ async function main() {
 
   // Create a new ContainerRegistryClient for anonymous access
   const client = new ContainerRegistryClient(endpoint, {
-    audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud
+    audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud,
   });
 
   // Obtain a RegistryArtifact object to get access to image operations
@@ -175,7 +175,7 @@ main().catch((err) => {
 ```javascript
 const {
   ContainerRegistryClient,
-  KnownContainerRegistryAudience
+  KnownContainerRegistryAudience,
 } = require("@azure/container-registry");
 const { DefaultAzureCredential } = require("@azure/identity");
 
@@ -185,7 +185,7 @@ async function main() {
 
   // Create a new ContainerRegistryClient and RegistryArtifact to access image operations
   const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(), {
-    audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud
+    audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud,
   });
   const image = client.getArtifact("library/hello-world", "v1");
 
@@ -203,7 +203,7 @@ main().catch((err) => {
 ```javascript
 const {
   ContainerRegistryClient,
-  KnownContainerRegistryAudience
+  KnownContainerRegistryAudience,
 } = require("@azure/container-registry");
 const { DefaultAzureCredential } = require("@azure/identity");
 
@@ -212,7 +212,7 @@ async function main() {
   const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
   // Create a new ContainerRegistryClient
   const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(), {
-    audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud
+    audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud,
   });
 
   // Iterate through repositories
@@ -221,7 +221,7 @@ async function main() {
     const repository = client.getRepository(repositoryName);
     // Obtain the images ordered from newest to oldest by passing the `order` option
     const imageManifests = repository.listManifestProperties({
-      order: "LastUpdatedOnDescending"
+      order: "LastUpdatedOnDescending",
     });
     const imagesToKeep = 3;
     let imageCount = 0;
@@ -249,15 +249,7 @@ main().catch((err) => {
 
 ## Troubleshooting
 
-### Logging
-
-Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
-
-```javascript
-const { setLogLevel } = require("@azure/logger");
-
-setLogLevel("info");
-```
+For infomation about troubleshooting, refer to the [troubleshooting guide].
 
 ## Next steps
 
@@ -291,3 +283,4 @@ If you'd like to contribute to this library, please read the [contributing guide
 [azure_sub]: https://azure.microsoft.com/free/
 [identity]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md
 [az_sdk_js]: https://github.com/Azure/azure-sdk-for-js
+[troubleshooting guide]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/containerregistry/container-registry/TROUBLESHOOTING.md

sdk/containerregistry/container-registry/TROUBLESHOOTING.md

@@ -0,0 +1,75 @@
+# Troubleshoot Azure Container Registry client library issues
+
+This troubleshooting guide contains instructions to diagnose frequently encountered issues while using the Azure Container Registry client library for JavaScript and TypeScript.
+
+## General Troubleshooting
+
+Container registry service methods throw [`RestError`] on failure.
+
+### Enable client logging
+
+Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
+
+```javascript
+const { setLogLevel } = require("@azure/logger");
+
+setLogLevel("info");
+```
+
+See the [logger reference documentation][logging reference] for more information on how to configure logging.
+
+## Troubleshooting authentication errors
+
+### HTTP 401 Errors
+
+HTTP 401 errors indicate problems authenticating. Check the exception message or logs for more information.
+
+#### Anonymous access issues
+
+You may see an error similar to the one below. It indicates an attempt to perform an operation that requires authentication without credentials.
+
+```
+{"errors":[{"code":"UNAUTHORIZED","message":"authentication required, visit https://aka.ms/acr/authorization for
+more information."}]}
+```
+
+Unauthorized (anonymous) access can only be enabled for read (pull) operations such as listing repositories, getting properties or tags. Refer to [Anonymous pull access] to learn about the limitations of anonymous access.
+
+### HTTP 403 Errors
+
+HTTP 403 errors indicate that user is not authorized to perform a specific operation in Azure Container Registry.
+
+#### Insufficient permissions
+
+If you see an error similar to the one below, it means that the provided credentials do not have permission to access the registry.
+
+```
+RestError: {"errors":[{"code":"DENIED","message":"retrieving permissions failed"}]}
+```
+
+To resolve:
+
+1. Check that the application or user that is making the request has sufficient permissions. Check [Troubleshoot registry login] for possible solutions.
+1. If the user or application is granted sufficient privileges to query the workspace, make sure you are authenticating as that user/application. If you are authenticating using [DefaultAzureCredential], check the logs to verify that the credential used is the one you expected. To enable logging, see the [Enable client logging] section above.
+
+#### Network access issues
+
+The below error indicates that public access to the Azure Container Registry is disabled or restricted. Refer to [Troubleshoot network issues with registry] for more information.
+
+```
+RestError: {"errors":[{"code":"DENIED","message":"client with IP '<your IP address>' is not allowed access. Refer https://aka.m
+s/acr/firewall to grant access."}]}
+```
+
+<!-- Links -->
+
+[`resterror`]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/core/core-rest-pipeline/src/restError.ts
+[azure logger client library]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger
+[logging reference]: https://docs.microsoft.com/javascript/api/overview/azure/logger-readme
+[anonymous pull access]: https://docs.microsoft.com/azure/container-registry/anonymous-pull-access
+[troubleshoot registry login]: https://docs.microsoft.com/azure/container-registry/container-registry-troubleshoot-login
+[defaultazurecredential]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md#authenticating-with-the-defaultazurecredential
+[enable client logging]: https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/containerregistry/container-registry/TROUBLESHOOTING.md#enable-client-logging
+[troubleshoot network issues with registry]: https://docs.microsoft.com/azure/container-registry/container-registry-troubleshoot-access
+
+![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fcontainerregistry%2Fcontainer-registry%TROUBLESHOOTING.png)