Executor Enrollment

Executor enrollment establishes secure mTLS connections between executors (workers) and the access point (control plane). This guide covers identity provider configuration for production deployments.

Overview

Agent Harbor supports multiple identity providers for executor authentication:

Provider	Use Case	Complexity
Files	Development, manual PKI	Low
SPIFFE	Production with SPIRE	Medium
Vault	Enterprise PKI with HashiCorp Vault	Medium
Exec	Custom PKI integrations	Variable

Quick Start

For local development, the default dev identity provider works out of the box:


# Access point (control plane)
ah agent access-point --fleet-listen 127.0.0.1:4433
 
# Executor (worker) - dev mode uses self-signed certs
ah agent enroll --remote-server https://127.0.0.1:4433 --name worker-1

Production Identity Providers

For production deployments, configure a proper identity provider:

Files Provider (Manual PKI)

Use existing X.509 certificates from your PKI:


ah agent enroll \
  --remote-server https://access-point.example.com:4433 \
  --identity files \
  --cert /etc/ah/executor.pem \
  --key /etc/ah/executor-key.pem \
  --ca /etc/ah/ca.pem

See Files Provider Guide for certificate generation instructions.

SPIFFE Provider (Recommended)

Use SPIRE for automatic SVID provisioning:


ah agent enroll \
  --remote-server https://access-point.example.com:4433 \
  --identity spiffe \
  --spiffe-socket /run/spire/agent.sock \
  --expected-server-id spiffe://example.org/ah/serve

See SPIFFE Deployment Guide for SPIRE setup.

Vault Provider (Enterprise)

Use HashiCorp Vault PKI secrets engine:


ah agent enroll \
  --remote-server https://access-point.example.com:4433 \
  --identity vault \
  --vault-addr https://vault.example.com:8200 \
  --vault-pki-path pki_int/issue/executor

See Vault Integration Guide for Vault PKI configuration.

Exec Provider (Custom)

Run a custom script to obtain certificates:


ah agent enroll \
  --remote-server https://access-point.example.com:4433 \
  --identity exec \
  --exec-command /usr/local/bin/get-executor-cert.sh

See Exec Provider Guide for script interface specification.

Access Point Configuration

The access point must also be configured with a server identity:


ah agent access-point \
  --fleet-listen 0.0.0.0:4433 \
  --server-identity spiffe \
  --spiffe-socket /run/spire/agent.sock \
  --executor-san-uri-prefix "spiffe://example.org/ah/agent/"

Server Identity Options

dev - Self-signed certificate for development
files - Load certificate from files
spiffe - Fetch SVID from SPIRE Workload API

Executor Validation

The access point validates executor certificates using:

--executor-san-uri-prefix - SPIFFE ID prefix (e.g., spiffe://example.org/ah/agent/)
--executor-san-dns - DNS SAN allowlist
--executor-san-ip - IP SAN allowlist

Certificate Rotation

All identity providers support automatic certificate rotation:

Files: Watches certificate files for changes (inotify/kqueue)
SPIFFE: Subscribes to SVID updates from Workload API
Vault: Renews before TTL expiry
Exec: Runs command periodically based on --exec-refresh-interval

Rotation is seamless - existing connections continue while new connections use fresh certificates.

Troubleshooting

Common enrollment issues:

Error	Cause	Solution
`certificate expired`	Clock skew or expired cert	Sync system time, renew cert
`certificate verify failed`	CA mismatch	Ensure executor trusts access point CA
`connection refused`	Firewall or service down	Check port 4433 is open
`SPIFFE ID mismatch`	Wrong trust domain	Check trust domain configuration

See Troubleshooting Guide for detailed diagnostics.

Security Considerations

Certificate TTL: Use short-lived certificates (hours, not days)
Private Key Protection: Store keys with 0600 permissions
Trust Domain Isolation: Use separate trust domains for dev/staging/prod
Audit Logging: Enable enrollment audit logs for compliance

Next Steps

Files Provider Guide - Manual PKI setup
SPIFFE Deployment Guide - SPIRE configuration
Vault Integration Guide - Enterprise PKI
Troubleshooting Guide - Common issues