# 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