Docker Hub 이미지와 상호작용

Docker Hub의 컨테이너 이미지를 사용하여 Cloud Build에서 태스크를 실행할 수 있습니다. 또한 빌드에서 이미지를 생성하는 경우 이미지를 Docker Hub에 푸시할 수 있습니다. 이 페이지에서는 빌드 구성 파일을 작성하여 Docker 허브 이미지를 푸시하고 가져오는 방법을 설명합니다. 빌드 구성 파일에서 사용할 수 있는 모든 필드에 대한 개요는 빌드 구성 개요를 참조하세요.

Docker Hub에서 공개 이미지 가져오기

name 필드에 이미지 이름을 지정하면 빌드 단계에서 공식 Docker 이미지, Docker 인증 이미지, Docker Hub에 저장된 커스텀 이미지를 가져올 수 있습니다. Cloud Build는 먼저 Docker Hub에서 지정된 이미지를 가져온 다음 이미지를 사용하여 빌드 단계를 실행합니다.

참고: 빌드 구성 파일에 사용할 Docker Hub에서 공개 컨테이너 이미지를 가져오면 Cloud Build는 캐싱 프록시 mirror.gcr.io에서 컨테이너 이미지의 캐시된 사본을 자동으로 확인합니다. 캐시된 사본을 사용할 수 없는 경우 Cloud Build는 Docker Hub에서 요청된 이미지를 가져오고 캐싱 프록시는 나중에 사용할 수 있도록 이미지를 캐시할 수 있습니다. 자세한 내용은 캐시된 이미지 가져오기를 참조하세요.

아래 예시에서 Cloud Build는 maven용 Docker 이미지를 가져와 args에 지정된 mvn 명령어를 실행합니다.

YAML

steps:
- name: "maven"
  args: ["mvn", "--version"]

JSON

{
   "steps": [
      {
         "name": "maven",
         "args": [
            "mvn",
            "--version"
         ]
      }
   ]
}

Secret Manager에 Docker 사용자 인증 정보 저장

비공개 이미지를 가져오고 공개 및 비공개 이미지를 Docker Hub에 푸시하려면 Cloud Build가 사용자 인증 정보로 Docker에 인증해야 합니다. 빌드에 Docker 사용자 인증 정보를 포함하려면 먼저 사용자 인증 정보를 Secret Manager에 저장하고, Cloud Build가 Secret Manager에서 보안 비밀에 액세스하도록 권한을 부여해야 합니다.

Secret Manager에 Docker 사용자 인증 정보를 저장하려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 Secret Manager 페이지로 이동합니다.

   Secret Manager 페이지로 이동

2. Secret Manager 페이지에서 보안 비밀 만들기를 클릭합니다.

3. 보안 비밀 만들기 페이지에서 이름 아래에 docker-username를 입력합니다.

4. 보안 비밀 값 필드에 Docker 사용자 이름을 입력합니다.

5. 리전 섹션을 변경하지 않은 상태로 둡니다.

6. 보안 비밀 만들기 버튼을 클릭합니다.

위 단계를 반복하여 Secret Manager에 Docker 비밀번호를 저장하세요.

빌드에 사용 중인 서비스 계정에 보안 비밀에 대한 Secret Manager 보안 비밀 접근자 IAM 역할을 부여하려면 다음 안내를 따르세요.

1. Google Cloud 콘솔에서 Secret Manager 페이지를 엽니다.

   Secret Manager 페이지로 이동

2. Docker 사용자 이름 및 비밀번호에 해당하는 보안 비밀의 체크박스를 선택합니다.

3. 아직 열려 있지 않으면 정보 패널 표시를 클릭하여 패널을 엽니다.

4. 패널의 권한에서 주 구성원 추가를 클릭합니다.

5. 새 주 구성원 필드에 서비스 계정의 이메일 주소를 입력합니다.

6. 역할 선택 드롭다운 메뉴에서 Secret Manager 보안 비밀 접근자 역할을 선택합니다.

7. 저장을 클릭합니다.

Docker Hub에서 비공개 이미지 가져오기

Docker Hub에서 비공개 이미지를 가져오려면 다음 안내를 따르세요.

1. Secret Manager에 Docker 사용자 인증 정보를 저장하고 Cloud Build가 보안 비밀에 액세스할 수 있는 권한을 부여했는지 확인합니다.

2. 빌드 구성 파일에서 다음 안내를 따릅니다.

   • 모든 빌드 steps 이후 Docker 사용자 이름 및 비밀번호에 대해 보안 비밀 버전과 환경 변수를 지정하는 availableSecrets 필드를 추가합니다.
   • 사용자 이름 및 비밀번호를 지정하려는 빌드 단계에서 다음을 수행합니다.
     • 빌드 단계에서 bash 도구를 사용하기 위해 bash를 가리키는 entrypoint 필드를 추가합니다. 이것은 보안 비밀에 대해 환경 변수를 참조하기 위해 필요합니다.
     • 사용자 이름 및 비밀번호에 대해 환경 변수를 지정하는 secretEnv 필드를 추가합니다.
     • args 필드에서 -c 플래그를 첫 번째 인수로 추가합니다. -c 다음에 전달하는 문자열은 모두 명령어로 취급됩니다. -c로 시작하는 bash 명령어 실행에 대한 자세한 내용은 bash 문서를 참조하세요.
     • args 필드에 보안 비밀을 지정할 때 $$.

   The following build config file shows how to login to Docker using the Docker username and password stored in Secret Manager, and run a private image.

   YAML

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      entrypoint: 'bash'
      args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
      secretEnv: ['USERNAME', 'PASSWORD']
    - name: "gcr.io/cloud-builders/docker"
      entrypoint: 'bash'
      args: ['-c', 'docker run $$USERNAME/REPOSITORY:TAG']
      secretEnv: ['USERNAME']
    availableSecrets:
      secretManager:
      - versionName: projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION
        env: 'PASSWORD'
      - versionName: projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION
        env: 'USERNAME'
   가 프리픽스로 포함된 환경 변수를 사용하여 지정합니다.
    JSON 
   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=$$USERNAME --password=$$PASSWORD"
       ],
       "secretEnv": [
         "USERNAME",
         "PASSWORD"
       ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker run $$USERNAME/REPOSITORY:TAG"
        ],
        "secretEnv": [
         "USERNAME"
       ]
     }
     ],
     "availableSecrets": {
       "secretManager": [{
         "versionName": "projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION",
         "env": "PASSWORD"
     }, {
       "versionName": "projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION",
       "env": "USERNAME"
        }]
     }
   }
   
   

   Replace the placeholder values in the above commands with the following:

   • PROJECT_ID: The ID of the Google Cloud project where you've stored your secrets.
   • DOCKER_USERNAME_SECRET_NAME: The secret name corresponding to your Docker username.
   • DOCKER_USERNAME_SECRET_VERSION: The secret version of your Docker username.
   • DOCKER_PASSWORD_SECRET_NAME: The secret name corresponding to your Docker password.
   • DOCKER_PASSWORD_SECRET_VERSION: The secret version of your Docker password.
   • REPOSITORY: The name of your Docker repository from where you're pulling the image.
   • TAG: The tag name of your image.

3. Use the build config file to manually start a build or to automate builds using triggers.

Pushing images to Docker Hub

To push public and private images to Docker Hub:

1. Make sure you've stored your Docker credentials in Secret Manager and granted permissions for Cloud Build to access the secret.

2. In the build config file:

   • After all the build steps, add an availableSecrets field specifying the secret version and the env variable for the Docker username and password.
   • In the build step where you want to specify the username and password:
     • Add an entrypoint field pointing to bash to use the bash tool in the build step. This is required to refer to the environment variable for the secret.
     • Add a secretEnv field specifying the environment variable for username and password.
     • In the args field, add a -c flag as the first argument. Any string you pass after -c is treated as a command. For more information on running bash commands with -c, see the bash documentation.
     • When specifying the secret in the args field, specify it using the environment variable prefixed with $$.

   The following example build config file shows how to login to Docker, build an image with source code stored locally, and then push the image to Docker repository.

   YAML

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      entrypoint: 'bash'
      args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
      secretEnv: ['USERNAME', 'PASSWORD']
    - name: 'gcr.io/cloud-builders/docker'
      entrypoint: 'bash'
      args: ['-c', 'docker build -t $$USERNAME/REPOSITORY:TAG .']
      secretEnv: ['USERNAME']
    - name: 'gcr.io/cloud-builders/docker'
      entrypoint: 'bash'
      args: ['-c', 'docker push $$USERNAME/REPOSITORY:TAG']
      secretEnv: ['USERNAME']
    availableSecrets:
      secretManager:
      - versionName: projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION
        env: 'PASSWORD'
      - versionName: projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION
        env: 'USERNAME'
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=$$USERNAME --password=$$PASSWORD"
       ],
       "secretEnv": [
         "USERNAME",
         "PASSWORD"
       ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker build -t $$USERNAME/REPOSITORY:TAG ."
        ],
        "secretEnv": [
         "USERNAME"
       ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker push $$USERNAME/REPOSITORY:TAG"
        ],
        "secretEnv": [
         "USERNAME"
       ]
     }
     ],
     "availableSecrets": {
       "secretManager": [{
         "versionName": "projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION",
         "env": "PASSWORD"
     }, {
       "versionName": "projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION",
       "env": "USERNAME"
        }]
     }
   }
   

   위 명령어의 자리표시자 값을 다음으로 바꿉니다.

   • PROJECT_ID: 보안 비밀을 저장한 Google Cloud 프로젝트의 ID입니다.
   • DOCKER_USERNAME_SECRET_NAME: Docker 사용자 이름에 해당하는 보안 비밀 이름입니다.
   • DOCKER_USERNAME_SECRET_VERSION: Docker 사용자 이름의 보안 비밀 버전입니다.
   • DOCKER_PASSWORD_SECRET_NAME: Docker 비밀번호에 해당하는 보안 비밀 이름입니다.
   • DOCKER_PASSWORD_SECRET_VERSION: Docker 비밀번호의 보안 비밀 버전입니다.
   • REPOSITORY: 이미지를 푸시하려는 Docker 저장소의 이름입니다.
   • TAG: 이미지의 태그 이름입니다.

3. 빌드 구성 파일을 사용하여 빌드를 수동으로 시작하거나 트리거를 사용하여 빌드를 자동화합니다.

Docker 클라이언트 버전 사용

Cloud Build에 지원되는 Docker 빌더인 gcr.io/cloud-builders/docker는 Docker 20.10.14를 사용합니다. 이 버전에서는 이미지를 Docker로 푸시할 때 태그를 지정하지 않으면 Docker는 latest 태그가 있는 이미지만 푸시합니다. latest 태그가 없으면 푸시가 실패합니다.

특정 태그가 있는 이미지를 Docker로 푸시하려면 docker push 빌드 단계에서 태그를 지정합니다. 다음은 prod 태그가 지정된 이미지를 푸시하는 예시입니다.

YAML

steps:
...
- name: 'gcr.io/cloud-builders/docker'
  args: ['docker', 'push', '$$USERNAME/myrepo:prod']
...

JSON

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "docker",
      "push", 
      "$$USERNAME/myrepo:prod"
      ],
  }
  ...
}

이미지의 모든 태그를 Docker로 푸시하려면 -a 플래그를 docker push 빌드 단계의 인수 목록에 추가합니다.

YAML

steps:
...
- name: 'gcr.io/cloud-builders/docker'
  args: ['docker', 'push', '-a', '$$USERNAME/myrepo']
...

JSON

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "docker",
      "push",
      "-a",
      "$$USERNAME/myrepo"
      ],
  }
  ...
}

Docker 빌더에서 버전에 태그를 지정하여 Docker 클라이언트 19.03.9를 사용할 수 있습니다.

YAML

steps:
...
- name: 'gcr.io/cloud-builders/docker:19.03.9'
  args: ['docker', 'push', '$$USERNAME/myrepo:prod']
...

JSON

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker:19.03.9",
    "args": [
      "docker",
      "push",
      "$$USERNAME/myrepo:prod"
      ],
  }
  ...
}

다음 단계

• 기본 빌드 구성 파일 작성 방법에 대해 알아보기
• 빌드를 수동으로 실행하거나 빌드 트리거를 사용하여 자동화하는 방법 알아보기