Saat menjalankan workload terkontainerisasi di Container Service for Kubernetes (ACK), hardcoding AccessKey dalam kode aplikasi menimbulkan risiko keamanan dan menyulitkan rotasi kredensial. Akses cloud-native KMS menghilangkan risiko ini dengan menyuntikkan KMS Agent Sidecar ke dalam pod, sehingga aplikasi dapat mengambil kredensial yang dikelola di KMS secara aman melalui permintaan HTTP lokal.
Cara kerja
Fitur akses cloud-native Key Management Service (KMS) menyediakan alur kerja terpandu untuk instalasi dan konfigurasi komponen. Saat sebuah pod di kluster Container Service for Kubernetes (ACK) Anda mengirim permintaan HTTP, KMS Agent—yang secara otomatis disuntikkan ke dalam pod melalui komponen Helm ack-kms-agent-webhook-injector—menerima permintaan tersebut dan melakukan autentikasi menggunakan JWT OpenID Connect (OIDC) atau Peran Resource Access Management (RAM). Setelah KMS memverifikasi izin, kredensial dikembalikan melalui Agent tersebut. Agent menyimpan cache kredensial secara lokal untuk mengurangi permintaan berulang dan menurunkan latensi pengambilan kredensial.
Lingkup
Batasan jenis kluster ACK: kluster ACK yang dikelola dan kluster khusus, kluster ACK Serverless, dan Buat kluster ACS didukung.
CatatanUntuk kluster khusus ACK dan kluster terdaftar ACK, lihat Sebarkan KMS Agent di ACK untuk mengambil rahasia.
Batasan wilayah: Kluster ACK dan instans KMS harus berada di wilayah yang sama.
Batasan kinerja: Setiap pod menjalankan kontainer KMS Agent Sidecar secara independen. Jika bisnis Anda menyebarkan sejumlah besar pod dan permintaan STS Token melebihi 500 per menit selama autentikasi, pembatasan laju akan dipicu, sehingga memengaruhi operasi normal KMS Agent.
Aktifkan RRSA untuk kluster ACK Anda
Aktifkan saat pembuatan kluster
Saat membuat kluster ACK yang dikelola dan kluster ACK Edge, Anda dapat mengaktifkan RRSA pada bagian Advanced Options (Optional) dalam konfigurasi kluster.
Aktifkan di halaman informasi kluster
-
Masuk ke Konsol ACK. Di panel navigasi kiri, klik Clusters.
-
Di halaman Clusters, klik nama kluster Anda. Di panel navigasi kiri, klik Cluster Information.
Di tab Basic Information, pada bagian Security and Auditing, klik Enable di samping RRSA OIDC.
Di kotak dialog Enable RRSA, klik OK.
CatatanDi halaman Basic Information, ketika status kluster berubah dari Updating menjadi Running, fitur RRSA telah diaktifkan untuk kluster tersebut.
Instal KMS Agent
Langkah 1: Buat namespace dan akun layanan (opsional)
Namespace mempartisi kluster ACK Anda menjadi ruang virtual yang terisolasi secara logis untuk lingkungan berbeda seperti development, testing, dan production. Aplikasi di namespace berbeda tidak dapat mengakses resource satu sama lain secara default. Jika Anda sudah memiliki namespace dan akun layanan untuk aplikasi bisnis Anda, lewati langkah ini.
Buat namespace.
Buat namespace menggunakan file YAML. Contoh berikut menggunakan
app1-namespace.yamluntuk membuat namespace bernamaapp1-dev:apiVersion: v1 kind: Namespace metadata: name: app1-devJalankan perintah berikut untuk membuat namespace:
kubectl apply -f app1-namespace.yamlVerifikasi bahwa namespace telah dibuat. Jika output mencakup
app1-dev, namespace berhasil dibuat.kubectl get namespaces
Buat akun layanan.
Buat akun layanan menggunakan file YAML. Contoh berikut menggunakan
app1-serviceaccount.yamluntuk membuat akun layanan bernamaapp1-servicedi namespaceapp1-devyang telah Anda buat pada langkah sebelumnya:apiVersion: v1 kind: ServiceAccount metadata: name: app1-service namespace: app1-devJalankan perintah berikut untuk membuat akun layanan:
kubectl apply -f app1-serviceaccount.yamlVerifikasi bahwa akun layanan telah dibuat. Jika output mencakup
app1-service, akun layanan berhasil dibuat.kubectl get serviceaccount -n app1-dev
Langkah 2: Konfigurasi izin
Akses cloud-native KMS mendukung dua metode autentikasi berikut.
OpenID Connect (OIDC) direkomendasikan untuk sebagian besar skenario karena konfigurasinya lebih sederhana. Gunakan Peran RAM jika Anda perlu menggunakan kembali kebijakan peran RAM yang sudah ada atau memerlukan akses lintas akun.
Metode autentikasi | Fitur |
OIDC (ACK) | Kluster ACK melakukan autentikasi menggunakan JWT standar OpenID Connect (OIDC). Agent secara otomatis memperoleh token akun layanan untuk membuktikan identitas pod kepada KMS. Tidak diperlukan peran RAM, dan konfigurasinya paling sederhana. |
Peran RAM | Mengakses KMS menggunakan kredensial sementara STS dari peran RAM. Metode ini cocok untuk skenario di mana Anda ingin menggunakan kembali pengaturan peran RAM yang sudah ada. |
OIDC (ACK)
Di panel konfigurasi yang muncul, atur Authentication Method ke OIDC (ACK).
Konfigurasikan parameter berikut:
Parameter
Deskripsi
Namespace
Nama namespace tempat pod berada, misalnya
app1-dev.ServiceAccount
Akun layanan yang digunakan oleh pod, misalnya
app1-service.PodNamePrefix
Awalan nama pod. Setelah parameter ini dikonfigurasi, hanya pod dengan nama yang sesuai dengan awalan yang diizinkan lolos verifikasi. Jika tidak dikonfigurasi, hanya namespace dan akun layanan yang diverifikasi.
Scope
Metode untuk mengakses KMS. Nilai yang valid:
Specified KMS Instance: Mengakses kunci dan kredensial di instans KMS tertentu melalui endpoint instans.
Shared KMS Gateway: Mengakses kredensial melalui endpoint layanan KMS.
Application Access Point Name
Nama kustom titik akses aplikasi (kredensial akses) untuk identifikasi dan manajemen.
Policy Name
Nama kustom kebijakan RAM. Buat kebijakan langsung pada langkah ini tanpa perlu membuatnya terlebih dahulu di konsol RAM.
RBAC Permissions
Tingkat izin RBAC (Role-Based Access Control), yang menentukan izin operasi kredensial untuk aplikasi.
Jika Specified KMS Instance dipilih untuk scope:
CryptoServiceKeyUser: Mengizinkan penggunaan kunci di instans KMS untuk enkripsi kredensial.
CryptoServiceSecretUser: Mengizinkan penggunaan kredensial di instans KMS dan mendukung API kredensial untuk instans tersebut.
Jika Shared KMS Gateway dipilih untuk scope: Hanya SecretUser yang didukung, yang mengizinkan penggunaan semua kredensial di bawah akun saat ini.
Accessible Resources
Pilih kredensial dan kunci (digunakan untuk enkripsi dan dekripsi kredensial) yang perlu diakses oleh aplikasi.
PentingJika Anda memilih beberapa kredensial dan panjang total nama kredensial melebihi batas, error "parameter invalid" akan dikembalikan. Dalam kasus ini, gunakan wildcard untuk menentukan kredensial yang diizinkan, misalnya
secret/rds-ibm*, yang mengizinkan akses ke kredensial dengan awalanrds-ibm.Description
Opsional. Deskripsi detail titik akses aplikasi. Panjang maksimum: 8.192 karakter.
Klik OK untuk melanjutkan.
Peran RAM
Konfirmasi bahwa kluster ACK dapat mengakses STS
Tambahkan endpoint layanan STS sts-intl.aliyuncs.com ke daftar putih egress kluster ACK agar tidak diblokir oleh firewall atau aturan pertahanan jaringan lainnya.
CatatanGunakan RAM Role untuk KMS Agent harus memanggil API STS
AssumeRoleWithOIDCguna memperoleh kredensial sementara. Jika endpoint diblokir, Agent tidak dapat merefresh kredensial sementara.Dapatkan informasi penyedia identitas.
Klik nama kluster target untuk membuka halaman detail.
Di tab Basic Information, arahkan pointer ke label Enabled di samping RRSA (RAM Roles for Service Accounts) OIDC pada bagian Security and Auditing untuk melihat informasi URL dan ARN penyedia. Format URL penyedia adalah
https://oidc-ack-<region>.oss-<region>.aliyuncs.com/<cluster_id>, dan format ARN penyedia adalahacs:ram::<account_id>:oidc-provider/ack-rrsa-<cluster_id>.
Buat Peran RAM.
Pilih IdP sebagai tipe entitas tepercaya, lalu klik Switch to Editor.
Di bagian Visual Editor, konfigurasikan item berikut:
Konfigurasi dasar
Parameter
Deskripsi
Effect
Pilih Allow.
Action
Biarkan nilai default
sts:AssumeRole.Condition
Tambahkan kondisi dengan kunci
oidc:sub, operatorStringEquals, dan nilaisystem:serviceaccount:<namespace>:<ServiceAccountName>, di mananamespacedanServiceAccountNamesesuai dengan namespace dan akun layanan pod yang menjalankan workload.Konfigurasikan principal sebagai berikut:
Pilih Identity Provider sebagai Principal, lalu klik Edit di bawahnya.
Di halaman konfigurasi Identity Provider, konfigurasikan parameter berikut dan klik OK.
Parameter
Deskripsi
IdP Type
Pilih OIDC.
Identity Provider
Pilih penyedia identitas yang secara otomatis dibuat oleh kluster ACK setelah RRSA diaktifkan:
ack-rrsa-<cluster_id>.CatatanJangan kelirukan nilai
audiencests.aliyuncs.comdalam kebijakan kepercayaan peran RAM dan templat pod dengan endpoint layanan STS yang digunakan oleh KMS Agent. Nilaiaudienceadalah client ID dari penyedia identitas OIDC yang dibuat setelah RRSA diaktifkan. Nilai ini tidak menentukan endpoint yang digunakan KMS Agent untuk memanggil STS.
Setelah konfigurasi selesai, klik OK untuk mengatur nama peran (misalnya,
app1-rrsa), lalu klik OK.
Buat kebijakan dan sambungkan ke Peran RAM. Untuk informasi selengkapnya, lihat Buat kebijakan kustom dan Sambungkan kebijakan ke Peran RAM.
Klik Create Policy, pilih Script Editor, lalu konfigurasikan kebijakan menggunakan contoh berikut.
CatatanDalam contoh ini, kebijakan diberi nama
dev-role-for-rrsa-kms-policydan hanya mengizinkan akses ke kredensial dengan tagenv:app1.{ "Version": "1", "Statement": [ { "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:GetSecretValue" ], "Resource": "*", "Condition": { "StringEqualsIgnoreCase": { "kms:tag/secret": [ "app1" ] } } } ] }Kembali ke daftar kebijakan, temukan kebijakan target, lalu klik Attach to Identity di kolom Actions.
Di bagian Principal, pilih Peran RAM yang telah Anda buat, lalu klik Confirm.
Langkah 3: Instal ack-kms-agent-webhook-injector
Di halaman Helm, klik Deploy. Konfigurasikan bagian Basic Information, lalu klik Next.
Parameter
Deskripsi
Application Name
Gunakan nama aplikasi default
ack-kms-agent-webhook-injector.Namespace
Gunakan namespace chart default
kube-system. Instal sekali per kluster ACK; tidak perlu menginstal berulang kali.Source
Default: Marketplace. Parameter ini tidak dapat diubah.
Chart
Cari dan pilih
ack-kms-agent-webhook-injector.Saat dialog konfirmasi muncul, verifikasi informasi dan klik Yes.
Di halaman Parameters, konfigurasikan parameter berdasarkan metode autentikasi yang Anda pilih di Langkah 2.
OIDC (ACK): Pertahankan konfigurasi default.
Peran RAM: Biarkan
agent.auth.roleArnkosong, dan aturagent.auth.roleArnMappingke<Namespace>:<ServiceAccountName>:<RAM Role ARN>. Contoh berikut menggunakan data yang dibuat di Langkah 2:CatatanNamespacedanServiceAccountNamesesuai dengan namespace dan akun layanan pod yang menjalankan workload.RAM Role ARNdapat dilihat di halaman detail Peran RAM.agent: auth: roleArn: roleArnMapping: app1-dev:app1-service: acs:ram::190325303126****:role/app1-rrsa
Setelah konfigurasi selesai, klik OK. Anda akan diarahkan ke halaman detail aplikasi.
Langkah 4: Suntikkan Agent Sidecar
Tambahkan anotasi pod: Atur kunci anotasi ke
kms-agent-webhook-injector/injectdan nilainya ketrue.Beralih ke namespace tempat workload Anda berjalan, lalu tambahkan anotasi pod ke Deployment tersebut.
PentingUntuk metode autentikasi Peran RAM, modifikasi konfigurasi YAML Deployment dan atur parameter
ServiceAccountNameke nama akun layanan pod yang menjalankan workload (misalnya,app1-service). Untuk metode autentikasi OIDC (ACK), tidak diperlukan modifikasi.Buat Deployment baru
Create from Image
Klik Create from Image di atas daftar Deployment dan konfigurasikan parameter.
Saat mengonfigurasi Advanced, buka bagian Labels and Annotations dan tambahkan anotasi pod: masukkan
kms-agent-webhook-injector/injectdi kolom Name dantruedi kolom Value.Klik Create untuk menyelesaikan.
Create from YAML
Klik Create from YAML di atas daftar Deployment.
Edit file YAML dan tambahkan
kms-agent-webhook-injector/inject: "true"di bawahspec.template.metadata.annotations(buat bagian ini jika belum ada).Klik Create untuk menyelesaikan.
Modifikasi Deployment yang sudah ada
Temukan workload target dan klik Actions > Details.
Di halaman detail, klik Edit YAML di pojok kanan atas.
Tambahkan
kms-agent-webhook-injector/inject: "true"di bawahspec.template.metadata.annotations(buat bagian ini jika belum ada).Klik Update dan tunggu hingga workload siap.
Verifikasi penyuntikan
Di tab Pods, periksa kolom Image. KMS Agent muncul tersuntik ke dalam pod sebagai Sidecar.
CatatanSebuah pod mungkin disuntik dengan KMS Agent dua kali. Hal ini terjadi karena kontainer init digunakan untuk inisialisasi. Kontainer init akan berhenti (Terminated) setelah inisialisasi selesai, dan tidak berdampak negatif pada aplikasi atau terus-menerus mengonsumsi sumber daya komputasi.
Integrasi aplikasi
Setelah Deployment Anda disuntik dengan KMS Agent, kontainer aplikasi dapat mengambil kredensial dari KMS melalui permintaan HTTP ke KMS Agent. Tidak perlu mengonfigurasi AccessKey dalam kode Anda. Contoh berikut menunjukkan cara mengambil kredensial. Ganti <SecretId> dengan nama kredensial aktual Anda.
KMS Agent hanya mendengarkan di 127.0.0.1, artinya hanya aplikasi atau proses di mesin yang sama yang dapat berkomunikasi dengannya. Perangkat jaringan eksternal tidak dapat terhubung. Alamat akses hanya mendukung localhost atau 127.0.0.1, bukan IP lokal aplikasi. Contoh berikut menggunakan localhost.
Selain metode akses KMS Agent, KMS juga mendukung akses melalui SDK. Untuk operasi spesifik, lihat Secrets Manager Client.
OIDC (ACK)
Menggunakan curl
Jalankan perintah berikut untuk mengambil kredensial:
# Baca token dari file, tentukan AapArn curl -v -H "X-KMS-Token:$(</var/run/kmstoken/token)" -H "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'Sintaks
$(<file)hanya didukung di shell seperti bash dan zsh. Jika image dasar Pod Anda menggunakan Alpine (shell default-nya adalah BusyBox ash) atau image lain yang shell default-nya tidak mendukung sintaks ini, gunakan perintah berikut sebagai gantinya:# Baca token dari file, tentukan AapArn (kompatibel dengan Alpine/BusyBox) curl -v -H "X-KMS-Token:$(cat /var/run/kmstoken/token)" -H "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
Menggunakan wget
Jalankan perintah berikut untuk mengambil kredensial:
# Baca token dari file, tentukan AapArn wget -q -O - --header "X-KMS-Token:$(</var/run/kmstoken/token)" --header "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'Sintaks
$(<file)hanya didukung di shell seperti bash dan zsh. Jika image dasar Pod Anda menggunakan Alpine (shell default-nya adalah ash) atau image lain yang shell default-nya tidak mendukung sintaks ini, gunakan perintah berikut sebagai gantinya:# Baca token dari file, tentukan AapArn (kompatibel dengan Alpine) wget -q -O - --header "X-KMS-Token:$(cat /var/run/kmstoken/token)" --header "AapArn:<AapArn>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
Contoh kode Go
Contoh berikut menunjukkan cara mengambil kredensial menggunakan Go:
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
// Anda dapat menentukan versionStage atau versionId untuk mengambil versi kredensial tertentu.
// Contoh berikut mengambil kredensial berdasarkan versionId:
// url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s&versionId=%s", "agent-test", "version-id")
aapArn := "acs:kms:cn-hangzhou:19*********224:applicationaccesspoint/****"
url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test")
token, err := ioutil.ReadFile("/var/run/kmstoken/token")
if err != nil {
fmt.Printf("error reading token file: %v\n", err)
}
req, err := http.NewRequest("GET", url, nil)
if err != nil {
fmt.Printf("error creating request: %v\n", err)
}
req.Header.Add("X-KMS-Token", string(token))
req.Header.Add("AapArn", aapArn)
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Printf("error sending request: %v \n", err)
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Printf("status code %d - %s \n", resp.StatusCode, string(body))
}Peran RAM
Menggunakan curl
Jalankan perintah berikut untuk mengambil kredensial:
# Baca token dari file curl -v -H "X-KMS-Token:$(</var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>' # Atau tulis token langsung curl -v -H "X-KMS-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'Sintaks
$(<file)hanya didukung di shell seperti bash dan zsh. Jika image dasar Pod Anda menggunakan Alpine (shell default-nya adalah BusyBox ash) atau image lain yang shell default-nya tidak mendukung sintaks ini, gunakan perintah berikut sebagai gantinya:# Baca token dari file (kompatibel dengan Alpine/BusyBox) curl -v -H "X-KMS-Token:$(cat /var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
Menggunakan wget
Jalankan perintah berikut untuk mengambil kredensial:
# Baca token dari file wget -q -O - --header "X-KMS-Token:$(</var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>' # Atau tulis token langsung wget -q -O - --header "X-KMS-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'Sintaks
$(<file)hanya didukung di shell seperti bash dan zsh. Jika image dasar Pod Anda menggunakan Alpine (shell default-nya adalah ash) atau image lain yang shell default-nya tidak mendukung sintaks ini, gunakan perintah berikut sebagai gantinya:# Baca token dari file (kompatibel dengan Alpine) wget -q -O - --header "X-KMS-Token:$(cat /var/run/kmstoken/token)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
Contoh kode Go
Contoh berikut menunjukkan cara mengambil kredensial menggunakan Go:
package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
// Anda dapat menentukan versionStage atau versionId untuk mengambil versi kredensial tertentu.
// Contoh berikut mengambil kredensial berdasarkan versionId:
// url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s&versionId=%s", "agent-test", "version-id")
url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test")
token, err := ioutil.ReadFile("/var/run/kmstoken/token")
if err != nil {
fmt.Printf("error reading token file: %v\n", err)
}
req, err := http.NewRequest("GET", url, nil)
if err != nil {
fmt.Printf("error creating request: %v\n", err)
}
req.Header.Add("X-KMS-Token", string(token))
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Printf("error sending request: %v \n", err)
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Printf("status code %d - %s \n", resp.StatusCode, string(body))
}Penagihan
Biaya sisi KMS:
Langganan: Beli instans KMS sebelum menggunakan KMS Agent. KMS Agent sendiri tidak menimbulkan biaya tambahan. Untuk informasi selengkapnya, lihat Langganan.
Pay-as-you-go: Selain biaya yang sudah Anda keluarkan, biaya QPS tambahan berlaku saat KMS Agent mengambil kredensial melalui panggilan API. Untuk informasi selengkapnya, lihat Pay-as-you-go.
Biaya sisi ACK:
Komponen ack-kms-agent-webhook-injector gratis. Anda mungkin mengalami biaya tambahan untuk sumber daya komputasi yang dikonsumsi oleh Sidecar dan workload Webhook yang disuntikkan.
Setelah menginstal komponen ack-kms-agent-webhook-injector, workload layanan Webhook dihasilkan, yang mengonsumsi sumber daya komputasi dan menimbulkan biaya. Batasi penggunaan CPU dan memori workload ini dalam file konfigurasi.
Saat Anda membuat atau memperbarui workload yang memenuhi syarat, ack-kms-agent-webhook-injector menyuntikkan KMS Agent sebagai Sidecar ke dalam kontainer. KMS Agent mengonsumsi sumber daya komputasi dan menimbulkan biaya.
Troubleshooting
Jika Anda mengalami masalah saat menginstal atau menggunakan KMS Agent, rujuk masalah umum berikut untuk troubleshooting.
Penyebab | Solusi |
Gagal menginstal Agent | Jalankan |
Jaringan tidak dapat dijangkau atau timeout | Pastikan kluster ACK dapat menjangkau layanan KMS. Jika Anda mengakses KMS melalui VPC, pastikan VPC tempat kluster ACK berada terhubung jaringan dengan instans KMS. |
KMS Agent gagal memperoleh kredensial sementara dari STS melalui | Lakukan troubleshooting sebagai berikut:
Catatan: Pembacaan sukses nilai rahasia yang di-cache tidak membuktikan bahwa rantai kredensial peran RAM dalam kondisi sehat. Verifikasi log untuk memastikan |
Izin tidak mencukupi | Periksa konfigurasi berikut:
|
Gagal menyuntikkan Agent | Periksa apakah komponen ack-kms-agent-webhook-injector terinstal dengan benar dan berjalan normal. Verifikasi bahwa anotasi pod |
RRSA tidak diaktifkan | Metode autentikasi OIDC (ACK) bergantung pada fitur RRSA (RAM Roles for Service Accounts). Di konsol ACK, buka modul keamanan dan audit kluster untuk mengaktifkan RRSA. Untuk langkah-langkah detail, lihat pengaturan penyedia identitas di tab Peran RAM pada Langkah 2. |