이 페이지는 Cloud Translation API를 통해 번역되었습니다.

사용자 지정 서비스 계정 구성

Cloud Build에서 최소 권한의 원칙을 따르려면 Cloud Build에서 빌드를 실행하는 데 충분한 권한이 있는 서비스 계정을 사용하도록 구성하면 됩니다. 이 페이지에서는 서비스 계정을 설정하는 방법을 설명합니다.

서비스 계정을 지정하지 않으면 Cloud Build에서 자동으로 서비스 계정을 선택하여 빌드를 대신 실행할 수 있습니다. 이 서비스 계정에는 Cloud Source Repositories 및 프로젝트의 Cloud Storage 버킷에 대한 액세스 권한과 같이 사용 사례에 불필요한 권한이 다양하게 있을 수 있습니다.

프로젝트의 보안 상황을 개선하고 구성 오류나 악의적인 사용자의 잠재적 영향을 줄이려면 최소 권한의 원칙을 따르는 것이 좋습니다. 이 원칙을 채택하면 수행하는 작업으로 범위가 지정된 권한과 역할을 각 서비스 계정에 할당할 수 있습니다. 예를 들어 Google Cloud 블로그와 같이 서비스 계정 하나를 사용하여 이미지를 빌드하여 Artifact Registry에 내보낼 수 있습니다.

시작하기 전에

Enable the Cloud Build and IAM APIs.
Enable the APIs
이 계정을 사용하여 사용자 인증 정보를 만들고 관리하려면(예: 단기 사용자 인증 정보 만들기) IAM Service Account Credentials API를 사용 설정합니다.

Enable the API
아직 서비스 계정을 만들지 않았으면 서비스 계정을 만듭니다.

IAM 권한 부여

빌드에서 연결해야 하는 서비스에 액세스할 수 있게 하려면 몇 가지 역할과 권한을 부여해야 합니다.

Cloud Build 설정 페이지를 엽니다.

Cloud Build 설정 페이지 열기

서비스 계정 권한 탭이 표시됩니다.
드롭다운 목록에서 역할을 변경하려는 서비스 계정을 선택합니다.
추가할 역할의 상태를 사용 설정으로 설정합니다.
빌드 파이프라인에 필요한 역할이 여기에 나와 있지 않으면 IAM 구성 페이지에서 추가 역할을 부여할 수 있습니다.

빌드에 일반적으로 필요한 역할에 대한 자세한 정보는 Cloud Build 리소스에 대한 액세스 구성 및 Cloud Build IAM 역할 및 권한의 전체 목록을 참조하세요.

빌드 로그 설정

빌드에 고유한 서비스 계정을 지정할 때 빌드 로그를 Cloud Logging 또는 사용자가 만든 Cloud Storage 버킷에 저장해야 합니다. 기본 로그 버킷에는 로그를 저장할 수 없습니다.

로그를 Cloud Storage 버킷에 저장하려면 사용자가 만든 버킷에 빌드 로그 저장의 안내를 따릅니다. 로그 버킷에 보관 정책을 설정하지 않았는지 확인합니다. 그러면 Cloud Build가 버킷에 빌드 로그를 쓸 수 없습니다.
Cloud Logging에 빌드 로그를 저장하려면 서비스 계정에 로그 작성자(roles/logging.logWriter) 역할을 부여합니다.
빌드 로그를 저장할 위치에 대한 자세한 내용은 빌드 로그를 저장할 위치 선택을 참조하세요.

구성 파일을 사용하여 빌드 실행

구성 파일을 사용하여 빌드를 수동으로 실행하려면 다음 안내를 따르세요.

프로젝트 루트 디렉터리에 cloudbuild.yaml 또는 cloudbuild.json이라는 Cloud Build 빌드 구성 파일을 만듭니다.
serviceAccount 필드와 기본 로깅 설정을 추가합니다.
- 빌드 로그를 Cloud Logging에 저장하는 경우 logging 필드를 추가하고 필드 값을 CLOUD_LOGGING_ONLY로 설정합니다.
- 사용자가 만든 Cloud Storage 버킷에 빌드 로그를 저장하는 경우 다음 안내를 따르세요.
  - logging 필드를 추가하고 값을 GCS_ONLY로 설정합니다.
  - logsBucket 필드를 추가하고 값을 Cloud Storage 버킷 위치에 설정합니다.
다음 예시는 사용자가 지정한 서비스 계정을 사용하여 빌드를 실행하도록 Cloud Build를 구성하고, 사용자가 만든 Cloud Storage 버킷에 저장하도록 빌드 로그를 구성합니다.
YAML
```
steps:
- name: 'bash'
  args: ['echo', 'Hello world!']
logsBucket: 'LOGS_BUCKET_LOCATION'
serviceAccount: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT'
options:
  logging: GCS_ONLY
```
JSON
```
{
  "steps": [
  {
    "name": "bash",
    "args": [
      "echo",
      "Hello world!"
    ]
  }
  ],
  "logsBucket": "LOGS_BUCKET_LOCATION",
  "serviceAccount": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT",
  "options": {
    "logging": "GCS_ONLY"
  }
}
```
빌드 구성 파일의 자리표시자 값을 다음으로 바꿉니다.
- LOGS_BUCKET_LOCATION은 빌드 로그를 저장할 Cloud Storage 버킷입니다. 예를 들면 gs://mylogsbucket입니다.
- PROJECT_ID는 빌드를 실행하는 Google Cloud 프로젝트의 ID입니다.
- SERVICE_ACCOUNT는 빌드에 지정할 서비스 계정의 이메일 주소나 고유 ID입니다. 예를 들어 서비스 계정 이메일 주소는 service-account-name@project-id.iam.gserviceaccount.com과 같습니다.
빌드 구성 파일을 사용하여 빌드를 시작합니다.
```
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
```
위 명령어의 자리표시자 값을 다음으로 바꿉니다.
- CONFIG_FILE_PATH는 빌드 구성 파일의 경로입니다.
- SOURCE_DIRECTORY는 소스 코드의 경로 또는 URL입니다.
gcloud builds submit 명령어에서 CONFIG_FILE_PATH와 SOURCE_DIRECTORY를 지정하지 않으면 Cloud Build는 빌드 구성 파일과 소스 코드가 현재 작업 디렉터리에 있다고 가정합니다.

트리거를 사용하여 빌드 실행

자체 서비스 계정을 사용하여 Cloud Build 트리거로 빌드를 실행하려면 원하는 로깅 옵션을 설정하고 트리거를 만들 때 원하는 서비스 계정을 선택합니다.

빌드 구성 파일에서 다음 안내를 따릅니다.
- 빌드 로그를 Cloud Logging에 저장하는 경우 logging 필드를 추가하고 필드 값을 CLOUD_LOGGING_ONLY로 설정합니다.
- 사용자가 만든 Cloud Storage 버킷에 빌드 로그를 저장하는 경우 다음 안내를 따르세요.
  - logging 필드를 추가하고 값을 GCS_ONLY로 설정합니다.
  - logsBucket 필드를 추가하고 값을 Cloud Storage 버킷 위치에 설정합니다.
다음 예시는 사용자가 만든 Cloud Storage 버킷에 저장하도록 빌드 로그를 구성합니다.
YAML
```
steps:
- name: 'bash'
  args: ['echo', 'Hello world!']
logsBucket: 'LOGS_BUCKET_LOCATION'
options:
  logging: GCS_ONLY
```
JSON
```
{
  "steps": [
  {
    "name": "bash",
    "args": [
      "echo",
      "Hello world!"
    ]
  }
  ],
  "logsBucket": "LOGS_BUCKET_LOCATION",
  "options": {
    "logging": "GCS_ONLY"
  }
}
```
LOGS_BUCKET_LOCATION을 빌드 로그를 저장할 Cloud Storage 버킷으로 바꿉니다. 예를 들면 gs://mylogsbucket입니다.
빌드 트리거에서 사용할 서비스 계정을 지정합니다.
콘솔
Google Cloud 콘솔에서 트리거 페이지를 사용하여 빌드를 실행하려면 사용자 지정 서비스 계정이 빌드 트리거와 동일한 프로젝트에 있어야 합니다. 프로젝트 간 서비스 계정에 트리거를 사용하려면 gcloud 도구를 사용하여 빌드 트리거를 만듭니다.
1. 빌드 트리거를 만들거나 수정합니다.
2. 서비스 계정 필드에서 서비스 계정을 지정합니다. 서비스 계정을 지정하지 않으면 Cloud Build에서 기본 서비스 계정을 사용합니다.
3. 만들기를 클릭하여 빌드 트리거를 저장합니다.
gcloud
빌드 트리거를 만들 때 --service-account 플래그를 사용하여 서비스 계정을 지정합니다. 다음 예시에서 gcloud 명령어는 Git 저장소에서 코드를 가져오는 빌드 트리거를 만듭니다.
```
gcloud builds triggers create github \
   --name=TRIGGER_NAME \
   --repo-name=REPO_NAME \
   --repo-owner=REPO_OWNER \
   --branch-pattern=BRANCH_PATTERN
   --build-config=BUILD_CONFIG_FILE
   --service-account=SERVICE_ACCOUNT
   --project=BUILD_PROJECT
```
빌드 구성 파일의 자리표시자 값을 다음으로 바꿉니다.
- TRIGGER_NAME은 빌드 트리거의 이름입니다.
- REPO_NAME은 저장소 이름입니다.
- REPO_OWNER은 저장소 소유자의 사용자 이름입니다.
- BRANCH_PATTERN은 빌드를 호출할 저장소의 브랜치 이름입니다.
- TAG_PATTERN: 빌드를 호출할 저장소의 태그 이름입니다.
- BUILD_CONFIG_FILE은 빌드 구성 파일의 경로입니다.
- SERVICE_ACCOUNT는 /projects/PROJECT_ID/serviceAccounts/ACCOUNT_ID_OR_EMAIL 형식의 서비스 계정입니다.
- BUILD_PROJECT는 빌드를 시작할 프로젝트입니다.

프로젝트 간 설정

사용자 지정 서비스 계정이 빌드를 시작할 프로젝트와 다른 프로젝트에 있는 경우 다음과 같이 필요한 액세스 권한을 부여합니다.

사용자 지정 서비스 계정이 포함된 프로젝트에서 iam.disableCrossProjectServiceAccountUsage 조직 정책 제약조건이 적용되지 않았는지 확인합니다. 이 제약조건은 기본적으로 적용됩니다. 이 조직 정책 제약조건을 사용 중지하려면 다음 명령어를 실행합니다. 여기서 SERVICE_ACCOUNT_PROJECT_ID는 사용자 지정 서비스 계정이 포함된 프로젝트입니다.
```
gcloud resource-manager org-policies disable-enforce \
   iam.disableCrossProjectServiceAccountUsage \
   --project=SERVICE_ACCOUNT_PROJECT_ID
```
사용자 지정 서비스 계정이 포함된 프로젝트에서 빌드를 실행 중인 프로젝트의 Cloud Build 서비스 에이전트에 대해 roles/iam.serviceAccountTokenCreator 역할을 부여합니다.
```
gcloud projects add-iam-policy-binding SERVICE_ACCOUNT_PROJECT_ID \
    --member="serviceAccount:BUILD_SERVICE_AGENT" \
    --role="roles/iam.serviceAccountTokenCreator"
```
명령어의 자리 표시자 값을 다음으로 바꿉니다.
- SERVICE_ACCOUNT_PROJECT_ID: 사용자 지정 서비스 계정이 포함된 프로젝트의 프로젝트 ID입니다.
- BUILD_SERVICE_AGENT: service-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com 형식의 서비스 에이전트의 이메일 ID입니다. 여기서 BUILD_PROJECT_NUMBER는 빌드를 실행 중인 프로젝트의 프로젝트 번호입니다. 프로젝트 설정 페이지에서 프로젝트 번호를 가져올 수 있습니다.

제한사항:

Google Cloud 프로젝트는 Google Cloud 조직에 있어야 합니다.
gcloud builds submit 또는 gcloud builds triggers create를 사용하여 명령줄에서 빌드를 시작해야 합니다. Google Cloud Console에서 트리거 페이지를 사용하려면 사용자 지정 서비스 계정 및 빌드 트리거가 동일한 프로젝트에 있어야 합니다.

다음 단계

Cloud Build IAM 역할 및 권한 자세히 알아보기
서비스 계정 변경사항이 빌드 실행 방식에 미치는 영향 알아보기