Issues SPIFFE identities to the platform workloads: SPIRE servers sign the SVIDs, a SPIRE agent on each host attests the node with its manager certificate and serves the workload API.
Generated from catalog/services/spire.yaml: do not edit by hand.
Summary
| |
|---|
| Version | 1.15.5 |
| Use | install and configure, configure and connect |
| Layer | functional (AI catalog) |
| Category | Identity and secrets |
| Installation methods | binary |
| External connection | no |
| Sandbox only | no |
Licence
| |
|---|
| SPDX identifier | Apache-2.0 |
| Licence policy | core licence (MIT or Apache-2.0) |
| Licence exception | - |
| Platform component | spire |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|
binary | RHEL family (dnf), Debian family (apt), Arch Linux (pacman) | x86_64 (architecture of the artifacts of the descriptor) |
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
- a synchronized clock (blocking,
time_sync).
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|
spire-server | grpc | 8081/tcp | yes |
spire-server | bundle | 8443/tcp | yes |
spire-server | health | 8080/tcp | no |
spire-server | metrics | 9988/tcp | yes |
spire-agent | health | 8089/tcp | no |
spire-agent | metrics | 9989/tcp | yes |
Services and connections needed
Details and resolution: see Dependencies.
Installation methods and modes
| Method | Default | What the method uses |
|---|
binary | yes | the binary archives of the descriptor, unpacked under the service directory |
Components
| Component | Kind | Installation methods | Ports |
|---|
SPIRE server (spire-server) | master | binary | 8081/tcp, 8443/tcp, 8080/tcp, 9988/tcp |
SPIRE agent (spire-agent) | worker | binary | 8089/tcp, 9989/tcp |
Single server (standalone) (default)
One SPIRE server with a local SQLite datastore, agents on any host.
What the mode deploys:
| Component | Placement |
|---|
spire-server | min 1, max 1 |
spire-agent | min 0 |
High availability (ha)
Three SPIRE servers sharing a PostgreSQL datastore.
What the mode deploys:
| Component | Placement |
|---|
spire-server | min 3, max 3 |
spire-agent | min 0 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select SPIRE. The card shows the licence Apache-2.0 and the dependencies the installation needs.
-
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: standalone (default), ha. Each mode deploys the components listed in Installation methods and modes. With several components, place each one on its hosts in Component placement (Suggest placement proposes a placement that respects the cardinalities).
-
Bind the dependencies. On the Bindings step, choose for each dependency (datastore) Install with the platform or Use an existing connection; an optional dependency can stay on No binding.
-
Configure. On the Configure step, review the parameters (see Configuration parameters); the required ones are trust_domain. Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
Connect an existing service
| |
|---|
| Schemes | https |
| Default port | 8081 |
| Authentication | none |
| Health check | health_url + /ready |
| Authentication method | Fields | Description |
|---|
none | - | The SPIRE server API is reached over mutual TLS with the SPIFFE identities it issues itself; the Manager only checks its health endpoint. |
Official documentation: https://spiffe.io/docs/latest/deploying/spire_server/
| Field | Type | Default | Description | Notes |
|---|
Health endpoint URL (health_url) | url | - | Health endpoint URL of the existing service. | required |
Trust domain (trust_domain) | string | - | Trust domain used by the platform. | required |
High availability
| |
|---|
| Cluster | replicas (replication) |
| High availability | external (external) |
| Failover | load balancer (load-balancer) |
| Replication | shared store (shared-store) |
| Quorum | none (none) |
| Discovery | none (none) |
| Entry point | load balancer (load-balancer) |
| Official documentation | https://spiffe.io/docs/latest/planning/scaling_spire/ |
Prerequisites
| Prerequisite | Must be highly available | Modes | Description |
|---|
datastore | yes | ha | Highly available PostgreSQL shared by the servers (MySQL is also supported upstream). |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|
standalone | standalone (standalone) | single (single) | - | 1 | One server with a local SQLite datastore, agents on any host. |
ha | ha (ha) | active-active (active-active) | - | 3 | Three servers sharing a PostgreSQL datastore; one agent per host. |
Notes
- The agents keep serving the identities already issued while the servers are unreachable, until the certificates expire.
Configuration parameters
Trust domain
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Trust domain (trust_domain) | string | navin.internal | ^[a-z0-9._-]+$ | yes | no | yes | SPIFFE trust domain (spiffe://<domain>/...). |
CA lifetime (ca_ttl) | duration | 24h | - | no | no | no | Lifetime of the signing CA of the servers. |
SVID lifetime (svid_ttl) | duration | 1h | - | no | no | no | Default lifetime of an X.509 SVID. |
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Server port (server_port) | port | 8081 | - | no | no | yes | gRPC port reached by the agents. |
Bundle endpoint port (bundle_port) | port | 8443 | - | no | no | yes | HTTPS port serving the trust bundle to the agents at bootstrap (certificate of the manager CA). |
Server health port (server_health_port) | port | 8080 | - | no | no | no | Port of /live and /ready of the server. |
Server metrics port (server_metrics_port) | port | 9988 | - | no | no | no | Prometheus port of the server. |
Agent health port (agent_health_port) | port | 8089 | - | no | no | no | Port of /live and /ready of the agent. |
Agent metrics port (agent_metrics_port) | port | 9989 | - | no | no | no | Prometheus port of the agent. |
Certificates of the manager CA (tls_enabled) | bool | true | - | no | no | yes | Issue a certificate of the manager CA to every server and agent: the bundle endpoint serves it and the agents attest their node with it (x509pop). Keep it on: SPIRE does not start without these certificates. |
Server address of the agents (server_address) | string | (empty) | ^([A-Za-z0-9.-]{1,253})?$ | no | no | no | Name of the load balancer in front of the SPIRE servers (ha mode), forwarding the server port; empty: the first server. The agents download the trust bundle from the first server at bootstrap only. |
Logging
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Log level (log_level) | enum | INFO | DEBUG, INFO, WARN, ERROR | no | no | no | Verbosity of the server and agent logs. |
Dependencies
For each active dependency the Manager takes the first of: the binding chosen in the wizard; a service of the same installation that provides it; a service already installed in the cluster; the only connection of the expected type. Otherwise an optional dependency stays unbound, and a required one is added to the installation in its default mode (the column below names the catalog service added).
| Binding | Provided by | Connection type | Endpoint | Optional | When nothing is bound | Description |
|---|
datastore (ha) | postgresql | postgresql | sql | no | postgresql is added to the installation | Shared datastore of the three SPIRE servers. |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|
server | tcp | spire-server | 8081 (server_port) | - | tls_enabled | - | - | - |
Client configuration files
Files rendered for the client configuration download:
spire.env (client.env.j2)
Commands
| Command | Component | Target | Description |
|---|
Server health (healthcheck) | spire-server | every host | Runs spire-server healthcheck on every server. |
List the agents (list_agents) | spire-server | first host | Lists the attested agents. |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|
spire-server | HTTP http://127.0.0.1:{{ config.server_health_port }}/ready | Expected 200; 30 retries; interval 2 s; timeout 3 s |
spire-agent | HTTP http://127.0.0.1:{{ config.agent_health_port }}/ready | Expected 200; 30 retries; interval 2 s; timeout 3 s |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|
server_port_free | port_free {"param": "server_port"} | port 8081 free on the host | blocking | spire-server |
time_sync | time_sync {} | a synchronized clock | blocking | every component |
Uninstall
Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.
Upstream documentation