Agent 配置

配置文件格式

SPIRE Agent 使用 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"
}

完整配置示例

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（也可命令行指定）

Socket 路径默认值

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

SDS 配置

用于 Envoy SDS 集成：

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

授权委托

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

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

插件配置

NodeAttestor

Kubernetes PSAT

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

AWS IID

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

Join Token

plugins {
    NodeAttestor "join_token" {
        plugin_data {}
    }
}

KeyManager

Disk

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

Memory

plugins {
    KeyManager "memory" {
        plugin_data {}
    }
}

WorkloadAttestor

Kubernetes

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

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

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>`	环境变量

环境变量

配置支持环境变量替换：

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

Kubernetes 配置示例

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"
    }

最佳实践

生产环境建议

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

下一步

了解 Agent 命令行命令行工具。