이 페이지에서는 Google Cloud CLI 및 Cloud Build API를 사용하여 Cloud Build에서 수동으로 빌드를 시작하는 방법을 설명합니다.
시작하기 전에
- Cloud Build 빌드 구성을 사용하여 빌드하려면 빌드 구성 파일을 생성합니다.
- 애플리케이션 소스 코드와
Dockerfile을 준비합니다. - Artifact Registry에서 이미지 저장을 위해 Docker 저장소를 준비하거나 저장소를 만듭니다.
필수 IAM 권한
빌드를 제출하는 데 필요한 권한을 얻으려면 관리자에게 서비스 계정에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
기본 로그 버킷에 빌드 로그 저장:
Cloud Build 편집자 (
roles/cloudbuild.builds.editor) -
사용자가 만든 로그 버킷에 빌드 로그 저장:
Cloud Build 편집자 (
roles/cloudbuild.builds.editor) -
비공개 풀 사용:
Cloud Build WorkerPool 사용자 (
roles/cloudbuild.workerPoolUser)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
빌드 실행
빌드 소스 필드를 사용해서 빌드 소스를 지정할 수 있습니다. 빌드 소스 필드는 storage_source, repo_source, git_source, connected_repository 중 하나입니다.
storage_source로 빌드 제출
gcloud
Dockerfile 사용:
Dockerfile에는 Cloud Build를 사용하여 Docker 이미지를 빌드하는 데 필요한 모든 정보가 들어 있습니다.
Dockerfile을 사용하여 빌드하려면 소스 코드 및 Dockerfile이 포함된 디렉터리에서 다음 명령어를 실행합니다.
gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME
각 항목의 의미는 다음과 같습니다.
- LOCATION: Artifact Registry에 있는 Docker 저장소의 리전 또는 멀티 리전 위치입니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- REPOSITORY: Artifact Registry 저장소의 이름입니다.
- IMAGE_NAME: 빌드할 컨테이너 이미지의 이름입니다.
빌드할 이미지의 전체 이름은 LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME입니다.
Artifact Registry에 푸시된 이미지는 Artifact Registry 이름 지정 규칙을 사용합니다.
gcloud builds submit 명령어:
.으로 지정된 현재 디렉터리에서 애플리케이션 코드,Dockerfile, 그 외 애셋을 압축합니다.- 업로드된 파일을 입력으로 사용하여
LOCATION위치에서 빌드를 시작합니다. - 지정된 이름을 사용하여 이미지에 태그를 지정합니다.
- 빌드된 이미지를 Artifact Registry에 푸시합니다.
빌드가 진행되면 셸 또는 터미널 창에 출력이 표시됩니다. 빌드가 완료되면 다음과 비슷한 출력이 표시됩니다.
DONE
---------------------------------------------------------------------------------
ID CREATE_TIME DURATION STATUS
$BUILD_ID 2023-10-28T15:21:18+00:00 12S SUCCESS
여기서 $BUILD_ID는 빌드의 고유 식별자입니다.
Cloud Build 빌드 구성 파일 사용:
빌드 구성을 사용하여 빌드를 제출하려면 다음 명령어를 실행하세요.
gcloud builds submit --config BUILD_CONFIG SOURCE
각 항목의 의미는 다음과 같습니다.
- BUILD_CONFIG는 빌드 구성 파일의 경로입니다.
- SOURCE는 경로 또는 URL 소스 코드입니다.
Google Cloud 프로젝트에서 gcloud builds submit을 처음 실행하면 Cloud Build가 해당 프로젝트에서 [YOUR_PROJECT_NAME]_cloudbuild라는 Cloud Storage 버킷을 만듭니다. Cloud Build는 이 버킷을 사용하여 빌드에 사용할 수 있는 모든 소스 코드를 저장합니다. Cloud Build는 이 버킷의 콘텐츠를 자동으로 삭제하지 않습니다. 빌드에 더 이상 사용하지 않는 객체를 삭제하려면 버킷에 수명 주기 구성을 설정하거나 수동으로 객체를 삭제하면 됩니다.
다음 명령어에서는 Cloud Storage 버킷에 저장된 소스 코드를 사용하여 cloudbuild.yaml 빌드 요청을 제출하는 방법을 보여줍니다.
gcloud builds submit --config cloudbuild.yaml \
gs://BUCKET/SOURCE.tar.gz
각 항목의 의미는 다음과 같습니다.
- BUCKET은 빌드할 소스 코드가 포함된 Cloud Storage의 버킷 이름입니다.
- SOURCE는 압축된 소스 코드 파일의 이름입니다.
.를 사용하여 소스 코드가 현재 작업 디렉터리에 있음을 지정할 수 있습니다.
gcloud builds submit --config=cloudbuild.yaml .
API
curl을 사용하여 빌드 요청을 제출하려면 다음 안내를 따르세요.
다음 콘텐츠로
request.json라는 파일을 만듭니다.{ "source": { "storageSource": { "bucket": "BUCKET", "object": "SOURCE.tar.gz" } }, "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" ] }각 항목의 의미는 다음과 같습니다.
- BUCKET은 빌드할 소스 코드가 포함된 Cloud Storage 버킷의 이름입니다.
- SOURCE는 압축된 소스 코드 파일의 이름입니다.
- IMAGE_NAME는 빌드할 이미지의 이름입니다.
- LOCATION: Artifact Registry에 있는 Docker 저장소의 리전 또는 멀티 리전 위치입니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- REPOSITORY: Artifact Registry에 있는 Docker 저장소의 이름입니다.
이 빌드 요청에서 Cloud Build는
build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY .인수를 사용하여docker빌드 단계를 호출합니다.빌드할 이미지의 전체 이름은
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY입니다.Artifact Registry에 푸시된 이미지는 Artifact Registry 이름 지정 규칙을 사용합니다.
다음 명령어를 실행합니다. 여기서
PROJECT_ID는Google Cloud 프로젝트 ID이고REGION는 지원되는 리전 중 하나입니다.curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \ --format='value(credential.access_token)')" \ https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds이 명령어에서
curl은 POST 호출의request.json을 projects.builds.create API 메서드의builds엔드포인트로 보냅니다.이 명령어는 셸 또는 터미널 창에 빌드에 대한 세부정보를 표시합니다. 출력은 JSON 응답이며 다음과 비슷하게 표시됩니다.
{ "name": "operations/build/$PROJECT-ID/NmZhZW...", "metadata": { "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata", "build": { "id": $BUILD-ID, "status": "QUEUED", "source": { "storageSource": { "bucket": "BUCKET", "object": "SOURCE.tar.gz" } }, "createTime": "2017-05-12T18:58:07.341526Z", "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME", "." ] } ], "timeout": "600s", "images": [ "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME" ], "projectId": $PROJECT-ID, "logsBucket": "gs://...", "sourceProvenance": { "resolvedStorageSource": { "bucket": "BUCKET", "object": "SOURCE.tar.gz" "generation": "..." } }, "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=$PROJECT_ID" } } }JSON 응답은 Cloud Build API의
Operation리소스를 사용하여 모델링됩니다.metadata필드는Build리소스를 사용하여 모델링됩니다.QUEUED상태는 빌드가 실행 대기 중임을 나타냅니다.
connected_repository로 빌드 제출
gcloud
2세대 저장소 리소스에서 빌드 소스로 빌드 요청을 실행하려면 다음 명령어를 실행합니다.
gcloud builds submit REPOSITORY --revision=REVISION --config=BUILD_CONFIG LOCATION
각 항목의 의미는 다음과 같습니다.
- LOCATION은 Artifact Registry에 있는 Docker 저장소의 리전 또는 멀티 리전 위치입니다.
- REPOSITORY은
projects/*/locations/*/connections/*repositories/*형식의 Cloud Build 2세대 저장소 이름입니다. - REVISION은 브랜치, 태그, 커밋 SHA, Git 참조와 같은 Git 저장소에서 가져올 버전입니다.
- BUILD_CONFIG는 빌드 구성 파일의 경로입니다.
빌드가 진행되면 셸 또는 터미널 창에 출력이 표시됩니다. 빌드가 완료되면 다음과 비슷한 출력이 표시됩니다.
DONE
---------------------------------------------------------------------------------
ID CREATE_TIME DURATION STATUS
$BUILD_ID 2023-10-28T15:21:18+00:00 12S SUCCESS
여기서 $BUILD_ID는 빌드의 고유 식별자입니다.
gcloudignore: 빌드에 소스 코드를 포함하면 이전 명령어는 지정된 디렉터리에 있는 모든 파일을 Google Cloud에 업로드하여 빌드합니다. 디렉터리에서 특정 파일을 제외하길 원하면 최상위 업로드 디렉터리에 .gcloudignore라는 파일을 포함시키면 됩니다. 지정된 파일은 무시됩니다. 최상위 업로드 디렉터리에 .gcloudignore 파일은 없으나 .gitignore 파일은 있으면 gcloud CLI는 .gitignore 대상 파일을 고려하는 Git 호환 .gcloudignore 파일을 생성합니다. 자세한 내용은 gcloudignore 문서를 참조하세요.
빌드에 전달할 소스 코드가 없으면 --no-source 플래그를 사용하세요. 여기서 BUILD_CONFIG는 빌드 구성 파일의 경로입니다.
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
API
curl을 사용하여 빌드 요청을 제출하려면 다음 안내를 따르세요.
다음 콘텐츠로
request.json라는 파일을 만듭니다.{ "source": { "connectedRepository": { "repository": "REPOSITORY", "revision": "REVISION" } }, "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" ] }각 항목의 의미는 다음과 같습니다.
- REPOSITORY은
projects/*/locations/*/connections/*repositories/*형식의 Cloud Build 2세대 저장소 이름입니다. - REVISION은 브랜치, 태그, 커밋 SHA, Git 참조와 같은 Git 저장소에서 가져올 버전입니다.
- IMAGE_NAME는 빌드할 이미지의 이름입니다.
- LOCATION: Artifact Registry에 있는 Docker 저장소의 리전 또는 멀티 리전 위치입니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
이 빌드 요청에서 Cloud Build는
build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME .인수를 사용하여docker빌드 단계를 호출합니다.빌드할 이미지의 전체 이름은
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME입니다. Artifact Registry에 푸시된 이미지는 Artifact Registry 이름 지정 규칙을 사용합니다.- REPOSITORY은
다음 명령어를 실행합니다. 여기서
PROJECT_ID는Google Cloud 프로젝트 ID이고 REGION는 지원되는 리전 중 하나입니다.curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \ --format='value(credential.access_token)')" \ https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds이 명령어에서
curl은 POST 호출의request.json을 projects.builds.create API 메서드의builds엔드포인트로 보냅니다.이 명령어는 셸 또는 터미널 창에 빌드에 대한 세부정보를 표시합니다. 출력은 JSON 응답이며 다음과 비슷하게 표시됩니다.
{ "name": "operations/build/$PROJECT-ID/NmZhZW...", "metadata": { "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata", "build": { "id": $BUILD-ID, "status": "QUEUED", "source": { "connectedRepository": { "repository": "REPOSITORY", "revision": "REVISION" } }, "createTime": "2017-05-12T18:58:07.341526Z", "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME", "." ] } ], "timeout": "600s", "images": [ "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME" ], "projectId": PROJECT_ID, "logsBucket": "gs://...", "sourceProvenance": { "resolvedConnectedRepository": { "repository": "REPOSITORY", "revision": "REVISION.tar.gz" "generation": "..." } }, "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=PROJECT_ID" } } }JSON 응답은 Cloud Build API의
Operation리소스를 사용하여 모델링됩니다.metadata필드는Build리소스를 사용하여 모델링됩니다.QUEUED상태는 빌드가 실행 대기 중임을 나타냅니다.
다음 단계
- 수동 트리거 만들기에 대해 알아보기
- 빌드 결과를 확인하는 방법 알아보기
- 빌드 오류 문제 해결 방법 알아보기