사용자 관리 서비스 계정으로 빌드 실행

이 문서에서는 사용자 관리 서비스 계정을 사용하도록 빌드를 구성하는 방법을 설명합니다.

빌드에 사용자 관리 서비스 계정을 지정하지 않으면 Cloud Build에서 자동으로 기본 Cloud Build 서비스 계정을 사용합니다. 이 기본 서비스 계정에는 Cloud Source Repositories 및 프로젝트의 Cloud Storage 버킷에 대한 액세스 권한과 같이 불필요한 권한이 다양하게 있을 수 있습니다.

수행하는 작업으로 범위가 지정된 권한과 역할을 서비스 계정에 할당하여 최소 권한의 원칙을 따르는 것이 좋습니다. 예를 들어 Google Cloud 블로그와 같이 서비스 계정 하나를 사용하여 이미지를 빌드하여 Artifact Registry에 내보낼 수 있습니다.

시작하기 전에

• 아직 사용 설정되지 않은 Cloud Build 및 IAM API가 있으면 사용 설정합니다.

  API 사용 설정에 필요한 역할

  API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않은 경우 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기

  API 사용 설정

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

  API 사용 설정에 필요한 역할

  API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않은 경우 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기

  API 사용 설정하기

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

서비스 계정 설정

사용자 관리 서비스 계정에 빌드를 실행하는 데 필요한 권한이 있도록 IAM 역할을 부여합니다. 새 트리거에 대해 이 서비스 계정을 자동으로 선택하도록 Cloud Build를 구성할 수도 있습니다.

1. Google Cloud 콘솔에서 settings Cloud Build 권한 페이지로 이동합니다.

   권한으로 이동

2. 서비스 계정 메뉴로 이동하여 서비스 계정을 선택합니다. 다른 프로젝트의 서비스 계정을 선택하려면 프로젝트 전환을 클릭합니다.

3. 선택한 서비스 계정을 새 트리거의 서비스 계정으로 사용하려면 새 트리거에 미리 선택된 항목으로 설정을 사용 설정합니다.

4. Google Cloud 서비스 목록에서 서비스 계정에 부여할 IAM 역할을 사용 설정합니다.

5. 빌드 파이프라인에 필요한 역할이 여기에 나와 있지 않으면 IAM 구성 페이지에서 추가 역할을 부여할 수 있습니다.

6. 다른 프로젝트의 서비스 계정을 선택한 경우 교차 프로젝트 설정의 단계를 완료합니다.

빌드에 일반적으로 필요한 IAM 역할에 대해 자세히 알아보려면 다음 정보를 참고하세요.

• 기본 Cloud Build 서비스 계정
• Cloud Build 리소스에 대한 액세스 구성
• Cloud Build IAM 역할 및 권한

빌드 로그 설정

빌드에 고유한 서비스 계정을 지정할 때 빌드 로그를 다음 버킷 유형 중 하나에 저장해야 합니다.

• 사용자 프로젝트의 Cloud Storage 버킷입니다. 사용자가 만든 버킷 또는 Google Cloud에서 만들고 사용자가 소유한 버킷일 수 있습니다.

• Cloud Logging 버킷.

로그 버킷을 만드는 경우 보관 정책이 없는지 확인합니다. 정책으로 인해 Cloud Build가 버킷에 빌드 로그를 쓸 수 없습니다.

Google Cloud소유 로그 버킷에는 로그를 저장할 수 없습니다.

빌드 로그를 저장할 위치에 대한 자세한 내용은 빌드 로그 저장 옵션을 참고하세요.

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

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

1. 프로젝트 루트 디렉터리에 cloudbuild.yaml 또는 cloudbuild.json이라는 Cloud Build 빌드 구성 파일을 만듭니다.

2. 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과 같습니다.

3. 빌드 구성 파일을 사용하여 빌드를 시작합니다.

   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 Build가 서비스 계정을 자동으로 선택하도록 구성하면 됩니다.

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

   • 빌드 로그를 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입니다.

2. 빌드 트리거에서 사용할 서비스 계정을 지정합니다.

   Console

   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 조직 정책 제약 조건이 적용되지 않는 경우에만 서비스 계정을 만든 프로젝트와 다른 프로젝트에서 사용자 관리 서비스 계정을 사용하여 빌드를 실행할 수 있습니다. 이 제약조건은 기본적으로 적용됩니다. 자세히 알아보기

• 다음 명령어는 해당 제약 조건의 시행을 사용 중지하고 필요한 액세스 권한을 부여합니다. 조직 정책에 제약 조건을 설정하기 전에 조직에서 다음과 같은 보안 트레이드 오프를 알고 있어야 합니다.

  gcloud resource-manager org-policies disable-enforce \
     iam.disableCrossProjectServiceAccountUsage \
     --project=SERVICE_ACCOUNT_PROJECT_ID
  

  이 명령어에서 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를 사용하여 명령줄에서 빌드를 시작해야 합니다.

다음 단계

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