낙관적 동시 실행 제어에 항목 태그 사용

Secret Manager는 최적의 동시 실행 제어를 위해 항목 태그(ETags) 사용을 지원합니다.

경우에 따라 동일한 리소스를 동시에 업데이트하는 두 프로세스가 서로 간섭할 수 있으며, 나중의 프로세스가 이전 프로세스의 작업을 덮어쓰게 됩니다.

ETag는 프로세스가 리소스에 조치를 취하기 전에 리소스가 수정되었는지 여부를 확인할 수 있도록 하여 낙관적 동시 실행 제어를 위한 수단을 제공합니다.

Secret Manager에서 ETag 사용

다음 리소스 수정 요청은 ETag를 지원합니다.

secrets.patch 요청에서 요청 ETag는 보안 비밀 데이터에 삽입됩니다. 다른 모든 요청은 선택적 etag 매개변수를 허용합니다.

ETag가 제공되고 현재 리소스 ETag와 일치하면 요청이 성공한 것이며 그렇지 않으면 FAILED_PRECONDITION 오류와 HTTP 상태 코드 400으로 실패합니다. ETag가 제공되지 않으면 현재 저장된 ETag 값을 확인하지 않고 요청이 진행됩니다.

리소스 ETag는 리소스 생성 시(projects.secrets.create, projects.secrets.addVersion) 생성되고 위에 나열된 각 수정 요청에 대해 업데이트됩니다. 수정 요청은 적용되는 리소스의 ETag만 업데이트합니다. 즉, 보안 비밀 버전을 업데이트해도 보안 비밀 ETag에 영향을 미치지 않으며 그 반대도 마찬가지입니다.

작업 없는 리소스 업데이트는 리소스 ETag도 업데이트합니다. 예를 들어 다음 시나리오를 고려해 보세요. 호출자는 자신이 알지 못하는 상태에서 이미 사용 설정된 보안 비밀 버전을 사용 설정하도록 요청을 실행합니다. 요청이 성공적으로 처리되고 버전 상태는 변경되지 않지만 버전 ETag가 변경됩니다. 이전 ETag를 사용하는 다른 호출자가 동일한 버전을 사용 중지하려고 시도합니다. 수정된 ETag에서 사용 중지 요청 전에 버전을 사용 설정하려는 인텐트를 캡처했으므로 요청이 실패합니다.

리소스 etag는 리소스(보안 비밀 또는 SecretVersion)가 포함될 때마다 응답에 반환됩니다.

용도

중요: Compute Engine 또는 Google Kubernetes Engine에서 실행되는 워크로드에 Secret Manager를 사용하려면 기본 인스턴스 또는 노드에 cloud-platform OAuth 범위가 있어야 합니다. 자세한 내용은 Secret Manager API 액세스를 참조하세요.

ETag로 보안 비밀 삭제

보안 비밀을 삭제할 때 etag를 사용하는 방법을 보여줍니다. 다른 프로세스에 의해 보안 비밀이 수정된 경우 삭제 작업이 실패합니다.

gcloud

명령줄에서 Secret Manager를 사용하려면 먼저 Google Cloud CLI 버전 338.0.0 이상을 설치하거나 업그레이드합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

etag에는 둘러싸인 따옴표를 포함해야 합니다. 예를 들어 etag 값이 "abc"이면 셸 이스케이프 처리된 값은 "\"abc\""입니다.

gcloud beta secrets delete "SECRET_ID" \
    --etag "ETAG"

다른 보안 비밀 변형 작업 중에 etag를 지정할 수도 있습니다.

API

이 예시에서는 curl을 사용하여 API를 사용하는 방법을 보여줍니다. gcloud auth print-access-token을 사용하여 액세스 토큰을 생성할 수 있습니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

etag는 URL 쿼리 문자열의 일부로 지정되며 URL로 인코딩되어야 합니다. 예를 들어 etag 값이 "abc"이면 따옴표 문자는 %22로 인코딩되므로 URL로 인코딩된 값은 %22abc%22가 됩니다.

curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?etag=ETAG" \
    --request "DELETE" \
    --header "Authorization: Bearer ACCESS_TOKEN"

ETag로 보안 비밀 업데이트

보안 비밀을 업데이트할 때 etag를 사용하는 방법을 보여줍니다. 다른 프로세스에 의해 보안 비밀이 수정된 경우 업데이트 작업이 실패합니다.

gcloud

etag에는 둘러싸인 따옴표를 포함해야 합니다. 예를 들어 etag 값이 "abc"이면 셸 이스케이프 처리된 값은 "\"abc\""입니다.

gcloud beta secrets update "SECERT_ID" \
    --update-labels "foo=bar" \
    --etag "ETAG"

다른 보안 비밀 변형 작업 중에 etag를 지정할 수도 있습니다.

API

etag는 Secret에서 필드로 지정되며 둘러싸인 따옴표를 포함해야 합니다. 예를 들어 etag 값이 "abc"이면 JSON 이스케이프 처리된 값은 {"etag":"\"abc\""}입니다.

curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=labels" \
    --request "PATCH" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{"etag":"ETAG", "labels":{"foo": "bar"}}'

ETag로 보안 비밀 버전 업데이트

보안 비밀 버전을 업데이트할 때 etag를 사용하는 방법을 보여줍니다. 보안 비밀 버전이 다른 프로세스에 의해 수정된 경우 업데이트 작업이 실패합니다.

gcloud

etag에는 둘러싸인 따옴표를 포함해야 합니다. 예를 들어 etag 값이 "abc"이면 셸 이스케이프 처리된 값은 "\"abc\""입니다.

gcloud beta secrets versions disable "VERSION_ID" \
    --secret "SECRET_ID" \
    --etag "ETAG"

다른 보안 비밀 버전 변형 작업 중에 etag를 지정할 수도 있습니다.

API

etag는 SecretVersion에서 필드로 지정되며 둘러싸인 따옴표를 포함해야 합니다. 예를 들어 etag 값이 "abc"이면 JSON 이스케이프 처리된 값은 {"etag":"\"abc\""}입니다.

curl "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION_ID:disable" \
    --request "POST" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{"etag":"ETAG"}'

다음 단계

보안 비밀의 순환 일정 설정 방법 알아보기
보안 비밀 수정 방법 알아보기
보안 비밀에 알림을 설정하는 방법 알아보기