Skip to content

Commit b777f24

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #222837 from SteveLasker/oras-oci-artifact-update
ORAS and OCI artifact updates
2 parents 607b4a8 + 0ed8bec commit b777f24

File tree

2 files changed

+315
-306
lines changed

2 files changed

+315
-306
lines changed

‎articles/container-registry/container-registry-oci-artifacts.md

Lines changed: 126 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,228 +1,222 @@
11
---
2-
title: Push and pull OCI artifact
3-
description: Push and pull Open Container Initiative (OCI) artifacts using a private container registry in Azure
2+
title: Push and pull OCI artifact references
3+
description: Push and pull Open Container Initiative (OCI) artifacts using a container registry in Azure
44
author: SteveLasker
55
manager: gwallace
66
ms.topic: article
7-
ms.date: 10/11/2022
7+
ms.date: 01/03/2023
88
ms.author: stevelas
99
---
1010

11-
# Push and pull an OCI artifact using an Azure container registry
11+
# Push and pull OCI artifacts using an Azure container registry
1212

13-
You can use an Azure container registry to store and manage [Open Container Initiative (OCI) artifacts](container-registry-image-formats.md#oci-artifacts) as well as Docker and Docker-compatible container images.
13+
You can use an [Azure container registry][acr-landing] to store and manage [Open Container Initiative (OCI) artifacts](container-registry-image-formats.md#oci-artifacts) as well as Docker and OCI container images.
1414

15-
To demonstrate this capability, this article shows how to use the [OCI Registry as Storage (ORAS)](https://github.com/deislabs/oras) tool to push a sample artifact - a text file - to an Azure container registry. Then, pull the artifact from the registry. You can manage a variety of OCI artifacts in an Azure container registry using different command-line tools appropriate to each artifact.
15+
To demonstrate this capability, this article shows how to use the [OCI Registry as Storage (ORAS)][oras-cli] CLI to push a sample artifact - a text file - to an Azure container registry. Then, pull the artifact from the registry. You can manage various OCI artifacts in an Azure container registry using different command-line tools appropriate to each artifact.
1616

1717
## Prerequisites
1818

19-
* **Azure container registry** - Create a container registry in your Azure subscription. For example, use the [Azure portal](container-registry-get-started-portal.md) or the [Azure CLI](container-registry-get-started-azure-cli.md).
20-
* **ORAS tool** - Download and install ORAS CLI v0.16.0 for your operating system from the [ORAS installation guide](https://oras.land/cli/).
21-
* **Azure Active Directory service principal (optional)** - To authenticate directly with ORAS, create a [service principal](container-registry-auth-service-principal.md) to access your registry. Ensure that the service principal is assigned a role such as AcrPush so that it has permissions to push and pull artifacts.
22-
* **Azure CLI (optional)** - To use an individual identity, you need a local installation of the Azure CLI. Version 2.0.71 or later is recommended. Run `az --version `to find the version. If you need to install or upgrade, see [Install Azure CLI](/cli/azure/install-azure-cli).
23-
* **Docker (optional)** - To use an individual identity, you must also have Docker installed locally, to authenticate with the registry. Docker provides packages that easily configure Docker on any [macOS][docker-mac], [Windows][docker-windows], or [Linux][docker-linux] system.
19+
* **Azure container registry** - Create a container registry in your Azure subscription. For example, use the [Azure portal](container-registry-get-started-portal.md) or [az acr create][az-acr-create].
20+
* **Azure CLI** - Version `2.29.1` or later is required. See [Install Azure CLI][azure-cli-install] for installation and/or upgrade.
21+
* **ORAS CLI** - Version `v0.16.0` is required. See: [ORAS installation][oras-install-docs].
22+
* **Docker (Optional)** - While Docker Desktop isn't required, the `oras` CLI utilizes the Docker desktop credential store for storing credentials. If Docker Desktop is installed, it must be running for `oras login`.
2423

24+
## Configure a registry
2525

26-
## Sign in to a registry
27-
28-
This section shows two suggested workflows to sign into the registry, depending on the identity used. Choose the one of the two methods below appropriate for your environment.
26+
Configure environment variables to easily copy/paste commands into your shell. The commands can be run locally or in the [Azure Cloud Shell](https://shell.azure.com/).
2927

30-
### Sign in with Azure CLI
28+
```bash
29+
ACR_NAME=myregistry
30+
REGISTRY=$ACR_NAME.azurecr.io
31+
```
3132

32-
[Sign in](/cli/azure/authenticate-azure-cli) to the Azure CLI with your identity to push and pull artifacts from the container registry.
33+
## Sign in to a registry
3334

34-
Then, use the Azure CLI command [az acr login](/cli/azure/acr#az-acr-login) to access the registry. For example, to authenticate to a registry named *myregistry*:
35+
Authenticate with your [individual Azure AD identity](container-registry-authentication.md?tabs=azure-cli#individual-login-with-azure-ad) using an AD token. Always use "000..." for the `USER_NAME` as the token is parsed through the `PASSWORD` variable.
3536

3637
```azurecli
38+
# Login to Azure
3739
az login
38-
az acr login --name myregistry
40+
41+
# Login to ACR, using a token based on your Azure identity
42+
USER_NAME="00000000-0000-0000-0000-000000000000"
43+
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
3944
```
4045

4146
> [!NOTE]
42-
> `az acr login` uses the Docker client to set an Azure Active Directory token in the `docker.config` file. The Docker client must be installed and running to complete the individual authentication flow.
47+
> ACR and ORAS support multiple authentication options for users and system automation. This article uses individual identity, using an Azure token. For more authentication options see [Authenticate with an Azure container registry][acr-authentication]
4348
4449
### Sign in with ORAS
4550

46-
This section shows options to sign into the registry. Choose one method below appropriate for your environment.
47-
48-
Run `oras login` to authenticate with the registry. You may pass [registry credentials](container-registry-authentication.md) appropriate for your scenario, such as service principal credentials, user identity, or a repository-scoped token (preview).
49-
50-
- Authenticate with your [individual Azure AD identity](container-registry-authentication.md?tabs=azure-cli#individual-login-with-azure-ad) to use an AD token. Always use "000..." as the token is parsed through the `PASSWORD` variable.
51-
52-
```azurecli
53-
USER_NAME="00000000-0000-0000-0000-000000000000"
54-
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
55-
```
56-
57-
- Authenticate with a [repository scoped token](container-registry-repository-scoped-permissions.md) (Preview) to use non-AD based tokens.
58-
59-
```azurecli
60-
USER_NAME="oras-token"
61-
PASSWORD=$(az acr token create -n $USER_NAME \
62-
-r $ACR_NAME \
63-
--repository $REPO content/write \
64-
--only-show-errors \
65-
--query "credentials.passwords[0].value" -o tsv)
66-
```
67-
68-
- Authenticate with an Azure Active Directory [service principal with pull and push permissions](container-registry-auth-service-principal.md#create-a-service-principal) (AcrPush role) to the registry.
69-
70-
```azurecli
71-
SERVICE_PRINCIPAL_NAME="oras-sp"
72-
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)
73-
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \
74-
--scopes $(az acr show --name $ACR_NAME --query id --output tsv) \
75-
--role acrpush \
76-
--query "password" --output tsv)
77-
USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)
78-
```
79-
80-
Supply the credentials to `oras login` after authentication configured.
51+
Provide the credentials to `oras login`.
8152

8253
```bash
8354
oras login $REGISTRY \
8455
--username $USER_NAME \
8556
--password $PASSWORD
8657
```
8758

88-
To read the password from Stdin, use `--password-stdin`.
59+
## Push a root artifact
8960

90-
## Push an artifact
61+
A root artifact is an artifact that has no `subject` parent. Root artifacts can be anything from a container image, a helm chart, a readme file for the repository. Reference artifacts, described in [Attach, push, and pull supply chain artifacts](container-registry-oras-artifacts.md) are artifacts that refer to another artifact. Reference artifacts can be anything from a signature, software bill of materials, scan report or other evolving types.
9162

92-
Create a text file in a local working working directory with some sample text. For example, in a bash shell:
63+
For this example, create content that represents a markdown file:
9364

9465
```bash
95-
echo "Here is an artifact" > artifact.txt
66+
echo 'Readme Content' > readme.md
9667
```
9768

98-
Use the `oras push` command to push this text file to your registry. The following example pushes the sample text file to the `samples/artifact` repo. The registry is identified with the fully qualified registry name *myregistry.azurecr.io* (all lowercase). The artifact is tagged `1.0`. The artifact has an undefined type, by default, identified by the *media type* string following the filename `artifact.txt`. See [OCI Artifacts](https://github.com/opencontainers/artifacts) for additional types.
69+
The following step pushes the `readme.md` file to `<myregistry>.azurecr.io/samples/artifact:readme`.
70+
- The registry is identified with the fully qualified registry name `<myregistry>.azurecr.io` (all lowercase), followed by the namespace and repo: `/samples/artifact`.
71+
- The artifact is tagged `:readme`, to identify it uniquely from other artifacts listed in the repo (`:latest, :v1, :v1.0.1`).
72+
- Setting `--artifact-type readme/example` differentiates the artifact from a container image, which uses `application/vnd.oci.image.config.v1+json`.
73+
- The `./readme.md` identifies the file uploaded, and the `:application/markdown` represents the [IANA `mediaType`][iana-mediatypes] of the file.
74+
For more information, see [OCI Artifact Authors Guidance](https://github.com/opencontainers/artifacts/blob/main/artifact-authors.md).
75+
76+
Use the `oras push` command to push the file to your registry.
9977

100-
**Linux or macOS**
78+
**Linux, WSL2 or macOS**
10179

10280
```bash
103-
oras push myregistry.azurecr.io/samples/artifact:1.0 \
104-
--config /dev/null:application/vnd.unknown.v1\
105-
./artifact.txt:application/vnd.unknown.layer.v1+txt
81+
oras push $REGISTRY/samples/artifact:readme \
82+
--artifact-type readme/example \
83+
./readme.md:application/markdown
10684
```
10785

10886
**Windows**
10987

11088
```cmd
111-
.\oras.exe push myregistry.azurecr.io/samples/artifact:1.0 ^
112-
--config NUL:application/vnd.unknown.v1 ^
113-
.\artifact.txt:application/vnd.unknown.layer.v1+txt
89+
.\oras.exe push $REGISTRY/samples/artifact:readme ^
90+
--artifact-type readme/example ^
91+
.\readme.md:application/markdown
11492
```
11593

116-
Output for a successful push is similar to the following:
94+
Output for a successful push is similar to the following output:
11795

11896
```console
119-
Uploading 33998889555f artifact.txt
120-
Pushed myregistry.azurecr.io/samples/artifact:1.0
121-
Digest: sha256:xxxxxxbc912ef63e69136f05f1078dbf8d00960a79ee73c210eb2a5f65xxxxxx
97+
Uploading 2fdeac43552b readme.md
98+
Uploaded 2fdeac43552b readme.md
99+
Pushed <myregistry>.azurecr.io/samples/artifact:readme
100+
Digest: sha256:e2d60d1b171f08bd10e2ed171d56092e39c7bac1aec5d9dcf7748dd702682d53
122101
```
123102

124-
To manage artifacts in your registry, if you are using the Azure CLI, run standard `az acr` commands for managing images. For example, get the attributes of the artifact using the [az acr repository show][az-acr-repository-show] command:
103+
## Push a multi-file root artifact
125104

126-
```azurecli
127-
az acr repository show \
128-
--name myregistry \
129-
--image samples/artifact:1.0
130-
```
105+
When OCI artifacts are pushed to a registry with ORAS, each file reference is pushed as a blob. To push separate blobs, reference the files individually, or collection of files by referencing a directory.
106+
For more information how to push a collection of files, see [Pushing artifacts with multiple files][oras-push-multifiles]
131107

132-
Output is similar to the following:
108+
Create some documentation for the repository:
133109

134-
```json
135-
{
136-
"changeableAttributes": {
137-
"deleteEnabled": true,
138-
"listEnabled": true,
139-
"readEnabled": true,
140-
"writeEnabled": true
141-
},
142-
"createdTime": "2019-08-28T20:43:31.0001687Z",
143-
"digest": "sha256:xxxxxxbc912ef63e69136f05f1078dbf8d00960a79ee73c210eb2a5f65xxxxxx",
144-
"lastUpdateTime": "2019-08-28T20:43:31.0001687Z",
145-
"name": "1.0",
146-
"signed": false
147-
}
110+
```bash
111+
echo 'Readme Content' > readme.md
112+
mkdir details/
113+
echo 'Detailed Content' > details/readme-details.md
114+
echo 'More detailed Content' > details/readme-more-details.md
148115
```
149116

150-
## Pull an artifact
117+
Push the multi-file artifact:
151118

152-
Run the `oras pull` command to pull the artifact from your registry.
153-
154-
First remove the text file from your local working directory:
119+
**Linux, WSL2 or macOS**
155120

156121
```bash
157-
rm artifact.txt
122+
oras push $REGISTRY/samples/artifact:readme \
123+
--artifact-type readme/example\
124+
./readme.md:application/markdown\
125+
./details
158126
```
159127

160-
Run `oras pull` to pull the artifact, and specify the media type used to push the artifact:
128+
**Windows**
161129

162-
```bash
163-
oras pull myregistry.azurecr.io/samples/artifact:1.0
130+
```cmd
131+
.\oras.exe push $REGISTRY/samples/artifact:readme ^
132+
--artifact-type readme/example ^
133+
.\readme.md:application/markdown ^
134+
.\details
164135
```
165136

166-
Verify that the pull was successful:
137+
## Discover the manifest
138+
139+
To view the manifest created as a result of `oras push`, use `oras manifest fetch`:
167140

168141
```bash
169-
$ cat artifact.txt
170-
Here is an artifact
142+
oras manifest fetch --pretty $REGISTRY/samples/artifact:readme
171143
```
172144

173-
## Remove the artifact (optional)
174-
175-
To remove the artifact from your Azure container registry, use the [az acr repository delete][az-acr-repository-delete] command. The following example removes the artifact you stored there:
145+
The output will be similar to:
176146

177-
```azurecli
178-
az acr repository delete \
179-
--name myregistry \
180-
--image samples/artifact:1.0
147+
```json
148+
{
149+
"mediaType": "application/vnd.oci.artifact.manifest.v1+json",
150+
"artifactType": "readme/example",
151+
"blobs": [
152+
{
153+
"mediaType": "application/markdown",
154+
"digest": "sha256:2fdeac43552b71eb9db534137714c7bad86b53a93c56ca96d4850c9b41b777fc",
155+
"size": 15,
156+
"annotations": {
157+
"org.opencontainers.image.title": "readme.md"
158+
}
159+
},
160+
{
161+
"mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
162+
"digest": "sha256:0d6c7434a34f6854f971487621426332e6c0fda08040b9e6cc8a93f354cee0b1",
163+
"size": 189,
164+
"annotations": {
165+
"io.deis.oras.content.digest": "sha256:11eceb2e7ac3183ec9109003a7389468ec73ad5ceaec0c4edad0c1b664c5593a",
166+
"io.deis.oras.content.unpack": "true",
167+
"org.opencontainers.image.title": "details"
168+
}
169+
}
170+
],
171+
"annotations": {
172+
"org.opencontainers.artifact.created": "2023-01-10T14:44:06Z"
173+
}
174+
}
181175
```
182176

183-
## Example: Build Docker image from OCI artifact
177+
## Pull a root artifact
184178

185-
Source code and binaries to build a container image can be stored as OCI artifacts in an Azure container registry. You can reference a source artifact as the build context for an [ACR task](container-registry-tasks-overview.md). This example shows how to store a Dockerfile as an OCI artifact and then reference the artifact to build a container image.
186-
187-
For example, create a one-line Dockerfile:
179+
Create a clean directory for downloading
188180

189181
```bash
190-
echo "FROM mcr.microsoft.com/hello-world" > hello-world.dockerfile
182+
mkdir ./download
191183
```
192184

193-
Log in to the destination container registry.
185+
Run the `oras pull` command to pull the artifact from your registry.
194186

195-
```azurecli
196-
az login
197-
az acr login --name myregistry
187+
```bash
188+
oras pull -o ./download $REGISTRY/samples/artifact:readme
198189
```
199190

200-
Create and push a new OCI artifact to the destination registry by using the `oras push` command. This example sets the default media type for the artifact.
191+
### View the pulled files
201192

202193
```bash
203-
oras push myregistry.azurecr.io/dockerfile:1.0 hello-world.dockerfile
194+
tree ./download
204195
```
205196

206-
Run the [az acr build](/cli/azure/acr#az-acr-build) command to build the hello-world image using the new artifact as build context:
197+
## Remove the artifact (optional)
207198

208-
```azurecli
209-
az acr build --registry myregistry --image builds/hello-world:v1 \
210-
--file hello-world.dockerfile \
211-
oci://myregistry.azurecr.io/dockerfile:1.0
199+
To remove the artifact from your registry, use the `oras manifest delete` command.
200+
201+
```bash
202+
oras manifest delete $REGISTRY/samples/artifact:readme
212203
```
213204

214205
## Next steps
215206

216-
* Learn more about [the ORAS Library](https://github.com/deislabs/oras), including how to configure a manifest for an artifact
207+
* Learn about [Artifact References](container-registry-oras-artifacts.md), associating signatures, software bill of materials and other reference types
208+
* Learn more about [the ORAS Project](https://oras.land/), including how to configure a manifest for an artifact
217209
* Visit the [OCI Artifacts](https://github.com/opencontainers/artifacts) repo for reference information about new artifact types
218210

219-
220-
221211
<!-- LINKS - external -->
222-
[docker-linux]: https://docs.docker.com/engine/installation/#supported-platforms
223-
[docker-mac]: https://docs.docker.com/docker-for-mac/
224-
[docker-windows]: https://docs.docker.com/docker-for-windows/
212+
[iana-mediatypes]: https://www.rfc-editor.org/rfc/rfc6838
213+
[oras-install-docs]: https://oras.land/cli/
214+
[oras-cli]: https://oras.land/cli_reference/
215+
[oras-push-multifiles]: https://oras.land/cli/1_pushing/#pushing-artifacts-with-multiple-files
225216

226217
<!-- LINKS - internal -->
227-
[az-acr-repository-show]: /cli/azure/acr/repository?#az_acr_repository_show
218+
[acr-landing]: https://aka.ms/acr
219+
[acr-authentication]: /azure/container-registry/container-registry-authentication?tabs=azure-cli
220+
[az-acr-create]: /azure/container-registry/container-registry-get-started-azure-cli
228221
[az-acr-repository-delete]: /cli/azure/acr/repository#az_acr_repository_delete
222+
[azure-cli-install]: /cli/azure/install-azure-cli

0 commit comments

Comments
 (0)