Docker Hub 이미지와 상호작용

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

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

name 필드에 이미지 이름을 지정하면 빌드 단계에서 공식 Docker 이미지, Docker 인증 이미지, Docker Hub에 저장된 커스텀 이미지를 가져올 수 있습니다. 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 사용자 인증 정보를 저장하려면 다음 안내를 따르세요.

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

Secret Manager 페이지로 이동
Secret Manager 페이지에서 보안 비밀 만들기를 클릭합니다.
보안 비밀 만들기 페이지에서 이름 아래에 docker-username를 입력합니다.
보안 비밀 값 필드에 Docker 사용자 이름을 입력합니다.
리전 섹션을 변경하지 않은 상태로 둡니다.
보안 비밀 만들기 버튼을 클릭합니다.

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

Cloud Build 서비스 계정에 보안 비밀에 대한 Secret Manager 보안 비밀 접근자 IAM 역할을 부여합니다.

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

Secret Manager 페이지로 이동
Docker 사용자 이름 및 비밀번호에 해당하는 보안 비밀의 체크박스를 선택합니다.
아직 열려 있지 않으면 정보 패널 표시를 클릭하여 패널을 엽니다.
패널의 권한에서 주 구성원 추가를 클릭합니다.
새 주 구성원 텍스트 상자에 Cloud Build 서비스 계정의 이메일 주소를 PROJECT_NUMBER@cloudbuild.gserviceaccount.com 형식으로 입력합니다. 여기서 PROJECT_NUMBER는 빌드를 실행하는 프로젝트의 프로젝트 번호입니다. 프로젝트 설정 페이지에서 프로젝트 번호를 찾을 수 있습니다.
역할 선택 드롭다운 메뉴에서 Secret Manager 보안 비밀 접근자 역할을 선택합니다.
저장을 클릭합니다.

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

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

Secret Manager에 Docker 사용자 인증 정보를 저장하고 Cloud Build가 보안 비밀에 액세스할 수 있는 권한을 부여했는지 확인합니다.
빌드 구성 파일에서 다음 안내를 따릅니다.
- 모든 빌드 steps 이후 Docker 사용자 이름 및 비밀번호에 대해 보안 비밀 버전과 환경 변수를 지정하는 availableSecrets 필드를 추가합니다.
- 사용자 이름 및 비밀번호를 지정하려는 빌드 단계에서 다음을 수행합니다.
  - 빌드 단계에서 bash 도구를 사용하기 위해 bash를 가리키는 entrypoint 필드를 추가합니다. 이것은 보안 비밀에 대해 환경 변수를 참조하기 위해 필요합니다.
  - 사용자 이름 및 비밀번호에 대해 환경 변수를 지정하는 secretEnv 필드를 추가합니다.
  - args 필드에서 -c 플래그를 첫 번째 인수로 추가합니다. -c 다음에 전달하는 문자열은 모두 명령어로 취급됩니다. -c로 시작하는 bash 명령어 실행에 대한 자세한 내용은 bash 문서를 참조하세요.
  - args 필드에 보안 비밀을 지정할 때 $$가 프리픽스로 포함된 환경 변수를 사용하여 지정합니다.
다음 빌드 구성 파일은 Secret Manager에 저장된 Docker 사용자 이름과 비밀번호를 사용하여 Docker에 로그인하고 비공개 이미지를 실행하는 방법을 보여줍니다.
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"
     }]
  }
}
```
위 명령어의 자리표시자 값을 다음으로 바꿉니다.
- 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: 이미지의 태그 이름입니다.
빌드 구성 파일을 사용하여 빌드를 수동으로 시작하거나 트리거를 사용하여 빌드를 자동화합니다.

이미지를 Docker Hub에 푸시하기

공개 및 비공개 이미지를 Docker Hub에 푸시하려면 다음 안내를 따르세요.

Secret Manager에 Docker 사용자 인증 정보를 저장하고 Cloud Build가 보안 비밀에 액세스할 수 있는 권한을 부여했는지 확인합니다.
빌드 구성 파일에서 다음 안내를 따릅니다.
- 모든 빌드 steps 이후 Docker 사용자 이름 및 비밀번호에 대해 보안 비밀 버전과 환경 변수를 지정하는 availableSecrets 필드를 추가합니다.
- 사용자 이름 및 비밀번호를 지정하려는 빌드 단계에서 다음을 수행합니다.
  - 빌드 단계에서 bash 도구를 사용하기 위해 bash를 가리키는 entrypoint 필드를 추가합니다. 이것은 보안 비밀에 대해 환경 변수를 참조하기 위해 필요합니다.
  - 사용자 이름 및 비밀번호에 대해 환경 변수를 지정하는 secretEnv 필드를 추가합니다.
  - args 필드에서 -c 플래그를 첫 번째 인수로 추가합니다. -c 다음에 전달하는 문자열은 모두 명령어로 취급됩니다. -c로 시작하는 bash 명령어 실행에 대한 자세한 내용은 bash 문서를 참조하세요.
  - args 필드에 보안 비밀을 지정할 때 $$가 프리픽스로 포함된 환경 변수를 사용하여 지정합니다.
다음 빌드 구성 파일 예시는 Docker에 로그인하고, 로컬로 저장된 소스 코드로 이미지를 빌드하고, 이미지를 Docker 저장소에 푸시하는 방법을 보여줍니다.
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: 이미지의 태그 이름입니다.
빌드 구성 파일을 사용하여 빌드를 수동으로 시작하거나 트리거를 사용하여 빌드를 자동화합니다.

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"
      ],
  }
  ...
}

다음 단계

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