Gerencie artefatos OCI e artefatos da cadeia de suprimentos com ORAS

O Registro de contêiner do Azure (ACR) ajuda você a gerenciar os artefatos da OCI (Open Container Initiative) e os artefatos da cadeia de suprimentos. Este artigo orienta como usar o ACR para gerenciar artefatos OCI e artefatos da cadeia de suprimentos de forma eficaz. Aprenda a armazenar, gestionar e recuperar tanto os artefatos OCI como um gráfico de artefatos da cadeia de abastecimento, incluindo assinaturas, lista de materiais de software (SBOM), resultados de análises de segurança e outros tipos.

Este artigo está dividido em duas seções principais:

• Empurre e puxe artefatos OCI com ORAS
• Anexe, empurre e puxe artefatos da cadeia de suprimentos com ORAS

Pré-requisitos

• Registo de contentores do Azure - crie um registos de contentores na sua subscrição do Azure. Por exemplo, use o portal do Azure ou a CLI do Azure.
• CLI do Azure - Versão 2.29.1 ou posterior é necessária. Consulte Instalar a CLI do Azure para instalação e/ou atualização.
• ORAS CLI - É necessária uma versão v1.2.3 ou versão posterior. Consulte: Instalação do ORAS.
• Docker (Opcional) - Para concluir o passo a passo, uma imagem de contêiner é referenciada. A oras CLI utiliza o gestor de credenciais do Docker Desktop para guardar credenciais. Você pode usar o Docker instalado localmente para criar e enviar por push uma imagem de contêiner ou usar acr build para criar remotamente no Azure.

Configurar o registo

Para configurar seu ambiente para fácil execução de comandos, siga estas etapas:

1. Defina a variável ACR_NAME para o nome do registo.
2. Defina a REGISTRY variável como $ACR_NAME.azurecr.io.
3. Defina a variável REPO para o nome do repositório.
4. Defina a TAG variável para a tag desejada.
5. Defina a IMAGE variável como $REGISTRY/${REPO}:$TAG.

Definir variáveis de ambiente

Configure um nome de registro, credenciais de login, um nome de repositório e tag para enviar e extrair artefatos. O exemplo a seguir usa o nome do net-monitor repositório e a tag v1. Substitua pelo seu próprio nome e tag do repositório.

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

Iniciar sessão num registo

Autentique-se com o ACR, para permitir que você puxe e envie imagens de contêiner.

az login  
az acr login -n $REGISTRY  

Essa configuração permite que você envie e extraia artefatos diretamente de e para o Registro de Contêiner do Azure. Agora o ORAS pode ser usado com ACR sem autenticação adicional usando oras login o comando.

Se o Docker não estiver disponível, você poderá usar o token do AD fornecido para autenticação. Autentique-se com sua identidade individual do Microsoft Entra usando um token AD. Use sempre "000..." para o USER_NAME uma vez que o token é analisado através da variável PASSWORD. O token usado por az acr login é válido por três horas.

Empurre e puxe artefatos OCI com ORAS

Você pode usar um registo de contentores do Azure para armazenar e gerir artefactos OCI (Open Container Initiative) bem como imagens de contentores do Docker e OCI.

Para demonstrar essa capacidade, esta seção mostra como usar a CLI do Registro OCI como Armazenamento (ORAS) para enviar e extrair artefatos OCI de/para um registro de contêiner do Azure. Você pode gerenciar vários artefatos OCI em um registro de contêiner do Azure usando diferentes ferramentas de linha de comando apropriadas para cada artefato.

Empurrar um artefato

Um único artefato de arquivo que não subject tem pai pode ser qualquer coisa, desde uma imagem de contentor, um gráfico Helm ou um arquivo README para o repositório. Os artefatos de referência podem ser qualquer coisa, desde uma assinatura, inventário de materiais de software, relatórios de análises ou verificações, ou outros tipos emergentes. Os artefatos de referência, descritos em Anexar, empurrar e puxar artefatos da cadeia de abastecimento, são artefatos que se referem a outro artefato.

Fazer push de um artefato de arquivo único

Para este exemplo, crie conteúdo que represente um arquivo de marcação:

echo 'Readme Content' > readme.md

A etapa a seguir envia o readme.md arquivo para <myregistry>.azurecr.io/samples/artifact:readme.

• O registo é identificado com o nome totalmente qualificado do registo <myregistry>.azurecr.io (todas minúsculas), seguido pelo namespace e repo: /samples/artifact.
• O artefato é marcado :readme, para identificá-lo exclusivamente a partir de outros artefatos listados no repositório (:latest, :v1, :v1.0.1).
• A definição de --artifact-type readme/example diferencia o artefacto de uma imagem de contentor; esta utiliza application/vnd.oci.image.config.v1+json.
• O ./readme.md identifica o ficheiro carregado, e o :application/markdown representa o IANA mediaType do ficheiro.
  Para obter mais informações, consulte OCI Artifact Authors Guidance.

Use o oras push comando para enviar o arquivo para o registro.

Linux, WSL2 ou 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

A saída para um push bem-sucedido é semelhante ao seguinte resultado:

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

aec5d9dcf7748dd702682d53

Fazer o push de um artefato com vários arquivos

Quando os artefatos OCI são enviados por push para um registro com ORAS, cada referência de arquivo é enviada por push como um blob. Para enviar blobs separados, faça referência aos arquivos individualmente ou à coleção de arquivos fazendo referência a um diretório.
Para obter mais informações sobre como enviar por push uma coleção de arquivos, consulte Enviando artefatos por push com vários arquivos.

Crie algumas documentações para o repositório:

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

Envie o artefato multificheiro:

Linux, WSL2 ou 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

Descubra o manifesto

Para exibir o manifesto criado como resultado do oras push, use oras manifest fetch:

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

O resultado é semelhante 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"
  }
}

Puxe um artefato

Crie um diretório limpo para download.

mkdir ./download

Execute o oras pull comando para extrair o artefato do seu registro.

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

Ver os ficheiros retirados

tree ./download

Remover o artefato (opcional)

Para remover o artefato do registro, use o oras manifest delete comando.

 oras manifest delete $REGISTRY/samples/artifact:readme

Anexe, empurre e puxe artefatos da cadeia de suprimentos com ORAS

Para demonstrar essa capacidade, este artigo mostra como usar a CLI do Registro OCI como Armazenamento (ORAS) para push, discovere pull um gráfico de artefatos da cadeia de suprimentos para um registro de contêiner do Azure. O armazenamento de artefatos OCI de indivíduos (sujeito) é abordado em Empurrar e puxar artefatos OCI.

Para armazenar um gráfico de artefatos, uma referência a um subject artefato é definida usando o manifesto de imagem OCI, que faz parte da especificação de distribuição OCI 1.1 de pré-lançamento.

Enviar uma imagem de contêiner por push

Para associar um gráfico de artefatos a uma imagem de contêiner usando a CLI do Azure:

Você pode criar e enviar por push uma imagem de contêiner ou ignorar esta etapa se $IMAGE fizer referência a uma imagem existente no Registro.

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

Anexar uma assinatura

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

Anexar uma assinatura ao registo, como referência à imagem do contentor

O oras attach comando cria uma referência entre o arquivo (./signature.json) e o $IMAGEarquivo . O --artifact-type permite diferenciar artefatos, semelhante às extensões de arquivo que possibilitam diferentes tipos de ficheiros. Um ou mais arquivos podem ser anexados especificando [file]:[mediaType].

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

Para obter mais informações sobre o anexo oras, consulte a documentação do ORAS.

Anexar um artefato composto por vários arquivos como referência

Quando os artefatos OCI são enviados por push para um registro com ORAS, cada referência de arquivo é enviada por push como um blob. Para enviar blobs separados, faça referência aos arquivos individualmente ou à coleção de arquivos fazendo referência a um diretório.
Para obter mais informações sobre como enviar por push uma coleção de arquivos, consulte Enviando artefatos por push com vários arquivos.

Descobrindo referências de artefatos

A especificação OCI v1.1 define uma API de referência para descobrir referências a um subject artefato. O oras discover comando pode mostrar a lista de referências à imagem do contêiner.

Usando oras discover, visualize o gráfico de artefatos agora armazenados no registro.

oras discover -o tree $IMAGE

A saída mostra o início de um gráfico de artefatos, onde a assinatura e os documentos são vistos como filhos da imagem do contêiner.

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

Criação de gráficos de artefatos

A especificação OCI v1.1 permite gráficos profundos, permitindo listas de materiais de software assinadas (SBOM) e outros tipos de artefatos.

Veja como criar e anexar uma SBOM ao registro:

Criar um exemplo de SBOM

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

Anexar um exemplo de SBOM à imagem no registo

Linux, WSL2 ou 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

Assine o SBOM

Os artefatos que são enviados como referências, normalmente não têm tags, pois são considerados parte do subject artefato. Para transferir uma assinatura para um artefato que é filho de outro artefato, use a oras discover com filtragem --artifact-type para encontrar o resumo criptográfico. Este exemplo usa uma assinatura JSON simples para fins de demonstração.

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

Crie uma assinatura de um SBOM.

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

Anexar a assinatura SBOM

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

Veja o gráfico

oras discover -o tree $IMAGE

Gera a seguinte saída:

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

Promovendo o gráfico de artefatos

Um fluxo de trabalho típico de DevOps promove artefactos desde o desenvolvimento, passando pela preparação, até o ambiente de produção. Fluxos de trabalho seguros da cadeia de abastecimento transferem conteúdo público para ambientes privados e protegidos. Em qualquer um dos casos, pretende promover as assinaturas, SBOMs, resultados de análises e outros artefatos relacionados ao artefato em questão para obter um gráfico completo de dependências.

Usando o oras copy comando, você pode promover um gráfico filtrado de artefatos entre registros.

Copie a imagem net-monitor:v1 e os artefatos relacionados para sample-staging/net-monitor:v1.

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

A saída 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

Descubra o gráfico dos artefactos promovidos

oras discover -o tree $TARGET_REPO:$TAG

Saída 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

Puxando artefatos referenciados

Para extrair um artefato referenciado específico, o resumo da referência é descoberto com o oras discover comando:

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

Criar um diretório limpo para download

mkdir ./download

Puxe os documentos para o diretório de download

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

Ver os documentos

tree ./download

A saída de tree:

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

Ver o repositório e a listagem de tags

ORAS permite que gráficos de artefatos sejam enviados, descobertos, extraídos e copiados sem a necessidade de atribuir tags. Ele também permite que uma listagem de tags se concentre nos artefatos em que os usuários pensam, em oposição às assinaturas e SBOMs associados às imagens de contêiner, gráficos de leme e outros artefatos.

Ver uma lista de etiquetas

oras repo tags $REGISTRY/$REPO

Excluindo todos os artefatos no gráfico

O suporte para a especificação OCI v1.1 permite excluir o grafo de artefatos associados ao artefato principal. Use o oras manifest delete comando para excluir o gráfico de artefatos (assinatura, SBOM e assinatura do SBOM).

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

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

Pode consultar a lista para confirmar a eliminação do artefato em questão e de todos os artefatos relacionados, deixando um ambiente limpo.

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

Saída:

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

Resumo

Neste artigo, você aprendeu como usar o Registro de Contêiner do Azure para armazenar, gerenciar e recuperar artefatos OCI e artefatos da cadeia de suprimentos. Você usou a CLI do ORAS para enviar e extrair artefatos de/para um Registro de Contêiner do Azure. Você também descobriu o manifesto dos artefatos enviados e visualizou o gráfico de artefatos anexados à imagem do contêiner.

Próximos passos

• Saiba mais sobre Referências de Artefatos, associando assinaturas, lista de materiais de software e outros tipos de referência.
• Saiba mais sobre o Projeto ORAS, incluindo como configurar um manifesto para um artefato.
• Visite o repositório OCI Artifacts para obter informações de referência sobre novos tipos de artefatos.