Bootstrap Certificate Management¶

Overview¶

This guide covers operational procedures for the bootstrap certificate used by cluster-sensor-service for its platform discovery-sensor registration.

Certificate Generation¶

Initial Setup¶

Generate the platform bootstrap CA (one-time operation):

./scripts/generate-bootstrap-ca.sh

This creates: - Platform bootstrap CA certificate and encrypted private key (stored in database) - CA certificate available for service configuration

Generate Service Certificates¶

Generate the bootstrap certificate:

./scripts/generate-bootstrap-certificates.sh

This creates a certificate for cluster-sensor-service.

Certificates are stored in: - Database: platform_bootstrap_certificates table - Filesystem: ./bootstrap-certs/ directory

Certificate Files¶

After generation, the following files are created:

bootstrap-certs/
├── cluster-sensor-service-cert.pem
├── cluster-sensor-service-key.pem
└── bootstrap-ca-cert.pem

The platform device-interrogation worker uses its database-provisioned system sensor identity and needs no bootstrap certificate. Operator-installed device agents receive tenant certificates through their enrollment flow.

Deployment¶

Development Environment¶

Certificates are not generated automatically — ./scripts/bootstrap-env.sh only writes .env. Run the two scripts above yourself, once:

./scripts/generate-bootstrap-ca.sh
./scripts/generate-bootstrap-certificates.sh

Bootstrap CA is created if it doesn't exist
Bootstrap certificates are generated for services
Certificates are mounted into containers via docker-compose.yml

Skipping this step is fine — cluster-sensor-service detects the missing bootstrap cert at startup, logs an informational message, and skips auto-registration silently rather than crashing.

Docker Compose "production-style" stack¶

Generate Certificates:

./scripts/generate-bootstrap-ca.sh
./scripts/generate-bootstrap-certificates.sh

Store Certificates Securely:
Use secrets manager (AWS Secrets Manager, HashiCorp Vault)
Store in encrypted storage
Never commit to version control

Set Permissions:

chmod 755 bootstrap-certs
chmod 600 bootstrap-certs/*.pem

For a real production deployment, use the Kubernetes (Helm chart) path below instead.

Kubernetes (Helm chart) Environment¶

The chart does not yet ship a built-in bootstrapCerts Secret/mount feature. If the bootstrap cert isn't mounted into the cluster-sensor-service pod, the service detects this at startup, logs an informational message, and skips auto-registration silently — it does not crash. Tenants in this state must be registered manually through the Tenant Admin UI's sensor-onboarding flow.

If you want auto-registration on K8s, provide the certs to the pod via a customer-owned overlay:

Create a Kubernetes Secret in the release namespace containing the four PEM files at /app/bootstrap-certs/:

kubectl -n <release-ns> create secret generic cluster-sensor-bootstrap \
  --from-file=cluster-sensor-service-cert.pem \
  --from-file=cluster-sensor-service-key.pem \
  --from-file=bootstrap-ca-cert.pem

In your values-customer.yaml, attach the Secret to the service via extraVolumes / extraVolumeMounts on backends.cluster-sensor-service (read-only, mode 0600). Use a stricter defaultMode (e.g. 0400) for long-lived environments.
Re-deploy. The startup log should now read 🔄 Registering platform discovery sensor for all tenants... instead of ℹ️ Bootstrap cert not present...; skipping auto-registration.

A native chart-level setting for this is tracked as a follow-up.

Certificate Rotation¶

When to Rotate¶

Before expiration (bootstrap certs expire in 90 days)
After security incident
During scheduled maintenance

Rotation Procedure¶

Generate New Certificates:

./scripts/generate-bootstrap-certificates.sh

Update Certificate Files:
Replace old certificate files in ./bootstrap-certs/
Update secrets manager if used

Restart Services:

docker compose restart cluster-sensor-service device-interrogation-service

Verify Registration:
Check service logs for successful registration
Verify services are using new certificates

CA Rotation¶

If the platform bootstrap CA needs to be rotated:

Generate New CA:

# This will mark old CA as inactive and create new one
go run scripts/initialize-bootstrap-ca.go \
  -db-url "$DATABASE_URL" \
  -encryption-key "$ENCRYPTION_MASTER_KEY" \
  -action rotate-ca

Regenerate All Certificates:

./scripts/generate-bootstrap-certificates.sh

Update Services:
Restart all platform services
Verify new certificates work

Certificate Revocation¶

Revoke Compromised Certificate¶

If a bootstrap certificate is compromised:

# Using Go program
go run scripts/initialize-bootstrap-ca.go \
  -db-url "$DATABASE_URL" \
  -encryption-key "$ENCRYPTION_MASTER_KEY" \
  -action revoke-cert \
  -service-name "cluster-sensor-service" \
  -reason "compromised"

Or directly in database:

UPDATE platform_bootstrap_certificates
SET revoked_at = NOW(),
    revocation_reason = 'compromised'
WHERE service_name = 'cluster-sensor-service';

After Revocation¶

Generate New Certificate:

./scripts/generate-bootstrap-certificates.sh

Update Certificate Files:
Replace revoked certificate
Restart affected service
Verify:
Check service can register with new certificate
Verify old certificate is rejected

Monitoring¶

Certificate Expiration Monitoring¶

Check certificate expiration dates:

SELECT service_name, expires_at, 
       expires_at - NOW() as days_until_expiration
FROM platform_bootstrap_certificates
WHERE revoked_at IS NULL
ORDER BY expires_at;

Alert on Expiration¶

Set up alerts for certificates expiring within 30 days:

SELECT service_name, expires_at
FROM platform_bootstrap_certificates
WHERE revoked_at IS NULL
  AND expires_at < NOW() + INTERVAL '30 days';

Troubleshooting¶

Certificate Not Found¶

Symptoms: Service fails to start, certificate file not found

Solutions: 1. Verify certificate files exist in ./bootstrap-certs/ 2. Check volume mount in docker-compose.yml 3. Regenerate certificates if missing 4. Verify file permissions

Certificate Validation Fails¶

Symptoms: Service registration fails with certificate validation error

Solutions: 1. Verify certificate is signed by platform bootstrap CA 2. Check certificate expiration date 3. Verify certificate is not revoked 4. Check CA certificate matches database

Service Cannot Register¶

Symptoms: Auto-registration endpoint returns 401 Unauthorized

Solutions: 1. Verify bootstrap certificate is valid 2. Check service name in certificate CN 3. Verify sensor-manager can access bootstrap CA 4. Check encryption key is correct

Security Best Practices¶

Certificate Storage:
Store certificates securely (secrets manager in production)
Use restricted file permissions (600 for keys, 644 for certs)
Never commit certificates to version control
Certificate Rotation:
Rotate before expiration
Rotate after security incidents
Document rotation procedures
Access Control:
Limit access to certificate generation scripts
Restrict database access to bootstrap CA tables
Monitor certificate operations
Audit:
Log certificate generation events
Track certificate usage
Monitor for suspicious activity

Certificate Management - General certificate management