144 lines
4.1 KiB
Markdown
144 lines
4.1 KiB
Markdown
# Deployment Guide
|
|
|
|
Kubernetes deployment of Guildhouse SPIRE plugins.
|
|
|
|
## Prerequisites
|
|
|
|
- SPIRE Server and Agent deployed (v1.9+)
|
|
- Guildhouse Quartermaster services running (GovernanceService, NotaryService)
|
|
- Guildhouse Bascule services running (CeremonyService)
|
|
- mTLS connectivity between SPIRE and Guildhouse services via SPIFFE
|
|
|
|
## Plugin Distribution
|
|
|
|
Plugin binaries are packaged as a container image:
|
|
|
|
```
|
|
ghcr.io/guildhouse-cooperative/spire-plugins:latest
|
|
```
|
|
|
|
The image contains:
|
|
```
|
|
/plugins/
|
|
oidc-attestor
|
|
ssh-credential-composer
|
|
governance-notifier
|
|
substrate-keymanager
|
|
```
|
|
|
|
## Installation via Kustomize
|
|
|
|
Apply the overlay in `deploy/kustomization.yaml` on top of your SPIRE deployment:
|
|
|
|
```bash
|
|
kubectl apply -k deploy/
|
|
```
|
|
|
|
This patches the SPIRE Server and Agent Deployments to:
|
|
1. Add an init container that copies plugin binaries to a shared volume
|
|
2. Mount the plugin directory into the SPIRE containers
|
|
|
|
## SPIRE Server Configuration
|
|
|
|
Add plugin blocks to your SPIRE Server configuration (`server.conf`):
|
|
|
|
```hcl
|
|
plugins {
|
|
KeyManager "guildhouse_substrate" {
|
|
plugin_cmd = "/opt/spire/plugins/substrate-keymanager"
|
|
plugin_data {
|
|
trust_domain = "guildhouse.example.org"
|
|
governance_addr = "governance.quartermaster.svc.cluster.local:50051"
|
|
notary_addr = "notary.quartermaster.svc.cluster.local:50051"
|
|
cluster_id = "guildhouse-prod"
|
|
}
|
|
}
|
|
|
|
CredentialComposer "guildhouse_ssh" {
|
|
plugin_cmd = "/opt/spire/plugins/ssh-credential-composer"
|
|
plugin_data {
|
|
trust_domain = "guildhouse.example.org"
|
|
governance_addr = "governance.quartermaster.svc.cluster.local:50051"
|
|
default_cert_ttl = "5m"
|
|
max_cert_ttl = "1h"
|
|
}
|
|
}
|
|
|
|
Notifier "guildhouse_governance" {
|
|
plugin_cmd = "/opt/spire/plugins/governance-notifier"
|
|
plugin_data {
|
|
governance_addr = "governance.quartermaster.svc.cluster.local:50051"
|
|
ceremony_addr = "ceremony.bascule.svc.cluster.local:50052"
|
|
notary_addr = "notary.quartermaster.svc.cluster.local:50051"
|
|
cluster_id = "guildhouse-prod"
|
|
trust_domain = "guildhouse.example.org"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## SPIRE Agent Configuration
|
|
|
|
Add the OIDC attestor to your SPIRE Agent configuration (`agent.conf`):
|
|
|
|
```hcl
|
|
plugins {
|
|
WorkloadAttestor "guildhouse_oidc" {
|
|
plugin_cmd = "/opt/spire/plugins/oidc-attestor"
|
|
plugin_data {
|
|
issuer = "https://keycloak.guildhouse.example.org/realms/platform"
|
|
audience = "spire"
|
|
token_path = "/var/run/secrets/oidc/token"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## RBAC
|
|
|
|
The SPIRE Server ServiceAccount needs access to read Kubernetes Secrets (for webhook secrets) and ConfigMaps (for Accord policy):
|
|
|
|
```yaml
|
|
apiVersion: rbac.authorization.k8s.io/v1
|
|
kind: ClusterRole
|
|
metadata:
|
|
name: spire-server-guildhouse
|
|
rules:
|
|
- apiGroups: [""]
|
|
resources: ["secrets"]
|
|
verbs: ["get"]
|
|
resourceNames: ["guildhouse-governance-certs"]
|
|
- apiGroups: [""]
|
|
resources: ["configmaps"]
|
|
verbs: ["get", "list", "watch"]
|
|
```
|
|
|
|
## mTLS Configuration
|
|
|
|
Plugins authenticate to Guildhouse services using the SPIRE Server's own SVID. The plugin inherits the server's SPIFFE identity and uses it for mTLS.
|
|
|
|
No additional certificate configuration is needed — the plugin obtains its mTLS credentials from the SPIRE Server's Workload API socket.
|
|
|
|
## Health Checks
|
|
|
|
Each plugin logs its health status at startup. Monitor SPIRE Server logs for:
|
|
|
|
```
|
|
level=info msg="guildhouse_ssh: connected to GovernanceService"
|
|
level=info msg="guildhouse_governance: connected to CeremonyService"
|
|
level=info msg="guildhouse_substrate: key manager initialized"
|
|
```
|
|
|
|
Plugin failures surface as SPIRE Server errors during credential minting or event notification.
|
|
|
|
## Environment Variables
|
|
|
|
Plugins read configuration from HCL `plugin_data` blocks. No environment variables are required. The SPIRE plugin framework passes configuration directly.
|
|
|
|
## Upgrading
|
|
|
|
To upgrade plugins:
|
|
1. Build new plugin container image
|
|
2. Update image tag in `deploy/kustomization.yaml`
|
|
3. Restart SPIRE Server and Agent pods
|
|
4. SPIRE reloads plugins on startup
|