Key Management Service:Ikhtisar KMS Agent

Cara kerja

Agent menyimpan nilai rahasia dalam cache di memori dan memperbaruinya secara berkala berdasarkan Time To Live (TTL) yang Anda konfigurasikan. Saat sebuah aplikasi meminta rahasia:

1. Agent memvalidasi permintaan menggunakan file token Server-Side Request Forgery (SSRF).

2. Jika terdapat nilai cache yang valid dan belum kedaluwarsa, agent segera mengembalikannya (cache hit).

3. Jika tidak ada entri cache yang valid, agent meneruskan permintaan ke KMS. KMS memverifikasi identitas agent, mendekripsi rahasia, lalu mengembalikannya. Agent memperbarui cache dan mengembalikan nilai tersebut ke aplikasi (cache miss).

Diagram berikut menunjukkan kedua alur tersebut:

• Proses cache hit

• Proses cache miss (tidak ada cache atau cache kedaluwarsa)

Deploy agent bersama aplikasi Anda di server fisik, mesin virtual seperti Elastic Compute Service (ECS), atau kontainer seperti Pod Kubernetes. Untuk kode sumber dan panduan penerapan, lihat alibabacloud-kms-agent.

Arsitektur

Agent terdiri dari empat komponen: server HTTP, cache, klien KMS, dan log.

Konfigurasikan keempat komponen tersebut dalam satu file konfigurasi. File berikut menampilkan semua opsi yang tersedia beserta nilai default-nya:

# Semua item konfigurasi
[Server]
# Opsional, nilai default adalah 2025. Agent mendengarkan di 127.0.0.1:2025.
HttpPort = 2025
# Opsional, nilai default adalah ["X-KMS-Token", "X-Vault-Token"].
# Permintaan ke agent harus menyertakan header SSRF; permintaan tanpa header tersebut ditolak.
SSRFHeaders = ["X-KMS-Token"]
# Opsional, nilai default adalah ["KMS_TOKEN", "KMS_SESSION_TOKEN", "KMS_CONTAINER_AUTHORIZATION_TOKEN"].
# Nilainya dapat berupa string literal atau path file, misalnya file:///var/run/awssmatoken.
# Agent membaca token SSRF dari variabel lingkungan yang ditentukan dan membandingkannya
# dengan token dalam header permintaan aplikasi. Akses hanya diberikan jika sesuai.
SSRFEnvVariables = ["KMS_TOKEN"]
# Opsional, nilai default adalah "/v1/". Awalan URI untuk permintaan berbasis path.
PathPrefix = "/v1/"
# Opsional, nilai default adalah 800. Jumlah maksimum permintaan konkuren.
MaxConn = 800
# Opsional, nilai default adalah 0.
# 0: format respons KMS GetSecretValue
# 1: format respons AWS Secrets Manager GetSecretValue
# 2: struktur HashiCorp Vault KV
ResponseType = 0
# Opsional, nilai default adalah true.
# Jika true, agent mengembalikan nilai cache yang kedaluwarsa jika KMS sementara tidak dapat dijangkau.
IgnoreTransientErrors = true

[Kms]
# Opsional, nilai default adalah cn-hangzhou.
Region = "cn-hangzhou"
# Opsional, nilai default adalah kms.cn-hangzhou.aliyuncs.com.
# Mendukung titik akhir gateway bersama maupun gateway khusus.
Endpoint = "kms.cn-hangzhou.aliyuncs.com"

[Cache]
# Opsional, nilai default adalah InMemory. Saat ini hanya caching in-memory yang didukung.
CacheType = "InMemory"
# Opsional, nilai default adalah 1000. Jika diatur ke 0, caching dinonaktifkan dan setiap
# permintaan langsung dikirim ke KMS.
CacheSize = 1000
# Opsional, nilai default adalah 300s.
TtlSeconds = 300
# Opsional, nilai default adalah false.
# false: mengganti rahasia cache tertua saat cache penuh.
# true: mengganti rahasia yang paling jarang digunakan (LRU) berdasarkan frekuensi akses.
EnableLRU = false

[Log]
# Opsional, nilai default adalah Debug.
LogLevel = "Debug"
# Opsional, nilai default adalah ./logs/ relatif terhadap direktori startup aplikasi.
LogPath = "./logs/"
# Opsional, nilai default adalah 100 (MB). Ukuran maksimum per file log.
MaxSize = 100
# Opsional, nilai default adalah 2. Jumlah file log yang disimpan.
MaxBackups = 2

curl -s \
  -H "X-KMS-Token: $(cat /var/run/kmstoken)" \
  "http://127.0.0.1:2025/v1/<secret-name>"

with open("/var/run/kmstoken") as f:
    token = f.read().strip()

headers = {"X-KMS-Token": token}
response = requests.get("http://127.0.0.1:2025/v1/<secret-name>", headers=headers)
print(response.json())

Keamanan

Stabilitas

Agent dirancang agar tetap tersedia selama gangguan jaringan dan kegagalan sementara.

Pemeriksaan mandiri saat startup: Saat startup, agent memverifikasi konektivitas ke KMS. Jika verifikasi gagal, agent keluar alih-alih berjalan dalam kondisi terdegradasi.

Retry otomatis: Agent menggunakan logika retry bawaan Alibaba Cloud SDK (V2). Untuk respons HTTP 429 (pembatasan kecepatan) dan HTTP 500 (kesalahan server internal), agent akan mencoba ulang sebanyak 3 kali menggunakan metode exponential backoff untuk interval waktu.

Fallback cache kedaluwarsa: Saat IgnoreTransientErrors diaktifkan (nilai default), agent mengembalikan nilai cache terbaru jika KMS sementara tidak dapat dijangkau. Hal ini mencegah kegagalan aplikasi selama gangguan jaringan atau server berdurasi singkat.

Ketersediaan tinggi:

• Linux (systemd): systemd memantau proses agent dan secara otomatis merestart jika terjadi crash.

• Kubernetes (kontainer sidecar): Diterapkan sebagai init container, kegagalan agent akan memicu restart kontainer, sehingga menjamin stabilitas aplikasi.

KMS Agent vs. Secret Client

KMS Agent bertindak sebagai lapisan perantara — aplikasi mengakses rahasia melalui agent alih-alih memanggil KMS secara langsung. Secret Client mengintegrasikan SDK KMS ke setiap aplikasi. Pilih berdasarkan skala penerapan dan kebutuhan kontrol akses Anda.