# SPIRE Agent

```{toctree}
:maxdepth: 2

configuration
cli
workload-api
```

## 概述

SPIRE Agent 是部署在每个节点上的守护进程，负责：

- 向 SPIRE Server 证明自身身份
- 维护本地身份缓存
- 通过 Workload API 向工作负载提供身份
- 自动轮换 SVID

## 架构

```{mermaid}
graph TB
    subgraph "节点"
        Agent[SPIRE Agent]
        Cache[(本地缓存)]
        Socket[Unix Socket]
        WA[工作负载证明器]
        
        Agent --> Cache
        Agent --> Socket
        Agent --> WA
    end
    
    subgraph "工作负载"
        W1[应用 1]
        W2[应用 2]
        W3[应用 3]
    end
    
    Server[SPIRE Server]
    
    Agent <-->|gRPC/mTLS| Server
    W1 <-->|Workload API| Socket
    W2 <-->|Workload API| Socket
    W3 <-->|Workload API| Socket
```

## 核心功能

### 节点证明

Agent 启动时向 Server 证明自身身份：

1. 使用 NodeAttestor 插件生成证明数据
2. 向 Server 发送证明请求
3. Server 验证后颁发 Agent SVID
4. Agent 存储 SVID 用于后续通信

### 工作负载证明

当工作负载请求 SVID 时：

1. Agent 通过 Socket 识别调用进程
2. WorkloadAttestor 插件生成选择器
3. 匹配缓存的注册条目
4. 返回对应的 SVID

### SVID 缓存和轮换

- 本地缓存所有已授权的 SVID
- 在 TTL 到达 50% 时自动轮换
- 定期从 Server 同步注册条目

## 部署模式

### DaemonSet（Kubernetes）

```yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: spire-agent
spec:
  selector:
    matchLabels:
      app: spire-agent
  template:
    spec:
      hostPID: true
      hostNetwork: true
      containers:
        - name: spire-agent
          image: ghcr.io/spiffe/spire-agent:latest
          volumeMounts:
            - name: spire-socket
              mountPath: /run/spire/sockets
      volumes:
        - name: spire-socket
          hostPath:
            path: /run/spire/sockets
            type: DirectoryOrCreate
```

### Systemd 服务

```ini
[Unit]
Description=SPIRE Agent
After=network.target

[Service]
Type=simple
User=root
ExecStart=/opt/spire/bin/spire-agent run -config /opt/spire/conf/agent/agent.conf
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

## 快速启动

```bash
# 生成引导信任包
spire-server bundle show > bootstrap.crt

# 生成 join token
TOKEN=$(spire-server token generate -spiffeID spiffe://example.org/agent -output json | jq -r '.value')

# 启动 Agent
spire-agent run -config agent.conf -joinToken "$TOKEN"
```

## 下一步

- {doc}`/5.agent/configuration` - 配置详解
- {doc}`/5.agent/cli` - 命令行参考
- {doc}`/5.agent/workload-api` - Workload API 使用