Enroll

expanso-edge enroll

Enroll your edge node directly with an orchestrator

Synopsis

Enroll your edge node directly with an Expanso orchestrator.

This is the direct node enrollment path: the orchestrator validates the node's identity proof and returns the connection details, which are persisted to your data directory.

The legacy cloud bootstrap flow is still supported, but it is not the recommended path for new deployments.

What Happens:

1. The agent generates (or loads) its local identity keypair (Ed25519).
2. It presents the proof as a credential to the orchestrator, which verifies it against the trust anchor (bootstrap token, x509 CA, or OIDC issuer).
3. The orchestrator assigns a node ID, derives the workspace, and returns the connection details, which are written to your data directory.
4. Run 'expanso-edge run' to connect.

Enrolling Without A Bootstrap Token:

Instead of a bootstrap token, enroll with a customer x509 certificate, an OIDC JWT, an AWS instance identity document, an Azure IMDS attested document, or a GCP instance identity token, validated against a trust anchor configured on the orchestrator. No bootstrap token is needed.

x509_ca: select with --enrollment-source x509_ca and pass --source-id, --cert, and --key (or set the 'enrollment.x509' config block). oidc_issuer: config-driven (its provider settings have no flag surface). Set 'enrollment.oidc.provider' to one of: kubernetes (projected service-account token file), client_credentials (OAuth2 token endpoint), azure (IMDS managed identity), or gcp (instance identity token). For client_credentials the client secret is read from the env var named by 'client_secret_env' -- never from config. aws_iid: select with --enrollment-source aws_iid and pass --source-id (run on an EC2 instance). The instance identity document is fetched from IMDS automatically; the optional 'enrollment.aws_iid' config block only tunes IMDS (allow_imdsv1, token_ttl_seconds, endpoint, document_path). azure_msi: select with --enrollment-source azure_msi and pass --source-id (run on an Azure VM). The IMDS attested document is fetched automatically; the optional 'enrollment.azure_msi' config block only tunes IMDS (api_version, nonce, endpoint). gcp_iit: select with --enrollment-source gcp_iit and pass --source-id (run on a GCE instance). The instance identity token is fetched from the metadata server automatically; the 'enrollment.gcp_iit' config block supplies the required 'audience' (matching the trust anchor) plus an optional 'endpoint' override.

Examples:

Enroll with a new orchestrator-only bootstrap token

expanso-edge enroll --token exp_obk_... --orchestrator https://orch.example.com

Force re-enroll (mint a fresh token first)

expanso-edge enroll --token exp_obk_... --orchestrator https://orch.example.com --force

Enroll with a customer x509 certificate

expanso-edge enroll --enrollment-source x509_ca --source-id <anchor-id>
--cert /etc/expanso/identity/cert.pem --key /etc/expanso/identity/key.pem
--orchestrator https://orch.example.com

Enroll with OIDC (config-driven -- providers have no flag surface):

enrollment:

source_type: oidc_issuer

source_id: <anchor-id>

oidc:

provider: kubernetes

token_path: /var/run/secrets/tokens/expanso

expanso-edge enroll --orchestrator https://orch.example.com --config /etc/expanso/edge.yaml

Enroll with an AWS instance identity document (run on an EC2 instance)

expanso-edge enroll --enrollment-source aws_iid --source-id <anchor-id>
--orchestrator https://orch.example.com

Enroll with an Azure IMDS attested document (run on an Azure VM)

expanso-edge enroll --enrollment-source azure_msi --source-id <anchor-id>
--orchestrator https://orch.example.com

Enroll with a GCP instance identity token (run on a GCE instance;

set enrollment.gcp_iit.audience in config to match the trust anchor)

expanso-edge enroll --enrollment-source gcp_iit --source-id <anchor-id>
--orchestrator https://orch.example.com

expanso-edge enroll [flags]

Options

      --cert string                x509_ca: PEM cert chain path (overrides config)
  -c, --config strings             Paths to configuration files or directories
      --data-dir string            Data directory path
      --enrollment-source string   Enrollment source type: bootstrap_token (default), x509_ca, oidc_issuer, aws_iid, azure_msi, or gcp_iit
  -f, --force                      Re-attempt enrollment even if local config shows the node is already enrolled (identity is bound to the keypair; an existing node returns its existing identity)
  -h, --help                       help for enroll
  -k, --insecure                   Skip TLS certificate verification
      --key string                 x509_ca: PEM private key path (overrides config)
  -o, --orchestrator string        Orchestrator base URL
      --source-id string           Trust-anchor id (required for every source except bootstrap_token)
  -t, --token string               Bootstrap token (exp_obk_...); for the bootstrap_token source

Options inherited from parent commands

  -v, --verbose   Enable verbose logging

SEE ALSO

• expanso-edge - Expanso Edge - Autonomous edge computing agent