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.
-
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
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": "\"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.
-
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.
-
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.