워커 풀의 종속 항목에 API 키, 비밀번호, 인증서 또는 기타 민감한 정보가 필요할 수 있습니다. Cloud Run의 경우 Secret Manager에서 생성한 보안 비밀에 이 민감한 정보를 저장하는 것이 좋습니다.
다음 방법 중 하나로 컨테이너에 보안 비밀을 제공합니다.
- 각 보안 비밀을 볼륨으로 마운트하면 Cloud Run에서 보안 비밀을 컨테이너에 파일로 제공합니다. 볼륨을 읽을 때 Cloud Run은 항상 Secret Manager에서 보안 비밀 값을 가져와 최신 버전의 값을 사용합니다. 이 방법은 보안 비밀 순환에도 사용할 수 있습니다.
- 환경 변수를 사용하여 보안 비밀을 전달합니다.
인스턴스 시작 시간에 환경 변수가 확인되므로 이 방법을 사용할 경우 버전으로
latest를 사용하는 대신 특정 버전에 보안 비밀을 고정하는 것이 좋습니다.
자세한 내용은 Secret Manager 권장사항을 참고하세요.
배포 및 런타임 중 보안 비밀 확인 방법
작업자 풀을 배포하는 동안 Cloud Run은 사용되는 모든 보안 비밀을 확인합니다. 이 확인을 통해 컨테이너를 실행하는 서비스 계정에 이러한 보안 비밀에 액세스할 권한이 있는지 확인할 수 있습니다.
런타임 중 인스턴스가 시작되면 다음이 수행됩니다.
- 보안 비밀이 환경 변수이면 Cloud Run은 인스턴스를 시작하기 전에 보안 비밀의 값을 검색합니다. 보안 비밀 검색 프로세스가 실패하면 인스턴스가 시작되지 않습니다.
- 보안 비밀을 볼륨으로 마운트하면 Cloud Run에서 인스턴스 시작 중에 검사를 실행하지 않습니다. 하지만 런타임 중 보안 비밀에 액세스할 수 없으면 마운트된 볼륨을 읽으려는 시도가 실패합니다.
볼륨 소유권
Cloud Run 보안 비밀 볼륨의 소유권은 실행 환경과 배포 유형에 따라 다릅니다.
작업자 풀의 경우인 2세대 실행 환경을 사용하여 보안 비밀 볼륨을 마운트하면 루트에서 볼륨을 소유합니다.
시작하기 전에
-
Enable the Secret Manager API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles. - 보안 비밀 만들기에 설명된 대로 기존 보안 비밀을 사용하거나 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를 사용하여 보안 비밀이 작업자 풀에 액세스하도록 할 수 있습니다. 원하는 탭을 클릭합니다.
콘솔
Google Cloud 콘솔에서 Cloud Run으로 이동합니다.
메뉴에서 작업자 풀을 선택하고 컨테이너 배포를 클릭하여 새 작업자 풀을 구성합니다. 초기 작업자 풀 설정 페이지를 작성한 후 컨테이너, 볼륨, 네트워킹, 보안을 클릭하여 구성 페이지를 펼칩니다.
기존 작업자 풀을 구성하는 경우 작업자 풀을 클릭한 후 새 버전 수정 및 배포를 클릭합니다.
단계에 따라 보안 비밀을 볼륨으로 마운트하거나 보안 비밀을 환경 변수로 노출합니다.
보안 비밀을 환경 변수로 노출하려면 다음 절차를 따르세요.
- 컨테이너 탭을 클릭합니다.
- 변수 및 보안 비밀 탭에서 보안 비밀 참조를 클릭합니다.
- 이름 1 필드에 환경 변수의 이름을 입력합니다.
- 보안 비밀 목록에서 사용할 보안 비밀을 선택합니다.
- 버전 1 목록에서 참조할 보안 비밀 버전을 선택합니다.
- 완료를 클릭합니다.
- 만들기 또는 배포를 클릭합니다.
보안 비밀을 볼륨으로 마운트하려면 다음 단계를 따르세요.
- 볼륨 탭을 클릭하고 볼륨 추가를 선택합니다.
- 볼륨 유형 목록에서 보안 비밀을 선택합니다.
- 볼륨 이름 필드에 이름을 입력하거나 기본 이름을 사용합니다.
- 보안 비밀 목록에서 사용할 보안 비밀을 선택합니다.
- 경로 1 필드에 마운트할 파일의 이름을 입력합니다.
- 버전 1 목록에서 참조할 보안 비밀 버전을 선택합니다. 기본적으로 최신 버전이 선택됩니다. 원하는 경우 특정 버전을 선택할 수 있습니다.
- 완료를 클릭합니다.
- 컨테이너 탭으로 이동하여 보안 비밀을 컨테이너에 마운트합니다.
- 볼륨 마운트 탭에서 볼륨 마운트를 클릭합니다.
- 이름 1 목록에서 볼륨 이름을 선택합니다.
- 마운트 경로 1 필드에 이 보안 비밀의 마운트 경로를 입력합니다. 이는 모든 버전의 보안 비밀이 저장되는 디렉터리입니다.
- 완료를 클릭합니다.
- 만들기 또는 배포를 클릭합니다.
gcloud
작업자 풀을 배포할 때 보안 비밀을 환경 변수로 노출하려면 다음 명령어를 실행합니다.
gcloud beta run worker-pools deploy WORKER_POOL \ --image IMAGE_URL \ --update-secrets=ENV_VAR_NAME=SECRET_NAME:VERSION
다음을 바꿉니다.
WORKER_POOL: 작업자 풀의 이름입니다.- IMAGE_URL: 작업자 풀이 포함된 컨테이너 이미지에 대한 참조(예:
us-docker.pkg.dev/cloudrun/container/worker-pool:latest)입니다. ENV_VAR_NAME: 보안 비밀과 함께 사용할 환경 변수의 이름입니다.SECRET_NAME: 동일한 프로젝트의 보안 비밀 이름입니다(예:mysecret).VERSION: 보안 비밀 버전입니다. 최신 버전에latest또는 정수(예:2)를 사용하세요.
여러 보안 비밀을 동시에 업데이트하려면 각 보안 비밀의 구성 옵션을 쉼표로 구분합니다. 다음 명령어는 볼륨으로 마운트된 보안 비밀 하나와 환경 변수로 노출된 다른 보안 비밀을 업데이트합니다. 기존 보안 비밀을 업데이트하려면 다음 명령어를 실행합니다.
gcloud beta run worker-pools deploy WORKER_POOL \ --image IMAGE_URL \ --update-secrets=PATH=SECRET_NAME:VERSION,ENV_VAR_NAME=SECRET_NAME:VERSION
기존 보안 비밀을 삭제하고 작업자 풀에서 새 보안 비밀에 액세스할 수 있게 하려면
--set-secrets플래그를 사용합니다.gcloud beta run worker-pools update WORKER_POOL \ --set-secrets="ENV_VAR_NAME=SECRET_NAME:VERSION"
다른 프로젝트의 보안 비밀 참조
다른 프로젝트의 보안 비밀을 참조하려면 프로젝트의 작업자 풀 계정에 보안 비밀에 대한 액세스 권한이 있는지 확인합니다.
콘솔
Google Cloud 콘솔에서 Cloud Run으로 이동합니다.
메뉴에서 작업자 풀을 선택하고 컨테이너 배포를 클릭하여 새 작업자 풀을 구성합니다. 초기 작업자 풀 설정 페이지를 작성한 후 컨테이너, 볼륨, 네트워킹, 보안을 클릭하여 구성 페이지를 펼칩니다.
기존 작업자 풀을 구성하는 경우 작업자 풀을 클릭한 후 새 버전 수정 및 배포를 클릭합니다.
단계에 따라 보안 비밀을 볼륨으로 마운트하거나 보안 비밀을 환경 변수로 노출합니다.
보안 비밀을 환경 변수로 노출하려면 다음 절차를 따르세요.
- 컨테이너 탭을 클릭합니다.
- 변수 및 보안 비밀 탭에서 보안 비밀 참조를 클릭합니다.
- 이름 1 필드에 환경 변수의 이름을 입력합니다.
- 보안 비밀 목록에서 직접 보안 비밀 입력을 클릭합니다.
보안 비밀의 리소스 ID를 다음 형식으로 입력합니다.
projects/PROJECT_NUMBER/secrets/SECRET_NAME다음을 바꿉니다.
PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다. 프로젝트 번호를 찾는 방법에 대한 자세한 내용은 프로젝트 만들기 및 관리를 참조하세요.
SECRET_NAME: Secret Manager의 보안 비밀 이름
버전 1 목록에서 참조할 보안 비밀 버전을 선택합니다.
완료를 클릭합니다.
만들기 또는 배포를 클릭합니다.
보안 비밀을 볼륨으로 마운트하려면 다음 단계를 따르세요.
- 볼륨 탭을 클릭하고 볼륨 추가를 선택합니다.
- 볼륨 유형 목록에서 보안 비밀을 선택합니다.
- 볼륨 이름 필드에 이름을 입력하거나 기본 이름을 사용합니다.
- 보안 비밀 목록에서 직접 보안 비밀 입력을 클릭합니다.
보안 비밀의 리소스 ID를 다음 형식으로 입력합니다.
projects/PROJECT_NUMBER/secrets/SECRET_NAME다음을 바꿉니다.
PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다. 프로젝트 번호를 찾는 방법에 대한 자세한 내용은 프로젝트 만들기 및 관리를 참조하세요.
SECRET_NAME: Secret Manager의 보안 비밀 이름
경로 1 필드에 마운트할 파일의 이름을 입력합니다.
버전 1 목록에서 참조할 보안 비밀 버전을 선택합니다. 기본적으로 최신 버전이 선택됩니다. 원하는 경우 특정 버전을 선택할 수 있습니다.
완료를 클릭합니다.
컨테이너 탭으로 이동하여 보안 비밀을 컨테이너에 마운트합니다.
볼륨 마운트 탭에서 볼륨 마운트를 클릭합니다.
이름 1 목록에서 볼륨 이름을 선택합니다.
마운트 경로 1 필드에 이 보안 비밀의 마운트 경로를 입력합니다. 이는 모든 버전의 보안 비밀이 저장되는 디렉터리입니다.
완료를 클릭합니다.
만들기 또는 배포를 클릭합니다.
gcloud
보안 비밀을 환경 변수로 참조하려면 다음 명령어를 실행하세요.
gcloud beta run worker-pools deploy WORKER_POOL \ --image IMAGE_URL \ --update-secrets=ENV_VAR_NAME=projects/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION
다음을 바꿉니다.
WORKER_POOL: 작업자 풀의 이름입니다.- IMAGE_URL: 작업자 풀이 포함된 컨테이너 이미지에 대한 참조(예:
us-docker.pkg.dev/cloudrun/container/worker-pool:latest)입니다. PROJECT_NUMBER: 보안 비밀이 생성된 프로젝트의 프로젝트 번호SECRET_NAME: 보안 비밀 이름입니다(예:mysecret).VERSION: 보안 비밀 버전. 최신 버전에latest또는 정수(예:2)를 사용하세요.
보안 비밀 설정 보기
Cloud Run 작업자 풀의 현재 보안 비밀 설정을 보려면 다음 안내를 따르세요.
콘솔
Google Cloud 콘솔에서 Cloud Run 작업자 풀 페이지로 이동합니다.
관심 있는 작업자 풀을 클릭하여 작업자 풀 세부정보 페이지를 엽니다.
새 버전 수정 및 배포를 클릭합니다.
구성 세부정보에서 보안 비밀 설정을 찾습니다.
gcloud
다음 명령어를 사용하세요.
gcloud beta run worker-pools describe WORKER_POOL
반환된 구성에서 보안 비밀 설정을 찾습니다.
작업자 풀에서 보안 비밀 삭제
Google Cloud 콘솔이나 gcloud CLI를 사용하여 작업자 풀에서 보안 비밀을 삭제할 수 있습니다.
콘솔
Google Cloud 콘솔에서 Cloud Run으로 이동합니다.
목록에서 작업자 풀을 선택하고 새 버전 수정 및 배포를 클릭합니다.
컨테이너 탭을 클릭합니다.
볼륨으로 마운트된 보안 비밀을 삭제하려면 볼륨 마운트 탭을 선택하고 삭제하려는 보안 비밀 위로 마우스 포인터를 가져간 후 삭제를 클릭합니다.
환경 변수로 노출된 보안 비밀을 삭제하려면 변수 및 보안 비밀 탭을 선택하고 삭제하려는 보안 비밀 위로 마우스 포인터를 가져간 후 삭제를 클릭합니다.
배포를 클릭합니다.
gcloud
작업자 풀에서 모든 보안 비밀을 삭제하거나 삭제할 보안 비밀을 하나 이상 지정할 수 있습니다.
- 모든 보안 비밀을 삭제하려면 다음 명령어를 실행합니다.
gcloud beta run worker-pools deploy WORKER_POOL --image IMAGE_URL \ --clear-secrets
다음을 바꿉니다.
- WORKER_POOL: 작업자 풀의 이름입니다.
IMAGE_URL: 작업자 풀이 포함된 컨테이너 이미지에 대한 참조(예:
us-docker.pkg.dev/cloudrun/container/worker-pool:latest)입니다.삭제할 보안 비밀 목록을 지정하려면
--remove-secrets플래그를 사용합니다. 다음 명령어는 볼륨으로 마운트된 보안 비밀 하나와 환경 변수로 노출된 다른 보안 비밀을 삭제합니다.
gcloud beta run worker-pools deploy WORKER_POOL --image IMAGE_URL \ --remove-secrets=ENV_VAR_NAME,SECRET_FILE_PATH
다음을 바꿉니다.
- WORKER_POOL: 작업자 풀의 이름입니다.
- IMAGE_URL: 작업자 풀이 포함된 컨테이너 이미지에 대한 참조(예:
us-docker.pkg.dev/cloudrun/container/worker-pool:latest)입니다. - ENV_VAR_NAME: 환경 변수의 이름입니다.
SECRET_FILE_PATH: 보안 비밀의 전체 경로입니다. 예를 들어
/mnt/secrets/primary/latest입니다. 여기서/mnt/secrets/primary/는 마운트 경로이고latest는 보안 비밀 경로입니다. 마운트 경로와 보안 비밀 경로를 개별적으로 지정할 수도 있습니다.--set-secrets MOUNT_PATH:SECRET_PATH=SECRET:VERSION
코드에서 보안 비밀 사용
코드에서 환경 변수로 보안 비밀에 액세스하는 예시는 최종 사용자 인증에 관한 튜토리얼, 특히 Secret Manager로 민감한 구성 처리 섹션을 참고하세요.
허용되지 않는 경로 및 제한사항
시크릿 마운트에는 다음과 같은 제한사항이 적용됩니다.
- Cloud Run에서는 보안 비밀을
/dev,/proc,/sys또는 해당 하위 디렉터리에 마운트할 수 없습니다. - 볼륨 마운트 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)를 만듭니다.