Inserción y extracción de artefactos de OCI con un registro de contenedor de Azure

  • Artículo

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 este artículo se muestra cómo usar la CLI de Registro de OCI como almacenamiento (ORAS) para insertar un artefacto de ejemplo, un archivo de texto, en un registro de contenedor de Azure. A continuación, se extrae el artefacto del registro. 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.

Prerrequisitos

  • Registro de contenedor de Azure: cree un registro de contenedor en la suscripción de Azure. Por ejemplo, use Azure Portal o az acr create.
  • 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 v0.16.0 o posterior. Consulte: Instalación de ORAS.
  • Docker (opcional): 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 de un registro

Configure variables de entorno para copiar y pegar comandos fácilmente en el shell. Los comandos se pueden ejecutar localmente o en Azure Cloud Shell.

ACR_NAME=myregistry
REGISTRY=$ACR_NAME.azurecr.io

Inicio de sesión en un registro

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

# Login to ACR, using a token based on your Azure identity
USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)

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 un registro de contenedor de Azure.

Inicio de sesión con ORAS

Proporcione las credenciales a oras login.

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

Inserción de un artefacto raíz

Un artefacto raíz es un artefacto que no tiene ningún primario subject. Los artefactos raíz pueden ser una imagen de contenedor, un gráfico de Helm o un archivo Léame del repositorio. 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. Los artefactos de referencia pueden ser una firma, una lista de materiales de software, un informe de examen u otros tipos en evolución.

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:e2d60d1b171f08bd10e2ed171d56092e39c7bac1aec5d9dcf7748dd702682d53

Inserción de un artefacto raíz 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 debe ser similar a:

{
  "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 raíz

Creación de 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

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