주석 만들기 및 관리

이 페이지에서는 보안 비밀에 주석을 추가하고 이러한 주석을 수정 및 확인하는 방법을 설명합니다.

개요

주석을 사용하면 보안 비밀에 대한 커스텀 메타데이터를 저장할 수 있습니다. 예를 들어 보안 비밀을 마운트할 경로에 보안 비밀을 주석으로 추가할 수 있습니다. 주석은 다음과 같은 경우에 유용할 수 있습니다.

목적, 환경(개발, 스테이징, 프로덕션), 민감도 수준에 따라 보안 비밀을 분류합니다. 이렇게 하면 Secret Manager 내에서 보안 비밀 검색, 필터링, 구성을 쉽게 수행할 수 있습니다.
워크로드에서 올바르게 해석할 수 있도록 보안 비밀 값의 특정 형식 또는 구조를 표시합니다.
보안 비밀의 사용 방법에 대한 힌트 또는 취급에 관한 특별한 고려사항을 제공합니다.

예를 들어 데이터베이스 비밀번호가 포함된 보안 비밀의 경우 다음과 같은 주석을 추가할 수 있습니다.

environment:production
purpose:database_access
owner:database_team

이러한 주석을 사용하면 보안 비밀의 목적, 환경, 책임자를 쉽게 식별할 수 있습니다. 또한 이 보안 비밀에 액세스하는 워크로드는 주석을 이용해서 프로덕션 환경에 대해 올바른 비밀번호를 사용 중인지 확인할 수 있습니다.

주석은 라벨과 같지 않습니다. 라벨은 리소스를 정렬, 필터링, 그룹화하는 데 사용되는 반면 주석은 임의의 식별되지 않는 메타데이터를 보안 비밀에 저장하는 데 사용됩니다. 라벨에 메타데이터를 지정할 때 문자 및 문자 길이에 제한이 있습니다. 주석의 메타데이터는 크거나 작거나 구조화되거나 구조화되지 않았을 수 있으며 라벨에 허용되지 않는 문자를 포함할 수 있습니다.

필요한 역할

보안 비밀에 주석을 추가하고 주석을 업데이트하려면 보안 비밀, 프로젝트, 폴더 또는 조직의 Secret Manager 관리자 역할(roles/secretmanager.admin)이 필요합니다.
주석을 보려면 보안 비밀, 프로젝트, 폴더 또는 조직의 Secret Manager 뷰어 역할(roles/secretmanager.viewer)이 필요합니다.

보안 비밀 버전에는 Identity and Access Management(IAM) 역할을 부여할 수 없습니다. 자세한 내용은 IAM으로 액세스 제어를 참조하세요.

보안 비밀에 주석 추가

새 보안 비밀을 만들거나 기존 보안 비밀을 업데이트할 때 주석을 추가할 수 있습니다. 주석의 메타데이터는 키-값 쌍으로 저장됩니다. 주석을 추가하려면 다음 방법 중 하나를 사용합니다.

콘솔

Google Cloud 콘솔에서 Secret Manager 페이지로 이동합니다.

Secret Manager로 이동
Secret Manager 페이지에서 보안 비밀 만들기를 클릭합니다.
보안 비밀 만들기 페이지에서 이름 필드에 보안 비밀 이름을 입력합니다.
보안 비밀 값을 입력합니다(예: abcd1234). 또한 파일 업로드 옵션을 사용하여 보안 비밀 값이 포함된 텍스트 파일을 업로드할 수 있습니다. 이 작업은 보안 비밀 버전을 자동으로 만듭니다.
주석 섹션으로 이동한 후 주석 추가를 클릭합니다.
키와 해당 값을 입력합니다.
보안 비밀 만들기를 클릭합니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

SECRET_ID: 보안 비밀의 ID
KEY: 주석 키입니다.
VALUE: 주석 키의 상응 값입니다.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud secrets create SECRET_ID \
    --set-annotations= KEY1=VAL1,KEY2=VAL2

Windows(PowerShell)

gcloud secrets create SECRET_ID `
    --set-annotations= KEY1=VAL1,KEY2=VAL2

Windows(cmd.exe)

gcloud secrets create SECRET_ID ^
    --set-annotations= KEY1=VAL1,KEY2=VAL2

응답에는 보안 비밀과 주석이 포함됩니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
SECRET_ID: 보안 비밀의 ID
KEY: 주석 키입니다.
VALUE: 주석 키의 상응 값입니다.

HTTP 메서드 및 URL:

PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations

JSON 요청 본문:

{'annotations': {'KEY1': 'VALUE1', 'KEY2': 'VALUE2' }}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations"

PowerShell

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

C#

이 코드를 실행하려면 먼저 C# 개발 환경을 설정하고 Secret Manager C# SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.


using Google.Api.Gax.ResourceNames;
using Google.Cloud.SecretManager.V1;
using System.Collections.Generic;

public class CreateSecretWithAnnotationsSample
{
    public Secret CreateSecretWithAnnotations(
      string projectId = "my-project", string secretId = "my-secret", string annotationKey = "my-annotation-key", string annotationValue = "my-annotation-value")
    {
        // Create the client.
        SecretManagerServiceClient client = SecretManagerServiceClient.Create();

        // Build the parent resource name.
        ProjectName projectName = new ProjectName(projectId);

        // Build the secret.
        Secret secret = new Secret
        {
            Replication = new Replication
            {
                Automatic = new Replication.Types.Automatic(),
            },
            Annotations =
            {
              { annotationKey, annotationValue }
            },
        };

        // Call the API.
        Secret createdSecret = client.CreateSecret(projectName, secretId, secret);
        return createdSecret;
    }
}

Go

이 코드를 실행하려면 먼저 Go 개발 환경을 설정하고 Secret Manager Go SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

import (
	"context"
	"fmt"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
)

// createSecretWithAnnotations creates a new secret with the given name and annotations.
func createSecretWithAnnotations(w io.Writer, parent, secretId string) error {
	// parent := "projects/my-project"
	// id := "my-secret"

	annotationKey := "annotationkey"
	annotationValue := "annotationvalue"

	ctx := context.Background()
	client, err := secretmanager.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create secretmanager client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &secretmanagerpb.CreateSecretRequest{
		Parent:   parent,
		SecretId: secretId,
		Secret: &secretmanagerpb.Secret{
			Replication: &secretmanagerpb.Replication{
				Replication: &secretmanagerpb.Replication_Automatic_{
					Automatic: &secretmanagerpb.Replication_Automatic{},
				},
			},
			Annotations: map[string]string{
				annotationKey: annotationValue,
			},
		},
	}

	result, err := client.CreateSecret(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to create secret: %w", err)
	}
	fmt.Fprintf(w, "Created secret with annotations: %s\n", result.Name)
	return nil
}

Java

이 코드를 실행하려면 먼저 자바 개발 환경을 설정하고 Secret Manager 자바 SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

import com.google.cloud.secretmanager.v1.ProjectName;
import com.google.cloud.secretmanager.v1.Replication;
import com.google.cloud.secretmanager.v1.Secret;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import java.io.IOException;

public class CreateSecretWithAnnotations {

  public static void createSecretWithAnnotations() throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // This is the id of the GCP project
    String projectId = "your-project-id";
    // This is the id of the secret to act on
    String secretId = "your-secret-id";
    // This is the key of the annotation to be added
    String annotationKey = "your-annotation-key";
    // This is the value of the annotation to be added
    String annotationValue = "your-annotation-value";
    createSecretWithAnnotations(projectId, secretId, annotationKey, annotationValue);
  }

  // Create a secret with annotations.
  public static Secret createSecretWithAnnotations(
       String projectId,
       String secretId,
       String annotationKey,
       String annotationValue
  ) throws IOException {

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (SecretManagerServiceClient client = SecretManagerServiceClient.create()) {

      // Build the name.
      ProjectName projectName = ProjectName.of(projectId);

      // Build the secret to create with labels.
      Secret secret =
          Secret.newBuilder()
                  .setReplication(
                  Replication.newBuilder()
                      .setAutomatic(Replication.Automatic.newBuilder().build())
                      .build())
                  .putAnnotations(annotationKey, annotationValue)
              .build();

      // Create the secret.
      Secret createdSecret = client.createSecret(projectName, secretId, secret);
      System.out.printf("Created secret %s\n", createdSecret.getName());
      return createdSecret;
    }
  }
}

Node.js

이 코드를 실행하려면 먼저 Node.js 개발 환경을 설정하고 Secret Manager Node.js SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const parent = 'projects/my-project';
// const secretId = 'my-secret';
// const annotationKey = 'exampleannotationkey';
// const annotationValue = 'exampleannotationvalue';

// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Instantiates a client
const client = new SecretManagerServiceClient();

async function createSecretWithAnnotations() {
  const [secret] = await client.createSecret({
    parent: parent,
    secretId: secretId,
    secret: {
      replication: {
        automatic: {},
      },
      annotations: {
        [annotationKey]: annotationValue,
      },
    },
  });

  console.log(`Created secret ${secret.name}`);
}

createSecretWithAnnotations();

PHP

이 코드를 실행하려면 먼저 Google Cloud에서 PHP 사용하는 방법을 알아보고 Secret Manager PHP SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

// Import the Secret Manager client library.
use Google\Cloud\SecretManager\V1\CreateSecretRequest;
use Google\Cloud\SecretManager\V1\Replication;
use Google\Cloud\SecretManager\V1\Replication\Automatic;
use Google\Cloud\SecretManager\V1\Secret;
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;

/**
 * @param string $projectId       Your Google Cloud Project ID (e.g. 'my-project')
 * @param string $secretId        Your secret ID (e.g. 'my-secret')
 * @param string $annotationKey   Your annotation key (e.g. 'annotation-key')
 * @param string $annotationValue Your annotation value (e.g. 'annotation-value')
 */
function create_secret_with_annotations(string $projectId, string $secretId, string $annotationKey, string $annotationValue): void
{
    // Create the Secret Manager client.
    $client = new SecretManagerServiceClient();

    // Build the resource name of the parent project.
    $parent = $client->projectName($projectId);

    $secret = new Secret([
        'replication' => new Replication([
            'automatic' => new Automatic(),
        ]),
    ]);

    // set the annoation.
    $annotation = [$annotationKey => $annotationValue];
    $secret->setAnnotations($annotation);

    // Build the request.
    $request = CreateSecretRequest::build($parent, $secretId, $secret);

    // Create the secret.
    $newSecret = $client->createSecret($request);

    // Print the new secret name.
    printf('Created secret %s with annotations', $newSecret->getName());
}

Python

이 코드를 실행하려면 먼저 Python 개발 환경을 설정하고 Secret Manager Python SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

import argparse
import typing

# Import the Secret Manager client library.
from google.cloud import secretmanager


def create_secret_with_annotations(
    project_id: str,
    secret_id: str,
    annotations: typing.Dict[str, str],
) -> secretmanager.Secret:
    """
    Create a new secret with the given name. A secret is a logical wrapper
    around a collection of secret versions. Secret versions hold the actual
    secret material.
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent project.
    parent = f"projects/{project_id}"

    # Create the secret.
    response = client.create_secret(
        request={
            "parent": parent,
            "secret_id": secret_id,
            "secret": {
                "replication": {"automatic": {}},
                "annotations": annotations,
            },
        }
    )

    # Print the new secret name.
    print(f"Created secret: {response.name}")

    return response

Ruby

이 코드를 실행하려면 먼저 Ruby 개발 환경을 설정하고 Secret Manager Ruby SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

require "google/cloud/secret_manager"

##
# Create a secret with annotation.
#
# @param project_id [String] Your Google Cloud project (e.g. "my-project")
# @param secret_id [String] Your secret name (e.g. "my-secret")
# @param annotation_key [String] Your annotation key (e.g. "my-annotation-key")
# @param annotation_value [String] Your annotation value (e.g. "my-annotation-value")
#
def create_secret_with_annotations project_id:, secret_id:, annotation_key:, annotation_value:
  # Create a Secret Manager client.
  client = Google::Cloud::SecretManager.secret_manager_service

  # Build the resource name of the parent project.
  parent = client.project_path project: project_id

  # Create the secret.
  secret = client.create_secret(
    parent:    parent,
    secret_id: secret_id,
    secret:    {
      replication: {
        automatic: {}
      },
      annotations: {
        annotation_key => annotation_value
      }
    }
  )

  # Print the new secret name.
  puts "Created secret: #{secret.name}"
end

기존 보안 비밀에 주석을 추가하려면 이 문서의 주석 수정 섹션을 참조하세요.

주석 키의 요구사항은 다음과 같습니다.

키는 보안 비밀마다 고유해야 합니다. 동일한 비밀에서 키를 반복할 수 없습니다.
키는 1~63자(영문 기준)여야 합니다.
키는 최대 128바이트의 UTF-8 인코딩을 포함해야 합니다.
키는 영숫자 문자로 시작하고 끝나야 합니다.
영숫자 문자 사이에는 대시, 밑줄, 마침표를 사용할 수 있습니다.
주석 키와 값의 총 크기는 16KiB 미만이어야 합니다.

주석 수정

주석을 수정하려면 다음 방법 중 하나를 사용합니다.

콘솔

Google Cloud 콘솔에서 Secret Manager 페이지로 이동합니다.

Secret Manager로 이동
목록에서 보안 비밀을 찾고 해당 보안 비밀과 연결된 작업 메뉴를 클릭합니다. 작업 메뉴에서 수정을 클릭합니다.
보안 비밀 수정 페이지에서 주석 섹션으로 이동합니다. 여기에서 기존 주석의 값을 변경하거나, 주석을 삭제하거나, 새 주석을 추가할 수 있습니다.
항목을 변경한 후 보안 비밀 업데이트를 클릭합니다.

gcloud

기존 주석 수정

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

SECRET_ID: 보안 비밀의 ID
KEY: 주석 키입니다.
VALUE: 주석 키의 상응 값입니다.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud secrets update SECRET_ID --update-annotations= KEY=VAL

Windows(PowerShell)

gcloud secrets update SECRET_ID --update-annotations= KEY=VAL

Windows(cmd.exe)

gcloud secrets update SECRET_ID --update-annotations= KEY=VAL

응답은 보안 비밀과 주석을 수정합니다.

특정 주석 삭제

주석을 삭제하려면 다음 명령어를 사용합니다.

gcloud secrets update SECRET_ID --remove-annotations= KEY=VAL

모든 주석 지우기

모든 주석을 지우려면 다음 명령어를 사용합니다.

gcloud secrets update SECRET_ID --clear-annotations

REST

모든 주석을 지우려면 다음 명령어를 사용합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
SECRET_ID: 보안 비밀의 ID

HTTP 메서드 및 URL:

PATCH https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations

JSON 요청 본문:

{'annotations': {}}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dd90b37e7\""
}

C#

이 코드를 실행하려면 먼저 C# 개발 환경을 설정하고 Secret Manager C# SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.


using Google.Api.Gax.ResourceNames;
using Google.Cloud.SecretManager.V1;
using Google.Protobuf.Collections;
using Google.Protobuf.WellKnownTypes;

public class EditSecretAnnotationsSample
{
    public Secret EditSecretAnnotations(
      string projectId = "my-project", string secretId = "my-secret", string annotationKey = "my-annotation-key", string annotationValue = "my-annotation-value")
    {
        // Create the client.
        SecretManagerServiceClient client = SecretManagerServiceClient.Create();

        // Build the secretName with the fields.
        SecretName secretName = new SecretName(projectId, secretId);

        // Get the exisitng secret.
        Secret secret = client.GetSecret(secretName);

        // Edit the Secret annotations
        secret.Annotations[annotationKey] = annotationValue;

        // Build the field mask.
        FieldMask fieldMask = FieldMask.FromString("annotations");

        // Call the API.
        Secret updatedSecret = client.UpdateSecret(secret, fieldMask);
        return updatedSecret;
    }
}

Go

이 코드를 실행하려면 먼저 Go 개발 환경을 설정하고 Secret Manager Go SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

import (
	"context"
	"fmt"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
	"google.golang.org/genproto/protobuf/field_mask"
)

// editSecretAnnotation updates the annotations about an existing secret.
// If the annotation key exists, it updates the annotation, otherwise it creates a new one.
func editSecretAnnotation(w io.Writer, secretName string) error {
	// name := "projects/my-project/secrets/my-secret"

	annotationKey := "annotationkey"
	annotationValue := "updatedannotationvalue"

	ctx := context.Background()
	client, err := secretmanager.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create secretmanager client: %w", err)
	}
	defer client.Close()

	// Build the request to get the secret.
	req := &secretmanagerpb.GetSecretRequest{
		Name: secretName,
	}

	result, err := client.GetSecret(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to get secret: %w", err)
	}

	annotations := result.Annotations

	annotations[annotationKey] = annotationValue

	// Build the request to update the secret.
	update_req := &secretmanagerpb.UpdateSecretRequest{
		Secret: &secretmanagerpb.Secret{
			Name:        secretName,
			Annotations: annotations,
		},
		UpdateMask: &field_mask.FieldMask{
			Paths: []string{"annotations"},
		},
	}

	update_result, err := client.UpdateSecret(ctx, update_req)
	if err != nil {
		return fmt.Errorf("failed to update secret: %w", err)
	}
	fmt.Fprintf(w, "Updated secret: %s\n", update_result.Name)
	return nil
}

Java

import com.google.cloud.secretmanager.v1.Secret;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretName;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.FieldMaskUtil;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

public class EditSecretAnnotations {

  public static void editSecretAnnotations() throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // This is the id of the GCP project
    String projectId = "your-project-id";
    // This is the id of the secret to act on
    String secretId = "your-secret-id";
    // This is the key of the annotation to be added/updated
    String annotationKey = "your-annotation-key";
    // This is the value of the annotation to be added/updated
    String annotationValue = "your-annotation-value";
    editSecretAnnotations(projectId, secretId, annotationKey, annotationValue);
  }

  // Update an existing secret, by creating a new annotation or updating an existing annotation.
  public static Secret editSecretAnnotations(
       String projectId,
       String secretId,
       String annotationKey,
       String annotationValue
  ) throws IOException {

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (SecretManagerServiceClient client = SecretManagerServiceClient.create()) {
      // Build the name.
      SecretName secretName = SecretName.of(projectId, secretId);

      // Get the existing secret
      Secret existingSecret = client.getSecret(secretName);

      Map<String, String> existingAnnotationsMap = 
                      new HashMap<String, String>(existingSecret.getAnnotationsMap());

      // Add a new annotation key and value.
      existingAnnotationsMap.put(annotationKey, annotationValue);

      // Build the updated secret.
      Secret secret =
          Secret.newBuilder()
              .setName(secretName.toString())
              .putAllAnnotations(existingAnnotationsMap)
              .build();

      // Build the field mask.
      FieldMask fieldMask = FieldMaskUtil.fromString("annotations");

      // Update the secret.
      Secret updatedSecret = client.updateSecret(secret, fieldMask);
      System.out.printf("Updated secret %s\n", updatedSecret.getName());

      return updatedSecret;
    }
  }
}

Node.js

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const name = 'projects/my-project/secrets/my-secret';
// const annotationKey = 'updatedannotationkey';
// const annotationValue = 'updatedannotationvalue';

// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Instantiates a client
const client = new SecretManagerServiceClient();

async function getSecret() {
  const [secret] = await client.getSecret({
    name: name,
  });

  return secret;
}

async function editSecretAnnotations() {
  const oldSecret = await getSecret();
  oldSecret.annotations[annotationKey] = annotationValue;
  const [secret] = await client.updateSecret({
    secret: {
      name: name,
      annotations: oldSecret.annotations,
    },
    updateMask: {
      paths: ['annotations'],
    },
  });

  console.info(`Updated secret ${secret.name}`);
}

editSecretAnnotations();

PHP

// Import the Secret Manager client library.
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;
use Google\Cloud\SecretManager\V1\GetSecretRequest;
use Google\Cloud\SecretManager\V1\UpdateSecretRequest;
use Google\Protobuf\FieldMask;

/**
 * @param string $projectId       Your Google Cloud Project ID (e.g. 'my-project')
 * @param string $secretId        Your secret ID (e.g. 'my-secret')
 * @param string $annotationKey   Your annotation key (e.g. 'annotation-key')
 * @param string $annotationValue Your annotation value (e.g. 'annotation-value')
 */
function edit_secret_annotations(string $projectId, string $secretId, string $annotationKey, string $annotationValue): void
{
    // Create the Secret Manager client.
    $client = new SecretManagerServiceClient();

    // Build the resource name of the parent project.
    $name = $client->secretName($projectId, $secretId);

    // Build the request.
    $request = GetSecretRequest::build($name);

    // get the secret.
    $getSecret = $client->getSecret($request);

    // get the annotations
    $annotations = $getSecret->getAnnotations();

    // update the annotation - need to create a new annotations map with the updated values
    $newAnnotations = [];
    foreach ($annotations as $key => $value) {
        $newAnnotations[$key] = $value;
    }
    $newAnnotations[$annotationKey] = $annotationValue;
    $getSecret->setAnnotations($newAnnotations);

    // set the field mask
    $fieldMask = new FieldMask();
    $fieldMask->setPaths(['annotations']);

    // build the secret
    $request = new UpdateSecretRequest();
    $request->setSecret($getSecret);
    $request->setUpdateMask($fieldMask);

    // update the secret
    $updateSecret = $client->updateSecret($request);

    // print the updated secret
    printf('Updated secret %s annotations' . PHP_EOL, $updateSecret->getName());
}

Python


import argparse
from typing import Dict

# Import the Secret Manager client library.
from google.cloud import secretmanager


def edit_secret_annotations(
    project_id: str, secret_id: str, new_annotations: Dict[str, str]
) -> secretmanager.UpdateSecretRequest:
    """
    Create or update a annotation on an existing secret.
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret.
    name = client.secret_path(project_id, secret_id)

    # Get the secret.
    response = client.get_secret(request={"name": name})

    annotations = response.annotations

    # Update the annotations
    for annotation_key in new_annotations:
        annotations[annotation_key] = new_annotations[annotation_key]

    # Update the secret.
    secret = {"name": name, "annotations": annotations}
    update_mask = {"paths": ["annotations"]}
    response = client.update_secret(
        request={"secret": secret, "update_mask": update_mask}
    )

    # Print the new secret name.
    print(f"Updated secret: {response.name}")

    return response

Ruby

require "google/cloud/secret_manager"

##
# Edits a secret annotations.
#
# @param project_id [String] Your Google Cloud project (e.g. "my-project")
# @param secret_id [String] Your secret name (e.g. "my-secret")
# @param annotation_key [String] Your annotation key (e.g. "my-annotation-key")
# @param annotation_value [String] Your annotation value (e.g. "my-annotation-value")
#
def edit_secret_annotations project_id:, secret_id:, annotation_key:, annotation_value:
  # Create a Secret Manager client.
  client = Google::Cloud::SecretManager.secret_manager_service

  # Build the resource name of the secret.
  name = client.secret_path project: project_id, secret: secret_id

  # Get the existing secret.
  existing_secret = client.get_secret name: name

  # Get the existing secret's annotations.
  existing_secret_annotations = existing_secret.annotations.to_h

  # Add a new annotation key and value.
  existing_secret_annotations[annotation_key] = annotation_value

  # Updates the secret.
  secret = client.update_secret(
    secret: {
      name: name,
      annotations: existing_secret_annotations
    },
    update_mask: {
      paths: ["annotations"]
    }
  )

  # Print the updated secret name and annotations.
  puts "Updated secret: #{secret.name}"
  puts "New updated annotations: #{secret.annotations}"
end

주석 보기

보안 비밀에 연결된 주석을 보려면 다음 방법 중 하나를 사용합니다.

콘솔

Google Cloud 콘솔에서 Secret Manager 페이지로 이동합니다.

Secret Manager로 이동
Secret Manager 페이지에서 주석을 보려는 보안 비밀을 클릭합니다.
보안 비밀 세부정보 페이지가 열립니다. 개요 탭을 클릭합니다. 여기에서 보안 비밀에 연결된 주석을 볼 수 있습니다. 키는 왼쪽 열에 나열되고 값은 오른쪽 열에 표시됩니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

SECRET_ID: 보안 비밀의 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud secrets describe SECRET_ID

Windows(PowerShell)

gcloud secrets describe SECRET_ID

Windows(cmd.exe)

gcloud secrets describe SECRET_ID

응답에는 보안 비밀과 주석이 포함됩니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
SECRET_ID: 보안 비밀의 ID

HTTP 메서드 및 URL:

GET https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID

JSON 요청 본문:

{}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID"

PowerShell

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-09-02T07:14:00.281541Z",
  "etag": "\"16211dcd99c386\"",
  "annotations": {
    "key1": "value1",
    "key2": "value2"
  }
}

C#

이 코드를 실행하려면 먼저 C# 개발 환경을 설정하고 Secret Manager C# SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.


using Google.Api.Gax.ResourceNames;
using Google.Cloud.SecretManager.V1;
using Google.Protobuf.Collections;
using Google.Protobuf.WellKnownTypes;
using System;

public class ViewSecretAnnotationsSample
{
    public Secret ViewSecretAnnotations(
      string projectId = "my-project", string secretId = "my-secret")
    {
        // Create the client.
        SecretManagerServiceClient client = SecretManagerServiceClient.Create();

        // Build the resource name.
        SecretName secretName = new SecretName(projectId, secretId);

        // Fetch the secret.
        Secret secret = client.GetSecret(secretName);

        // Get the secret's annotations.
        MapField<string, string> secretAnnotations = secret.Annotations;

        // Print the annotations.
        foreach (var annotation in secret.Annotations)
        {
            Console.WriteLine($"Annotation Key: {annotation.Key}, Annotation Value: {annotation.Value}");
        }
        return secret;
    }
}

Go

이 코드를 실행하려면 먼저 Go 개발 환경을 설정하고 Secret Manager Go SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.

import (
	"context"
	"fmt"
	"io"

	secretmanager "cloud.google.com/go/secretmanager/apiv1"
	"cloud.google.com/go/secretmanager/apiv1/secretmanagerpb"
)

// viewSecretAnnotations gets annotations with the given secret.
func viewSecretAnnotations(w io.Writer, secretName string) error {
	// name := "projects/my-project/secrets/my-secret"

	ctx := context.Background()
	client, err := secretmanager.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create secretmanager client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &secretmanagerpb.GetSecretRequest{
		Name: secretName,
	}

	result, err := client.GetSecret(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to get secret: %w", err)
	}

	annotations := result.Annotations
	fmt.Fprintf(w, "Found secret %s\n", result.Name)

	for key, value := range annotations {
		fmt.Fprintf(w, "Annotations key %s : Annotations Value %s", key, value)
	}
	return nil
}

Java

import com.google.cloud.secretmanager.v1.Secret;
import com.google.cloud.secretmanager.v1.SecretManagerServiceClient;
import com.google.cloud.secretmanager.v1.SecretName;
import java.io.IOException;
import java.util.Map;

public class ViewSecretAnnotations {

  public static void viewSecretAnnotations() throws IOException {
    // TODO(developer): Replace these variables before running the sample.

    // This is the id of the GCP project
    String projectId = "your-project-id";
    // This is the id of the secret whose annotations to view
    String secretId = "your-secret-id";
    viewSecretAnnotations(projectId, secretId);
  }

  // View the annotations of an existing secret.
  public static Map<String, String> viewSecretAnnotations(
      String projectId,
      String secretId
  ) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (SecretManagerServiceClient client = SecretManagerServiceClient.create()) {
      // Build the name.
      SecretName secretName = SecretName.of(projectId, secretId);

      // Create the secret.
      Secret secret = client.getSecret(secretName);

      Map<String, String> annotations = secret.getAnnotationsMap();

      System.out.printf("Secret %s \n", secret.getName());

      for (Map.Entry<String, String> annotation : annotations.entrySet()) {
        System.out.printf("Annotation key : %s, Annotation Value : %s\n", 
            annotation.getKey(), annotation.getValue());
      }

      return secret.getAnnotationsMap();
    }
  }
}

Node.js

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const parent = 'projects/my-project/secrets/my-secret';

// Imports the Secret Manager library
const {SecretManagerServiceClient} = require('@google-cloud/secret-manager');

// Instantiates a client
const client = new SecretManagerServiceClient();

async function viewSecretAnnotations() {
  const [secret] = await client.getSecret({
    name: name,
  });

  for (const key in secret.annotations) {
    console.log(`${key} : ${secret.annotations[key]}`);
  }
}

viewSecretAnnotations();

PHP

// Import the Secret Manager client library.
use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient;
use Google\Cloud\SecretManager\V1\GetSecretRequest;

/**
 * @param string $projectId Your Google Cloud Project ID (e.g. 'my-project')
 * @param string $secretId  Your secret ID (e.g. 'my-secret')
 */
function view_secret_annotations(string $projectId, string $secretId): void
{
    // Create the Secret Manager client.
    $client = new SecretManagerServiceClient();

    // Build the resource name of the parent project.
    $name = $client->secretName($projectId, $secretId);

    // Build the request.
    $request = GetSecretRequest::build($name);

    // get the secret.
    $getSecret = $client->getSecret($request);

    // get the annotations
    $annotations = $getSecret->getAnnotations();

    // print the secret name
    printf('Get secret %s with annotation:' . PHP_EOL, $getSecret->getName());
    // we can even loop over all the annotations
    foreach ($annotations as $key => $val) {
        printf("\t$key: $val" . PHP_EOL);
    }
}

Python

import argparse

# Import the Secret Manager client library.
from google.cloud import secretmanager


def view_secret_annotations(project_id: str, secret_id: str) -> None:
    """
    List all secret annotations in the given secret.
    """
    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent secret.
    name = client.secret_path(project_id, secret_id)

    response = client.get_secret(request={"name": name})

    print(f"Got secret {response.name} with annotations :")
    for key in response.annotations:
        print(f"{key} : {response.annotations[key]}")

Ruby

require "google/cloud/secret_manager"

##
# View annotations of a secret.
#
# @param project_id [String] Your Google Cloud project (e.g. "my-project")
# @param secret_id [String] Your secret name (e.g. "my-secret")
#
def view_secret_annotations project_id:, secret_id:
  # Create a Secret Manager client.
  client = Google::Cloud::SecretManager.secret_manager_service

  # Build the resource name of the secret.
  name = client.secret_path project: project_id, secret: secret_id

  # Get the existing secret.
  existing_secret = client.get_secret name: name

  # Get the existing secret's annotations.
  existing_secret_annotations = existing_secret.annotations.to_h

  # Print the secret name and the annotations.
  puts "Secret: #{existing_secret.name}"
  existing_secret_annotations.each do |key, value|
    puts "Annotation Key: #{key}, Annotation Value: #{value}"
  end
end

다음 단계

보안 비밀 액세스 관리 방법 알아보기
보안 비밀의 순환 일정 설정 방법 알아보기
보안 비밀에 알림을 설정하는 방법 알아보기

주석 만들기 및 관리 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

개요

필요한 역할

보안 비밀에 주석 추가

콘솔

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

curl

PowerShell

C#

Go

Java

Node.js

PHP

Python

Ruby

주석 수정

콘솔

gcloud

기존 주석 수정

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

특정 주석 삭제

모든 주석 지우기

REST

curl

PowerShell

C#

Go

Java

Node.js

PHP

Python

Ruby

주석 보기

콘솔

gcloud

Linux, macOS 또는 Cloud Shell

Windows(PowerShell)

Windows(cmd.exe)

REST

curl

PowerShell

C#

Go

Java

Node.js

PHP

Python

Ruby

다음 단계

주석 만들기 및 관리