Compartir por

Administración de artefactos de OCI y artefactos de cadena de suministro con ORAS

  • Artigo

Azure Container Registry (ACR) le ayuda a administrar los artefactos de Open Container Initiative (OCI) y los artefactos de la cadena de suministro. En este artículo se explica cómo usar ACR para administrar artefactos de OCI y artefactos de cadena de suministro de forma eficaz. Aprenda a almacenar, administrar y recuperar los artefactos de OCI y un gráfico de artefactos de la cadena de suministro, incluidas firmas, lista de materiales de software (SBOM), resultados de análisis de seguridad y otros tipos.

Este artículo se divide en dos secciones principales:

Requisitos previos

  • Registro de contenedor de Azure: cree un registro de contenedor en la suscripción de Azure. Por ejemplo, use Azure Portal o la CLI de Azure.
  • CLI de Azure: se requiere la versión 2.29.1 o posterior. Consulte Instalación de la CLI de Azure para obtener información sobre la instalación o actualización.
  • CLI de ORAS: se requiere la versión v1.1.0 o una versión posterior. Consulte: Instalación de ORAS.
  • Docker (opcional): para completar el tutorial, se hace referencia a una imagen de contenedor. Puede usar Docker instalado localmente para crear e insertar una imagen de contenedor, o bien usar acr build para crear de forma remota en Azure.
    Aunque Docker Desktop no es necesario, la CLI de oras usa el almacén de credenciales de escritorio de Docker para almacenar credenciales. Si Docker Desktop está instalado, debe ejecutarse para oras login.

Configuración del registro

Para configurar el entorno para facilitar la ejecución de comandos, siga estos pasos:

  1. Establezca la variable ACR_NAME en el nombre de registro.
  2. Establezca la variable REGISTRY en $ACR_NAME.azurecr.io.
  3. Establezca la variable REPO en el nombre del repositorio.
  4. Establezca la variable TAG en la etiqueta deseada.
  5. Establezca la variable IMAGE en $REGISTRY/${REPO}:$TAG.

Establecimiento de variables de entorno

Configure un nombre de registro, credenciales de inicio de sesión, un nombre de repositorio y una etiqueta para insertar y extraer artefactos. En el ejemplo siguiente se usa el nombre de repositorio net-monitor y la etiqueta v1. Reemplace por su propio nombre y etiqueta del repositorio.

ACR_NAME=myregistry
REGISTRY=$ACR_NAME.azurecr.io
REPO=net-monitor
TAG=v1
IMAGE=$REGISTRY/${REPO}:$TAG

Inicio de sesión en un registro

Autentíquese con ACR para permitirle extraer e insertar imágenes de contenedor.

az login  
az acr login -n $REGISTRY

Si Docker no está disponible, puede usar el token de AD proporcionado para la autenticación. Autentíquese con la identidad individual de Microsoft Entra mediante un token de AD. Utilice siempre "000..." para USER_NAME, ya que el token se analiza mediante la variable PASSWORD.

# Login to Azure
az login

Inicio de sesión con ORAS

Proporcione las credenciales a oras login.

oras login $REGISTRY \
    --username $USER_NAME \
    --password $PASSWORD

Esta configuración le permite insertar y extraer artefactos sin problemas hacia Azure Container Registry y desde él. Ajuste las variables según sea necesario para la configuración específica.

Inserción y extracción de artefactos de OCI con ORAS

Puede usar un registro de contenedor de Azure para almacenar y administrar artefactos de Open Container Initiative (OCI), así como imágenes de contenedor de Docker y OCI.

Para demostrar esta funcionalidad, en esta sección se muestra cómo usar la CLI de Registro de OCI como almacenamiento (ORAS) para insertar y extraer artefactos hacia una instancia de Azure Container Registry y desde ella. Puede administrar varios artefactos de OCI en un registro de contenedor de Azure mediante diferentes herramientas de línea de comandos adecuadas para cada artefacto.

Nota:

ACR y ORAS admiten varias opciones de autenticación para los usuarios y la automatización del sistema. En este artículo se usa una identidad individual, que emplea un token de Azure. Para ver más opciones de autenticación, consulte Autenticación con una instancia de Azure Container Registry.

Inserción de un artefacto

Un artefacto de único archivo que no tiene un subject primario puede ser una imagen de contenedor, un gráfico de Helm o un archivo Léame para el repositorio. Los artefactos de referencia pueden ser una firma, una lista de materiales de software, informes de análisis u otros tipos en evolución. Los artefactos de referencia, descritos en Artefactos de cadena de suministro de asociación, inserción y extracción son artefactos que hacen referencia a otro artefacto.

Inserción de un artefacto de un único archivo

En este ejemplo, cree contenido que represente un archivo Markdown:

echo 'Readme Content' > readme.md

En el paso siguiente se inserta el archivo readme.md en <myregistry>.azurecr.io/samples/artifact:readme.

  • El registro se identifica con el nombre completo de registro <myregistry>.azurecr.io (todo en minúsculas), seguido del espacio de nombres y el repositorio: /samples/artifact.
  • El artefacto se etiqueta con :readme, para identificarlo de forma única respecto a otros artefactos enumerados en el repositorio (:latest, :v1, :v1.0.1).
  • La configuración de --artifact-type readme/example distingue el artefacto de una imagen de contenedor, que usa application/vnd.oci.image.config.v1+json.
  • ./readme.md identifica el archivo cargado y :application/markdown representa la IANA mediaType del archivo.
    Para obtener más información, consulte la Guía para autores de artefactos de OCI.

Use el comando oras push para insertar el archivo en el registro.

Linux, WSL2 o macOS

oras push $REGISTRY/samples/artifact:readme \
    --artifact-type readme/example \
    ./readme.md:application/markdown

Windows

.\oras.exe push $REGISTRY/samples/artifact:readme ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown

La salida de una inserción correcta es similar a la salida siguiente:

Uploading 2fdeac43552b readme.md
Uploaded  2fdeac43552b readme.md
Pushed <myregistry>.azurecr.io/samples/artifact:readme
Digest: sha256:e2d60d1b171f08bd10e2ed171d56092e39c7bac1

aec5d9dcf7748dd702682d53

Inserción de un artefacto de varios archivos

Cuando se insertan artefactos de OCI en un registro con ORAS, cada referencia de archivo se inserta como un blob. Para insertar blobs independientes, haga referencia a los archivos individualmente o a la colección de archivos haciendo referencia a un directorio.
Para obtener más información sobre cómo insertar una colección de archivos, consulte Inserción de artefactos con varios archivos.

Cree documentación para el repositorio:

echo 'Readme Content' > readme.md
mkdir details/
echo 'Detailed Content' > details/readme-details.md
echo 'More detailed Content' > details/readme-more-details.md

Inserte el artefacto de varios archivos:

Linux, WSL2 o macOS

oras push $REGISTRY/samples/artifact:readme \
    --artifact-type readme/example\
    ./readme.md:application/markdown\
    ./details

Windows

.\oras.exe push $REGISTRY/samples/artifact:readme ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown ^
    .\details

Detección del manifiesto

Para ver el manifiesto creado como resultado de oras push, use oras manifest fetch:

oras manifest fetch --pretty $REGISTRY/samples/artifact:readme

La salida es parecida a esta:

{
  "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
  "artifactType": "readme/example",
  "blobs": [
    {
      "mediaType": "application/markdown",
      "digest": "sha256:2fdeac43552b71eb9db534137714c7bad86b53a93c56ca96d4850c9b41b777fc",
      "size": 15,
      "annotations": {
        "org.opencontainers.image.title": "readme.md"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:0d6c7434a34f6854f971487621426332e6c0fda08040b9e6cc8a93f354cee0b1",
      "size": 189,
      "annotations": {
        "io.deis.oras.content.digest": "sha256:11eceb2e7ac3183ec9109003a7389468ec73ad5ceaec0c4edad0c1b664c5593a",
        "io.deis.oras.content.unpack": "true",
        "org.opencontainers.image.title": "details"
      }
    }
  ],
  "annotations": {
    "org.opencontainers.artifact.created": "2023-01-10T14:44:06Z"
  }
}

Extracción de un artefacto

Cree un directorio limpio para la descarga.

mkdir ./download

Ejecute el comando oras pull para extraer el artefacto del registro.

oras pull -o ./download $REGISTRY/samples/artifact:readme

Visualización de los archivos extraídos

tree ./download

Eliminación del artefacto (opcional)

Para eliminar el artefacto del registro, use el comando oras manifest delete.

 oras manifest delete $REGISTRY/samples/artifact:readme

Asociación, inserción y extracción de artefactos de cadena de suministro con ORAS

Para demostrar esta funcionalidad, en este artículo se muestra cómo usar la CLI de OCI Registry as Storage (ORAS) para push, discover y pull un grafo de artefactos de cadena de suministros en una instancia de Azure Container Registry. El almacenamiento de artefactos de OCI individuales (sujeto) se trata en Inserción y extracción de artefactos de OCI.

Para almacenar un grafo de artefactos, se define una referencia a un artefacto subject mediante el manifiesto de imagen de OCI, que forma parte de la especificación de la distribución OCI 1.1 en versión preliminar.

Inserción de una imagen de contenedor

Para asociar un grafo de artefactos a una imagen de contenedor mediante la CLI de Azure:

Puede crear e insertar una imagen de contenedor u omita este paso si $IMAGE hace referencia a una imagen existente en el registro.

az acr build -r $ACR_NAME -t $IMAGE https://github.com/wabbit-networks/net-monitor.git#main

Asociación de una firma

echo '{"artifact": "'${IMAGE}'", "signature": "jayden hancock"}' > signature.json

Asociación de una firma en el registro, como referencia a la imagen de contenedor

El comando oras attach crea una referencia entre el archivo (./signature.json) y $IMAGE. El --artifact-type proporciona artefactos de diferenciación, de forma similar a las extensiones de archivo que habilitan diferentes tipos de archivo. Se pueden asociar uno o varios archivos especificando [file]:[mediaType].

oras attach $IMAGE \
    --artifact-type signature/example \
    ./signature.json:application/json

Para obtener más información sobre la asociación con ORAS, consulte Documentación de ORAS.

Asociación de un artefacto de varios archivos como referencia

Cuando se insertan artefactos de OCI en un registro con ORAS, cada referencia de archivo se inserta como un blob. Para insertar blobs independientes, haga referencia a los archivos individualmente o a la colección de archivos haciendo referencia a un directorio.
Para obtener más información sobre cómo insertar una colección de archivos, consulte Inserción de artefactos con varios archivos.

Descubrimiento de referencias de artefacto

La especificación OCI v1.1 define una API de referencias para detectar referencias a un artefacto subject. El comando oras discover puede mostrar la lista de referencias a la imagen de contenedor.

Con oras discover, consulte el grafo de artefactos ahora almacenados en el registro.

oras discover -o tree $IMAGE

La salida muestra el principio de un grafo de artefactos, donde la firma y los documentos se ven como elementos secundarios de la imagen de contenedor.

myregistry.azurecr.io/net-monitor:v1
├── signature/example
│   └── sha256:555ea91f39e7fb30c06f3b7aa483663f067f2950dcb...
└── readme/example
    └── sha256:1a118663d1085e229ff1b2d4d89b5f6d67911f22e55...

Creación de grafos de artefactos

La especificación OCI v1.1 permite grafos profundos, que habilitan la lista de materiales de software firmados (SBOM) y otros tipos de artefactos.

A continuación se muestra cómo crear y adjuntar una SBOM al registro:

Creación de una SBOM de muestra

echo '{"version": "0.0.0.0", "artifact": "'${IMAGE}'", "contents": "good"}' > sbom.json

Asociación de una SBOM de muestra a la imagen del registro

Linux, WSL2 o macOS

oras attach $IMAGE \
  --artifact-type sbom/example \
  ./sbom.json:application/json

Windows

.\oras.exe attach $IMAGE ^
    --artifact-type sbom/example ^
    ./sbom.json:application/json

Firma de la SBOM

Importante

Microsoft recomienda usar una herramienta de firma criptográfica segura, como Notación para firmar la imagen y generar una firma para firmar la SBOM.

Los artefactos que se insertan como referencias normalmente no tienen etiquetas, ya que se consideran parte del artefacto subject. Para insertar una firma en un artefacto que es un elemento secundario de otro artefacto, use el oras discover con el filtrado --artifact-type para buscar la síntesis del mensaje. En este ejemplo se usa una firma JSON simple con fines de demostración.

SBOM_DIGEST=$(oras discover -o json \
                --artifact-type sbom/example \
                $IMAGE | jq -r ".manifests[0].digest")

Cree una firma de una SBOM.

echo '{"artifact": "'$IMAGE@$SBOM_DIGEST'", "signature": "jayden hancock"}' > sbom-signature.json

Asociación de la firma de SBOM

oras attach $IMAGE@$SBOM_DIGEST \
  --artifact-type 'signature/example' \
  ./sbom-signature.json:application/json

Consulte el grafo

oras discover -o tree $IMAGE

Se genera el siguiente código resultado:

myregistry.azurecr.io/net-monitor:v1
├── sbom/example
│   └── sha256:4f1843833c029ecf0524bc214a0df9a5787409fd27bed2160d83f8cc39fedef5
│       └── signature/example
│           └── sha256:3c43b8cb0c941ec165c9f33f197d7f75980a292400d340f1a51c6b325764aa93
├── readme/example
│   └── sha256:5fafd40589e2c980e2864a78818bff51ee641119cf96ebb0d5be83f42aa215af
└── signature/example
    └── sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5

Promoción del grafo de artefactos

Un flujo de trabajo típico de DevOps promueve artefactos de desarrollo a través del almacenamiento provisional al entorno de producción. Los flujos de trabajo seguros de la cadena de suministro promueven el contenido público a entornos protegidos de forma privada. En cualquier caso, querrá promover las firmas, las SBOM, examinar los resultados y otros artefactos relacionados con el artefacto sujeto para tener un grafo completo de dependencias.

Con el comando oras copy, puede promover un grafo filtrado de artefactos entre registros.

Copie la imagen net-monitor:v1 y sus artefactos relacionados en sample-staging/net-monitor:v1:

TARGET_REPO=$REGISTRY/sample-staging/$REPO
oras copy -r $IMAGE $TARGET_REPO:$TAG

La salida de oras copy:

Copying 6bdea3cdc730 sbom-signature.json
Copying 78e159e81c6b sbom.json
Copied  6bdea3cdc730 sbom-signature.json
Copied  78e159e81c6b sbom.json
Copying 7cf1385c7f4d signature.json
Copied  7cf1385c7f4d signature.json
Copying 3e797ecd0697 details
Copying 2fdeac43552b readme.md
Copied  3e797ecd0697 details
Copied  2fdeac43552b readme.md
Copied demo42.myregistry.io/net-monitor:v1 => myregistry.azurecr.io/sample-staging/net-monitor:v1
Digest: sha256:ff858b2ea3cdf4373cba65d2ca6bcede4da1d620503a547cab5916614080c763

Detección del grafo de artefactos promocionados

oras discover -o tree $TARGET_REPO:$TAG

Salida de oras discover:

myregistry.azurecr.io/sample-staging/net-monitor:v1
├── sbom/example
│   └── sha256:4f1843833c029ecf0524bc214a0df9a5787409fd27bed2160d83f8cc39fedef5
│       └── signature/example
│           └── sha256:3c43b8cb0c941ec165c9f33f197d7f75980a292400d340f1a51c6b325764aa93
├── readme/example
│   └── sha256:5fafd40589e2c980e2864a78818bff51ee641119cf96ebb0d5be83f42aa215af
└── signature/example
    └── sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5

Extracción de artefactos a los que se hace referencia

Para extraer un artefacto específico al que se hace referencia, la síntesis del mensaje de referencia se detecta con el comando oras discover:

DOC_DIGEST=$(oras discover -o json \
              --artifact-type 'readme/example' \
              $TARGET_REPO:$TAG | jq -r ".manifests[0].digest")

Creación de un directorio limpio para la descarga

mkdir ./download

Extracción de los documentos en el directorio de descarga

oras pull -o ./download $TARGET_REPO@$DOC_DIGEST

Visualización de los documentos

tree ./download

La salida de tree:

./download
├── details
│   ├── readme-details.md
│   └── readme-more-details.md
└── readme.md

Visualización del repositorio y la lista de etiquetas

ORAS permite insertar, detectar, extraer y copiar grafos de artefactos sin tener que asignar etiquetas. Esto permite que una lista de etiquetas se centre en los artefactos en los que los usuarios piensan, en lugar de las firmas y las SBOM asociados a las imágenes de contenedor, gráficos de Helm y otros artefactos.

Consulte una lista de etiquetas

oras repo tags $REGISTRY/$REPO

Eliminación de todos los artefactos del grafo

La compatibilidad con la especificación OCI v1.1 permite eliminar el grafo de artefactos asociados al artefacto raíz. Use el comando oras manifest delete para eliminar el grafo de artefactos (firma, SBOM y la firma de la SBOM).

oras manifest delete -f $REGISTRY/$REPO:$TAG

oras manifest delete -f $REGISTRY/sample-staging/$REPO:$TAG

Puede ver la lista de manifiestos para confirmar la eliminación del artefacto del asunto y todos los artefactos relacionados que dejan un entorno limpio.

az acr manifest list-metadata \
  --name $REPO \
  --registry $ACR_NAME -o jsonc

Salida:

2023-01-10 18:38:45.366387 Error: repository "net-monitor" is not found.

Resumen

En este artículo, ha aprendido a usar Azure Container Registry para almacenar, administrar y recuperar artefactos de OCI y artefactos de la cadena de suministro. Ha usado la CLI de ORAS para insertar y extraer artefactos hacia una instancia de Azure Container Registry o desde ella. También ha descubierto el manifiesto de los artefactos insertados y ha visto el gráfico de artefactos adjuntos a la imagen de contenedor.

Pasos siguientes

  • Más información sobre las referencias de artefactos, la asociación de firmas, la lista de materiales de software y otros tipos de referencia
  • Más información acerca del Proyecto ORAS, incluido cómo configurar un manifiesto para un artefacto
  • Visite el repositorio Artefactos de OCI para obtener información de referencia sobre los nuevos tipos de artefactos.