# Agent 配置

## 配置文件格式

SPIRE Agent 使用 HCL 格式的配置文件。

## 基本配置

```hcl
agent {
    # 数据目录
    data_dir = "/opt/spire/data/agent"
    
    # 日志级别
    log_level = "INFO"
    
    # 日志格式
    log_format = "text"
    
    # Server 地址
    server_address = "spire-server.example.org"
    server_port = "8081"
    
    # 信任域
    trust_domain = "example.org"
    
    # Workload API socket 路径
    socket_path = "/tmp/spire-agent/public/api.sock"
    
    # 引导信任包
    trust_bundle_path = "/opt/spire/conf/agent/bootstrap.crt"
}
```

## 完整配置示例

```hcl
agent {
    data_dir = "/opt/spire/data/agent"
    log_level = "INFO"
    log_format = "json"
    server_address = "spire-server.example.org"
    server_port = "8081"
    trust_domain = "example.org"
    socket_path = "/tmp/spire-agent/public/api.sock"
    trust_bundle_path = "/opt/spire/conf/agent/bootstrap.crt"
    
    # 不安全引导（仅用于测试）
    # insecure_bootstrap = true
    
    # SDS 配置
    sds {
        default_svid_name = "default"
        default_bundle_name = "ROOTCA"
        default_all_bundles_name = "ALL"
    }
    
    # 授权策略
    authorized_delegates = [
        "spiffe://example.org/envoy",
    ]
}

plugins {
    NodeAttestor "k8s_psat" {
        plugin_data {
            cluster = "production"
            token_path = "/var/run/secrets/tokens/spire-agent"
        }
    }

    KeyManager "disk" {
        plugin_data {
            directory = "/opt/spire/data/agent"
        }
    }

    WorkloadAttestor "k8s" {
        plugin_data {
            skip_kubelet_verification = false
            node_name_env = "MY_NODE_NAME"
        }
    }

    WorkloadAttestor "unix" {
        plugin_data {
            discover_workload_path = true
        }
    }
}

# 健康检查
health_checks {
    listener_enabled = true
    bind_address = "0.0.0.0"
    bind_port = "8080"
    live_path = "/live"
    ready_path = "/ready"
}

# 遥测
telemetry {
    Prometheus {
        host = "0.0.0.0"
        port = 9989
    }
}
```

## 配置参数详解

### agent 块

| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `data_dir` | string | 必填 | 数据目录 |
| `log_level` | string | "INFO" | 日志级别 |
| `log_format` | string | "text" | 日志格式 |
| `server_address` | string | 必填 | Server 地址 |
| `server_port` | string | "8081" | Server 端口 |
| `trust_domain` | string | 必填 | 信任域 |
| `socket_path` | string | 见备注 | Workload API socket 路径 |
| `trust_bundle_path` | string | - | 引导信任包路径 |
| `insecure_bootstrap` | bool | false | 不安全引导（不验证 Server）|
| `join_token` | string | - | Join Token（也可命令行指定）|

:::{admonition} Socket 路径默认值
:class: note

- Linux: `/tmp/spire-agent/public/api.sock`
- Windows: `\\.\pipe\spire-agent\public\api`
:::

### SDS 配置

用于 Envoy SDS 集成：

```hcl
agent {
    sds {
        # 默认 SVID 资源名称
        default_svid_name = "default"
        
        # 默认信任包资源名称
        default_bundle_name = "ROOTCA"
        
        # 所有信任包资源名称
        default_all_bundles_name = "ALL"
        
        # 禁用 SPIFFE 认证（仅用于测试）
        disable_spiffe_cert_validation = false
    }
}
```

### 授权委托

允许某些工作负载代表其他工作负载获取 SVID：

```hcl
agent {
    authorized_delegates = [
        "spiffe://example.org/envoy",
        "spiffe://example.org/sidecar",
    ]
}
```

## 插件配置

### NodeAttestor

#### Kubernetes PSAT

```hcl
plugins {
    NodeAttestor "k8s_psat" {
        plugin_data {
            cluster = "production"
            token_path = "/var/run/secrets/tokens/spire-agent"
        }
    }
}
```

#### AWS IID

```hcl
plugins {
    NodeAttestor "aws_iid" {
        plugin_data {
            # 可选：EC2 实例配置
        }
    }
}
```

#### Join Token

```hcl
plugins {
    NodeAttestor "join_token" {
        plugin_data {}
    }
}
```

### KeyManager

#### Disk

```hcl
plugins {
    KeyManager "disk" {
        plugin_data {
            directory = "/opt/spire/data/agent"
        }
    }
}
```

#### Memory

```hcl
plugins {
    KeyManager "memory" {
        plugin_data {}
    }
}
```

### WorkloadAttestor

#### Kubernetes

```hcl
plugins {
    WorkloadAttestor "k8s" {
        plugin_data {
            # Kubelet 地址
            kubelet_read_only_port = 10255
            
            # 跳过 Kubelet 验证
            skip_kubelet_verification = false
            
            # 节点名称环境变量
            node_name_env = "MY_NODE_NAME"
            
            # 最大轮询重试
            max_poll_attempts = 60
            
            # 轮询间隔
            poll_retry_interval = "500ms"
        }
    }
}
```

生成的选择器：

| 选择器 | 描述 |
|--------|------|
| `k8s:ns:<namespace>` | Pod 命名空间 |
| `k8s:sa:<service-account>` | 服务账户 |
| `k8s:pod-uid:<uid>` | Pod UID |
| `k8s:pod-name:<name>` | Pod 名称 |
| `k8s:pod-label:<key>:<value>` | Pod 标签 |
| `k8s:container-name:<name>` | 容器名称 |
| `k8s:container-image:<image>` | 容器镜像 |

#### Unix

```hcl
plugins {
    WorkloadAttestor "unix" {
        plugin_data {
            # 发现工作负载路径
            discover_workload_path = true
        }
    }
}
```

生成的选择器：

| 选择器 | 描述 |
|--------|------|
| `unix:uid:<uid>` | 用户 ID |
| `unix:gid:<gid>` | 组 ID |
| `unix:user:<username>` | 用户名 |
| `unix:group:<groupname>` | 组名 |
| `unix:path:<path>` | 可执行文件路径 |
| `unix:sha256:<hash>` | 可执行文件哈希 |

#### Docker

```hcl
plugins {
    WorkloadAttestor "docker" {
        plugin_data {
            docker_socket_path = "unix:///var/run/docker.sock"
        }
    }
}
```

生成的选择器：

| 选择器 | 描述 |
|--------|------|
| `docker:label:<key>:<value>` | 容器标签 |
| `docker:image_id:<id>` | 镜像 ID |
| `docker:env:<key>:<value>` | 环境变量 |

## 环境变量

配置支持环境变量替换：

```hcl
agent {
    server_address = "${SPIRE_SERVER_ADDRESS}"
    trust_domain = "${SPIRE_TRUST_DOMAIN}"
}
```

## Kubernetes 配置示例

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: spire-agent
  namespace: spire
data:
  agent.conf: |
    agent {
        data_dir = "/run/spire"
        log_level = "INFO"
        server_address = "spire-server"
        server_port = "8081"
        socket_path = "/run/spire/sockets/agent.sock"
        trust_domain = "example.org"
        trust_bundle_path = "/run/spire/bundle/bundle.crt"
    }

    plugins {
        NodeAttestor "k8s_psat" {
            plugin_data {
                cluster = "production"
                token_path = "/var/run/secrets/tokens/spire-agent"
            }
        }

        KeyManager "memory" {
            plugin_data {}
        }

        WorkloadAttestor "k8s" {
            plugin_data {
                node_name_env = "MY_NODE_NAME"
            }
        }
    }

    health_checks {
        listener_enabled = true
        bind_address = "0.0.0.0"
        bind_port = "8080"
    }
```

## 最佳实践

:::{admonition} 生产环境建议
:class: tip

1. **使用持久化 KeyManager**: 避免重启后重新证明
2. **启用健康检查**: 便于 Kubernetes 探针
3. **配置适当的 WorkloadAttestor**: 根据部署环境选择
4. **保护 socket 文件**: 限制访问权限
5. **使用 JSON 日志**: 便于日志分析
:::

## 下一步

了解 {doc}`/5.agent/cli` 命令行工具。