Gerenciar artefatos do OCI e artefatos da cadeia de suprimentos com o ORAS

Artigo
10/16/2024

O ACR (Registro de Contêiner do Azure) ajuda a gerenciar artefatos da OCI (Iniciativa de contêiner aberto) e artefatos da cadeia de suprimentos. Este artigo orienta como usar o ACR para gerenciar artefatos do OCI e artefatos da cadeia de suprimentos com eficiência. Aprenda a armazenar, gerenciar e recuperar artefatos do OCI e um grafo de artefatos da cadeia de suprimentos, incluindo assinaturas, cobrança de software de materiais (SBOM), resultados de verificação de segurança e outros tipos.

Este artigo é dividido em duas seções principais:

Pré-requisitos

Registro de Contêiner do Azure - crie um registro de contêiner em sua assinatura do Azure. Por exemplo, use o Portal do Azure ou a CLI do Azure.
CLI do Azure – A versão 2.29.1 ou mais recente é necessária. Para informações de instalação e atualização, confira Instalar a CLI do Azure.
CLI do ORAS – versão v1.1.0 ou versão posterior é necessária. Confira: Instalação do ORAS.
Docker (opcional) – Para que você conclua o passo a passo, uma imagem de contêiner é referenciada. Você pode usar o Docker instalado localmente para criar e efetuar push de uma imagem de contêiner ou usar o acr build para criá-la remotamente no Azure.
Embora o Docker Desktop não seja necessário, a CLI do oras utiliza o repositório de credenciais do Docker Desktop para armazenar credenciais. Se o Docker Desktop estiver instalado, ele precisará estar em execução para efetuar oras login.

Configurar o registro

Para configurar o ambiente e facilitar a execução de comandos, siga estas etapas:

Defina a variável ACR_NAME com o nome do registro.
Defina a variável REGISTRY como $ACR_NAME.azurecr.io.
Defina a variável REPO com o nome do repositório.
Defina a variável TAG para a marca desejada.
Defina a variável IMAGE como $REGISTRY/${REPO}:$TAG.

Definir variáveis de ambiente

Configure um nome de registro, credenciais de logon, um nome de repositório e uma marca para efetuar push e efetuar pull de artefatos. O exemplo a seguir usa o nome de repositório net-monitor e a marca v1. Substitua por seu próprio nome de repositório e marca.

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

Autentique-se no ACR, para ter permissão de efetuar pull e efetuar push de imagens de contêiner.

az login  
az acr login -n $REGISTRY

Se o Docker não estiver disponível, é possível utilizar o token do AD fornecido para autenticação. Autentique-se com a sua identidade individual do Microsoft Entra para usar um token do AD. Sempre use "000..." para o USER_NAME, pois o token é analisado por meio da variável PASSWORD.

# Login to Azure
az login

Forneça as credenciais para oras login.

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

Essa configuração permite efetuar push e efetuar pull contínuos de artefatos de e para o Registro de Contêiner do Azure. Ajuste as variáveis conforme necessário para sua configuração específica.

Efetuar push e efetuar pull de artefatos do OCI com o ORAS

Você pode usar um Registro de Contêiner do Azure para armazenar e gerenciar artefatos de OCI (Open Container Initiative) e imagens de contêiner do Docker e de OCI.

Para demonstrar essa funcionalidade, essa seção mostra como usar a CLI do ORAS (OCI Registry as Storage) para efetuar push e pull de artefatos do OCI de/para um registro de contêiner do Azure. É possível gerenciar uma variedade de artefatos de OCI em um Registro de Contêiner do Azure usando diferentes ferramentas de linha de comando apropriadas para cada artefato.

Observação

O ACR e o ORAS dão suporte a várias opções de autenticação para usuários e automação do sistema. Este artigo usa uma identidade individual, com um token do Azure. Para obter mais opções de autenticação, confira Autenticar-se em um Registro de Contêiner do Azure.

Efetuar push de um artefato

Um único artefato de arquivo que não tem pai subject pode ser qualquer coisa, como uma imagem de contêiner, um gráfico de helm, um arquivo leiame para o repositório. Os artefatos de referência podem ser qualquer coisa, como uma assinatura, uma lista de materiais de software, um relatório de verificação ou outros tipos que possam surgir. Os artefatos de referência, descritos em Anexar artefatos da cadeia de fornecedores e efetuar push e pull neles são artefatos que se referem a outro artefato.

Transmitir um único artefato de arquivo

Neste exemplo, crie um conteúdo que represente um arquivo markdown:

echo 'Readme Content' > readme.md

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

O registro é identificado com o nome totalmente qualificado <myregistry>.azurecr.io do registro (em letras minúsculas), seguido pelo namespace e o repositório: /samples/artifact.
O artefato é marcado como :readme, para ser identificado como exclusivo entre os 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 :application/markdown representa o IANA mediaType do arquivo.
Para obter mais informações, confira Diretrizes de autores de artefatos de OCI.

Use o comando oras push para efetuar push desse 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

O resultado de um push bem-sucedido é semelhante ao seguinte:

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

aec5d9dcf7748dd702682d53

Transmitir um artefato de vários arquivos

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

Crie uma documentação 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 por push 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

Descobrir o manifesto

Para ver o manifesto criado como resultado de oras push, use oras manifest fetch:

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

A saída deverá ser 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"
  }
}

Efetuar pull de um artefato

Criar um diretório limpo para download.

mkdir ./download

Execute o comando oras pull para efetuar pull do artefato no seu Registro.

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

Exibir os arquivos enviados por pull

tree ./download

Remover o artefato (opcional)

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

 oras manifest delete $REGISTRY/samples/artifact:readme

Anexar, efetuar push e efetuar pull de artefatos da cadeia de fornecedores com o ORAS

Para demonstrar essa funcionalidade, este artigo mostra como usar a CLI do ORAS (OCI Registry as Storage) para efetuar push, discover e pull de um grafo de artefatos da cadeia de fornecedores para um Registro de Contêiner do Azure. O armazenamento de artefatos do OCI (objeto) individual é abordado em Efetuar push e pull de artefatos do OCI.

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

Efetuar push de uma imagem de contêiner

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

É possível compilar e efetuar push de uma imagem de contêiner ou ignorar esta etapa caso $IMAGE faça 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 registro, como uma referência à imagem de contêiner

O comando oras attach cria uma referência entre o arquivo (./signature.json) e o $IMAGE. O --artifact-type é fornecido para diferenciar artefatos, semelhantes às extensões de arquivo que habilitam tipos de arquivo diferentes. Um ou mais arquivos podem ser anexados pela especificação de [file]:[mediaType].

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

Para obter mais informações sobre a anexação do ORAS, confira a documentação do ORAS.

Anexar um artefato de vários arquivos como uma referência

Descobrindo referências de artefato

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

Usando oras discover, veja o grafo de artefatos já armazenado no registro.

oras discover -o tree $IMAGE

A saída mostra o início de um grafo de artefatos, em que a assinatura e os documentos são exibidos como filhos da imagem de contêiner.

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

Criar grafos de artefatos

A especificação do OCI v1.1 permite grafos detalhados, habilitando a SBOM (lista de materiais de software) assinada e outros tipos de artefatos.

Confira como criar e anexar um SBOM ao registro:

Criar uma SBOM de exemplo

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

Assinar a SBOM

Importante

A Microsoft recomenda usar uma ferramenta de assinatura de criptografia segura, como o Notation, para assinar a imagem e gerar uma assinatura para assinar SBOMs.

Os artefatos, que são enviados por push como referências, não costumam ter marcas, pois são considerados parte do artefato subject. Para efetuar push de uma assinatura para um artefato que seja filho de outro artefato, use a filtragem oras discover com --artifact-type para localizar o resumo da mensagem. 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")

Criar uma assinatura de uma SBOM.

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

Anexar uma assinatura de SBOM

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

Exibir o gráfico

oras discover -o tree $IMAGE

Isso gera a saída a seguir:

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

Promover o grafo de artefatos

Um fluxo de trabalho comum do DevOps promove artefatos do desenvolvimento de preparo até o ambiente de produção. Fluxos de trabalho seguros da cadeia de suprimentos promovem conteúdo público para ambientes protegidos privadamente. Nos dois casos, é possível promover as assinaturas, as SBOMs, os resultados da verificação e outros artefatos relacionados ao artefato em questão para obter um grafo completo de dependências.

Usando o comando oras copy, você pode promover um grafo 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

Descobrir o grafo de artefato promovido

oras discover -o tree $TARGET_REPO:$TAG

A 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

Transmitir artefatos referenciados

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

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

Efetuar pull dos documentos no diretório de download

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

Exibir os documentos

tree ./download

A saída de tree:

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

Exibir o repositório e a listagem de marcas

Os artefatos do ORAS permitem que grafos de artefato sejam enviados, descobertos, recebidos e copiados sem a necessidade de atribuir marcas. Isso também permite que uma listagem de marcas se concentre nos artefatos considerados pelos usuários, ao contrário das assinaturas e SBOMs associadas às imagens de contêiner, gráficos Helm e outros artefatos.

Exibir uma lista de marcas

oras repo tags $REGISTRY/$REPO

Excluir todos os artefatos no grafo

O suporte para a especificação do OCI v1.1 permite excluir o grafo de artefatos associados ao artefato em questão. Use o comando oras manifest delete para excluir o grafo de artefatos (assinatura, SBOM e assinatura de 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 em questão 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 do OCI e artefatos da cadeia de suprimentos. Você usou a CLI do ORAS para efetuar push e efetuar pull de artefatos de/para um Registro de Contêiner do Azure. Você também descobriu o manifesto dos artefatos enviados por push e visualizou o grafo de artefatos anexados à imagem do contêiner.

Próximas etapas

Saiba mais sobre Referências de artefato, associação de 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 Artefatos do OCI para ver informações de referência sobre novos tipos de artefato.

Compartilhar via

Gerenciar artefatos do OCI e artefatos da cadeia de suprimentos com o ORAS

Pré-requisitos

Configurar o registro

Definir variáveis de ambiente

Efetuar push e efetuar pull de artefatos do OCI com o ORAS

Efetuar push de um artefato

Transmitir um único artefato de arquivo

Transmitir um artefato de vários arquivos

Descobrir o manifesto

Efetuar pull de um artefato

Exibir os arquivos enviados por pull

Remover o artefato (opcional)

Anexar, efetuar push e efetuar pull de artefatos da cadeia de fornecedores com o ORAS

Efetuar push de uma imagem de contêiner

Anexar uma assinatura

Anexar uma assinatura ao registro, como uma referência à imagem de contêiner

Anexar um artefato de vários arquivos como uma referência

Descobrindo referências de artefato

Criar grafos de artefatos

Criar uma SBOM de exemplo

Anexar um exemplo de SBOM à imagem no registro

Assinar a SBOM

Anexar uma assinatura de SBOM

Exibir o gráfico

Promover o grafo de artefatos

Descobrir o grafo de artefato promovido

Transmitir artefatos referenciados

Criar um diretório limpo para download

Efetuar pull dos documentos no diretório de download

Exibir os documentos

Exibir o repositório e a listagem de marcas

Exibir uma lista de marcas

Excluir todos os artefatos no grafo

Resumo

Próximas etapas

Comentários

Recursos adicionais

Compartilhar via

Gerenciar artefatos do OCI e artefatos da cadeia de suprimentos com o ORAS

Pré-requisitos

Configurar o registro

Definir variáveis de ambiente

Entrar em um Registro

Entrar com o ORAS

Efetuar push e efetuar pull de artefatos do OCI com o ORAS

Efetuar push de um artefato

Transmitir um único artefato de arquivo

Transmitir um artefato de vários arquivos

Descobrir o manifesto

Efetuar pull de um artefato

Exibir os arquivos enviados por pull

Remover o artefato (opcional)

Anexar, efetuar push e efetuar pull de artefatos da cadeia de fornecedores com o ORAS

Efetuar push de uma imagem de contêiner

Anexar uma assinatura

Anexar uma assinatura ao registro, como uma referência à imagem de contêiner

Anexar um artefato de vários arquivos como uma referência

Descobrindo referências de artefato

Criar grafos de artefatos

Criar uma SBOM de exemplo

Anexar um exemplo de SBOM à imagem no registro

Assinar a SBOM

Anexar uma assinatura de SBOM

Exibir o gráfico

Promover o grafo de artefatos

Descobrir o grafo de artefato promovido

Transmitir artefatos referenciados

Criar um diretório limpo para download

Efetuar pull dos documentos no diretório de download

Exibir os documentos

Exibir o repositório e a listagem de marcas

Exibir uma lista de marcas

Excluir todos os artefatos no grafo

Resumo

Próximas etapas

Comentários

Recursos adicionais