Cloud KMS에서 암호화된 사용자 인증 정보 사용

Cloud Key Management Service는 암호화 키를 관리하고 사용할 수 있게 해주는 Google Cloud 서비스입니다. 이 페이지에서는 Cloud Build의 Cloud KMS에서 암호화된 정보를 사용하는 방법을 설명합니다.

참고: Secret Manager는 Cloud Build로 민감한 정보를 관리하는 데 권장되는 기술입니다. 기존 프로젝트의 경우 Cloud KMS를 계속 사용할 수 있지만 새 프로젝트에서는 Secret Manager를 사용합니다. Secret Manager의 보안 비밀에 액세스하도록 빌드를 구성하는 방법은 Secret Manager의 보안 비밀 사용을 참조하세요.

시작하기 전에

• API Cloud Build and Cloud KMS 사용 설정

  API 사용 설정

• 이 가이드에서 명령줄 예시를 사용하려면 Google Cloud CLI를 설치하고 구성합니다.

  참고: 이전에 이미 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 사용할 수 있는지 확인합니다.

• Cloud KMS를 사용하여 민감한 정보를 암호화합니다. Cloud KMS는 파일에 암호화된 콘텐츠를 저장합니다.

• [선택사항] 암호화된 데이터를 사용하도록 빌드를 구성하려면 ENCRYPTED_FILE을 base64로 변환합니다(이 단계는 암호화된 파일을 사용하는 빌드 구성에 필요하지 않음).

      base64 ENCRYPTED_FILE
  

필수 IAM 권한

Cloud Build 서비스 계정에 Cloud KMS CryptoKey 복호화(roles/cloudkms.cryptoKeyDecrypter) IAM 역할을 부여합니다.

1. Google Cloud Console에서 Cloud Build 설정 페이지로 이동합니다.

   설정 페이지 열기

2. Cloud KMS CryptoKey 복호화기 역할이 있는 행을 찾고 상태를 사용 설정됨으로 설정합니다.

경고: Cloud KMS CryptoKey 복호화 역할 역할을 Cloud Build 서비스 계정에 부여하면 서비스 계정이 암호화된 정보를 복호화할 수 있습니다. 빌드 트리거는 Cloud Build 서비스 계정을 사용하여 빌드를 실행합니다. 따라서 빌드 실행을 위해 빌드 트리거를 사용하는 누구나 빌드 시간에 서비스 계정에 대한 권한이 부여됩니다. 따라서 CryptoKey 복호화 역할이 없는 사용자도 빌드 트리거를 사용하여 암호화된 정보를 복호화하는 빌드를 수행할 수 있습니다. 이 작업은 프로젝트의 빌드 기록에 기록됩니다.

암호화된 데이터를 사용하도록 빌드 구성

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

2. 빌드 구성 파일에서 다음을 수행합니다.

   • 모든 빌드 steps 이후 availableSecrets 필드를 추가하여 암호화된 값을 환경 변수로 지정하고 이를 암호화하기 위해 사용할 kmsKeyName을 지정합니다. kmsKeyName 값에 대체 변수를 사용할 수 있습니다.
   • 보안 비밀을 지정하려는 빌드 단계에서 다음을 수행합니다.
     • 빌드 단계에서 bash 도구를 사용하기 위해 bash를 가리키는 entrypoint 필드를 추가합니다. 이것은 보안 비밀에 대해 환경 변수를 참조하기 위해 필요합니다.
     • 암호화된 값에 대해 환경 변수를 지정하는 secretEnv 필드를 추가합니다.
     • args 필드에서 -c 플래그를 첫 번째 인수로 추가합니다. -c 다음에 전달하는 문자열은 모두 명령어로 취급됩니다. -c로 시작하는 bash 명령어 실행에 대한 자세한 내용은 bash 문서를 참조하세요.
     • args 필드에 암호화된 값을 지정할 때 $$가 프리픽스로 포함된 환경 변수를 사용하여 지정합니다.
   참고: 빌드 단계의 args 필드에서만 환경 변수를 사용하여 암호화된 값을 참조할 수 있습니다.

   다음 빌드 구성 파일 예시는 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 pull $$USERNAME/IMAGE:TAG']
      secretEnv: ['USERNAME']
    availableSecrets:
      inline:
      - kmsKeyName: projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAME
        envMap:
          USERNAME: 'ENCRYPTED_USERNAME'
      - kmsKeyName: projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAME
        envMap:
          PASSWORD: 'ENCRYPTED_PASSWORD'
   

   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 pull $$USERNAME/REPOSITORY:TAG"
        ],
        "secretEnv": [
         "USERNAME"
       ]
     }
     ],
     "availableSecrets": {
       "inline": [{
         "kmsKeyName":  "projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAME",
         "envMap": {
           "USERNAME": "ENCRYPTED_USERNAME"
          }
      },
      {
       "kmsKeyName": "projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAME",
       "envMap": {
           "PASSWORD": "ENCRYPTED_PASSWORD"
          }
      }]
    }
   }
   

   위 명령어의 자리표시자 값을 다음으로 바꿉니다.

   • PROJECT_ID: Cloud KMS 서비스가 포함된 Google Cloud 프로젝트의 ID입니다.
   • USERNAME_KEYRING_NAME: Docker 사용자 이름의 키 링 이름입니다.
   • USERNAME_KEY_NAME: Docker 사용자 이름의 키 이름입니다.
   • ENCRYPTED_USERNAME: base64 형식의 암호화된 Docker 사용자 이름입니다.
   • PASSWORD_KEYRING_NAME: Docker 비밀번호의 키 링 이름입니다.
   • PASSWORD_KEY_NAME: Docker 비밀번호의 키 이름입니다.
   • ENCRYPTED_PASSWORD: base64 형식의 암호화된 Docker 비밀번호입니다.
   • REPOSITORY: 이미지를 가져오려는 Docker 저장소의 이름입니다.

   • TAG: 이미지의 태그 이름입니다.

     참고: secretEnv 필드는 대체 변수를 지원하지 않습니다. 키를 호스팅하는 Google Cloud 프로젝트가 변경될 경우 해당 프로젝트 내의 암호화된 콘텐츠도 변경됩니다.

3. 빌드 구성 파일을 사용하여 빌드를 수동으로 시작하거나 트리거를 사용하여 빌드를 자동화합니다.

암호화된 파일을 사용하도록 빌드 구성

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

2. 빌드 구성 파일에서 복호화된 파일과 상호작용하는 빌드 단계 이전에 gcloud 빌드 단계를 추가하여 암호화 키를 사용하여 암호화된 파일을 복호화합니다. 다음 빌드 구성 파일 예시는 Docker 비밀번호로 암호화된 파일을 사용하여 Docker에 로그인하는 방법을 보여줍니다.

   YAML

   steps:
   - name: gcr.io/cloud-builders/gcloud
     args:
     - kms
     - decrypt
     - "--ciphertext-file=ENCRYPTED_PASSWORD_FILE"
     - "--plaintext-file=PLAINTEXT_PASSWORD_FILE"
     - "--location=global"
     - "--keyring=KEYRING_NAME"
     - "--key=KEY_NAME"
   - name: gcr.io/cloud-builders/docker
     entrypoint: bash
     args:
     - "-c"
     - docker login --username=DOCKER_USERNAME --password-stdin < PLAINTEXT_PASSWORD_FILE
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/gcloud",
       "args": [
         "kms",
         "decrypt",
         "--ciphertext-file=ENCRYPTED_PASSWORD_FILE",
         "--plaintext-file=PLAINTEXT_PASSWORD_FILE",
         "--location=global",
         "--keyring=KEYRING_NAME",
         "--key=KEY_NAME"
       ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=DOCKER_USERNAME --password-stdin < PLAINTEXT_PASSWORD_FILE"
       ]
      }
     ]
   }
   

   위 명령어의 자리표시자 값을 다음으로 바꿉니다.

   • KEYRING_NAME: Docker 비밀번호의 키 링 이름입니다.
   • KEY_NAME: Docker 비밀번호의 키 이름입니다.
   • ENCRYPTED_PASSWORD_FILE: Docker 비밀번호로 암호화된 파일입니다.
   • PLAINTEXT_PASSWORD_FILE: Docker 비밀번호가 포함된 일반 텍스트 파일입니다.

3. 빌드 구성 파일을 사용하여 빌드를 수동으로 시작하거나 트리거를 사용하여 빌드를 자동화합니다.

암호화된 데이터를 사용하도록 빌드 구성(레거시)

경고: 이는 Cloud Build에서 Cloud KMS를 사용하는 기존 방법입니다. 이 방법은 계속 작동하지만 암호화된 데이터를 사용하도록 빌드를 구성하는 새로운 방법을 사용하는 것이 좋습니다.

Cloud KMS를 사용하여 민감한 정보를 암호화하고 이 데이터를 빌드 구성 파일에 사용하려면 다음 안내를 따르세요.

1. 빌드 구성 파일에 secrets 필드를 추가하여 암호화된 값을 지정하고 CryptoKey를 사용하여 복호화합니다. 그런 다음 암호화된 변수를 사용할 빌드 단계에 secretEnv 필드를 추가하여 변수를 환경 변수로 지정합니다. secretEnv 필드에 변수 이름을 포함합니다. 변수 값이나 이름은 동일하지만 보안 비밀이 아닌 환경 변수를 지정하면 Cloud Build에서 오류가 발생합니다.

   YAML

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     entrypoint: 'bash'
     args: ['-c', 'docker login --username=user-name --password=$$PASSWORD']
     secretEnv: ['PASSWORD']
   - name: 'gcr.io/cloud-builders/docker'
     args: ['push', 'user-name/myubuntu']
   secrets:
   - kmsKeyName: projects/project-id/locations/global/keyRings/keyring-name/cryptoKeys/key-name
     secretEnv:
       PASSWORD: 'encrypted-password'
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=user-name --password=$$PASSWORD"
       ],
       "secretEnv": [
         "PASSWORD"
        ]
      },
      {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
          "push",
          "user-name/myubuntu"
         ]
      }
      ],
      "secrets": [
      {
        "kmsKeyName": "projects/project-id/locations/global/keyRings/keyring-name/cryptoKeys/key-name",
        "secretEnv": {
          "PASSWORD": "encrypted-password"
        }
      }
      ]
   }
   

다음 단계

• Secret Manager에서 보안 비밀에 액세스하도록 빌드를 구성하는 방법 알아보기
• 비공개 GitHub 저장소 액세스 방법 알아보기