diff --git a/sdk/containerregistry/container-registry/CHANGELOG.md b/sdk/containerregistry/container-registry/CHANGELOG.md index 98877c63323d..afeeaf6aea15 100644 --- a/sdk/containerregistry/container-registry/CHANGELOG.md +++ b/sdk/containerregistry/container-registry/CHANGELOG.md @@ -1,5 +1,8 @@ # Release History -## 1.0.0-beta.1 (Unreleased) +## 1.0.0-beta.1 (2021-04-06) -Initial version of Azure Container Registry client SDK library. +- Initial version of Azure Container Registry client SDK library. +- This release is a preview of our efforts to create a client library that is user friendly and + idiomatic to the JavaScript ecosystem. The reasons for most of the changes in this update can be found in the + [Azure SDK Design Guidelines for TypeScript](https://azure.github.io/azure-sdk/typescript_introduction.html). diff --git a/sdk/containerregistry/container-registry/README.md b/sdk/containerregistry/container-registry/README.md index e1cebe5b4a9d..4661067eaa4f 100644 --- a/sdk/containerregistry/container-registry/README.md +++ b/sdk/containerregistry/container-registry/README.md @@ -1,8 +1,20 @@ # Azure Container Registry client library for JavaScript -Azure [Container Registry](https://azure.microsoft.com/services/container-registry/) is a managed, private Docker registry service based on the open-source Docker Registry 2.0. Create and maintain Azure container registries to store and manage your private Docker container images and related artifacts. +Azure Container Registry allows you to store and manage container images and artifacts in a private registry for all types of container deployments. -Use Azure container registries with your existing container development and deployment pipelines, or use Azure Container Registry Tasks to build container images in Azure. Build on demand, or fully automate builds with triggers such as source code commits and base image updates. +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 + +[Source code][source] | +[Package (NPM)] | +[API reference documentation] | +[REST API documentation][rest_docs] | +[Product documentation][product_docs] | +[Samples][samples] ## Getting started @@ -12,10 +24,15 @@ Use Azure container registries with your existing container development and depl ### Prerequisites -- An [Azure subscription][azure_sub]. -- An [Azure Container Registry resource][acr_resource] +You need an [Azure subscription][azure_sub] and a [Container Registry account][container_registry_docs] to use this package. -Usually you'd put a shell command for provisioning the necessary Azure services here. +To create a new Container Registry, you can use the [Azure Portal][container_registry_create_portal], +[Azure PowerShell][container_registry_create_ps], or the [Azure CLI][container_registry_create_cli]. +Here's an example using the Azure CLI: + +```Powershell +az acr create --name MyContainerRegistry --resource-group MyResourceGroup --location westus --sku Basic +``` ### Install the `@azure/container-registry` package @@ -31,21 +48,67 @@ npm install @azure/container-registry 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](https://aka.ms/AzureSDKBundling). -### Further examples +### Authenticate the client + +The [Azure Identity library][identity] provides easy Azure Active Directory support for authentication. + +```javascript +const { ContainerRegistryClient } = require("@azure/container-registry"); +const { DefaultAzureCredential } = require("@azure/identity"); + +const endpoint = process.env.REGISTRY_ENDPOINT; +// Create a ContainerRegistryClient that will authenticate through Active Directory +const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential()); +``` + +Note that these samples assume you have a `REGISTRY_ENDPOINT` environment variable set, which is the URL including the name of the login server and the `https://` prefix. -Top-level examples usually include things like creating and authenticating the main Client. If your service supports multiple means of authenticating (e.g. key-based and Azure Active Directory) you can give a separate example of each. +For more information on using AAD with Azure Container Registry, please see the service's [Authentication Overview](https://docs.microsoft.com/azure/container-registry/container-registry-authentication). ## Key concepts -### ContainerRegistryClient +A **registry** stores Docker images and [OCI Artifacts](https://opencontainers.org/). 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**. -`ContainerRegistryClient` provides operations to interact with an Azure Container Registry instance. +For more information please see [Container Registry Concepts](https://docs.microsoft.com/azure/container-registry/container-registry-concepts). ## Examples -### First Example +### Listing repositories - +Iterate through the collection of repositories in the registry. + +```javascript +const { ContainerRegistryClient } = require("@azure/container-registry"); +const { DefaultAzureCredential } = require("@azure/identity"); + +async function main() { + // Get the service endpoint from the environment + const endpoint = process.env.REGISTRY_ENDPOINT; + // Create a new ContainerRegistryClient + const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential()); + + console.log("Listing repositories"); + const iterator = client.listRepositories(); + for await (const repository of iterator) { + console.log(` repository: ${repository}`); + } + + console.log(" by pages"); + const pages = client.listRepositories().byPage({ maxPageSize: 2 }); + let result = await pages.next(); + while (!result.done) { + console.log(" -- page -- "); + for (const repository of result.value) { + console.log(` repository: ${repository}`); + } + result = await pages.next(); + } +} + +main().catch((err) => { + console.error("The sample encountered an error:", err); +}); +``` Create several code examples for how someone would use your library to accomplish a common task with the service. @@ -63,7 +126,7 @@ setLogLevel("info"); ## Next steps -Please take a look at the [samples](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/containerregistry/container-registry/samples) directory for detailed examples that demonstrate how to use the client libraries. +Please take a look at the [samples][samples] directory for detailed examples that demonstrate how to use the client libraries. ## Contributing @@ -71,10 +134,24 @@ If you'd like to contribute to this library, please read the [contributing guide ## Related projects -- [Microsoft Azure SDK for Javascript](https://github.com/Azure/azure-sdk-for-js) +- [Microsoft Azure SDK for Javascript][az_sdk_js] ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fcontainerregistry%2Fcontainer-registry%2FREADME.png) -[azure_cli]: https://docs.microsoft.com/cli/azure [azure_sub]: https://azure.microsoft.com/free/ [acr_resource]: https://ms.portal.azure.com/#create/Microsoft.ContainerRegistry +[source]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/containerregistry/container-registry/ +[package]: https://www.npmjs.com/package/@azure/container-registry +[api_docs]: https://docs.microsoft.com/javascript/api/@azure/container-registry +[rest_docs]: https://docs.microsoft.com/rest/api/containerregistry/ +[product_docs]: https://docs.microsoft.com/azure/container-registry/ +[samples]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/containerregistry/container-registry/samples +[container_registry_docs]: https://docs.microsoft.com/azure/container-registry/container-registry-intro +[container_registry_create_ps]: https://docs.microsoft.com/azure/container-registry/container-registry-get-started-powershell +[container_registry_create_cli]: https://docs.microsoft.com/azure/container-registry/container-registry-get-started-azure-cli +[container_registry_create_portal]: https://docs.microsoft.com/azure/container-registry/container-registry-get-started-portal +[container_registry_concepts]: https://docs.microsoft.com/azure/container-registry/container-registry-concepts +[azure_cli]: https://docs.microsoft.com/cli/azure +[azure_sub]: https://azure.microsoft.com/free/ +[identity]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/README.md +[az_sdk_js]: https://github.com/Azure/azure-sdk-for-js