本文为 SPIRE 官方文档 spire_server.md 的中文译本,内容较长,以英文原文为准。 🔗 穿越源码分析:Server 详解 · 职责与装配 · 整体架构

SPIRE Server 配置参考

本文档是 SPIRE Server 的配置参考。内容涵盖插件类型(plugin type)、内置插件、服务端配置文件、插件配置,以及 spire-server 各命令的命令行选项。

插件类型(Plugin types)

类型	说明
DataStore	提供持久化存储与高可用(HA)特性。注意: DataStore 不再支持可插拔性(pluggability),只能使用内置的 SQL 插件。
KeyManager	为服务端的签名操作同时实现签名逻辑与密钥存储逻辑。适用于借助基于硬件的密钥操作的场景。
CredentialComposer	允许自定义 SVID 与 CA 的属性。
NodeAttestor	为尝试断言自身身份的节点实现校验逻辑。通常与同类型的 agent 插件配对使用。
UpstreamAuthority	允许 SPIRE server 与既有的 PKI 系统集成。
Notifier	在某些事件正在发生或已经发生时,由 SPIRE server 通知。对于正在发生的事件,notifier 可就其结果向 SPIRE server 提出建议。
BundlePublisher	将本地的信任捆绑包(trust bundle)发布到某个存储中。

内置插件

类型	名称	说明
DataStore	sql	面向 SQLite、PostgreSQL 和 MySQL 数据库的 SQL 存储,用作 SPIRE 数据存储(datastore)
KeyManager	aws_kms	在 AWS KMS 中管理密钥的 key manager
KeyManager	disk	管理持久化到磁盘上的密钥的 key manager
KeyManager	hashicorp_vault	在 HashiCorp Vault 的 Transit Secret Engine 中管理密钥的 key manager
KeyManager	memory	在内存中管理不持久化密钥的 key manager
CredentialComposer	uniqueid	为工作负载的 X509-SVID 添加 x509UniqueIdentifier 属性。
NodeAttestor	aws_iid	使用 AWS 实例身份文档(Instance Identity Document)校验 agent 身份的 node attestor
NodeAttestor	azure_imds	使用 Azure 实例元数据服务(Instance Metadata Service)校验 agent 身份的 node attestor
NodeAttestor	azure_msi	使用 Azure MSI 令牌校验 agent 身份的 node attestor
NodeAttestor	gcp_iit	使用 GCP 实例身份令牌(Instance Identity Token)校验 agent 身份的 node attestor
NodeAttestor	join_token	校验以服务端生成的 join token 进行证明的 agent 的 node attestor
NodeAttestor	k8s_psat	使用 Kubernetes 投射服务账号令牌(Projected Service Account token)校验 agent 身份的 node attestor
NodeAttestor	sshpop	使用既有 ssh 证书校验 agent 身份的 node attestor
NodeAttestor	tpm_devid	使用已配置 DevID 证书的 TPM 校验 agent 身份的 node attestor
NodeAttestor	x509pop	使用既有 X.509 证书校验 agent 身份的 node attestor
UpstreamAuthority	disk	使用从磁盘加载的 CA 为 SPIRE server 的中间证书(intermediate certificate)签名。
UpstreamAuthority	aws_pca	使用 AWS Certificate Manager 中的私有证书颁发机构(Private Certificate Authority)为 SPIRE server 的中间证书签名。
UpstreamAuthority	awssecret	使用从 AWS SecretsManager 加载的 CA 为 SPIRE server 的中间证书签名。
UpstreamAuthority	gcp_cas	使用 GCP Certificate Authority Service 中的私有证书颁发机构为 SPIRE Server 的中间证书签名。
UpstreamAuthority	vault	使用 HashiCorp Vault 的 PKI Secret Engine 为 SPIRE server 的中间证书签名。
UpstreamAuthority	spire	使用同一信任域(trust domain)内的上游 SPIRE server,为 SPIRE server 获取中间签名证书。
UpstreamAuthority	cert-manager	使用引用的 cert-manager Issuer 来请求中间签名证书。
Notifier	gcs_bundle	将最新的信任捆绑包内容推送到 Google Cloud Storage 中某个对象的 notifier。
Notifier	k8sbundle	将最新的信任捆绑包内容推送到 Kubernetes ConfigMap 的 notifier。
BundlePublisher	aws_s3	将信任捆绑包发布到 Amazon S3 存储桶。
BundlePublisher	gcp_cloudstorage	将信任捆绑包发布到 Google Cloud Storage 存储桶。
BundlePublisher	aws_rolesanywhere_trustanchor	将信任捆绑包发布到 AWS IAM Roles Anywhere 的信任锚(trust anchor)。
BundlePublisher	k8s_configmap	将信任捆绑包发布到 Kubernetes ConfigMap。

服务端配置文件

下表列出了 SPIRE server 的配置选项。这些选项可以在配置文件顶层的 server { ... } 区块中设置。大多数选项都有对应的 CLI flag;若设置了该 flag,它会覆盖文件中定义的值。

SPIRE 配置文件可以用 HCL 或 JSON 表示。完整示例请参见示例配置文件一节。

如果向 SPIRE 传入 -expandEnv flag,则 $VARIABLE 或 ${VARIABLE} 形式的环境变量会在解析之前被展开。这在为配置文件做模板化时很有用,例如跨不同信任域复用配置,或注入数据库连接密码之类的机密(secret)。

配置项	说明	默认值
`admin_ids`	当调用方的 X509-SVID 中包含这些 SPIFFE ID 时,授予该调用方管理员权限。这些 admin ID 必须属于服务端所在的信任域或某个联邦信任域,且无需在服务端有对应的 admin 注册条目(registration entry)。
`agent_ttl`	agent SVID 使用的 TTL	`default_x509_svid_ttl` 的值
`audit_log_enabled`	若为 true,启用审计日志(audit logging)	false
`bind_address`	SPIRE server 的 IP 地址或 DNS 名称	0.0.0.0
`bind_port`	SPIRE server 的 HTTP 端口号	8081
`ca_key_type`	服务端 CA 使用的密钥类型(X509 与 JWT 均适用),<rsa-2048\|rsa-4096\|ec-p256\|ec-p384>	ec-p256(JWT 密钥类型可由 `jwt_key_type` 覆盖)
`ca_subject`	CA 证书应使用的 Subject(见下文)
`ca_ttl`	默认的 CA/签名密钥 TTL	24h
`data_dir`	服务端在运行时可使用的目录
`default_x509_svid_ttl`	默认的 X509-SVID TTL	1h
`default_jwt_svid_ttl`	默认的 JWT-SVID TTL	5m
`experimental`	实验性(experimental)选项,可能会变更或移除(见下文)
`federation`	用于联邦的 bundle endpoint 配置区块
`disable_jwt_svids`	若为 true,完全禁用 JWT-SVID 功能。服务端将不再生成 JWT 密钥、不签发 JWT-SVID,也不实现与 JWT 相关的 API 调用。适用于不需要 JWT-SVID 支持的部署。	false
`jwt_key_type`	服务端 CA(JWT)使用的密钥类型,<rsa-2048\|rsa-4096\|ec-p256\|ec-p384>	`ca_key_type` 的值;若未定义则为 ec-p256
`jwt_issuer`	签发(mint)JWT-SVID 时使用的 issuer 声明(claim)
`log_file`	日志写入的文件
`log_level`	设置日志级别 <DEBUG\|INFO\|WARN\|ERROR>	INFO
`log_format`	日志格式,<text\|json>	text
`log_source_location`	若为 true,日志中包含源文件、行号和方法名字段(会带来少量运行时开销)	false
`profiling_enabled`	若为 true,启用 net/http/pprof 端点	false
`proxy_protocol_trusted_cidrs`	用于支持 PROXY protocol 的受信任 CIDR 列表。当该列表非空时,TCP 监听器仅接受来自这些 CIDR 内来源的 PROXY protocol 头;其他来源若发送 PROXY 头,连接将被拒绝。当服务端位于负载均衡器之后时很有用,这样按 IP 的限流(rate limiting)才能看到真实的客户端 IP。
`profiling_freq`	将性能剖析(profiling)数据转储到磁盘的频率。仅当 `profiling_enabled` 为 `true` 且 `profiling_freq` > 0 时启用。
`profiling_names`	每次 profiling tick 时转储到磁盘的 profile 名称列表,见 Profiling 名称
`profiling_port`	net/http/pprof 端点的端口号。仅当 `profiling_enabled` 为 `true` 时使用。
`prune_attested_nodes_expired_for`	启用对 SVID 已过期的已证明节点(attested node)记录的定期清理,条件是过期时间比指定的时长更早。除非 `prune_tofu_nodes` 设为 `true`,否则不可重新证明(non-reattestable)的节点不会被清理。被封禁(banned)的节点不会被清理。对于 join-token 节点,在清理或 `agent evict`/`purge` 时还会级联删除 `CreateJoinToken` 别名条目(仅向前生效)。
`prune_attested_nodes_batch_size`	每个清理周期最多清理的已过期已证明节点数量。仅在设置了 `prune_attested_nodes_expired_for` 时生效。	1000
`prune_tofu_nodes`	将已过期的 TOFU 节点纳入清理考量。这不影响被封禁的节点,后者不会被清理。	false
`ratelimit`	限流(rate limiting)配置,通常用于服务端位于负载均衡器之后的场景(见下文)
`socket_path`	SPIRE Server API socket 绑定的路径(仅 Unix)	/tmp/spire-server/private/api.sock
`trust_domain`	本服务端所属的信任域(不应超过 255 个字符)
`max_attested_node_info_staleness`	在需要从 datastore 获取最新数据之前,缓存并使用已证明节点信息的时长。	0s

ca_subject	说明	默认值
`country`	`Country` 值的数组
`organization`	`Organization` 值的数组
`common_name`	`CommonName` 值

experimental	说明	默认值
`agent_spiffe_id_as_selector`	启用后自动将 agent 的 spiffe_id 加入到节点选择器(node selector)列表中。	false
`cache_reload_interval`	内存中条目缓存(entry cache)两次重新加载之间的时间间隔。增大该值可缓解超大规模部署下的数据库高负载,但也会减慢新增或更新条目向 agent 传播的速度。	5s
`full_cache_reload_interval`	使用基于事件的缓存(events based cache)时,从数据库对缓存执行完整重载的频率。	24h
`events_based_cache`	使用事件来将自上次更新以来的变更同步到缓存。启用后可降低数据库开销。	false
`prune_events_older_than`	事件在被删除前可存留的最长时间。与基于事件的缓存配合使用。减小该值可让事件表(events table)更小,但会增大在数据库连接中断时漏掉事件的风险。	12h
`event_timeout`	在放弃之前,等待某个事件到来的最长时间。	15m
`auth_opa_policy_engine`	用于授权决策的 auth opa_policy 引擎	默认的 SPIRE 授权策略
`named_pipe_name`	SPIRE Server API 命名管道(named pipe)的管道名(仅 Windows)	\spire-server\private\api
`require_pq_kem`	要求在 TLS 握手中使用抗量子安全(post-quantum-safe)的密钥交换方法	false
`wit_issuer`	签发 WIT-SVID 时使用的 issuer 声明(claim)

ratelimit	说明	默认值
`attestation`	是否对节点证明(node attestation)限流。若为 true,则节点证明按每个 IP 地址每秒一次进行限流。	true
`signing`	是否对 JWT 与 X509 签名限流。若为 true,则 JWT 与 X509 签名分别按每个 IP 地址每秒 500 次请求进行限流。	true

auth_opa_policy_engine	说明	默认值
`local`	用于授权策略的本地 OPA 配置。

auth_opa_policy_engine.local	说明	默认值
`rego_path`	用于检索授权用 OPA rego 策略的文件。
`policy_data_path`	用于检索策略求值所需数据绑定(databinding)的文件。

Profiling 名称

以下是可在 profiling_names 配置值中设置的可用 profile:

goroutine
threadcreate
heap
block
mutex
trace
cpu

插件配置

服务端配置文件还包含一个用于配置各种 SPIRE server 插件的区块。插件配置位于顶层的 plugins { ... } 区块内,其格式如下:

hcl

plugins {
    pluginType "pluginName" {
        ...
        plugin configuration options here
        ...
    }
}

配置插件时可使用以下配置选项:

配置项	说明
plugin_cmd	插件实现二进制文件的路径(可选,内置插件不需要)
plugin_checksum	插件二进制文件的可选 sha256 校验和(可选,内置插件不需要)
enabled	启用或禁用该插件(默认启用)
plugin_data	插件专属数据(与 `plugin_data_file` 互斥)
plugin_data_file	包含插件专属数据的文件路径(与 `plugin_data` 互斥)

关于开箱即用的插件信息,请参见下方的内置插件一节。

示例

使用静态配置的内置插件

hcl

plugins {
    SomeType "some_plugin" {
        plugin_data = {
            option1 = "foo"
            option2 = 3
        }
    }
}

使用动态配置的外部插件

在 agent.conf 中,使用 plugin_data_file 选项声明插件,以便从文件中读取插件配置。

hcl

plugins {
    SomeType "some_plugin" {
        plugin_cmd = "./path/to/plugin"
        plugin_checksum = "4e1243bd22c66e76c2ba9eddc1f91394e57f9f83"
        plugin_data_file = "some_plugin.conf"
    }
}

然后在 some_plugin.conf 中放置插件配置:

hcl

option1 = "foo"
option2 = 3

重新配置插件(仅 Posix)

使用动态配置源(即 plugin_data_file)的插件,可以通过向 SPIRE Server 发送 SIGUSR1 信号在运行时重新配置。内置插件和外部插件均是如此。

SPIRE Server 在收到该信号后,会执行以下操作:

重新加载插件数据
将插件数据与先前的数据进行比较
如有变更,则用新数据重新配置该插件

注意即使使用动态数据源(例如 plugin_data_file)配置,DataStore 也无法被重新配置。

联邦(Federation)配置

可以将 SPIRE Server 配置为与位于不同信任域的其他 SPIRE Server 建立联邦(federate)。SPIRE 支持在 SPIRE Server 配置文件中配置联邦关系(静态关系),也支持通过 Trust Domain API 配置(动态关系)。本节介绍如何在配置文件中配置静态定义的关系。

注意:静态关系会覆盖动态关系。如果需要配置动态关系,请参见 federation 命令。静态关系不会体现在 federation 命令中。

配置联邦信任域可以让一个信任域对由其他 SPIFFE 权威机构(authority)签发的身份进行认证,从而让一个信任域中的工作负载能够安全地认证外部信任域中的工作负载。实现联邦的一个关键要素是使用 SPIFFE bundle endpoint,它们是(以 URL 表示的)资源,为某个信任域提供其信任捆绑包的副本。通过 federation 区块,你既可以将 SPIRE 设置为 SPIFFE bundle endpoint 服务器,也可以配置本 SPIRE Server 将从哪些联邦信任域拉取捆绑包。

hcl

server {
    .
    .
    .
    federation {
        bundle_endpoint {
            address = "0.0.0.0"
            port = 8443
            refresh_hint = "10m"
            profile "https_web" {
                acme {
                    domain_name = "example.org"
                    email = "mail@example.org"
                }
            }
        }
        federates_with "domain1.test" {
            bundle_endpoint_url = "https://1.2.3.4:8443"
            bundle_endpoint_profile "https_web" {}
        }
        federates_with "domain2.test" {
            bundle_endpoint_url = "https://5.6.7.8:8443"
            bundle_endpoint_profile "https_spiffe" {
                endpoint_spiffe_id = "spiffe://domain2.test/beserver"
            }
        }
    }
}

federation.bundle_endpoint 区块是可选的,用于在 SPIRE Server 中设置一个 SPIFFE bundle endpoint 服务器。 federation.federates_with 区块同样是可选的,用于配置与外部信任域的联邦关系。SPIRE Server 会为其中每个联邦信任域周期性地拉取捆绑包。

`federation.bundle_endpoint` 的配置选项

这个可选区块包含 SPIRE Server 用于暴露 bundle endpoint 的可配置项。

配置项	说明
address	本服务器监听 HTTP 请求的 IP 地址
port	本服务器监听 HTTP 请求的 TCP 端口号
refresh_hint	允许手动指定一个 refresh hint。默认为 5 分钟。较小的值可以及时获取到信任捆绑包的更新
profile "<https_web\|https_spiffe>"	允许配置捆绑包 profile

`federation.bundle_endpoint.profile` 的配置选项

在设置 bundle_endpoint 时,必须指定捆绑包 profile。

允许的 profile:

https_web 允许配置 Automated Certificate Management Environment 或 serving cert file 区块中的一种。
https_spiffe

`federation.bundle_endpoint.profile "https_web".acme` 的配置选项

配置项	说明	默认值
directory_url	Directory 端点 URL	https://acme-v02.api.letsencrypt.org/directory
domain_name	证书管理器尝试为其获取新证书的域名
email	联系邮箱地址。CA(如 Let's Encrypt)会用它来就已签发证书的问题发送通知
tos_accepted	是否接受 ACME 服务条款(Terms of Service)。若不为 true 且提供方要求接受,则证书获取将失败	false

`federation.bundle_endpoint.profile "https_web".serving_cert_file` 的配置选项

配置项	说明	默认值
cert_file_path	证书文件的路径,PEM 格式
key_file_path	密钥文件的路径,PEM 格式
file_sync_interval	从磁盘重新加载这些文件的间隔	1h

`federation.bundle_endpoint.profile "https_spiffe"` 的配置选项

默认的捆绑包 profile 配置。

`federation.federates_with["<trust domain>"].bundle_endpoint` 的配置选项

可选的 federates_with 区块是一个以本服务器想要与之建立联邦的 "<trust domain>" 名称为键的 bundle endpoint profile 配置映射。该区块有以下可配置项:

配置项	说明	默认值
bundle_endpoint_url	提供待联邦信任捆绑包的 SPIFFE bundle endpoint 的 URL。必须使用 HTTPS 协议。
bundle_endpoint_profile "<https_web\|https_spiffe>"	SPIFFE endpoint profile 类型的配置。

SPIRE 支持 https_web 与 https_spiffe 两种 bundle endpoint profile。

https_web profile 不需要额外设置。

配置为使用 https_spiffe bundle endpoint profile 的信任域,必须在配置中通过 endpoint_spiffe_id 设置项指定远端 SPIFFE bundle endpoint 服务器的预期 SPIFFE ID。

关于 SPIFFE 中定义的不同 profile 以及搭建 SPIFFE Federation 时的安全考量,更多信息请参阅 SPIFFE Federation 标准。

遥测(Telemetry)配置

关于配置 SPIRE Server 输出遥测数据的更多信息,请参见遥测配置指南。

健康检查(Health check)配置

服务端可以暴露一个额外的端点用于健康检查。通过设置 listener_enabled = true 启用。目前它暴露两个路径:一个用于存活性(liveness,服务端是否已启动?),一个用于就绪性(readiness,服务端是否已准备好处理请求?)。除非另行配置,健康检查端点默认监听 localhost:80。

hcl

health_checks {
        listener_enabled = true
        bind_address = "localhost"
        bind_port = "8080"
        live_path = "/live"
        ready_path = "/ready"
}

命令行选项

`spire-server run`

上述配置文件中的大多数选项都有完全对应的命令行版本。此外,还提供以下 flag。

命令	作用	默认值
`-bindAddress`	SPIRE server 的 IP 地址或 DNS 名称
`-config`	SPIRE 配置文件的路径	conf/server/server.conf
`-dataDir`	存放运行时数据的目录
`-expandEnv`	展开配置文件中的 $VARIABLES 环境变量
`-logFile`	日志写入的文件
`-logFormat`	日志格式,<text\|json>
`-logLevel`	DEBUG、INFO、WARN 或 ERROR
`-serverPort`	SPIRE server 的端口号
`-socketPath`	SPIRE Server API socket 绑定的路径
`-trustDomain`	本服务端所属的信任域(不应超过 255 个字符)

将 SPIRE Server 作为 Windows 服务运行

在 Windows 平台上,SPIRE Server 可以选择作为 Windows 服务运行。作为 Windows 服务运行时,唯一支持的命令是 run 命令。

注意:SPIRE 不会自动在系统中创建该服务,必须由用户创建。启动该服务时,以 run 命令执行 SPIRE Server 所需的所有参数都必须作为服务参数传入。

创建 SPIRE Server Windows 服务的示例

bash

> sc.exe create spire-server binpath=c:\spire\bin\spire-server.exe

运行 SPIRE Server Windows 服务的示例

bash

> sc.exe start spire-server run -config c:\spire\conf\server\server.conf

`spire-server token generate`

生成一个节点 join token,并为其创建一个注册条目。该 token 可用于引导(bootstrap)一个 spire-agent 安装实例。可选的 -spiffeID 可在基于 token 的 ID 之外,为该 token 赋予一个人类可读的注册条目名称。

命令	作用	默认值
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-spiffeID`	为 token 所有者分配的额外 SPIFFE ID(可选)
`-ttl`	Token TTL,以秒为单位	600

`spire-server entry create`

创建注册条目。

命令	作用	默认值
`-admin`	若设置,该条目中的 SPIFFE ID 将被授予访问 Server API 的权限
`-data`	包含 JSON 格式注册数据的文件路径(可选;若指定,则必须省略其他与条目信息相关的 flag)。若设为 '-',则从 stdin 读取 JSON。
`-disableX509SVIDPrefetch`	布尔值;设置后禁用为该条目预取(prefetch)X509 SVID	`false`
`-dns`	在适当情况下,将被包含到基于该条目签发的 SVID 中的 DNS 名称。可多次使用
`-downstream`	布尔值;设置后表示该条目描述的是一个下游(downstream)SPIRE server
`-entryExpiry`	所生成注册条目从 datastore 中清理的过期时间(自纪元起的秒数)。请注意,这是一个数据管理特性,而非安全特性(可选)。
`-entryID`	为新创建的注册条目指定的用户自定义 ID(可选)。若未提供条目 ID,则在创建时自动生成一个
`-federatesWith`	一组信任域 SPIFFE ID,表示该注册条目要与之建立联邦的信任域。该信任域的捆绑包必须已存在
`-node`	若设置,该条目将应用于匹配的节点,而非工作负载
`-parentID`	本记录父级(parent)的 SPIFFE ID。
`-selector`	用于证明的、以冒号分隔的 type:value 选择器(selector)。该参数可多次使用,以指定多个必须同时满足的选择器。
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-spiffeID`	本记录所代表的 SPIFFE ID,将被设置到所签发的 SVID 上。
`-x509SVIDTTL`	基于本记录签发的任何 X509-SVID 的 TTL,以秒为单位。	由 `default_x509_svid_ttl` 配置的 TTL
`-jwtSVIDTTL`	基于本记录签发的任何 JWT-SVID 的 TTL,以秒为单位。	由 `default_jwt_svid_ttl` 配置的 TTL
`-storeSVID`	布尔值;设置后表示基于该条目签发的 SVID 必须通过 SVIDStore 插件进行存储

`spire-server entry update`

更新注册条目。

命令	作用	默认值
`-admin`	若设置,该条目中的 SPIFFE ID 将被授予访问 Server API 的权限
`-data`	包含 JSON 格式注册数据的文件路径(可选;若指定,则必须省略其他与条目信息相关的 flag)。若设为 '-',则从 stdin 读取 JSON。
`-disableX509SVIDPrefetch`	布尔值;设置后禁用为该条目预取(prefetch)X509 SVID	`false`
`-dns`	在适当情况下,将被包含到基于该条目签发的 SVID 中的 DNS 名称。可多次使用
`-downstream`	布尔值;设置后表示该条目描述的是一个下游(downstream)SPIRE server
`-entryExpiry`	所生成注册条目从 datastore 中清理的过期时间(自纪元起的秒数)。请注意,这是一个数据管理特性,而非安全特性(可选)。
`-entryID`	为新创建的注册条目指定的用户自定义 ID(可选)。若未提供条目 ID,则在创建时自动生成一个
`-federatesWith`	一组信任域 SPIFFE ID,表示该注册条目要与之建立联邦的信任域。该信任域的捆绑包必须已存在
`-parentID`	本记录父级(parent)的 SPIFFE ID。
`-selector`	用于证明的、以冒号分隔的 type:value 选择器(selector)。该参数可多次使用,以指定多个必须同时满足的选择器。
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-spiffeID`	本记录所代表的 SPIFFE ID,将被设置到所签发的 SVID 上。
`-x509SVIDTTL`	基于本记录签发的任何 X509-SVID 的 TTL,以秒为单位。	由 `default_x509_svid_ttl` 配置的 TTL
`-jwtSVIDTTL`	基于本记录签发的任何 JWT-SVID 的 TTL,以秒为单位。	由 `default_jwt_svid_ttl` 配置的 TTL
`-storeSVID`	布尔值;设置后表示基于该条目签发的 SVID 必须通过 SVIDStore 插件进行存储

`spire-server entry count`

显示注册条目的总数。

命令	作用	默认值
`-downstream`	布尔值;设置后表示该条目描述的是一个下游 SPIRE server
`-federatesWith`	某个条目与之联邦的信任域的 SPIFFE ID。可多次使用
`-parentID`	要统计的记录的 Parent ID。
`-selector`	以冒号分隔的 type:value 选择器。可多次使用以指定多个选择器。
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-spiffeID`	要统计的记录的 SPIFFE ID。

`spire-server entry delete`

删除指定的注册条目。

命令	作用	默认值
`-entryID`	要删除的记录的注册条目 ID(Registration Entry ID)
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server entry show`

显示已配置的注册条目。

命令	作用	默认值
`-downstream`	布尔值;设置后表示该条目描述的是一个下游 SPIRE server
`-entryID`	要显示的记录的条目 ID(Entry ID)。
`-federatesWith`	某个条目与之联邦的信任域的 SPIFFE ID。可多次使用
`-parentID`	要显示的记录的 Parent ID。
`-selector`	以冒号分隔的 type:value 选择器。可多次使用以指定多个选择器。
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-spiffeID`	要显示的记录的 SPIFFE ID。

`spire-server bundle count`

显示捆绑包的总数。

命令	作用	默认值
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server bundle show`

显示服务端所在信任域的捆绑包。

命令	作用	默认值
`-format`	展示捆绑包的格式。`pem` 或 `spiffe`	pem
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server bundle list`

显示联邦捆绑包。

命令	作用	默认值
`-id`	要显示的捆绑包所属信任域的 SPIFFE ID。若未设置,则显示所有信任捆绑包
`-format`	展示联邦捆绑包的格式。`pem` 或 `spiffe`	pem
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server bundle set`

为某个信任域创建或更新捆绑包数据。此命令不能用于更改服务端自身信任域的捆绑包,只能操作其他信任域的捆绑包。

命令	作用	默认值
`-id`	要设置的捆绑包所属信任域的 SPIFFE ID。
`-path`	包含捆绑包数据的磁盘文件路径。若未设置,则从 stdin 读取数据。
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-format`	要设置的捆绑包的格式。`pem` 或 `spiffe`	pem

`spire-server bundle delete`

删除某个信任域的捆绑包数据。此命令不能用于删除服务端自身信任域的捆绑包,只能操作其他信任域的捆绑包。

命令	作用	默认值
`-id`	要删除的捆绑包所属信任域的 SPIFFE ID。
`-mode`	以下之一:`restrict`、`dissociate`、`delete`。`restrict` 在捆绑包已关联到注册条目(即被联邦引用)时阻止其被删除。`dissociate` 允许删除该捆绑包,并从注册条目中移除该关联。`delete` 在删除捆绑包的同时删除相关联的注册条目。	`restrict`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server federation create`

与外部信任域创建一个动态联邦关系。

命令	作用	默认值
`-bundleEndpointProfile`	Endpoint profile 类型。`https_web` 或 `https_spiffe`。
`-bundleEndpointURL`	提供信任捆绑包的 SPIFFE bundle endpoint 的 URL(必须使用 HTTPS 协议)。
`-data`	包含 JSON 格式联邦关系的文件路径(可选;若指定,则必须省略其他与联邦关系信息相关的 flag)。若设为 '-',则从 stdin 读取 JSON。
`-endpointSpiffeID`	SPIFFE bundle endpoint 服务器的 SPIFFE ID。仅用于 `https_spiffe` profile。
`-socketPath`	SPIRE Server API socket 的路径。	/tmp/spire-server/private/api.sock
`-trustDomain`	要与之联邦的信任域名称(例如 example.org)
`-trustDomainBundleFormat`	捆绑包数据的格式(可选)。`pem` 或 `spiffe`。	pem
`-trustDomainBundlePath`	信任域捆绑包数据的路径(可选)。

`spire-server federation delete`

删除一个动态联邦关系。

命令	作用	默认值
`-id`	该关系所涉信任域的 SPIFFE ID。
`-socketPath`	SPIRE Server API socket 的路径。	/tmp/spire-server/private/api.sock

`spire-server federation list`

列出所有动态联邦关系。

命令	作用	默认值
`-id`	该关系所涉信任域的 SPIFFE ID
`-socketPath`	SPIRE Server API socket 的路径。	/tmp/spire-server/private/api.sock

`spire-server federation refresh`

从指定的联邦信任域刷新捆绑包。

命令	作用	默认值
`-id`	该关系所涉信任域的 SPIFFE ID
`-socketPath`	SPIRE Server API socket 的路径。	/tmp/spire-server/private/api.sock

`spire-server federation show`

显示一个动态联邦关系。

命令	作用	默认值
`-socketPath`	SPIRE Server API socket 的路径。	/tmp/spire-server/private/api.sock
`-trustDomain`	要显示的联邦关系的信任域名称(例如 example.org)

`spire-server federation update`

更新与外部信任域的一个动态联邦关系。

命令	作用	默认值
`-bundleEndpointProfile`	Endpoint profile 类型。`https_web` 或 `https_spiffe`。
`-bundleEndpointURL`	提供信任捆绑包的 SPIFFE bundle endpoint 的 URL(必须使用 HTTPS 协议)。
`-data`	包含 JSON 格式联邦关系的文件路径(可选;若指定,则必须省略其他与联邦关系信息相关的 flag)。若设为 '-',则从 stdin 读取 JSON。
`-endpointSpiffeID`	SPIFFE bundle endpoint 服务器的 SPIFFE ID。仅用于 `https_spiffe` profile。
`-socketPath`	SPIRE Server API socket 的路径。	/tmp/spire-server/private/api.sock
`-trustDomain`	要与之联邦的信任域名称(例如 example.org)
`-trustDomainBundleFormat`	捆绑包数据的格式(可选)。`pem` 或 `spiffe`。	pem
`-trustDomainBundlePath`	信任域捆绑包数据的路径(可选)。

`spire-server agent ban`

根据 spiffeID 封禁一个已证明节点。被封禁的已证明节点无法重新证明(re-attest)。

命令	作用	默认值
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-spiffeID`	要封禁的 agent 的 SPIFFE ID(agent 身份)

`spire-server agent count`

显示已证明节点的总数。

命令	作用	默认值
`-selector`	以冒号分隔的 type:value 选择器。可多次使用以指定多个选择器。
`-canReattest`	按接收到的字符串过滤,'true':可重新证明的 agent,'false':不可重新证明的 agent,其他值则返回全部
`-banned`	按接收到的字符串过滤,'true':已封禁的 agent,'false':未封禁的 agent,其他值则返回全部
`-expiresBefore`	按过期时间过滤(格式:"2006-01-02 15:04:05 -0700 -07")
`-spiffeID`	要统计的记录的 SPIFFE ID。

`spire-server agent evict`

根据 spiffeID 对一个已证明节点解除证明(de-attest)。

命令	作用	默认值
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-spiffeID`	要驱逐(evict)的 agent 的 SPIFFE ID(agent 身份)

`spire-server agent list`

显示已证明节点。

命令	作用	默认值
`-selector`	以冒号分隔的 type:value 选择器。可多次使用以指定多个选择器。
`-canReattest`	按接收到的字符串过滤,'true':可重新证明的 agent,'false':不可重新证明的 agent,其他值则返回全部
`-banned`	按接收到的字符串过滤,'true':已封禁的 agent,'false':未封禁的 agent,其他值则返回全部
`-expiresBefore`	按过期时间过滤(格式:"2006-01-02 15:04:05 -0700 -07")
`-attestationType`	将 agent 过滤为匹配指定证明类型(attestation type)的那些,例如 join_token 或 x509pop。

`spire-server agent show`

根据 spiffeID 显示某个已证明节点的详情(包括节点选择器)。

命令	作用	默认值
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-spiffeID`	要显示的 agent 的 SPIFFE ID(agent 身份)

`spire-server healthcheck`

检查 SPIRE server 的健康状况。

命令	作用	默认值
`-shallow`	执行一次较为宽松的健康检查
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-verbose`	打印详细信息

`spire-server logger get`

获取 SPIRE Server 当前的日志级别。

命令	作用	默认值
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server logger set`

设置 SPIRE Server 的日志级别。

命令	作用	默认值
`-level`	新的日志级别,取值为(panic、fatal、error、warn、info、debug、trace)之一
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server logger reset`

将 SPIRE Server 的日志级别重置为启动时所设置的级别。

命令	作用	默认值
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server validate`

校验 SPIRE server 配置文件。参数与 spire-server run 相同。通常你至少会用到:

命令	作用	默认值
`-config`	SPIRE server 配置文件的路径	server.conf
`-expandEnv`	展开配置文件中的 $VARIABLES 环境变量	false

`spire-server x509 mint`

签发(mint)一个 X509-SVID。

命令	作用	默认值
`-dns`	将被包含到 SVID 中的 DNS 名称。可多次使用
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-spiffeID`	该 X509-SVID 的 SPIFFE ID
`-ttl`	该 X509-SVID 的 TTL	取 `Entry.x509_svid_ttl`、`Entry.ttl`、`default_x509_svid_ttl`、`1h` 中第一个非零值
`-write`	将输出写入的目录,而非 stdout

`spire-server jwt mint`

签发(mint)一个 JWT-SVID。

命令	作用	默认值
`-audience`	将被包含到 SVID 中的 audience 声明(claim)。可多次使用
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-spiffeID`	该 JWT-SVID 的 SPIFFE ID
`-ttl`	该 JWT-SVID 的 TTL	取 `Entry.jwt_svid_ttl`、`Entry.ttl`、`default_jwt_svid_ttl`、`5m` 中第一个非零值
`-write`	将令牌写入的文件,而非 stdout

`spire-server localauthority jwt activate`

激活一个已准备好的 JWT 权威(authority)以供使用,此后本服务端处理的所有 JWT 签名操作都将使用它。

命令	作用	默认值
`-authorityID`	要激活的 JWT 权威的 authority ID
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server localauthority jwt prepare`

通过生成新密钥并将其注入捆绑包,准备一个新的 JWT 权威以供使用。

命令	作用	默认值
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server localauthority jwt revoke`

通过将先前处于活动状态的 JWT 权威从捆绑包中移除并将该更新传播到整个集群,来吊销(revoke)它。

命令	作用	默认值
`-authorityID`	要吊销的 JWT 权威的 authority ID
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server localauthority jwt show`

显示本地的 JWT 权威。

命令	作用	默认值
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server localauthority jwt taint`

将先前处于活动状态的 JWT 权威标记为已污染(tainted)。

命令	作用	默认值
`-authorityID`	要标记为污染的 JWT 权威的 authority ID
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server localauthority x509 activate`

激活一个已准备好的 X.509 权威以供使用,此后本服务端处理的所有 X.509 签名操作都将使用它。

命令	作用	默认值
`-authorityID`	要激活的 X.509 权威的 authority ID
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server localauthority x509 prepare`

通过生成新密钥并将所生成的 CA 证书注入捆绑包,准备一个新的 X.509 权威以供使用。

命令	作用	默认值
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server localauthority x509 revoke`

通过将先前处于活动状态的 X.509 权威从捆绑包中移除并将该更新传播到整个集群,来吊销它。

命令	作用	默认值
`-authorityID`	要吊销的 X.509 权威的 authority ID
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server localauthority x509 show`

显示本地的 X.509 权威。

命令	作用	默认值
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server localauthority x509 taint`

将先前处于活动状态的 X.509 权威标记为已污染。

命令	作用	默认值
`-authorityID`	要标记为污染的 X.509 权威的 authority ID
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock

`spire-server upstreamauthority revoke`

通过将先前处于活动状态的 X.509 上游权威(upstream authority)从捆绑包中移除并将该更新传播到整个集群,来吊销它。

命令	作用	默认值
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-subjectKeyID`	要吊销的 X.509 上游权威的 CA 证书的 X.509 Subject Key Identifier(即 SKID)

`spire-server upstreamauthority taint`

将所提供的 X.509 上游权威标记为已污染。

命令	作用	默认值
`-output`	期望的输出格式(`pretty`、`json`)	`pretty`
`-socketPath`	SPIRE Server API socket 的路径	/tmp/spire-server/private/api.sock
`-subjectKeyID`	要标记为污染的上游 X.509 权威的 CA 证书的 X.509 Subject Key Identifier(即 SKID)

`-data` 所用的 JSON 对象

传给 entry create/update 的 -data 的 JSON 对象应符合以下形式:

json

{
    "entries":[]
}

条目对象由 common protobuf 文件中的 RegistrationEntry 描述。

注意:要创建节点条目,请将 parent_id 设为特殊值 spiffe://<your-trust-domain>/spire/server。当在命令行传入 -node flag 时,代码正是这样做的。

示例配置文件

本节提供一个示例配置文件,供格式与语法参考

hcl

server {
    trust_domain = "example.org"

    bind_address = "0.0.0.0"
    bind_port = "8081"
    log_level = "INFO"
    data_dir = "/opt/spire/.data/"
    default_x509_svid_ttl = "6h"
    default_jwt_svid_ttl = "5m"
    ca_ttl = "72h"
    ca_subject {
        country = ["US"]
        organization = ["SPIRE"]
        common_name = ""
    }
}

telemetry {
    Prometheus {
        port = 1234
        # optional TLS for prometheus
        tls {
            use_spire_svid = true
            authorized_spiffe_ids = [
                "spiffe://example.org/monitoring/prometheus",
            ]

            # Alternatively, configure a web certificate directly:
            # cert_file = "/path/to/cert.pem"
            # key_file = "/path/to/key.pem"
            # client_ca_file = "/path/to/ca.pem"
        }
    }
}

plugins {
    DataStore "sql" {
        plugin_data {
            database_type = "sqlite3"
            connection_string = "/opt/spire/.data/datastore.sqlite3"
        }
    }
    NodeAttestor "join_token" {
        plugin_data {}
    }
    KeyManager "disk" {
        plugin_data {
            keys_path = "/opt/spire/.data/keys.json"
        }
    }
}

SPIRE Server 配置参考 ​

插件类型(Plugin types) ​

内置插件 ​

服务端配置文件 ​

Profiling 名称 ​

插件配置 ​

示例 ​

使用静态配置的内置插件 ​

使用动态配置的外部插件 ​

重新配置插件(仅 Posix) ​

联邦(Federation)配置 ​

federation.bundle_endpoint 的配置选项 ​

federation.bundle_endpoint.profile 的配置选项 ​

federation.bundle_endpoint.profile "https_web".acme 的配置选项 ​

federation.bundle_endpoint.profile "https_web".serving_cert_file 的配置选项 ​

federation.bundle_endpoint.profile "https_spiffe" 的配置选项 ​

federation.federates_with["<trust domain>"].bundle_endpoint 的配置选项 ​

遥测(Telemetry)配置 ​

健康检查(Health check)配置 ​

命令行选项 ​

spire-server run ​

将 SPIRE Server 作为 Windows 服务运行 ​

创建 SPIRE Server Windows 服务的示例 ​

运行 SPIRE Server Windows 服务的示例 ​

spire-server token generate ​

spire-server entry create ​

spire-server entry update ​

spire-server entry count ​

spire-server entry delete ​

spire-server entry show ​

spire-server bundle count ​

spire-server bundle show ​

spire-server bundle list ​

spire-server bundle set ​

spire-server bundle delete ​

spire-server federation create ​

spire-server federation delete ​

spire-server federation list ​

spire-server federation refresh ​

spire-server federation show ​

spire-server federation update ​

spire-server agent ban ​

spire-server agent count ​

spire-server agent evict ​

spire-server agent list ​

spire-server agent show ​

spire-server healthcheck ​

spire-server logger get ​

spire-server logger set ​

spire-server logger reset ​

spire-server validate ​

spire-server x509 mint ​

spire-server jwt mint ​

spire-server localauthority jwt activate ​

spire-server localauthority jwt prepare ​

spire-server localauthority jwt revoke ​

spire-server localauthority jwt show ​

spire-server localauthority jwt taint ​

spire-server localauthority x509 activate ​

spire-server localauthority x509 prepare ​

spire-server localauthority x509 revoke ​

spire-server localauthority x509 show ​

spire-server localauthority x509 taint ​

spire-server upstreamauthority revoke ​

spire-server upstreamauthority taint ​

-data 所用的 JSON 对象 ​

示例配置文件 ​

延伸阅读 ​