보안 비밀 구성

작업에 API 키, 암호, 인증서 또는 기타 민감한 정보가 필요한 종속 항목이 있어야 할 수 있습니다. Cloud Run의 경우 Secret Manager에서 생성된 보안 비밀에 이 유형의 민감한 정보를 저장하는 것이 좋습니다.

다음 두 방법 중 하나로 컨테이너에 보안 비밀을 제공할 수 있습니다.

• 각 보안 비밀을 볼륨으로 마운트하여, 보안 비밀을 컨테이너에 파일로 제공합니다. 볼륨을 읽으면 항상 Secret Manager에서 보안 비밀 값을 가져오므로 최신 버전에 사용될 수 있습니다. 이 방법은 보안 비밀 순환에도 사용할 수 있습니다.
• 환경 변수를 사용하여 보안 비밀을 전달합니다. 인스턴스 시작 시간에 환경 변수가 확인되므로 이 방법을 사용할 경우 최신 항목을 사용하는 대신 특정 버전에 보안 비밀을 고정하는 것이 좋습니다.

자세한 내용은 Secret Manager 권장사항 문서를 참조하세요.

배포 및 런타임 중 보안 비밀 확인 방법

작업 생성 중에 환경 변수로 사용되거나 볼륨으로 마운트되는 모든 보안 비밀은 컨테이너를 실행하는 데 사용되는 서비스 계정에 액세스 권한이 있는지 확인합니다. 검사가 실패하면 작업 만들기가 실패합니다.

런타임 중 인스턴스가 시작되면 다음이 수행됩니다.

• 보안 비밀이 환경 변수이면 인스턴스 시작 전에 보안 비밀 값이 검색되므로 보안 비밀 검색이 실패하면 인스턴스가 시작되지 않습니다.
• 보안 비밀이 볼륨으로 마운트된 경우 인스턴스 시작 중에 검사가 수행되지 않습니다. 하지만 런타임 중 보안 비밀에 액세스할 수 없으면 마운트된 볼륨을 읽으려는 시도가 실패합니다.

실행 환경과 배포 유형에 따라 달라지는 볼륨 소유권

작업의 경우인 2세대 실행 환경을 사용하여 보안 비밀 볼륨을 마운트하면 루트에서 볼륨을 소유합니다.

시작하기 전에

기존 Secret Manager 보안 비밀 또는 새 보안 비밀을 사용할 수 있습니다.

필요한 역할

보안 비밀을 구성하는데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

• Cloud Run 작업에 대한 Cloud Run 관리자(roles/run.admin) 역할
• 서비스 ID에 대한 서비스 계정 사용자(roles/iam.serviceAccountUser) 역할

Cloud Run에서 보안 비밀에 액세스하도록 허용하려면 서비스 ID에 다음 역할이 있어야 합니다.

• Secret Manager 보안 비밀 접근자(roles/secretmanager.secretAccessor) 역할

서비스 ID 주 구성원을 Secret Manager 보안 비밀 접근자 역할에 추가하는 방법은 보안 비밀에 대한 액세스 관리를 참조하세요.

Cloud Run과 연결된 IAM 역할 및 권한 목록은 Cloud Run IAM 역할 및 Cloud Run IAM 권한을 참조하세요. Cloud Run 작업이 Cloud 클라이언트 라이브러리와 같은 Google Cloud API와 상호작용하는 경우에는 서비스 ID 구성 가이드를 참조하세요. 역할 부여에 대한 자세한 내용은 배포 권한 및 액세스 관리를 참조하세요.

Cloud Run에서 액세스할 수 있는 보안 비밀 만들기

Google Cloud 콘솔, Google Cloud CLI, YAML을 사용하여 작업에 대한 보안 비밀에 액세스할 수 있습니다.

콘솔

1. Google Cloud 콘솔에서 Cloud Run 작업 페이지로 이동합니다.

   Cloud Run으로 이동

2. 컨테이너 배포를 클릭하고 작업을 선택하여 초기 작업 설정 페이지를 작성합니다. 기존 작업을 구성하는 경우 작업을 선택한 후 수정을 클릭합니다.

3. 컨테이너, 변수 및 보안 비밀, 연결, 보안을 클릭하여 작업 속성 페이지를 펼칩니다.

4. 변수 및 보안 비밀 탭을 클릭합니다.

   

   • 변수 및 보안 비밀 탭에서 다음을 수행합니다.
     • 보안 비밀에서 보안 비밀 참조 추가를 클릭합니다.
     • 보안 비밀 풀다운 목록에서 사용할 보안 비밀을 선택합니다.
     • 참조 메서드 풀다운 메뉴에서 보안 비밀을 볼륨으로 마운트할지 아니면 환경 변수로 공개할지 선택합니다.
     • 보안 비밀을 볼륨으로 마운트하는 경우 다음 안내를 따르세요.
       1. 마운트 경로에서 보안 비밀에 사용하는 마운트 경로를 지정합니다.
       2. 기본적으로 최신 버전이 선택됩니다. 원하는 경우 특정 버전을 선택할 수 있습니다. 보안 비밀 버전에 지정된 경로 아래에서 버전 경로 및 버전 번호를 지정합니다.
       3. 완료를 클릭합니다.
     • 보안 비밀을 환경 변수로 노출하는 경우:
       1. 변수의 이름을 제공하고 보안 비밀 버전을 선택합니다. 또는 항상 최신 보안 비밀 버전을 사용하려면 최신을 선택합니다.
       2. 완료를 클릭합니다.

5. 만들기 또는 업데이트를 클릭합니다.

gcloud

참고: 여러 보안 비밀을 동시에 업데이트할 수 있습니다. 이렇게 하려면 각 보안 비밀의 구성 옵션을 쉼표로 구분합니다.

• 새 작업을 만들 때 환경 변수에 보안 비밀을 지정합니다.

  gcloud run jobs create JOB_NAME \
  --image IMAGE_URL \
  --set-secrets ENV_VAR_NAME=SECRET_NAME:VERSION

  다음과 같이 바꿉니다.

  • JOB_NAME을 작업 이름으로 바꿉니다.
  • ENV_VAR_NAME을 보안 비밀에 사용할 환경 변수의 이름으로 바꿉니다.
  • SECRET_NAME을 동일한 프로젝트의 보안 비밀 이름으로 바꿉니다(예: mysecret).
  • VERSION을 보안 비밀 버전으로 바꿉니다. latest(최신 버전의 경우) 또는 숫자(예: 2)를 사용합니다.
  • IMAGE_URL을 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/job:latest)로 바꿉니다.

  쉼표로 구분된 목록을 사용하여 여러 환경 변수/보안 비밀 쌍을 지정할 수 있습니다.

• 작업을 업데이트할 때 환경 변수에 보안 비밀을 지정합니다.

  gcloud run jobs update JOB_NAME \
  --set-secrets ENV_VAR_NAME=SECRET_NAME:VERSION

• 작업을 만들 때 보안 비밀을 볼륨으로 마운트하려면 다음 명령어를 실행합니다.

  gcloud run jobs create JOB_NAME \
  --image IMAGE_URL \
  --set-secrets=PATH=SECRET_NAME:VERSION

  다음과 같이 바꿉니다.

  • JOB_NAME을 작업 이름으로 바꿉니다.
  • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/job:latest)
  • PATH: 볼륨의 마운트 경로 및 보안 비밀의 파일 이름 /etc/secrets/dbconfig/password와 같이 선행 슬래시로 시작해야 합니다. 여기서 /etc/secrets/dbconfig/는 볼륨의 마운트 경로이고, password는 보안 비밀의 파일 이름입니다.
  • SECRET_NAME을 동일한 프로젝트의 보안 비밀 이름으로 바꿉니다(예: mysecret).
  • VERSION: 보안 비밀 버전. 최신 버전에 latest 또는 정수(예: 2)를 사용하세요.

• 기존 작업에서 보안 비밀을 업데이트하려면 다음 명령어를 실행합니다.

  gcloud run jobs update JOB_NAME \
  --update-secrets=PATH=SECRET_NAME:VERSION

YAML

API 호환성 관련 제약조건으로 인해 보안 비밀 위치는 주석에 저장되어야 합니다.

1. 새 서비스를 만드는 경우에는 이 단계를 건너뜁니다. 기존 서비스를 업데이트하는 경우 YAML 구성을 다운로드합니다.

   gcloud run jobs describe JOB_NAME --format export > job.yaml

2. 환경 변수로 노출된 보안 비밀의 경우:

   apiVersion: run.googleapis.com/v1
   kind: Job
   metadata:
     name: JOB
   spec:
     template:
       spec:
         template:
           spec:
             containers:
             - env:
               - name: SECRET_NAME
                 valueFrom:
                   secretKeyRef:
                     key: VERSION
                     name: SECRET_LOOKUP_NAME
               image: IMAGE_URL 

   다음과 같이 바꿉니다.

   • JOB을 작업 이름으로 바꿉니다.
   • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL의 형식은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG입니다.
   • SECRET_NAME: 보안 비밀 이름(예: mysecret)
   • VERSION: 보안 비밀 버전. 최신 버전에 latest 또는 정수(예: 2)를 사용하세요.
   • SECRET_LOOKUP_NAME: 적합한 보안 비밀 이름 구문을 갖는 이름(예: my-secret). SECRET_NAME과 동일해도 됩니다.

3. 파일 경로로 마운트된 보안 비밀의 경우:

   apiVersion: run.googleapis.com/v1
   kind: Job
   metadata:
     name: JOB_NAME
   spec:
     template:
       spec:
         template:
           spec:
             containers:
             - image: IMAGE_URL
               volumeMounts:
               - mountPath: MOUNT_PATH
                 name: VOLUME_NAME
             volumes:
             - name: VOLUME_NAME
               secret:
                 items:
                 - key: VERSION
                   path: FILENAME
                 secretName: SECRET_LOOKUP_NAME

   다음과 같이 바꿉니다.

   • JOB_NAME을 작업 이름으로 바꿉니다.
   • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL의 형식은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG입니다.
   • PATH: 볼륨의 마운트 경로 및 보안 비밀의 파일 이름 /etc/secrets/dbconfig/password와 같이 선행 슬래시로 시작해야 합니다. 여기서 /etc/secrets/dbconfig/는 볼륨의 마운트 경로이고, password는 보안 비밀의 파일 이름입니다.
   • PROJECT_NUMBER: 보안 비밀이 생성된 프로젝트의 프로젝트 번호
   • SECRET_NAME을 보안 비밀 이름으로 바꿉니다(예: mysecret).
   • VERSION: 보안 비밀 버전. 최신 버전에 latest 또는 정수(예: 2)를 사용하세요.
   • SECRET_LOOKUP_NAME: 적합한 보안 비밀 이름 구문을 갖는 이름(예: my-secret). SECRET_NAME과 동일해도 됩니다.
   • VOLUME_NAME: 아무 이름(예: my-volume). SECRET_NAME과 동일해도 됩니다.

다른 프로젝트의 보안 비밀 참조

프로젝트의 서비스 계정이 보안 비밀에 액세스하도록 허용된 경우 다른 프로젝트의 보안 비밀을 참조할 수 있습니다.

콘솔

1. Google Cloud 콘솔에서 Cloud Run 작업 페이지로 이동합니다.

   Cloud Run으로 이동

2. 컨테이너 배포를 클릭하고 작업을 선택하여 초기 작업 설정 페이지를 작성합니다. 기존 작업을 구성하는 경우 작업을 선택한 후 수정을 클릭합니다.

3. 컨테이너, 변수 및 보안 비밀, 연결, 보안을 클릭하여 작업 속성 페이지를 펼칩니다.

4. 변수 및 보안 비밀 탭을 클릭합니다.

   

   • 변수 및 보안 비밀 탭에서 다음을 수행합니다.
     • 보안 비밀에서 보안 비밀 참조 추가를 클릭합니다.
     • 보안 비밀 풀다운 목록에서 직접 보안 비밀 입력을 선택하여 다음 양식을 표시합니다.

       

     • 리소스 ID별로 보안 비밀 추가 양식에서 projects/PROJECT_NUMBER/secrets/SECRET_NAME 형식으로 다른 프로젝트의 보안 비밀을 입력합니다. 또는 액세스 권한이 있으면 보안 비밀을 선택하고, 보안 비밀 오른쪽에 있는 작업 줄임표를 클릭하고, 풀다운 메뉴에서 리소스 ID 복사를 선택하여 다른 프로젝트에서 리소스 ID를 복사하여 붙여넣을 수 있습니다.
     • 보안 비밀 추가를 클릭합니다.
     • 참조 메서드 풀다운 메뉴에서 보안 비밀을 볼륨으로 마운트할지 아니면 환경 변수로 공개할지 선택합니다.
     • 보안 비밀을 볼륨으로 마운트하는 경우 다음 안내를 따르세요.
       1. 마운트 경로에서 보안 비밀에 사용하는 마운트 경로를 지정합니다.
       2. 기본적으로 최신 버전이 선택됩니다. 원하는 경우 특정 버전을 선택할 수 있습니다. 보안 비밀 버전에 지정된 경로 아래에서 버전 경로 및 버전 번호를 지정합니다.
       3. 완료를 클릭합니다.
     • 보안 비밀을 환경 변수로 노출하는 경우:
       1. 변수의 이름을 제공하고 보안 비밀 버전을 선택합니다. 또는 항상 최신 보안 비밀 버전을 사용하려면 최신을 선택합니다.
       2. 완료를 클릭합니다.

5. 만들기 또는 업데이트를 클릭합니다.

gcloud

• 작업을 업데이트할 때 보안 비밀을 볼륨으로 마운트하려면 다음을 수행합니다.

  gcloud run jobs update JOB_NAME \
  --image IMAGE_URL \
  --update-secrets=PATH=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION

  • JOB_NAME을 작업 이름으로 바꿉니다.
  • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL의 형식은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG입니다.
  • PATH: 볼륨의 마운트 경로 및 보안 비밀의 파일 이름 /etc/secrets/dbconfig/password와 같이 선행 슬래시로 시작해야 합니다. 여기서 /etc/secrets/dbconfig/는 볼륨의 마운트 경로이고, password는 보안 비밀의 파일 이름입니다.
  • PROJECT_NUMBER: 보안 비밀이 생성된 프로젝트의 프로젝트 번호
  • SECRET_NAME: 보안 비밀 이름(예: mysecret)
  • VERSION: 보안 비밀 버전. 최신 버전에 latest 또는 정수(예: 2)를 사용하세요.

YAML

1. 새 작업을 만드는 경우에는 이 단계를 건너뜁니다. 기존 서비스를 업데이트하는 경우 YAML 구성을 다운로드합니다.

   gcloud run jobs describe JOB_NAME --format export > job.yaml

API 호환성 관련 제약조건으로 인해 보안 비밀 위치는 주석에 저장되어야 합니다.

1. 환경 변수로 노출된 보안 비밀의 경우:

   apiVersion: run.googleapis.com/v1
   kind: Job
   metadata:
     name: JOB
   spec:
     template:
       metadata:
         annotations:
           run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
       spec:
         template:
           spec:
             containers:
             - env:
               - name: SECRET_NAME
                 valueFrom:
                   secretKeyRef:
                     key: VERSION
                     name: SECRET_LOOKUP_NAME
               image: IMAGE_URL 

   다음과 같이 바꿉니다.

   • JOB을 작업 이름으로 바꿉니다.
   • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL의 형식은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG입니다.
   • SECRET_NAME을 보안 비밀 이름으로 바꿉니다(예: mysecret).
   • VERSION: 보안 비밀 버전. 최신 버전에 latest 또는 정수(예: 2)를 사용하세요.
   • PROJECT_NUMBER: 보안 비밀이 생성된 프로젝트의 프로젝트 번호
   • SECRET_LOOKUP_NAME: 적합한 보안 비밀 이름 구문을 갖는 이름(예: my-secret). SECRET_NAME과 동일해도 됩니다.

2. 파일 경로로 마운트된 보안 비밀의 경우:

   apiVersion: run.googleapis.com/v1
   kind: Job
   metadata:
     name: JOB_NAME
   spec:
     template:
       metadata:
         annotations:
           run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
       spec:
         template:
           spec:
             containers:
             - image: IMAGE_URL
               volumeMounts:
               - mountPath: MOUNT_PATH
                 name: VOLUME_NAME
             volumes:
             - name: VOLUME_NAME
               secret:
                 items:
                 - key: VERSION
                   path: FILENAME
                 secretName: SECRET_LOOKUP_NAME

   다음과 같이 바꿉니다.

   • JOB_NAME을 작업 이름으로 바꿉니다.
   • IMAGE_URL: 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest). Artifact Registry를 사용하는 경우 저장소 REPO_NAME이 이미 생성되어 있어야 합니다. URL의 형식은 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG입니다.
   • PATH: 볼륨의 마운트 경로 및 보안 비밀의 파일 이름 /etc/secrets/dbconfig/password와 같이 선행 슬래시로 시작해야 합니다. 여기서 /etc/secrets/dbconfig/는 볼륨의 마운트 경로이고, password는 보안 비밀의 파일 이름입니다.
   • PROJECT_NUMBER: 보안 비밀이 생성된 프로젝트의 프로젝트 번호
   • SECRET_NAME을 보안 비밀 이름으로 바꿉니다(예: mysecret).
   • VERSION: 보안 비밀 버전. 최신 버전에 latest 또는 정수(예: 2)를 사용하세요.
   • SECRET_LOOKUP_NAME: 적합한 보안 비밀 이름 구문을 갖는 이름(예: my-secret). SECRET_NAME과 동일해도 됩니다.
   • VOLUME_NAME: 아무 이름(예: my-volume). SECRET_NAME과 동일해도 됩니다.

보안 비밀 설정 보기

Cloud Run 작업의 현재 보안 비밀 설정을 보려면 다음 안내를 따르세요.

콘솔

1. Google Cloud 콘솔에서 Cloud Run 작업 페이지로 이동합니다.

   Cloud Run 작업으로 이동

2. 관심 있는 작업을 클릭하여 작업 세부정보 페이지를 엽니다.

3. 구성 탭을 클릭합니다.

4. 구성 세부정보에서 보안 비밀 설정을 찾습니다.

gcloud

1. 다음 명령어를 사용하세요.

   gcloud run jobs describe JOB_NAME

2. 반환된 구성에서 보안 비밀 설정을 찾습니다.

허용되지 않는 경로 및 제한사항

Cloud Run에서는 보안 비밀을 /dev, /proc, /sys 또는 해당 하위 디렉터리에 마운트할 수 없습니다.

보안 비밀을 /tmp에 마운트하고 1세대 실행 환경을 사용하는 경우 /tmp에 보안 비밀 마운트에 대한 알려진 문제를 참조하세요.

볼륨 마운트 2개를 같은 위치에 마운트할 수 없으므로 Cloud Run에서 같은 경로에 보안 비밀 여러 개를 마운트할 수 없습니다.

디렉터리 재정의

보안 비밀이 Cloud Run에 볼륨으로 마운트되고 볼륨 마운트 경로의 마지막 디렉터리가 이미 있으면 기존 디렉터리의 파일이나 폴더에 액세스할 수 없습니다.

예를 들어 my-secret이라는 보안 비밀이 /etc/app_data 경로에 마운트되면 app_data 디렉터리 내의 모든 콘텐츠를 덮어쓰고 표시되는 유일한 파일은 /etc/app_data/my-secret입니다.

기존 디렉터리의 파일을 덮어쓰지 않게 하려면 보안 비밀의 마운트 경로가 /etc/app_data/secrets/my-secret가 되도록 보안 비밀을 마운트할 새 디렉터리(예: /etc/app_data/secrets)를 만듭니다.