Criar imagens de contêiner

Nesta página, descrevemos como configurar o Cloud Build para criar e armazenar imagens do Docker. Se você não estiver familiarizado com o Cloud Build, leia os guias de início rápido e a visão geral da configuração do build primeiro.

O Cloud Build fornece imagens pré-criadas que podem ser consultadas em um arquivo de configuração do Cloud Build para executar suas tarefas. Essas imagens são compatíveis e mantidas por Google Cloud. Use a imagem Docker compatível e pré-criada para executar comandos e criar imagens Docker.

Antes de começar

As instruções nesta página presumem que você tenha familiaridade com o Docker. Além disso:

  • Tenha o código-fonte do aplicativo e o Dockerfile.
  • Tenha um repositório do Docker para armazenar imagens no Artifact Registry ou crie um novo repositório.
  • Se você quiser usar os gcloud comandos nesta página, instale a Google Cloud CLI.
  • Se você quiser executar as imagens, instale o Docker
  • Se você quiser assinar as imagens com o cosign, siga as instruções em Autorizar o acesso entre serviços para criar uma conta de serviço especificada pelo usuário e conceder as permissões necessárias para gerar tokens de ID.

Criar com um arquivo de configuração de build

Para criar sua imagem Docker usando um arquivo de configuração de build:

  1. no mesmo diretório que contém o código-fonte do aplicativo, crie um arquivo chamado cloudbuild.yaml ou cloudbuild.json;

  2. No arquivo de configuração de build:

    • Adicione um campo name e especifique a imagem Docker pré-criada. A imagem pré-criada é armazenada em gcr.io/cloud-builders/docker. No exemplo de arquivo de configuração a seguir, o campo name especifica que a imagem pré-criada do Docker é usada pelo Cloud Build para executar a tarefa indicada pelo campo args.

    • No campo args, adicione os argumentos para criar a imagem.

      YAML 

      steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME', '.' ]

      JSON 

      {
 "steps": [
  {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "-t",
        "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
        "."
       ]
   }
   ]
 }

    Em que:

    • LOCATION: o local regional ou multirregional do repositório do Docker no Artifact Registry.
    • PROJECT_ID: o ID do Google Cloud projeto.
    • REPOSITORY: o nome do repositório do Docker no Artifact Registry.

    • IMAGE_NAME: o nome da imagem do contêiner.

      Se Dockerfile e o código-fonte estiverem em diretórios diferentes, adicione -f e o caminho para Dockerfile à lista de argumentos no campo args:

      YAML 

      steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME', '-f', 'DOCKERFILE_PATH', '.' ]

      JSON 

      {
 "steps": [
  {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "-t",
        "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME", '-f', 'DOCKERFILE_PATH', "."
       ]
   }
   ]
 }

      Em que:

      • LOCATION: o local regional ou multirregional do repositório.
      • PROJECT_ID: o ID do Google Cloud projeto.
      • REPOSITORY: o nome do repositório do Artifact Registry
      • IMAGE_NAME: o nome da imagem do contêiner.
      • DOCKERFILE_PATH: caminho para Dockerfile.

  3. Inicie o build usando o arquivo de configuração do build:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

    Em que:

    • CONFIG_FILE_PATH: o caminho para o arquivo de configuração da compilação;
    • SOURCE_DIRECTORY: o caminho ou URL do código-fonte.

    Se você não especificar CONFIG_FILE_PATH e SOURCE_DIRECTORY no comando gcloud builds submit, o Cloud Build presumirá que o arquivo de configuração e o código-fonte estão no diretório de trabalho atual.

Criar com o Dockerfile

O Cloud Build permite criar uma imagem Docker usando apenas um Dockerfile. Você não precisa de um arquivo de configuração de build à parte.

Para criar usando um Dockerfile, execute o seguinte comando no diretório que contém seu código-fonte e o Dockerfile:

    gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME

Em que:

  • LOCATION: o local regional ou multirregional do repositório.
  • PROJECT_ID: o ID do Google Cloud projeto.
  • REPOSITORY: o nome do repositório do Artifact Registry
  • IMAGE_NAME: o nome da imagem do contêiner.

Criar com os buildpacks do Google Cloud

O Cloud Build permite criar uma imagem sem um Dockerfile ou um arquivo de configuração da versão. É possível fazer isso usando os buildpacks do Google Cloud.

Para criar usando pacotes de criação, execute o seguinte comando no diretório que contém seu código-fonte:

    gcloud builds submit --pack builder=BUILDPACK_BUILDER, \
        env=ENVIRONMENT_VARIABLE, \
        image=IMAGE_NAME

Em que:

  • BUILDPACK_BUILDER: o builder do pacote de criação a ser usado. Se você não especificar um builder, o Cloud Build usará gcr.io/buildpacks/builder por padrão.
  • ENVIRONMENT_VARIABLE: qualquer variável de ambiente para a sua versão.
  • IMAGE: o URL da imagem no Artifact Registry. O URL da imagem precisa estar no formato LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME.

Veja alguns comandos de exemplo:

  • Como executar uma versão usando o gcr.io/buildpacks/builder padrão para criar a imagem us-docker.pkg.dev/gcb-docs-project/containers/gke/hello-app:

      gcloud builds submit --pack image=us-docker.pkg.dev/gcb-docs-project/containers/gke/hello-app

  • Como transmitir várias variáveis de ambiente para sua versão usando ^--^ como um separador. Para mais informações sobre como usar argumentos de escape, consulte gcloud topic escaping.

      gcloud builds submit --pack \
      ^--^image=gcr.io/my-project/myimage--env=GOOGLE_ENTRYPOINT='java -jar target/myjar.jar',GOOGLE_RUNTIME_VERSION='3.1.301'

Configuração de gatilhos para usar o buildpacks: além de criar usando a linha de comando, é possível configurar os gatilhos para usar buildpacks para criar a imagem automaticamente. Para saber mais, consulte Como criar e gerenciar gatilhos de compilação.

Diferentes maneiras de armazenar imagens no Artifact Registry

Configure o Cloud Build para armazenar uma imagem criada de uma das seguintes maneiras:

  • Use o campo images para armazenar uma imagem Docker no Artifact Registry após a conclusão da build.
  • Use o campo artifacts.oci para armazenar uma imagem OCI no Artifact Registry após a conclusão da build.
  • Use o comando docker push para armazenar uma imagem do contêiner no Artifact Registry como parte do fluxo de build.

A diferença entre o uso do campo images e do comando push do Docker é que, se você usar o campo images, a imagem armazenada será exibida nos resultados da versão. Isso inclui a página Descrição da build para uma build no Google Cloud console, os resultados de Build.get(), e os resultados de gcloud builds list. No entanto, se você usar o comando push do Docker para armazenar a imagem criada, ela não será exibida nos resultados da versão.

Se quiser armazenar a imagem como parte de seu fluxo de build e exibir a imagem nos resultados do build, use o comando push do Docker e o campo images em seu arquivo de configuração de build.

Armazenar uma imagem de contêiner no Artifact Registry após a conclusão da build

  1. Se não existir um repositório de destino, crie um novo repositório.
  2. no mesmo diretório que contém o código-fonte do aplicativo e Dockerfile, crie um arquivo chamado cloudbuild.yaml ou cloudbuild.json;

  3. no seu arquivo de configuração de build, adicione uma etapa da criação para criar uma imagem e, em seguida, adicione um campo images especificando a imagem criada. Isso armazena a imagem no Artifact Registry. O snippet a seguir mostra uma configuração de build para criar uma imagem e armazená-la no Artifact Registry:

    YAML 

    steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME', '.' ]
images: ['LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME']

    JSON 

    {
"steps": [
{
    "name": "gcr.io/cloud-builders/docker",
    "args": [
        "build",
        "-t",
        "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
        "."
    ]
}
],
"images": [
    "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
]
}

    Em que:

    • LOCATION: o local regional ou multirregional do repositório.
    • PROJECT_ID: o ID do Google Cloud projeto.
    • REPOSITORY: o nome do repositório do Artifact Registry
    • IMAGE_NAME: o nome da imagem do contêiner.

  4. Inicie o build usando o arquivo de configuração do build:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

    Em que:

    • CONFIG_FILE_PATH é o caminho para o arquivo de configuração da compilação;
    • SOURCE_DIRECTORY é o caminho ou o URL do código-fonte.

Armazenar a imagem no Artifact Registry como parte do fluxo de build

  1. no mesmo diretório que contém o código-fonte do aplicativo e Dockerfile, crie um arquivo chamado cloudbuild.yaml ou cloudbuild.json;

  2. no seu arquivo de configuração de build, adicione uma etapa de build docker para criar uma imagem, adicione outra etapa de build docker e transmita argumentos para invocar o comando push:

    YAML 

    steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME', '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['push', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME']

    JSON 

    {
  "steps": [
   {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
          "build",
          "-t",
          "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
          "."
       ]
   },
   {
       "name": "gcr.io/cloud-builders/docker",
       "args": [
          "push",
          "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
        ]
   }
  ]
}

    Em que:

    • LOCATION: o local regional ou multirregional do repositório.
    • PROJECT_ID: o ID do Google Cloud projeto.
    • REPOSITORY: o nome do repositório do Artifact Registry
    • IMAGE_NAME: o nome da imagem do contêiner.

  3. Inicie o build usando o arquivo de configuração do build:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

    Em que:

    • CONFIG_FILE_PATH é o caminho para o arquivo de configuração da compilação;
    • SOURCE_DIRECTORY é o caminho ou o URL do código-fonte.

Armazenar uma imagem como parte de seu fluxo de build e para exibir a imagem nos resultados da build

  1. no mesmo diretório que contém o código-fonte do aplicativo e Dockerfile, crie um arquivo chamado cloudbuild.yaml ou cloudbuild.json;

  2. no arquivo de configuração de build, após a etapa de criação da imagem, adicione uma etapa para invocar o comando push do Docker e, em seguida, adicione o campo images:

    YAML 

    steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME', '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['push', 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME']
images: ['LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME']

    JSON 

    {
    "steps": [
   {
       "name": "gcr.io/cloud-builders/docker",
       "args": [
           "build",
           "-t",
           "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
           "."
        ]
   },
   {
       "name": "gcr.io/cloud-builders/docker",
       "args": [
           "push",
           "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
        ]
   }
   ],
    "images": [
       "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"
    ]
}

    Em que:

    • LOCATION: o local regional ou multirregional do repositório.
    • PROJECT_ID: o ID do Google Cloud projeto.
    • REPOSITORY: o nome do repositório do Artifact Registry
    • IMAGE_NAME: o nome da imagem do contêiner.

  3. Inicie o build usando o arquivo de configuração do build:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

    Em que:

    • CONFIG_FILE_PATH é o caminho para o arquivo de configuração da compilação;
    • SOURCE_DIRECTORY é o caminho ou o URL do código-fonte.

Armazenar uma imagem OCI no Artifact Registry após a conclusão da build

  1. no mesmo diretório que contém o código-fonte do aplicativo e Dockerfile, crie um arquivo chamado cloudbuild.yaml ou cloudbuild.json;

  2. no seu arquivo de configuração de build, adicione um campo artifacts especificando a imagem OCI criada. Essa configuração armazena a imagem OCI no Artifact Registry. O exemplo a seguir mostra uma configuração de build que cria uma imagem OCI e a armazena no Artifact Registry:

    YAML 

    artifacts:
  oci:
  - file: 'OCI_IMAGE_PATH'
    registryPath: 'https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY'
    tags: ["primary_image"]

    JSON 

    {
  "artifacts": {
    "oci": [
      {
        "file": "OCI_IMAGE_PATH",
        "registryPath": "https://LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY",
        "tags": ["primary_image"]
      }
    ]
  }
}

    Em que:

    • OCI_IMAGE_PATH é o endereço do diretório local que contém a imagem OCI a ser enviada, por exemplo, /.pack/layout-repo/my-app.
    • LOCATION é o local regional ou multirregional do repositório.
    • PROJECT_ID é o ID do Google Cloud projeto.
    • REPOSITORY: é o nome do repositório do Artifact Registry

Assinar imagens de contêiner com o cosign

Se você estiver armazenando imagens no Artifact Registry, poderá adicionar outra camada de segurança usando a ferramenta cosign para criar um registro de qual conta de serviço é usada para iniciar uma build. Com o apoio do padrão OpenID Connect (OIDC), os auditores podem usar esse registro para verificar se uma imagem foi criada por uma conta de serviço confiável.

As etapas a seguir demonstram como usar o arquivo de configuração cloudbuild.yaml para receber um token de identidade e assinar a imagem do contêiner.

YAML 

  steps:
  - name: 'gcr.io/cloud-builders/docker'
    id: 'tag-and-push'
    script: |
      #!/bin/sh
      set -e
      docker build -t $_IMAGE .
      docker push "$_IMAGE"
      docker inspect $_IMAGE --format "$_IMAGE@{{.Id}}" >image_with_digest
  - name: 'gcr.io/cloud-builders/gcloud'
    id: 'generate-token'
    script: |
      #!/bin/sh
      set -e
      gcloud auth print-identity-token --audiences=sigstore > token
  - name: 'gcr.io/cloud-builders/docker'
    id: 'sign-image'
    script: |
      #!/bin/sh
      set -e
      docker run \
      --network=cloudbuild \
      --mount source=home-volume,target=/builder/home \
      --rm \
      -e SIGSTORE_NO_CACHE=true \
      -e HOME=/builder/home \
      gcr.io/projectsigstore/cosign \
      sign --identity-token=$(cat token) $(cat image_with_digest) -y
  service_account: '$_SERVICE_ACCOUNT'
  artifacts:
    images:
    - $_IMAGE
  substitutions:
    _IMAGE: 'LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME'
    _SERVICE_ACCOUNT_ID: 'SERVICE_ACCOUNT_ID'
    _SERVICE_ACCOUNT: projects/${PROJECT_ID}/serviceAccounts/${_SERVICE_ACCOUNT_ID}
  options:
    env:
    - '_IMAGE=$_IMAGE'
    dynamic_substitutions: true
    logging: CLOUD_LOGGING_ONLY

JSON 

    {
        "steps": [
            {
                "name": "gcr.io/cloud-builders/docker",
                "id": "tag-and-push",
                "script": "#!/bin/sh set -e \ndocker build -t $_IMAGE . \ndocker push \"$_IMAGE\""
            },
            {
                "name": "gcr.io/cloud-builders/gcloud",
                "id": "generate-token-and-get-digest",
                "script": "#!/bin/sh set -e \ngcloud auth print-identity-token --audiences=sigstore > token \ngcloud container images describe \"$_IMAGE\" --format=\"value(image_summary.fully_qualified_digest)\" > image_with_digest"
            },
            {
                "name": "gcr.io/projectsigstore/cosign",
                "id": "sign-image",
                "script": "#!/busybox/sh cosign sign --identity-token=$(cat token) $(cat image_with_digest) -y",
                "env": [
                    "SIGSTORE_NO_CACHE=true"
                ]
            }
        ],
        "service_account": "$_SERVICE_ACCOUNT",
        "artifacts": {
            "images": [
                "$_IMAGE"
            ]
        },
        "substitutions": {
            "_IMAGE": "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",
            "_SERVICE_ACCOUNT_ID": "SERVICE_ACCOUNT_ID",
            "_SERVICE_ACCOUNT": "projects/${PROJECT_ID}/serviceAccounts/${_SERVICE_ACCOUNT_ID}"
        },
        "options": {
            "env": [
                "_IMAGE=$_IMAGE"
            ],
            "dynamic_substitutions": true,
            "logging": "CLOUD_LOGGING_ONLY"
        }
    }

Em que:

  • LOCATION é o local regional ou multirregional do repositório em que a imagem está armazenada, por exemplo, us-east1 ou us.

  • PROJECT_ID: o ID do Google Cloud projeto.

  • REPOSITORY é o nome do repositório em que a imagem está armazenada.

  • IMAGE_NAME é o nome da imagem.

  • SERVICE_ACCOUNT_ID é o endereço de e-mail da conta de serviço especificada pelo usuário que você quer executar a build. Por exemplo, um endereço de e-mail da conta de serviço é semelhante a: service-account-name@project-id.iam.gserviceaccount.com.

Para verificar a assinatura, instale o cosign na máquina local e execute o comando cosign verify:

cosign verify \
--certificate-identity=SERVICE_ACCOUNT_ID \
--certificate-oidc-issuer=https://accounts.google.com \
IMAGE

Em que:

  • SERVICE_ACCOUNT_ID é o endereço de e-mail da conta de serviço confiável que você espera ter sido usada para criar a imagem do contêiner.
  • IMAGE é o nome completo da imagem, incluindo o resumo da imagem sha256.

Executar a imagem Docker

Para verificar se a imagem que você criou funciona como esperado, é possível executá-la usando o Docker.

  1. Configure o Docker para usar as credenciais do Artifact Registry ao interagir com ele. Você só precisa fazer isso uma vez. Use o comando a seguir para fazer a autenticação usando o assistente de credenciais do gcloud.

    gcloud auth configure-docker HOSTNAME-LIST

    Em que HOSTNAME-LIST é uma lista separada por vírgulas de nomes de host de repositório para adicionar à configuração do assistente de credenciais.

    Por exemplo, para adicionar as regiões us-central1 e asia-northeast1, execute o comando:

    gcloud auth configure-docker us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

  2. Execute a imagem Docker que você criou antes:

    docker run LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME

    Em que:

    • LOCATION: o local regional ou multirregional do repositório.
    • PROJECT_ID: o ID do Google Cloud projeto.
    • REPOSITORY: o nome do repositório do Artifact Registry
    • IMAGE_NAME: o nome da imagem do contêiner.

    Você verá um resultado semelhante a este:

    Hello, world! The time is Fri Feb  2 16:09:54 UTC 2018.

A seguir