Gerencie artefatos OCI e artefatos da cadeia de suprimentos com ORAS

  • Artigo

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, gerenciar e recuperar artefatos OCI e um gráfico de artefatos da cadeia de suprimentos, incluindo assinaturas, lista de materiais de software (SBOM), resultados da verificação de segurança e outros tipos.

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

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.1.0 ou versão posterior. Consulte: Instalação do ORAS.
  • Docker (Opcional) - Para concluir o passo a passo, uma imagem de contêiner é referenciada. 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.
    Embora o Docker Desktop não seja necessário, a oras cli utiliza o armazenamento de credenciais da área de trabalho do Docker para armazenar credenciais. Se o Docker Desktop estiver instalado, ele deverá estar em execução para oras login.

Configurar o registo

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

  1. Defina a variável como seu nome do ACR_NAME Registro.
  2. Defina a REGISTRY variável como $ACR_NAME.azurecr.io.
  3. Defina a variável para o nome do REPO 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 e v1 a tag do net-monitor repositório. 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

Se o Docker não estiver disponível, você poderá utilizar 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 como o token é analisado através da PASSWORD variável.

# Login to Azure
az login

Iniciar sessão com a ORAS

Forneça as credenciais para oras login.

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

Essa configuração permite que você envie e extraia artefatos diretamente de e para o Registro de Contêiner do Azure. Ajuste as variáveis conforme necessário para sua configuração específica.

Empurre e puxe artefatos OCI com ORAS

Você pode usar um registro de contêiner do Azure para armazenar e gerenciar artefatos OCI (Open Container Initiative), bem como imagens de contêiner 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.

Nota

ACR e ORAS suportam várias opções de autenticação para usuários e automação do sistema. Este artigo usa identidade individual, usando um token do Azure. Para obter mais opções de autenticação, consulte Autenticar com um registro de contêiner do Azure.

Empurrar um artefato

Um único artefato de arquivo que não subject tem pai pode ser qualquer coisa de uma imagem de contêiner, um gráfico de leme, um arquivo readme para o repositório. Os artefatos de referência podem ser qualquer coisa, desde uma assinatura, lista de materiais de software, relatórios de digitalização ou outros tipos em evolução. Os artefatos de referência, descritos em Anexar, empurrar e puxar artefatos da cadeia de suprimentos são artefatos que se referem a outro artefato.

Enviar por push 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 registro é identificado com o nome <myregistry>.azurecr.io do registro totalmente qualificado (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 configuração --artifact-type readme/example diferencia o artefato de uma imagem de contêiner, que usa application/vnd.oci.image.config.v1+json.
  • O ./readme.md identifica o arquivo carregado e o representa a :application/markdown IANA mediaType do arquivo.
    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 à seguinte saída:

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

aec5d9dcf7748dd702682d53

Enviar por push um artefato de 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

Empurre o artefato de vários arquivos:

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. Armazenando artefatos OCI individuais (assunto) são abordados em Push e pull OCI artifacts.

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 fornece para diferenciar artefatos, semelhante a extensões de arquivo que permitem diferentes tipos de arquivo. 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 de 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 discovero , exiba 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 registro

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

Importante

A Microsoft recomenda o uso de uma ferramenta segura de assinatura de criptografia, como Notação , para assinar a imagem e gerar uma assinatura para assinar SBOMs.

Os artefatos que são enviados como referências, normalmente não têm tags, pois são considerados parte do subject artefato. Para enviar uma assinatura para um artefato que é filho de outro artefato, use a oras discover filtragem com --artifact-type para localizar o resumo. 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 artefatos desde o desenvolvimento até o ambiente de produção, passando pelo preparo. Fluxos de trabalho seguros da cadeia de suprimentos promovem conteúdo público para ambientes privados. Em ambos os casos, você deseja promover as assinaturas, SBOMs, resultados da verificação e outros artefatos relacionados com o artefato de assunto para ter 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 e os net-monitor:v1 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 de 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

O ORAS permite que gráficos de artefatos sejam enviados, descobertos, puxados 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 gráfico de artefatos associados ao artefato do assunto. 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

Você pode exibir a lista de manifestos para confirmar a exclusão do artefato de assunto e 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.