Share via

Efetuar push e pull de artefatos de OCI usando um Registro de Contêiner do Azure

  • Artigo

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, esse artigo mostra como usar a CLI do ORAS (OCI Registry as Storage) para efetuar push de um exemplo de artefato, um arquivo de texto, para um Registro de Contêiner do Azure. Em seguida, você efetuará pull do artefato no Registro. É 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.

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 az acr create.
  • 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 – A versão v0.16.0 é necessária. Confira: Instalação do ORAS.
  • Docker (opcional) – Embora o Docker Desktop não seja necessário, a CLI 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 um registro

Configure variáveis de ambiente para copiar/colar comandos facilmente no seu shell. Os comandos podem ser executados localmente no Azure Cloud Shell.

ACR_NAME=myregistry
REGISTRY=$ACR_NAME.azurecr.io

Entrar em um Registro

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

# 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)

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

Entrar com o ORAS

Forneça as credenciais para oras login.

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

Enviar por push um artefato raiz

Um artefato raiz é um artefato que não tem pai subject. Os artefatos raiz podem ser qualquer coisa de uma imagem de contêiner, como um gráfico de helm ou um arquivo de leiame do repositório. 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. 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.

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

Enviar por push um artefato raiz 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, confira 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 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"
  }
}

Enviar por pull um artefato raiz

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

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 da OCI para ver informações de referência sobre novos tipos de artefato