Membuat dan mengelola anotasi

Halaman ini menjelaskan cara menambahkan anotasi ke secret regional serta cara mengedit dan melihat anotasi ini.

Ringkasan

Anda dapat menggunakan anotasi untuk menyimpan metadata kustom tentang secret. Misalnya, Anda mungkin ingin memberi anotasi pada secret dengan jalur tempat secret akan di-mount. Anotasi dapat berguna dengan cara berikut:

  • Untuk mengategorikan secret berdasarkan tujuan, lingkungan (pengembangan, staging, produksi), atau tingkat sensitivitasnya. Hal ini mempermudah penelusuran, pemfilteran, dan pengelolaan secret dalam Secret Manager.

  • Untuk menunjukkan format atau struktur spesifik dari nilai rahasia, yang membantu beban kerja menafsirkannya dengan benar.

  • Untuk memberikan petunjuk tentang cara menggunakan secret atau pertimbangan khusus untuk penanganannya.

Misalnya, jika Anda memiliki secret yang berisi sandi database, Anda dapat menambahkan anotasi seperti berikut:

  • environment:production

  • purpose:database_access

  • owner:database_team

Anotasi ini memudahkan identifikasi tujuan rahasia, lingkungannya, dan siapa yang bertanggung jawab atas rahasia tersebut. Selain itu, workload yang mengakses secret ini dapat menggunakan anotasi untuk mengonfirmasi bahwa workload tersebut menggunakan sandi yang tepat untuk lingkungan produksi.

Anotasi tidak sama dengan label. Label digunakan untuk mengurutkan, memfilter, dan mengelompokkan resource, sedangkan anotasi digunakan untuk menyimpan metadata arbitrer yang tidak mengidentifikasi pada secret. Ada batasan karakter dan panjang karakter saat menentukan metadata dalam label. Metadata dalam anotasi dapat berukuran kecil atau besar, terstruktur atau tidak terstruktur, dan dapat menyertakan karakter yang tidak diizinkan oleh label.

Peran yang diperlukan

  • Menambahkan anotasi pada secret dan memperbarui anotasi memerlukan peran Admin Secret Manager (roles/secretmanager.admin) pada secret, project, folder, atau organisasi.

  • Untuk melihat anotasi, Anda memerlukan peran Secret Manager Viewer (roles/secretmanager.viewer) pada rahasia, project, folder, atau organisasi.

Peran Identity and Access Management (IAM) tidak dapat diberikan pada versi rahasia. Lihat Kontrol akses dengan IAM untuk mengetahui informasi selengkapnya.

Menambahkan anotasi ke secret

Anda dapat menambahkan anotasi saat membuat secret baru atau memperbarui secret yang ada. Metadata dalam anotasi disimpan sebagai key-value pair. Untuk menambahkan anotasi, gunakan salah satu metode berikut:

Konsol

  1. Di konsol Google Cloud , buka halaman Secret Manager.

    Buka Secret Manager

  2. Di halaman Secret Manager, klik tab Regional secrets, lalu klik Create regional secret.

  3. Di halaman Buat secret regional, masukkan nama untuk secret di kolom Nama.

  4. Masukkan nilai untuk secret (misalnya, abcd1234). Anda juga dapat mengupload file teks yang berisi nilai secret menggunakan opsi Upload file. Tindakan ini akan otomatis membuat versi secret.

  5. Pilih lokasi tempat Anda ingin menyimpan rahasia regional dari daftar Region.

  6. Buka bagian Anotasi, lalu klik Tambahkan anotasi.

  7. Masukkan kunci dan nilai yang sesuai.

  8. Klik Buat secret.

gcloud

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • SECRET_ID: ID secret atau ID yang memenuhi syarat sepenuhnya untuk secret
  • LOCATION: Google Cloud lokasi secret
  • KEY: kunci anotasi
  • VALUE: nilai yang sesuai dari kunci anotasi

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

Respons berisi rahasia dan anotasi.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION: Google Cloud lokasi secret
  • PROJECT_ID: Google Cloud project ID
  • SECRET_ID: ID secret atau ID yang memenuhi syarat sepenuhnya untuk secret
  • KEY: kunci anotasi
  • VALUE: nilai yang sesuai dari kunci anotasi

Metode HTTP dan URL: 

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

Isi JSON permintaan: 

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

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

Anda akan melihat respons JSON seperti berikut:

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

Untuk menambahkan anotasi ke secret yang ada, lihat bagian Mengedit anotasi dalam dokumen ini.

Kunci anotasi memiliki persyaratan berikut:

  • Kunci harus unik untuk rahasia. Anda tidak dapat mengulang kunci yang sama dalam secret yang sama.

  • Kunci harus memiliki panjang antara 1 dan 63 karakter.

  • Kunci harus memiliki encoding UTF-8 dengan ukuran maksimum 128 byte.

  • Kunci harus diawali dan diakhiri dengan karakter alfanumerik.

  • Kunci dapat memiliki tanda hubung, garis bawah, dan titik di antara karakter alfanumerik.

  • Ukuran total kunci dan nilai anotasi harus kurang dari 16 KiB.

Mengedit anotasi

Untuk mengedit anotasi, gunakan salah satu metode berikut:

Konsol

  1. Di konsol Google Cloud , buka halaman Secret Manager.

    Buka Secret Manager

  2. Di halaman Secret Manager, klik tab Regional secrets.

  3. Cari secret dalam daftar, lalu klik menu Tindakan yang terkait dengan secret tersebut. Di menu Tindakan, klik Edit.

  4. Di halaman Edit secret, buka bagian Anotasi. Di sini, Anda dapat mengubah nilai anotasi yang ada, menghapus anotasi, atau menambahkan anotasi baru.

  5. Setelah Anda melakukan perubahan, klik Perbarui rahasia.

gcloud

Mengedit anotasi yang ada

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • SECRET_ID: ID secret atau ID yang memenuhi syarat sepenuhnya untuk secret
  • LOCATION: Google Cloud lokasi secret
  • KEY: kunci anotasi
  • VALUE: nilai yang sesuai dari kunci anotasi

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

Respons mengedit secret dan anotasi.

Menghapus anotasi tertentu

Untuk menghapus anotasi, gunakan perintah berikut:

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

Menghapus semua anotasi

Untuk menghapus semua anotasi, gunakan perintah berikut:

gcloud secrets update SECRET_ID --location=LOCATION --clear-annotations

REST

Untuk menghapus semua anotasi, gunakan perintah berikut:

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION: Google Cloud lokasi secret
  • PROJECT_ID: Google Cloud project ID
  • SECRET_ID: ID secret atau ID yang memenuhi syarat sepenuhnya untuk secret

Metode HTTP dan URL: 

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

Isi JSON permintaan: 

{'annotations': {}}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=annotations" | Select-Object -Expand Content

Anda akan melihat respons JSON seperti berikut:

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

Melihat anotasi

Untuk melihat anotasi yang dilampirkan ke rahasia, gunakan salah satu metode berikut:

Konsol

  1. Di konsol Google Cloud , buka halaman Secret Manager.

    Buka Secret Manager

  2. Di halaman Secret Manager, klik tab Regional secrets, lalu klik secret yang anotasinya ingin Anda lihat.

  3. Halaman detail rahasia akan terbuka. Klik tab Ringkasan. Di sini Anda dapat melihat anotasi yang dilampirkan ke rahasia. Kunci dicantumkan di kolom kiri sementara nilai ditampilkan di kolom kanan.

gcloud

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

  • SECRET_ID: ID secret atau ID yang memenuhi syarat sepenuhnya untuk secret
  • LOCATION: Google Cloud lokasi secret

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (PowerShell)

gcloud secrets describe SECRET_ID --location=LOCATION

Windows (cmd.exe)

gcloud secrets describe SECRET_ID --location=LOCATION

Respons berisi rahasia dan anotasi.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • LOCATION: Google Cloud lokasi secret
  • PROJECT_ID: Google Cloud project ID
  • SECRET_ID: ID secret atau ID yang memenuhi syarat sepenuhnya untuk secret

Metode HTTP dan URL: 

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

Isi JSON permintaan: 

{}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

PowerShell

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID" | Select-Object -Expand Content

Anda akan melihat respons JSON yang mirip dengan berikut ini:

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

Langkah berikutnya