Merge pull request #102052 from FeynmanZhou/main

Update container-registry-oras-artifacts.md and container-registry-oci-artifacts.md

Author: jborsecnik

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

@@ -17,25 +17,15 @@ To demonstrate this capability, this article shows how to use the [OCI Registry
 ## Prerequisites
 
 * **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).
-* **ORAS tool** - Download and install a current ORAS release for your operating system from the [GitHub repo](https://github.com/deislabs/oras/releases). The tool is released as a compressed tarball (`.tar.gz` file). Extract and install the file using standard procedures for your operating system.
+* **ORAS tool** - Download and install ORAS CLI v0.16.0 for your operating system from the [ORAS installation guide](https://oras.land/cli/). 
 * **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.
 * **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).
 * **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.
 
 
 ## Sign in to a registry
 
-This section shows two suggested workflows to sign into the registry, depending on the identity used. Choose the method appropriate for your environment.
-
-### Sign in with ORAS
-
-Using a [service principal](container-registry-auth-service-principal.md) with push rights, run the `oras login` command to sign in to the registry using the service principal application ID and password. Specify the fully qualified registry name (all lowercase), in this case *myregistry.azurecr.io*. The service principal application ID is passed in the environment variable `$SP_APP_ID`, and the password in the variable `$SP_PASSWD`.
-
-```bash
-oras login myregistry.azurecr.io --username $SP_APP_ID --password $SP_PASSWD
-```
-
-To read the password from Stdin, use `--password-stdin`.
+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.
 
 ### Sign in with Azure CLI
 
@@ -51,6 +41,52 @@ az acr login --name myregistry
 > [!NOTE]
 > `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.
 
+### Sign in with ORAS
+
+This section shows options to sign into the registry. Choose one method below appropriate for your environment.
+
+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).
+
+- 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.
+
+  ```azurecli
+  USER_NAME="00000000-0000-0000-0000-000000000000"
+  PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
+  ```
+
+- Authenticate with a [repository scoped token](container-registry-repository-scoped-permissions.md) (Preview) to use non-AD based tokens.
+
+  ```azurecli
+  USER_NAME="oras-token"
+  PASSWORD=$(az acr token create -n $USER_NAME \
+                    -r $ACR_NAME \
+                    --repository $REPO content/write \
+                    --only-show-errors \
+                    --query "credentials.passwords[0].value" -o tsv)
+  ```
+
+- 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.
+
+  ```azurecli
+  SERVICE_PRINCIPAL_NAME="oras-sp"
+  ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)
+  PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \
+            --scopes $(az acr show --name $ACR_NAME --query id --output tsv) \
+             --role acrpush \
+            --query "password" --output tsv)
+  USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)
+  ```
+  
+  Supply the credentials to `oras login` after authentication configured.
+
+  ```bash
+  oras login $REGISTRY \
+    --username $USER_NAME \
+    --password $PASSWORD
+  ```
+
+To read the password from Stdin, use `--password-stdin`.
+
 ## Push an artifact
 
 Create a text file in a local working working directory with some sample text. For example, in a bash shell:
@@ -65,15 +101,15 @@ Use the `oras push` command to push this text file to your registry. The followi
 
 ```bash
 oras push myregistry.azurecr.io/samples/artifact:1.0 \
-    --manifest-config /dev/null:application/vnd.unknown.config.v1+json \
+    --config /dev/null:application/vnd.unknown.v1\
     ./artifact.txt:application/vnd.unknown.layer.v1+txt
 ```
 
 **Windows**
 
 ```cmd
 .\oras.exe push myregistry.azurecr.io/samples/artifact:1.0 ^
-    --manifest-config NUL:application/vnd.unknown.config.v1+json ^
+    --config NUL:application/vnd.unknown.v1 ^
     .\artifact.txt:application/vnd.unknown.layer.v1+txt
 ```
 
@@ -124,8 +160,7 @@ rm artifact.txt
 Run `oras pull` to pull the artifact, and specify the media type used to push the artifact:
 
 ```bash
-oras pull myregistry.azurecr.io/samples/artifact:1.0 \
-    --media-type application/vnd.unknown.layer.v1+txt
+oras pull myregistry.azurecr.io/samples/artifact:1.0
 ```
 
 Verify that the pull was successful:

articles/container-registry/container-registry-oras-artifacts.md

@@ -11,27 +11,27 @@ ms.custom: references_regions, devx-track-azurecli
 
 # Push and pull supply chain artifacts using Azure Registry (Preview)
 
-Use an Azure container registry to store and manage a graph of artifacts, including signatures, software bill of materials (SBoM), security scan results or other types. 
+Use an Azure container registry to store and manage a graph of supply chain artifacts along side container images, including signatures, software bill of materials (SBoM), security scan results or other types. 
 
 ![Graph of artifacts, including a container image, signature and signed software bill of materials](./media/container-registry-artifacts/oras-artifact-graph.svg)
 
-To demonstrate this capability, this article shows how to use the [OCI Registry as Storage (ORAS)](https://oras.land) tool to push and pull a graph of artifacts to an Azure container registry.
+To demonstrate this capability, this article shows how to use the [OCI Registry as Storage (ORAS)](https://oras.land) tool to push and pull a graph of supply chain artifacts to an Azure container registry. 
 
-ORAS Artifacts support is a preview feature and subject to [limitations](#preview-limitations). It requires [zone redundancy](zone-redundancy.md), which is available in the Premium service tier. For information about registry service tiers and limits, see [Azure Container Registry service tiers](container-registry-skus.md).
+Supply chain artifact is a type of [OCI Artifact Manifest][oci-artifact-manifest]. OCI Artifact Manifest support is a preview feature and subject to [limitations](#preview-limitations). 
 
 ## Prerequisites
 
-* **ORAS CLI** - The ORAS CLI enables attach, copy, push, discover, pull of artifacts to an ORAS Artifacts enabled registry.
+* **ORAS CLI** - The ORAS CLI enables attach, copy, push, discover, pull of artifacts to an OCI Artifact Manifest enabled registry. 
 * **Azure CLI** - To create an identity, list and delete repositories, you need a local installation of the Azure CLI. Version 2.29.1 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).
 * **Docker (optional)** - To complete the walkthrough, a container image is referenced. You can use Docker installed locally to build and push a container image, or reference an existing container image. Docker provides packages that easily configure Docker on any [macOS][docker-mac], [Windows][docker-windows], or [Linux][docker-linux] system.
 
 ## Preview limitations
 
-ORAS Artifacts support is not available in the government or China clouds, but available in all other regions.
+OCI Artifact Manifest support is not available in the government or China clouds, but available in all other regions.
 
 ## ORAS installation
 
-Download and install a preview ORAS release for your operating system. See [ORAS installation instructions][oras-install-docs] for how to extract and install the file for your operating system. This article uses ORAS CLI 0.14.1 to demonstrate how to manage supply chain artifacts in ACR.
+Download and install a preview ORAS release for your operating system. See [ORAS installation instructions][oras-install-docs] for how to extract and install ORAS for your operating system. This article uses ORAS CLI 0.16.0 to demonstrate how to manage supply chain artifacts in ACR.
 
 ## Configure a registry
 
@@ -52,9 +52,9 @@ If needed, run the [az group create](/cli/azure/group#az-group-create) command t
 ```azurecli
 az group create --name $ACR_NAME --location southcentralus
 ```
-### Create ORAS Artifact enabled registry
+### Create OCI Artifact Manifest enabled registry
 
-Preview support for ORAS Artifacts requires Zone Redundancy, which requires a Premium service tier, in the South Central US region. Run the [az acr create](/cli/azure/acr#az-acr-create) command to create an ORAS Artifacts enabled registry. See the `az acr create` command help for more registry options.
+Preview support for OCI Artifact Manifest requires Zone Redundancy, which requires a Premium service tier, in the South Central US region. Run the [az acr create](/cli/azure/acr#az-acr-create) command to create an OCI Artifact Manifest enabled registry. See the `az acr create` command help for more registry options.
 
 ```azurecli
 az acr create \
@@ -65,7 +65,7 @@ az acr create \
   --output jsonc
 ```
 
-In the command output, note the `zoneRedundancy` property for the registry. When enabled, the registry is zone redundant, and ORAS Artifact enabled.
+In the command output, note the `zoneRedundancy` property for the registry. When enabled, the registry is zone redundant, and OCI Artifact Manifest enabled.
 
 ```output
 {
@@ -177,13 +177,13 @@ Attach the multi-file artifact as a reference.
 ```bash
 oras attach $IMAGE \
     ./readme.md:application/markdown \
-    ./readme-details.md:application/markdown
+    ./readme-details.md:application/markdown \
     --artifact-type readme/example
 ```
 
 ## Discovering artifact references
 
-The ORAS Artifacts Specification defines a [referrers API][oras-artifacts-referrers] for discovering references to a `subject` artifact. The `oras discover` command can show the list of references to the container image.
+The [OCI v1.1 Specification][oci-spec] defines a [referrers API][oci-artifacts-referrers] for discovering references to a `subject` artifact. The `oras discover` command can show the list of references to the container image.
 
 Using `oras discover`, view the graph of artifacts now stored in the registry.
 
@@ -203,7 +203,7 @@ myregistry.azurecr.io/net-monitor:v1
 
 ## Creating a deep graphs of artifacts
 
-The ORAS Artifacts specification enables deep graphs, enabling signed software bill of materials (SBoM) and other artifact types.
+The OCI v1.1 Specification enables deep graphs, enabling signed software bill of materials (SBoM) and other artifact types.
 
 ### Create a sample SBoM
 
@@ -226,7 +226,7 @@ Artifacts that are pushed as references, typically do not have tags as they are
 ```bash
 SBOM_DIGEST=$(oras discover -o json \
                 --artifact-type sbom/example \
-                $IMAGE | jq -r ".referrers[0].digest")
+                $IMAGE | jq -r ".manifests[0].digest")
 ```
 
 Create a signature of an SBoM
@@ -270,7 +270,7 @@ To pull a referenced type, the digest of reference is discovered with the `oras
 ```bash
 DOC_DIGEST=$(oras discover -o json \
               --artifact-type 'readme/example' \
-              $IMAGE | jq -r ".referrers[0].digest")
+              $IMAGE | jq -r ".manifests[0].digest")
 ```
 
 ### Create a clean directory for downloading
@@ -291,7 +291,7 @@ ls ./download
 
 ## View the repository and tag listing
 
-ORAS Artifacts enables artifact graphs to be pushed, discovered, pulled and copied without having to assign tags. This enables a tag listing to focus on the artifacts users think about, as opposed to the signatures and SBoMs that are associated with the container images, helm charts and other artifacts.
+OCI Artifact Manifest enables artifact graphs to be pushed, discovered, pulled and copied without having to assign tags. This enables a tag listing to focus on the artifacts users think about, as opposed to the signatures and SBoMs that are associated with the container images, helm charts and other artifacts.
 
 ### View a list of tags
 
@@ -356,7 +356,7 @@ The signature is untagged, but tracked as a `oras.artifact.manifest` reference t
 ```
 ## Delete all artifacts in the graph
 
-Support for the ORAS Artifacts specification enables deleting the graph of artifacts associated with the root artifact. Use the [az acr repository delete][az-acr-repository-delete] command to delete the signature, SBoM and the signature of the SBoM.
+Support for the OCI v1.1 Specification enables deleting the graph of artifacts associated with the root artifact. Use the [az acr repository delete][az-acr-repository-delete] command to delete the signature, SBoM and the signature of the SBoM.
 
 ```azurecli
 az acr repository delete \
@@ -376,15 +376,18 @@ az acr manifest list-metadata \
 ## Next steps
 
 * Learn more about [the ORAS CLI](https://oras.land/cli/)
-* Learn more about [ORAS Artifacts][oras-artifacts] for how to push, discover, pull, copy a graph of supply chain artifacts
+* Learn more about [OCI Artifact Manifest][oci-artifact-manifest] for how to push, discover, pull, copy a graph of supply chain artifacts
 
 <!-- LINKS - external -->
 [docker-linux]:         https://docs.docker.com/engine/installation/#supported-platforms
 [docker-mac]:           https://docs.docker.com/docker-for-mac/
 [docker-windows]:       https://docs.docker.com/docker-for-windows/
 [oras-install-docs]:    https://oras.land/cli/
 [oras-docs]:       https://oras.land/
-[oras-artifacts]:       https://github.com/oras-project/artifacts-spec/
+[oci-artifacts-referrers]:  https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers/
+[oci-artifact-manifest]:  https://github.com/opencontainers/image-spec/blob/main/artifact.md/
+[oci-spec]:  https://github.com/opencontainers/distribution-spec/blob/main/spec.md/
+
 <!-- LINKS - internal -->
 [az-acr-repository-show]: /cli/azure/acr/repository?#az_acr_repository_show
 [az-acr-repository-delete]: /cli/azure/acr/repository#az_acr_repository_delete