Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat dan mengelola anotasi

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

Ringkasan

Anda dapat menggunakan anotasi untuk menyimpan metadata kustom tentang secret. Misalnya, Anda mungkin ingin menganotasi secret dengan jalur tempat secret akan dipasang. Anotasi dapat berguna dengan cara berikut:

Untuk mengategorikan secret berdasarkan tujuan, lingkungan (pengembangan, staging, produksi), atau tingkat sensitivitas. Hal ini mempermudah penelusuran, pemfilteran, dan pengelolaan secret dalam Secret Manager.
Untuk menunjukkan format atau struktur tertentu dari nilai secret, yang membantu beban kerja menafsirkannya dengan benar.
Untuk memberikan petunjuk tentang cara menggunakan secret atau pertimbangan khusus untuk penanganannya.

Misalnya, jika 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 secret, lingkungannya, dan siapa yang bertanggung jawab untuknya. 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) di secret, 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 pada 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

Buka halaman Secret Manager di konsol Google Cloud.

Buka Secret Manager
Di halaman Secret Manager, klik Buat secret.
Di halaman Buat secret, masukkan nama untuk secret di kolom Nama.
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.
Buka bagian Annotations, lalu klik Add annotation.
Masukkan kunci dan nilai yang sesuai.
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
KEY: kunci anotasi
VALUE: nilai yang sesuai dari kunci anotasi

Jalankan perintah berikut:

Linux, macOS, atau 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

Respons berisi secret dan anotasi.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations

Isi JSON permintaan:

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

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login , atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI . Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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.googleapis.com/v1/projects/PROJECT_ID/secrets/SECRET_ID?updateMask=annotations"

PowerShell

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login . Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

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.googleapis.com/v1/projects/PROJECT_ID/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 secret. Anda tidak dapat mengulangi kunci dalam secret yang sama.
Kunci harus antara 1 dan 63 karakter.
Kunci harus memiliki encoding UTF-8 maksimum 128 byte.
Kunci harus diawali dan diakhiri dengan karakter alfanumerik.
Kunci dapat memiliki tanda pisah, garis bawah, dan titik di antara karakter alfanumerik.
Total ukuran kunci dan nilai anotasi harus kurang dari 16 KiB.

Mengedit anotasi

Untuk mengedit anotasi, gunakan salah satu metode berikut:

Konsol

Buka halaman Secret Manager di konsol Google Cloud.

Buka Secret Manager
Cari secret dalam daftar, lalu klik menu Actions yang terkait dengan secret tersebut. Di menu Tindakan, klik Edit.
Di halaman Edit secret, buka bagian Annotations. Di sini, Anda dapat mengubah nilai anotasi yang ada, menghapus anotasi, atau menambahkan anotasi baru.
Setelah melakukan perubahan, klik Perbarui secret.

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
KEY: kunci anotasi
VALUE: nilai yang sesuai dari kunci anotasi

Jalankan perintah berikut:

Linux, macOS, atau 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

Respons akan mengedit secret dan anotasi.

Menghapus anotasi tertentu

Untuk menghapus anotasi, gunakan perintah berikut:

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

Menghapus semua anotasi

Untuk menghapus semua anotasi, gunakan perintah berikut:

gcloud secrets update SECRET_ID --clear-annotations

REST

Untuk menghapus semua anotasi, gunakan perintah berikut:

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/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 secret, gunakan salah satu metode berikut:

Konsol

Buka halaman Secret Manager di konsol Google Cloud.

Buka Secret Manager
Di halaman Secret Manager, klik secret yang anotasi-nya ingin Anda lihat.
Halaman detail secret akan terbuka. Klik tab Ringkasan. Di sini, Anda dapat melihat anotasi yang dilampirkan ke secret. Kunci tercantum di kolom kiri, sedangkan 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

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

gcloud secrets describe SECRET_ID

Windows (PowerShell)

gcloud secrets describe SECRET_ID

Windows (cmd.exe)

gcloud secrets describe SECRET_ID

Respons berisi secret dan anotasi.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/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.googleapis.com/v1/projects/PROJECT_ID/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 selanjutnya

Pelajari cara mengelola akses ke secret.
Pelajari cara menyiapkan jadwal rotasi untuk secret.
Pelajari cara menyiapkan notifikasi pada secret.