Cloud Build는 Slack 또는 SMTP 서버와 같은 원하는 채널에 알림을 전송하여 빌드 업데이트를 알릴 수 있습니다. 이 페이지에서는 BigQuery 알리미를 사용하여 알림을 구성하는 방법을 설명합니다.
BigQuery 알리미는 사용자가 데이터베이스에 저장할 빌드를 지정하는 기능을 제공합니다. 예를 들어 트리거 ID, 태그, 대체 값을 사용하여 빌드를 그룹화할 수 있습니다. 또한 BigQuery 알리미는 이미지 크기 또는 실행 기간과 같이 빌드 객체에서 즉각적으로 엑세스할 수 없는 필드를 포함하는 표준화된 형식으로 BigQuery에 데이터를 씁니다. 로그 항목을 BigQuery 또는 다른 대상으로 내보내는 방법을 알아보려면 Google Cloud Console로 로그 내보내기를 참조하세요.
시작하기 전에
-
Enable the Cloud Build, Cloud Run, Pub/Sub, and BigQuery APIs.
BigQuery 알림 구성
다음 섹션에서는 BigQuery 알리미를 사용하여 HTTP 알림을 수동으로 구성하는 방법을 설명합니다. 대신 구성을 자동화하려면 알림 구성 자동화를 참조하세요.
BigQuery 알림을 구성하려면 다음 안내를 따르세요.
Cloud Run 서비스 계정에 BigQuery 테이블을 만들고 쓸 수 있는 권한, 빌드와 관련된 Artifact Registry 데이터를 가져올 수 있는 권한, Cloud Storage 버킷에 대한 읽기 및 쓰기 액세스 권한을 부여합니다.
Google Cloud Console의 IAM 페이지로 이동합니다.
프로젝트와 연결된 Compute Engine 기본 서비스 계정을 찾습니다.
Compute Engine 기본 서비스 계정은 다음과 비슷하게 표시됩니다.
project-number-compute@developer.gserviceaccount.comCompute Engine 기본 서비스 계정이 있는 행에서 연필 아이콘을 클릭합니다. 수정 액세스 탭이 표시됩니다.
다른 역할 추가를 클릭합니다.
다음 역할을 추가합니다.
- Artifact Registry 리더
- BigQuery 데이터 편집자
- 스토리지 객체 뷰어
Artifact Registry 리더 역할을 사용하면 이미지의 데이터를 가져올 수 있습니다. BigQuery 데이터 편집자는 데이터에 대한 읽기 및 쓰기 액세스 권한을 제공합니다. 스토리지 객체 뷰어는 Cloud Storage 객체에 대한 읽기 액세스 권한을 제공합니다.
'Save(저장)'를 클릭합니다.
알리미 구성 파일을 작성하여 BigQuery 알리미를 구성하고 빌드 이벤트로 필터링합니다.
다음 알리미 알림 구성 파일 예시에서
filter필드는build인 변수와 함께 Common Expression Language를 사용하여 지정된 트리거 ID로 빌드 이벤트를 필터링합니다.apiVersion: cloud-build-notifiers/v1 kind: BigQueryNotifier metadata: name: example-bigquery-notifier spec: notification: filter: build.build_trigger_id == "123e4567-e89b-12d3-a456-426614174000" params: buildStatus: $(build.status) delivery: table: projects/project-id/datasets/dataset-name/tables/table-name template: type: golang uri: gs://example-gcs-bucket/bq.json각 항목의 의미는 다음과 같습니다.
buildStatus는 사용자 정의 매개변수입니다. 이 매개변수는 빌드 상태인 ${build.status} 값을 사용합니다.project-id는 Google Cloud 프로젝트의 ID입니다.dataset-name은 데이터 세트에 지정할 이름입니다.table-name은 테이블에 지정할 이름입니다.uri필드는bq.json파일을 참조합니다. 이 파일은 Cloud Storage에서 호스팅되는 JSON 템플릿을 참조하며 BigQuery 테이블에 삽입할 정보를 나타냅니다.
템플릿 파일의 예시를 보려면 cloud-build-notifiers 저장소의
bq.json파일을 참조하세요.알리미 구성 파일의 table-name은 다음을 참조할 수 있습니다.
- 존재하지 않는 테이블
- 스키마가 없는 빈 테이블
BigQuery 알리미의 스키마 사양과 일치하는 스키마가 포함된 기존 테이블
빌드 트리거 ID를 지정하면 트리거의 빌드 데이터를 상호 연결할 수 있으므로 빌드 트리거 ID를 필터로 지정하는 것이 좋습니다. 다음 목록에서 트리거 ID를 여러 개 지정할 수도 있습니다.
build.build_trigger_id in ["example-id-123", "example-id-456"]트리거 ID를 가져오려면 다음 명령어를 실행합니다. 여기서 trigger-name은 트리거의 이름입니다.
gcloud 빌드 트리거는 trigger-name을 설명합니다.
이 명령어는 트리거 ID를 포함하여 트리거와 연관된 필드를 나열합니다.
예시를 보려면 BigQuery 알리미에 대한 알리미 구성 파일을 참조하세요.
필터링할 수 있는 추가 필드는 빌드 리소스를 참조하세요. 추가적인 필터링 예시에 대해서는 CEL을 사용하여 빌드 이벤트 필터링을 참조하세요.
알리미 구성 파일을 Cloud Storage 버킷에 업로드합니다.
Cloud Storage 버킷이 없으면 다음 명령어를 실행하여 버킷을 만듭니다. 여기서 bucket-name은 버킷에 지정할 이름으로, 이름 지정 요구사항이 적용됩니다.
gsutil mb gs://bucket-name/버킷에 알리미 구성 파일을 업로드합니다.
gsutil cp config-file-name gs://bucket-name/config-file-name각 항목의 의미는 다음과 같습니다.
bucket-name은 버킷의 이름입니다.config-file-name은 알리미 구성 파일의 이름입니다.
Cloud Run에 알리미를 배포합니다.
gcloud run deploy service-name \ --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/bigquery:latest \ --no-allow-unauthenticated \ --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id각 항목의 의미는 다음과 같습니다.
service-name은 이미지를 배포할 Cloud Run 서비스의 이름입니다.config-path는 BigQuery 알리미의 구성 파일 경로입니다(예:gs://bucket-name/config-file-name).project-id는 Google Cloud 프로젝트의 ID입니다.
gcloud run deploy명령어는 Artifact Registry에서 빌드된 이미지의 최신 버전을 가져옵니다. Cloud Build는 9개월 동안 알리미 이미지를 지원합니다. 9개월이 지나면 Cloud Build는 이미지 버전을 삭제합니다. 이전 이미지 버전을 사용하려면gcloud run deploy명령어의image속성에 이미지 태그의 전체 시맨틱 버전을 지정해야 합니다. 이전 이미지 버전 및 태그는 Artifact Registry에서 찾을 수 있습니다.프로젝트에서 인증 토큰을 만들도록 Pub/Sub 권한을 부여합니다.
gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \ --role=roles/iam.serviceAccountTokenCreator각 항목의 의미는 다음과 같습니다.
project-id는 Google Cloud 프로젝트의 ID입니다.project-number는 Google Cloud 프로젝트 번호입니다.
Pub/Sub 구독 ID를 나타내는 서비스 계정을 만듭니다.
gcloud iam service-accounts create cloud-run-pubsub-invoker \ --display-name "Cloud Run Pub/Sub Invoker"cloud-run-pubsub-invoker또는 Google Cloud 프로젝트 내의 고유 이름을 사용할 수 있습니다.cloud-run-pubsub-invoker서비스 계정에 Cloud RunInvoker권한을 부여합니다.gcloud run services add-iam-policy-binding service-name \ --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \ --role=roles/run.invoker각 항목의 의미는 다음과 같습니다.
service-name은 이미지를 배포할 Cloud Run 서비스의 이름입니다.project-id는 Google Cloud 프로젝트의 ID입니다.
cloud-builds주제를 만들어 알리미의 빌드 업데이트 메시지를 수신합니다.gcloud pubsub topics create cloud-builds알리미에 대해 Pub/Sub 푸시 구독자를 만듭니다.
gcloud pubsub subscriptions create subscriber-id \ --topic=cloud-builds \ --push-endpoint=service-url \ --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com각 항목의 의미는 다음과 같습니다.
subscriber-id는 구독에 지정하려는 이름입니다.service-url은 Cloud Run에서 생성된 새 서비스에 대한 URL입니다.project-id는 Google Cloud 프로젝트의 ID입니다.
Cloud Build 프로젝트 알림이 이제 설정되었습니다.
다음에 빌드를 호출하면 BigQuery 알리미에 구성한 필터와 일치하는 최신 데이터가 테이블에 업데이트됩니다.
빌드 데이터 보기
BigQuery에서 빌드 데이터를 보려면 다음 안내를 따르세요.
BigQuery 콘솔 페이지를 엽니다.
리소스에서 BigQuery 알리미를 구성하는 데 사용하는 프로젝트 ID를 클릭합니다.
데이터 세트 이름을 클릭합니다.
테이블 이름을 클릭합니다.
이제 이 테이블에 있는 스키마와 빌드 데이터 미리보기를 포함하여 테이블과 관련된 정보를 볼 수 있습니다.
빌드 데이터 액세스
bq 명령줄 도구 또는 BigQuery 콘솔을 사용하여 테이블의 데이터를 쿼리할 수 있습니다.
CLI
bq 명령줄 도구를 사용하여 테이블의 데이터를 쿼리하려면 터미널에서 다음 명령어를 실행합니다. 여기서 sql-query는 쿼리입니다.
bq query sql-query
이 페이지에서 쿼리 예시를 사용하려면 명령어에 --nouse_legacy_sql 플래그를 지정해야 합니다. bq 명령줄 도구는 legacy SQL을 사용하지만 예시 쿼리는 사용하지 않습니다. 터미널에서 다음 명령어를 실행하여 legacy SQL 없이 데이터를 쿼리합니다.
bq query sql-query --nouse_legacy_sql
Console
BigQuery 콘솔을 사용하여 테이블의 데이터를 쿼리하려면 다음 안내를 따르세요.
BigQuery 콘솔 페이지를 엽니다.
리소스에서 쿼리하려는 테이블 이름을 클릭합니다.
쿼리 편집기에 SQL 쿼리를 작성합니다.
쿼리를 사용하여 빌드 데이터 액세스
다음 예시 쿼리는 BigQuery 알리미의 구성에 따라 빌드 이벤트의 빌드 데이터에 액세스하는 방법을 보여줍니다.
전체 빌드 기록
SELECT * FROM `projectID.datasetName.tableName`
상태별로 그룹화된 빌드 수
SELECT STATUS, COUNT(*)
FROM `projectID.datasetName.tableName`
GROUP BY STATUS
현재 주 일일 배포 빈도
SELECT DAY, COUNT(STATUS) AS Deployments
FROM (SELECT DATETIME_TRUNC(CreateTime, WEEK) AS WEEK,
DATETIME_TRUNC(CreateTime, DAY) AS DAY,
STATUS
FROM `projectID.datasetName.tableName`
WHERE STATUS="SUCCESS")
WHERE WEEK = DATETIME_TRUNC(CURRENT_DATETIME(), WEEK)
GROUP BY DAY
더 많은 예시 쿼리를 보려면 GitHub의 cloud-build-notifiers 저장소에서 Cloud Build BigQuery Notifier README를 참조하세요.
BigQuery를 사용하여 데이터를 쿼리하는 방법에 대한 자세한 내용은 데이터 쿼리 및 보기를 참조하세요.
CEL을 사용하여 빌드 이벤트 필터링
Cloud Build는 트리거 ID, 이미지 목록 또는 대체 값과 같은 빌드 이벤트와 연결된 필드에 액세스하기 위해 빌드 리소스에 나열된 필드에서 build 변수로 CEL을 사용합니다. filter 문자열을 사용하여 빌드 리소스에 나열된 필드를 사용해서 빌드 구성 파일의 빌드 이벤트를 필터링할 수 있습니다. 필드와 연결된 정확한 구문을 찾으려면 cloudbuild.proto 파일을 참조하세요.
트리거 ID로 필터링
트리거 ID로 필터링하려면 build.build_trigger_id를 사용하여 filter 필드에 트리거 ID 값을 지정합니다. 여기서 trigger-id는 문자열인 트리거 ID입니다.
filter: build.build_trigger_id == trigger-id
상태별 필터링
상태를 기준으로 필터링하려면 build.status를 사용하여 filter 필드에서 필터링할 빌드 상태를 지정합니다.
다음 예시는 filter 필드를 사용하여 SUCCESS 상태인 빌드 이벤트를 필터링하는 방법을 보여줍니다.
filter: build.status == Build.Status.SUCCESS
또한 여러 상태로 빌드를 필터링할 수 있습니다. 다음 예시에서는 filter 필드를 사용하여 SUCCESS, FAILURE, TIMEOUT 상태의 빌드 이벤트를 필터링하는 방법을 보여줍니다.
filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]
필터링할 수 있는 추가 상태 값을 보려면 빌드 리소스 참조 아래에서 상태를 참조하세요.
태그 기준 필터링
태그를 필터링하려면 build.tags를 사용하여 filter 필드에 태그 값을 지정합니다. 여기서 tag-name은 태그의 이름입니다.
filter: tag-name in build.tags
size를 사용하여 빌드 이벤트에 지정된 태그 수에 따라 필터링할 수 있습니다. 다음 예시에서 filter 필드는 v1로 지정된 한 개의 태그를 사용하여 정확히 지정된 태그 2개가 있는 빌드 이벤트를 필터링합니다.
filter: size(build.tags) == 2 && "v1" in build.tags
이미지로 필터링
이미지로 필터링하려면 build.images를 사용하여 filter 필드에 이미지 값을 지정합니다. 여기서 image-name은 Artifact Registry에 나열된 이미지의 전체 이름입니다(예: us-east1-docker.pkg.dev/my-project/docker-repo/image-one)
filter: image-name in build.images
다음 예시에서 filter는 이미지 이름으로 us-east1-docker.pkg.dev/my-project/docker-repo/image-one 또는 us-east1-docker.pkg.dev/my-project/docker-repo/image-two가 지정된 빌드 이벤트를 필터링합니다.
filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images
시간별 필터링
filter 필드에 build.create_time, build.start_time 또는 build.finish_time 옵션 중 하나를 지정하여 빌드의 생성 시간, 시작 시간 또는 종료 시간을 기준으로 빌드 이벤트를 필터링할 수 있습니다.
다음 예시에서 filter는 timestamp를 사용하여 빌드 만들기 요청 시간이 2020년 7월 20일 오전 6:00인 빌드 이벤트를 필터링합니다.
filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")
또한 시간 비교로 빌드 이벤트를 필터링할 수도 있습니다. 다음 예시에서 filter 필드는 timestamp를 사용하여 시작 시간이 2020년 7월 20일 오전 6:00부터 2020년 7월 30일 오전 6:00 사이인 빌드 이벤트를 필터링합니다.
filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")
CEL에서 시간대가 표현되는 방식을 자세히 알아보려면 시간대의 언어 정의를 참조하세요.
빌드 기간을 기준으로 필터링하려면 duration을 사용하여 타임스탬프를 비교할 수 있습니다.
다음 예시에서 filter 필드는 duration을 사용하여 최소 5분 동안 실행되는 빌드가 있는 빌드 이벤트를 필터링합니다.
filter: build.finish_time - build.start_time >= duration("5m")
대체 항목 기준 필터링
build.substitutions를 사용해서 filter 필드에 대체 변수를 지정하여 대체 항목으로 필터링할 수 있습니다. 다음 예시에서 filter 필드는 대체 변수 substitution-variable이 포함된 빌드를 나열하고 substitution-variable이 지정된 substitution-value와 일치하는지 확인합니다.
filter: build.substitutions[substitution-variable] == substitution-value
각 항목의 의미는 다음과 같습니다.
substitution-variable은 대체 변수의 이름입니다.substitution-value는 대체 값의 이름입니다.
또한 기본 대체 변수 값으로 필터링할 수 있습니다. 다음 예시에서 filter 필드에는 분기 이름이 master인 빌드와 저장소 이름이 github.com/user/my-example-repo인 빌드가 나열됩니다. 기본 대체 변수 BRANCH_NAME 및 REPO_NAME은 build.substitutions에 키로 전달됩니다.
filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"
정규 표현식을 사용하여 문자열로 필터링하려면 기본 제공되는 matches 함수를 사용할 수 있습니다. 아래 예시에서 filter 필드는 상태가 FAILURE 또는 TIMEOUT이고 v{DIGIT}.{DIGIT}.{3 DIGITS}) 정규 표현식과 일치하는 값으로 빌드 대체 변수가 TAG_NAME인 빌드를 필터링합니다.
filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`
기본 대체 값 목록을 보려면 기본 대체 항목 사용을 참조하세요.
다음 단계
- Cloud Build 알리미 알아보기
- 빌드 알림 구독하는 방법 알아보기
- Cloud Build 빌드 구성 파일 작성 방법을 알아보세요.