# alibabacloud-kms-agent

**Repository Path**: aliyun/alibabacloud-kms-agent

## Basic Information

- **Project Name**: alibabacloud-kms-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-08
- **Last Updated**: 2025-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Alibaba Cloud KMS Agent

阿里云 KMS Agent 是一个HTTP代理服务, 可以部署在本地开发环境、虚拟机、容器环境，为业务程序访问阿里云KMS服务提供一种更便捷的方式。
阿里云 KMS Agent 目前提供凭据检索功能，KMS Agent 从阿里云KMS服务获取凭据并将其提供给应用程序， 简化了应用程序访问直接访问KMS服务的身份认证以及缓存管理工作。

阿里云 KMS Agent 使用阿里云 [默认凭证链](
https://help.aliyun.com/zh/sdk/developer-reference/v2-manage-go-access-credentials?spm=a2c4g.11186623.help-menu-262060.d_1_9_1_2.33a45c4fAoE9MW&scm=20140722.H_2579531._.OR_help-T_cn~zh-V_1#3ca299f04bw3c)
访问KMS服务，支持设置阿里云AK/SK、STSToken、ECSRAMRole、OIDC等认证方式。
同时，KMS Agent 支持设置公共网关以及专属私网网关 2 条链路访问阿里云KMS服务。

KMS Agent 分为 HTTPServer、缓存、KMS服务、日志管理 4 部分， 可以通过配置文件对这 4 部分进行配置。
KMS Agent在 HTTPServer里默认开启针对服务端请求伪造(SSRF)的保护，开启后应用程序需要携带SSRF Token 才能访问Agent获取凭据。

## 编译二进制
 基于源码安装您要先安装golang环境，然后下载源码进行编译。

### 安装Go环境
参考： https://go.dev/doc/install

### 下载源码
```bash
git clone https://github.com/aliyun/alibabacloud-kms-agent
```
### 编译
#### Mac下编译Linux, Windows平台的64位可执行程序
```bash
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build .
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build .
```
#### Linux下编译Mac, Windows平台的64位可执行程序
```bash
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build .
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build .
```
#### Windows下编译Mac, Linux平台的64位可执行程序
```bash
SET CGO_ENABLED=0 SET GOOS=darwin SET GOARCH=amd64 go build .
SET CGO_ENABLED=0 SET GOOS=linux SET GOARCH=amd64 go build  .
```

##  部署 Agent
### Agent 配置说明
```toml
# 全部配置项
[Server]
# 可选, 不填Agent默认开放端口2025，默认监听本机地址 127.0.0.1:2025
HttpPort = 2025
# 可选，不填默认值 ["X-KMS-Token", "X-Vault-Token"]
# Agent 会检查 SSRFHeaders 列表 Header 里所携带的SSRF Token
SSRFHeaders = ["X-KMS-Token"]
# 可选，不填默认值 ["KMS_TOKEN", "KMS_SESSION_TOKEN", "KMS_CONTAINER_AUTHORIZATION_TOKEN"]，变量值可以是具体值，也可以是文件路径如 file:///var/run/awssmatoken.
# Agent从SSRFEnvVariables 列表中的 Env 解析出 SSRF Token，与请求 Header 里携带的Token比较，一致才允许访问
SSRFEnvVariables = ["KMS_TOKEN"]
# 可选, 不填默认值 "/v1/"。
# 基于路径访问时，可以通过该参数设置URI前缀
PathPrefix = "/v1/"
# 可选, 默认值 800
# Agent能够并发处理的最多请求数
MaxConn = 800
# 可选, 不填默认值 0
# 0表示凭据内容按照KMS GetSecretvalue 格式返回；1表示凭据内容按照 AWS SeceretManager GetSecretvalue 格式返回; 2表示以 key-value 格式返回
ResponseType = 0
# 可选, 默认值 true
# 当访问阿里云KMS服务失败而缓存凭据也过期时，IgnoreTransientErrors为true会返回过期凭据，IgnoreTransientErrors为false会返回失败
IgnoreTransientErrors = true

[Kms]
# 可选, 不填默认地址cn-hangzhou
# 访问KMS的所在的地域
Region = "cn-hangzhou"
# 可选, 不填默认是阿里云SDK寻址逻辑
# 可以通过设置 Endpoint，设置从公共网关还是专属网关访问阿里云KMS服务。
#Endpoint = <instanceId>.cryptoservice.kms.aliyuncs.com # KMS实例专属网关地址
Endpoint = "kms.cn-hangzhou.aliyuncs.com"  # KMS公共网关地址
# 可选，不填默认为空，仅访问KMS实例网关需要CA。
# Agent已经内置了部分地域实例网关的CA证书，alibaba-kms-agent/internal/kms/privateca.go 里已经内置CA的地域无需再设置该参数。
CaFilePath = ""

[Cache]
# 可选, 缓存类型，不填默认为 InMemory，当前Agent仅支持内存型缓存
CacheType = "InMemory"
# 可选, 不填默认最多缓存1000个凭据。当 CacheSize=0 时是禁用缓存，每次请求都访问阿里云KMS服务
CacheSize = 1000
# 可选, 不填缓存有效时间默认是 300s.
TtlSeconds = 300
# 可选, 不填默认 false.
# 当缓存凭据到了CacheSize上限，EnableLRU为false按照缓存开始时间删除最早存入缓存凭据，EnableLRU为ture则按照最近一次使用时间删除最不常用的凭据。
EnableLRU = false

[Log]
# 可选, 不填默认日志级别 debug, 还可以选择 info、warn、error
LogLevel = "debug"
# 可选, 不填默认日志存储是应用启动目录下的 ./logs/
LogPath = "./logs/"
# 可选, 不填默认单个日志大小 100M
MaxSize = 100
# 可选, 不填默认保留 2 个日志文件数量
MaxBackups = 2
```

### 本地部署
#### 1. 设置环境变量
```bash
export ALIBABA_CLOUD_ACCESS_KEY_ID=***
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=***
export KMS_TOKEN='file:///var/run/kmstoken'
```

#### 2. 设置 SSRF Token
```bash
# 生成一个随机的 SSRF token，并存入本机文件 /var/run/kmstoken
./alibabacloud-kms-agent token /var/run/kmstoken
```

#### 3. 修改配置文件
参考Agent配置说明，按需修改配置文件。
```toml
# config demo
[Server]
HttpPort = 2025

[AliyunKMS]
Region = "cn-hangzhou"

[Cache]
CacheType = "InMemory"
CacheSize = 1000
TtlSeconds = 300

[Log]
LogLevel = "Debug"
LogPath = "./logs/"
MaxSize = 100
MaxBackups = 2
```

##### 4. 启动Agent
二进制与配置文件放到相同目录下，启动进程。
```bash
./alibabacloud-kms-agent agent ./config.toml
```

### Linux 环境部署
将 kms agent 部署到 Linux 服务器上并托管给 systemd。
#### 1. 设置身份凭证
如果部署环境是阿里云ECS，推荐使用ECSRamRole的安全认证方式访问阿里云KMS服务，当然也可以使用环境变量、Credentials配置文件等认证方式。
为 ECS 设置 实例RAM 角色参考：[实例RAM角色](https://help.aliyun.com/zh/ecs/user-guide/attach-an-instance-ram-role-to-an-ecs-instance?spm=a2c4g.11174283.help-menu-25365.d_4_11_3.15cade53RS4CV9&scm=20140722.H_61175._.OR_help-T_cn~zh-V_1)

#### 2. 安装并启动Agent
进入到目录
```bash
cd alibabacloud-kms-agent/deploy/linux
```
确认同级目录已经存下 alibabacloud-kms-agent、config.toml、 alibabacloud-kms-agent.service，执行安装脚本。
```bash
sudo bash -x ./install.sh
```
执行后会创建 SSRF token 文件、同时将 alibabacloud-kms-agent 进程托管给systemd，并启动。
需改 alibabacloud-kms-agent.service User 字段，将运行Agent的系统用户修改agent运行用户，否则应用程序没权限读取SSRF token，无法的访问Agent。


### Sidecar容器部署
使用 docker-compose 工具编排Agent sidecar容器与应用容器。
#### 1. 创建容器Dockerfile
创建 Agent Sidecar容器以及有业务容器的Dockerfile文件。参考deploy/docker-compose/目录下 Dockerfile.agent 和 Dockerfile.app.
#### 2. 编写容器编排文件
进入到 deploy/docker-compose/, 参考deploy/docker-compose/目录下 docker-compose.yaml
#### 3. 编译并启动进行容器
将alibabacloud-kms-agent，config.toml，Dockerfile.agent，Dockerfile.app 放到和docker-compose.yml文件同一个目录. 执行：
```bash
docker-compose up --build
```
#### 4. 登录上app容器，在容器内访问agent.

### 部署到阿里云ACK容器服务
将 KMS Agent 作为sidecar容器与应用程序容器一起部署到阿里云的ACK容器服务。
#### 1. 设置身份凭证
在阿里云ACK容器服务推荐使用RRSA(RAM Roles for Service Accounts) 访问KMS，当然也可以使用环境变量、Credentials配置文件等认证方式。
为ACK集群开启和配置RRSA参考：[通过RRSA配置ServiceAccount的RAM权限实现Pod权限隔离](https://help.aliyun.com/zh/ack/ack-managed-and-ack-dedicated/user-guide/use-rrsa-to-authorize-pods-to-access-different-cloud-services?spm=a2c4g.11186623.0.0.7dcc2da79k2DVz)

#### 2. 编译Agent sidecar容器镜像
进入 deploy/ack/agent 文件夹, 创建Dockerfile，编译Agent容器镜像。
```bash
cd alibabacloud-kms-agent/deploy/ack/agent
# 这里测试上传到了阿里云镜像仓库
docker build -t registry.cn-hangzhou.aliyuncs.com/<namespace>/<repository> .
docker push registry.cn-hangzhou.aliyuncs.com/<namespace>/<repository>:kmsagent-1.0
```
#### 3. 编译应用容器镜像
进入 deploy/ack/app 文件夹, 创建Dockerfile，编译Agent容器镜像。
```bash
cd alibabacloud-kms-agent/deploy/ack/app
docker build -t registry.cn-hangzhou.aliyuncs.com/<namespace>/<repository> .
docker push registry.cn-hangzhou.aliyuncs.com/<namespace>/<repository>:app-1.0
```

#### 4. 编写 k8s yaml 资源文件，部署容器
参考 alibabacloud-kms-agent/deploy/ack/demo.yaml 文件，将应用和Agent容器一起部署到阿里云ACK。

## 检索凭据
### 使用 Curl  
```bash
 # 从文件读取 token
 curl -v -H "X-Vault-Token:$(</var/run/kmstoken)" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
 
 # 直接写 token
 curl -v -H "X-Vault-Token:<token>" 'http://localhost:2025/secretsmanager/get?secretId=<SecretId>'
```

### 使用 Go 代码
```go
package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	url := fmt.Sprintf("http://localhost:2025/secretsmanager/get?secretId=%s", "agent-test")

	token, err := ioutil.ReadFile("/var/run/kmstoken")
	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))
}
```