보안 비밀 사용

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

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

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

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

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

배포 중 환경 변수로 사용되거나 볼륨으로 마운트되는 모든 보안 비밀은 컨테이너 실행을 위해 사용되는 서비스 계정에 액세스 권한이 포함되는지 확인됩니다. 검사가 실패하면 배포가 실패합니다.

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

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

Cloud Run에서 보안 비밀에 액세스하도록 허용

기존 Secret Manager 보안 비밀 또는 새 보안 비밀을 사용할 수 있습니다. 그러나 Cloud Run 서비스에서 보안 비밀에 액세스하도록 허용하려면 Cloud Run 서비스 계정에 Secret Manager 보안 비밀 접근자 역할을 부여해야 합니다.

  1. Cloud Console에서 Secret Manager 페이지로 이동합니다.

  2. 보안 비밀을 선택하고 오른쪽 권한 탭에서 주 구성원 추가를 클릭합니다.

  3. 새로운 주 구성원 텍스트 상자에 Cloud Run 서비스에 대한 서비스 계정 이메일을 입력합니다.

  4. 여기에 Secret Manager 보안 비밀 접근자 역할을 부여합니다.

서비스에 보안 비밀 사용 설정

구성을 변경하면 새 버전이 생성됩니다. 이를 변경하는 명시적 업데이트가 없으면 이후 버전에도 이 구성 설정이 자동으로 적용됩니다.

서비스를 배포하거나 기존 서비스를 업데이트하고 버전을 배포할 때 Cloud Console, gcloud 명령줄 도구 또는 YAML 파일을 사용하여 서비스에 보안 비밀에 액세스할 수 있습니다.

Console

  1. Cloud Run으로 이동

  2. 배포할 새 서비스를 구성하려면 서비스 만들기를 클릭합니다. 기존 서비스를 구성하는 경우 서비스를 클릭한 다음 새 버전 수정 및 배포를 클릭합니다.

  3. 새 서비스를 구성하는 경우 필요에 따라 초기 서비스 설정 페이지를 작성한 후 다음 > 고급 설정을 클릭하여 서비스 구성 페이지에 연결합니다.

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

    이미지

  5. 변수 및 보안 비밀 탭에서 다음을 수행합니다.

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

  6. 만들기 또는 배포를 클릭합니다.

명령줄

서비스에서 보안 비밀에 액세스할 수 있게 하려면 다음 명령어 중 하나를 입력합니다.

  • 서비스를 배포할 때 보안 비밀을 볼륨으로 마운트하려면 다음을 실행합니다.

    gcloud beta run deploy SERVICE --image IMAGE_URL  \
    --update-secrets=PATH=SECRET_NAME:VERSION

    다음과 같이 바꿉니다.

    • SERVICE를 서비스 이름으로 바꿉니다.
    • IMAGE_URL을 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest)로 바꿉니다.
    • PATH를 볼륨의 마운트 경로 및 보안 비밀의 파일 이름으로 바꿉니다. /etc/secrets/dbconfig/password와 같이 선행 슬래시로 시작해야 합니다. 여기서 /etc/secrets/dbconfig/는 볼륨의 마운트 경로이고, password는 보안 비밀의 파일 이름입니다.
    • SECRET_NAME을 보안 비밀 이름으로 바꿉니다.
    • VERSION을 보안 비밀 버전으로 바꿉니다. 최신 버전의 경우 latest 또는 2와 같은 정수를 사용합니다.
  • 서비스를 배포할 때 보안 비밀을 환경 변수로 노출하려면 다음을 실행합니다.

    gcloud beta run deploy SERVICE --image IMAGE_URL --update-secrets=ENV_VAR_NAME=SECRET_NAME:VERSION

    다음과 같이 바꿉니다.

    • SERVICE를 서비스 이름으로 바꿉니다.
    • IMAGE_URL을 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest)로 바꿉니다.
    • ENV_VAR_NAME을 보안 비밀에 사용하려는 환경 변수의 이름으로 바꿉니다.
    • SECRET_NAME을 보안 비밀 이름으로 바꿉니다.
    • VERSION을 보안 비밀 버전으로 바꿉니다. 최신 버전의 경우 latest 또는 2와 같은 정수를 사용합니다.
  • 보안 비밀 여러 개를 한 번에 업데이트할 수 있습니다. 각 보안 비밀의 구성 옵션을 쉼표로 구분합니다. 다음 명령어는 볼륨으로 마운트된 보안 비밀 하나와 환경 변수로 노출된 다른 보안 비밀을 업데이트합니다.

    기존 보안 비밀을 업데이트하려면 다음 명령어를 입력합니다.

    gcloud beta run deploy SERVICE --image IMAGE_URL \
    --update-secrets=PATH=SECRET_NAME:VERSION,ENV_VAR_NAME=SECRET_NAME:VERSION
    
  • 기존 보안 비밀을 삭제하고 서비스에서 새 보안 비밀에 액세스할 수 있게 하려면 --set-secrets 플래그를 사용합니다.

    gcloud beta run services update SERVICE \
    --set-secrets="ENV_VAR_NAME=SECRET_NAME:VERSION"
    

YAML

YAML 형식으로 정리된 결과를 반환하는 gcloud run services describe --format export 명령어를 사용하면 기존 서비스 구성을 다운로드하고 볼 수 있습니다. 그런 다음 아래 설명된 필드를 수정하고 gcloud run services replace 명령어를 사용하여 수정된 YAML을 업로드할 수 있습니다. 설명된 대로 필드만 수정해야 합니다.

  1. 구성을 보고 다운로드하려면 다음을 실행합니다.

    gcloud run services describe SERVICE --format export > service.yaml
  2. 환경 변수로 노출되는 보안 비밀의 경우 env 아래에서 필요에 따라 ENV_VAR, VERSION 또는 SECRET_NAME을 업데이트합니다. 환경 변수로 마운트되는 여러 보안 비밀이 있으면 이러한 속성이 여러 개 포함됩니다.

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
        spec:
          containers:
          - image: IMAGE_URL
            env:
            - name: ENV_VAR
              valueFrom:
                secretKeyRef:
                  key: VERSION
                  name: SECRET_NAME
  3. 파일 경로로 마운트된 보안 비밀의 경우 필요에 따라 MOUNT_PATH, VOLUME_NAME, VERSION, FILENAME 또는 SECRET_NAME을 업데이트합니다. 파일 경로로 마운트된 보안 비밀이 여러 개 있으면 이러한 속성이 여러 개 포함됩니다.

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    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_NAME

    VOLUME_NAME은 어떤 이름으로든 설정할 수 있습니다.

  4. 다음 명령어를 사용하여 서비스를 새 구성으로 바꿉니다.

    gcloud run services replace service.yaml

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

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

Console

  1. Cloud Run으로 이동

  2. 배포할 새 서비스를 구성하려면 서비스 만들기를 클릭합니다. 기존 서비스를 구성하는 경우 서비스를 클릭한 다음 새 버전 수정 및 배포를 클릭합니다.

  3. 새 서비스를 구성하는 경우 필요에 따라 초기 서비스 설정 페이지를 작성한 후 다음 > 고급 설정을 클릭하여 서비스 구성 페이지에 연결합니다.

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

    이미지

  5. 변수 및 보안 비밀 탭에서 다음을 수행합니다.

    • 보안 비밀에서 보안 비밀 참조를 클릭합니다.
    • 보안 비밀이 표시되지 않나요? 보안 비밀 리소스 ID 입력보안 비밀 풀다운 목록에서 선택하여 다음 양식을 표시합니다.

      프로젝트 간 보안 비밀

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

  6. 만들기 또는 배포를 클릭합니다.

명령줄

  • 서비스를 배포할 때 보안 비밀을 볼륨으로 마운트하려면 다음을 실행합니다.

    gcloud beta run deploy SERVICE --image IMAGE_URL  \
    --update-secrets=PATH=project/PROJECT_NUMBER/secrets/SECRET_NAME:VERSION

    다음과 같이 바꿉니다.

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

보안 비밀 설정 보기

서비스의 현재 보안 비밀 설정을 확인하려면 다음 안내를 따르세요.

Console

  1. Cloud Run으로 이동

  2. 관심이 있는 서비스를 클릭하여 서비스 세부정보 페이지를 엽니다.

  3. 버전 탭을 클릭합니다.

  4. 오른쪽의 세부정보 패널에서 보안 비밀 설정이 변수 및 보안 비밀 탭에 나열됩니다.

명령줄

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

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

YAML

YAML 형식으로 정리된 결과를 반환하는 gcloud run services describe --format export 명령어를 사용하면 기존 서비스 구성을 다운로드하고 볼 수 있습니다. 그런 다음 아래 설명된 필드를 수정하고 gcloud run services replace 명령어를 사용하여 수정된 YAML을 업로드할 수 있습니다. 설명된 대로 필드만 수정해야 합니다.

  1. 구성을 보고 다운로드하려면 다음을 실행합니다.

    gcloud run services describe SERVICE --format export > service.yaml

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

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

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
          run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
        spec:
          containers:
          - image: IMAGE_URL
            env:
            - name: ENV_VAR
              valueFrom:
                secretKeyRef:
                  key: VERSION
                  name: SECRET_LOOKUP_NAME

    다음과 같이 바꿉니다.

    • SERVICE를 서비스 이름으로 바꿉니다.
    • IMAGE_URL을 컨테이너 이미지에 대한 참조(예: us-docker.pkg.dev/cloudrun/container/hello:latest)로 바꿉니다.
    • ENV_VAR
    • PROJECT_NUMBER를 보안 비밀이 생성된 프로젝트의 프로젝트 번호로 바꿉니다.
    • SECRET_NAME을 보안 비밀 이름으로 바꿉니다.
    • VERSION을 보안 비밀 버전으로 바꿉니다. 최신 버전의 경우 latest 또는 2와 같은 정수를 사용합니다.
    • SECRET_LOOKUP_NAME을 적합한 보안 비밀 이름 구문(예: my-secret)을 갖는 이름으로 바꿉니다. SECRET_NAME과 동일할 수 있습니다.
  2. 파일 경로로 마운트된 보안 비밀의 경우:

    apiVersion: serving.knative.dev/v1
    kind: Service
    metadata:
      name: SERVICE
    spec:
      template:
          run.googleapis.com/secrets: SECRET_LOOKUP_NAME:projects/PROJECT_NUMBER/secrets/SECRET_NAME
        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

    다음과 같이 바꿉니다.

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

코드에 보안 비밀 사용

코드에서 환경 변수로 보안 비밀에 액세스하는 예시는 최종 사용자 인증, 특히 Secret Manager로 민감한 구성 처리 섹션을 참조하세요.