@azure/container-registry
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0-beta.5 • Public • Published

    Azure Container Registry client library for JavaScript

    Azure Container Registry allows you to store and manage container images and artifacts in a private registry for all types of container deployments.

    Use the client library for Azure Container Registry to:

    • List images or artifacts in a registry
    • Obtain metadata for images and artifacts, repositories and tags
    • Set read/write/delete properties on registry items
    • Delete images and artifacts, repositories and tags

    Key links:

    Getting started

    Currently supported environments

    See our support policy for more details.

    Prerequisites

    To create a new Container Registry, you can use the Azure Portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI:

    az acr create --name MyContainerRegistry --resource-group MyResourceGroup --location westus --sku Basic

    Install the @azure/container-registry package

    Install the Container Registry client library for JavaScript with npm:

    npm install @azure/container-registry

    Browser support

    JavaScript Bundle

    To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our bundling documentation.

    Authenticate the client

    The Azure Identity library provides easy Azure Active Directory support for authentication.

    const {
      ContainerRegistryClient,
      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
    });

    Note that these samples assume you have a CONTAINER_REGISTRY_ENDPOINT environment variable set, which is the URL including the name of the login server and the https:// prefix.

    National Clouds

    To authenticate with a registry in a National Cloud, you will need to make the following additions to your configuration:

    • Set the authorityHost in the credential options or via the AZURE_AUTHORITY_HOST environment variable
    • Set the audience in ContainerRegistryClientOptions
    const {
      ContainerRegistryClient,
      KnownContainerRegistryAudience
    } = require("@azure/container-registry");
    const { DefaultAzureCredential, AzureAuthorityHosts } = require("@azure/identity");
    
    const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT;
    // Create a ContainerRegistryClient that will authenticate through AAD in the China national cloud
    const client = new ContainerRegistryClient(
      endpoint,
      new DefaultAzureCredential({ authorityHost: AzureAuthorityHosts.AzureChina }),
      {
        audience: KnownContainerRegistryAudience.AzureResourceManagerChina
      }
    );

    For more information on using AAD with Azure Container Registry, please see the service's Authentication Overview.

    Key concepts

    A registry stores Docker images and OCI Artifacts. An image or artifact consists of a manifest and layers. An image's manifest describes the layers that make up the image, and is uniquely identified by its digest. An image can also be "tagged" to give it a human-readable alias. An image or artifact can have zero or more tags associated with it, and each tag uniquely identifies the image. A collection of images that share the same name but have different tags, is referred to as a repository.

    For more information please see Container Registry Concepts.

    Examples

    Listing repositories

    Iterate through the collection of repositories in the registry.

    const {
      ContainerRegistryClient,
      KnownContainerRegistryAudience
    } = require("@azure/container-registry");
    const { DefaultAzureCredential } = require("@azure/identity");
    
    async function main() {
      // endpoint should be in the form of "https://myregistryname.azurecr.io"
      // 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
      });
    
      console.log("Listing repositories");
      const iterator = client.listRepositoryNames();
      for await (const repository of iterator) {
        console.log(`  repository: ${repository}`);
      }
    }
    
    main().catch((err) => {
      console.error("The sample encountered an error:", err);
    });

    List tags with anonymous access

    const {
      ContainerRegistryClient,
      KnownContainerRegistryAudience
    } = require("@azure/container-registry");
    
    async function main() {
      // Get the service endpoint from the environment
      const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
    
      // Create a new ContainerRegistryClient for anonymous access
      const client = new ContainerRegistryClient(endpoint, {
        audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud
      });
    
      // Obtain a RegistryArtifact object to get access to image operations
      const image = client.getArtifact("library/hello-world", "latest");
    
      // List the set of tags on the hello_world image tagged as "latest"
      const tagIterator = image.listTagProperties();
    
      // Iterate through the image's tags, listing the tagged alias for the image
      console.log(`${image.fullyQualifiedReference}  has the following aliases:`);
      for await (const tag of tagIterator) {
        console.log(`  ${tag.registryLoginServer}/${tag.repositoryName}:${tag.name}`);
      }
    }
    
    main().catch((err) => {
      console.error("The sample encountered an error:", err);
    });

    Set artifact properties

    const {
      ContainerRegistryClient,
      KnownContainerRegistryAudience
    } = require("@azure/container-registry");
    const { DefaultAzureCredential } = require("@azure/identity");
    
    async function main() {
      // Get the service endpoint from the environment
      const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
    
      // Create a new ContainerRegistryClient and RegistryArtifact to access image operations
      const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(), {
        audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud
      });
      const image = client.getArtifact("library/hello-world", "v1");
    
      // Set permissions on the image's "latest" tag
      await image.updateTagProperties("latest", { canWrite: false, canDelete: false });
    }
    
    main().catch((err) => {
      console.error("The sample encountered an error:", err);
    });

    Delete images

    const {
      ContainerRegistryClient,
      KnownContainerRegistryAudience
    } = require("@azure/container-registry");
    const { DefaultAzureCredential } = require("@azure/identity");
    
    async function main() {
      // Get the service endpoint from the environment
      const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
      // Create a new ContainerRegistryClient
      const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(), {
        audience: KnownContainerRegistryAudience.AzureResourceManagerPublicCloud
      });
    
      // Iterate through repositories
      const repositoryNames = client.listRepositoryNames();
      for await (const repositoryName of repositoryNames) {
        const repository = client.getRepository(repositoryName);
        // Obtain the images ordered from newest to oldest by passing the `orderBy` option
        const imageManifests = repository.listManifestProperties({
          orderBy: "LastUpdatedOnDescending"
        });
        const imagesToKeep = 3;
        let imageCount = 0;
        // Delete images older than the first three.
        for await (const manifest of imageManifests) {
          imageCount++;
          if (imageCount > imagesToKeep) {
            const image = repository.getArtifact(manifest.digest);
            console.log(`Deleting image with digest ${manifest.digest}`);
            console.log(`  Deleting the following tags from the image:`);
            for (const tagName of manifest.tags) {
              console.log(`    ${manifest.repositoryName}:${tagName}`);
              image.deleteTag(tagName);
            }
            await image.delete();
          }
        }
      }
    }
    
    main().catch((err) => {
      console.error("The sample encountered an error:", 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:

    import { setLogLevel } from "@azure/logger";
    
    setLogLevel("info");

    Next steps

    Please take a look at the samples directory for detailed examples that demonstrate how to use the client libraries.

    Contributing

    If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

    Related projects

    Impressions

    Install

    npm i @azure/container-registry

    DownloadsWeekly Downloads

    391

    Version

    1.0.0-beta.5

    License

    MIT

    Unpacked Size

    882 kB

    Total Files

    69

    Last publish

    Collaborators

    • southpolesteve
    • christopheranderson
    • azure-sdk