Pair Kerrigan with a Cloud Environment

Cloud pairing gives a Kerrigan appliance a dedicated AWS IoT identity without moving its private key off the host. A local administrator starts the request from Kerrigan, an authorized backoffice operator approves the displayed activation code, and Kerrigan installs the returned certificate after verifying that it matches the locally generated key.

Pairing is optional. It enables the Cloud API, but it is not required for local operation. Kerrigan's Admin Console and local REST API remain reachable only to controllers with direct network access to the Kerrigan admin interface; cloud control does not expose or proxy that interface.

Pairing flow

The activation code authorizes one pending request; it is not a credential for the appliance. Kerrigan stores the private key locally with restricted file permissions and sends only a certificate signing request (CSR) to the selected cloud environment.

Before you begin

You need:

• administrator access to the Kerrigan Admin Console or shell;
• a configured HTTPS pairing endpoint for the selected environment; and
• a backoffice identity authorized to invoke that environment's pairing claim route.

Kerrigan presents Vulcan Staging, Vulcan Prod, Arthas Staging, and Arthas Prod as possible targets. A target is selectable only when its pairing endpoint is configured. All four targets have bundled pairing endpoints. An unset endpoint override or the value default uses the bundled endpoint; an explicitly empty override disables that target. Existing installations with an empty KERRIGAN_VULCAN_PAIRING_PRODUCTION_URL=, KERRIGAN_ARTHAS_PAIRING_STAGING_URL= or KERRIGAN_ARTHAS_PAIRING_PRODUCTION_URL= must change that setting to default and recreate the Fleet Manager container after upgrading to expose that target. Custom HTTPS endpoint overrides remain supported.

Selecting a target does not migrate an appliance automatically. The existing cloud profile stays active until an administrator approves the new pairing. Vulcan staging and production profiles can enable peer pairing when the approved profile includes P2P endpoints and target authorization. The appliance must run this production-aware Fleet Manager version, and the user client must accept production allocation profiles. A configuration upgrade does not pair an appliance or qualify end-to-end production transport; device validation remains required.

Pair from the Admin Console

1. Open the local Kerrigan Admin Console and sign in as an administrator.
2. Open System, then Cloud.
3. Under Cloud pairing, select an available environment and enter a stable, human-readable cluster name such as lab-2.
4. Select Get activation code.
5. Use Copy code and send the code to the authorized backoffice operator through your approved communication channel.
6. Wait for automatic polling, or select Check approval after the operator completes the claim.

The panel changes to paired after Kerrigan validates and atomically installs the new cloud profile. You can close the page while approval is pending; pairing state is persisted locally.

Pair from the Ubuntu host CLI

Run pairing through kerrigan-ubuntu-stack on the Kerrigan host. The wrapper is installed with the Kerrigan Ubuntu host package and runs the pairing command in the Fleet Manager container, using the appliance's persistent configuration and credential storage.

List the targets and their configuration status:

sudo kerrigan-ubuntu-stack pair environments

Start pairing and wait for approval:

sudo kerrigan-ubuntu-stack pair start \
  --environment vulcan-staging \
  --cluster-name lab-2

In an interactive terminal, omit --environment to select from a menu. Use --no-wait when you want to display the code and poll separately:

sudo kerrigan-ubuntu-stack pair status
sudo kerrigan-ubuntu-stack pair poll
sudo kerrigan-ubuntu-stack pair cancel

Interactive Ubuntu installation also offers pairing during onboarding. The local installation remains usable if pairing is skipped or the cloud service is unavailable.

Complete approval in the cloud

For Vulcan production, select Vulcan Prod in the local Cloud panel, or run:

sudo kerrigan-ubuntu-stack pair start \
  --environment vulcan-production \
  --cluster-name lab-2

A production NeatOps administrator completes approval at ops.neat.sima.ai using the activation code.

For Arthas production, select Arthas Prod or pass --environment arthas-production; an Arthas operator completes approval in the Arthas console using the activation code. Arthas refuses a cluster name that contains a dot. Staging and production use separate identities; a staging administrator role does not authorize production approval. Production integrations can also claim through the IAM-protected HTTPS contract. For staging validation, the optional Cloud Control CLI can act as the backoffice client:

AWS_PROFILE=vulcan-stg \
  kerrigan-cloud-control-cli claim-pairing \
  AAAQE-AYEAU-DAOCA-JBIFQ-YDIOB-4

The CLI derives the built-in pairing URL from the AWS environment. Its claim-pairing command is a validation and troubleshooting convenience, not a required component of cloud integration. See Cloud Control CLI.

Change or cancel pairing

An administrator can start a replacement from System > Cloud > Change cloud pairing, or run sudo kerrigan-ubuntu-stack pair start again when no request is pending. Kerrigan keeps the active cloud profile in service while the new request awaits approval. It replaces the profile only after the returned certificate passes validation, so a cancelled, expired, or failed request does not disrupt the current connection.

Only one pending request is allowed. Cancel it before starting another:

sudo kerrigan-ubuntu-stack pair cancel

The current implementation does not automatically revoke the previous AWS IoT certificate after re-pairing. An authorized operator should retire the obsolete identity after confirming the replacement is healthy:

AWS_PROFILE=vulcan-stg \
  kerrigan-cloud-control-cli delete-system \
  <old-immutable-cluster-id>

Security model

Control	Behavior
Appliance key	Kerrigan generates an RSA-3072 private key locally and never uploads it.
Activation code	The service generates a 128-bit random Base32 code, stores only its SHA-256 verifier, and accepts it once.
Polling	Kerrigan receives a separate high-entropy poll token; the local REST API never returns that token.
Expiration	Pending requests expire after the service-configured TTL, currently 10 minutes in Vulcan Staging.
Cloud approval	The claim route requires AWS IAM authorization and uses a conditional state transition to prevent duplicate claims.
Edge protection	The public request and polling routes use HTTPS and are protected by AWS WAF managed rules, source rate limiting, and bounded Lambda concurrency.
Certificate install	Kerrigan verifies the certificate belongs to its local private key and matches the selected environment before an atomic profile replacement.
Secret handling	Pairing state and key files use restricted permissions; application and WAF sampling logs exclude codes, tokens, CSRs, and certificates.

Treat an activation code as short-lived sensitive data. Do not put it in issue trackers, persistent chat history, shell scripts, or logs. The WAF and rate limits reduce abuse, but they do not replace IAM authorization on the claim operation.

Pairing service contract

Operation	Authentication	Purpose
POST /v1/pairings	Public HTTPS behind WAF	Submit a CSR and receive the pairing ID, activation code, poll token, and expiration.
GET /v1/pairings/{pairing_id}	x-pairing-token	Read approval status and retrieve the approved certificate profile.
DELETE /v1/pairings/{pairing_id}	x-pairing-token	Cancel a pending request.
POST /v1/pairings/claim	AWS IAM	Claim a code once and provision the AWS IoT Thing and certificate.

These are cloud pairing-service endpoints, not Kerrigan's local admin REST API. Appliance and backoffice clients should use their documented commands instead of manually constructing requests.

Troubleshooting

• Environment is disabled: its pairing URL is not configured on this Kerrigan host. Check the relevant KERRIGAN_*_PAIRING_*_URL setting. Set it to default to use the bundled endpoint (available for Vulcan Staging), or supply a custom HTTPS URL. An explicit empty value disables the choice. Recreate Fleet Manager to load environment changes.
• A request already exists: check sudo kerrigan-ubuntu-stack pair status, then poll it or cancel it before starting another.
• The code expired: cancel the local request and generate a new code.
• Claim is rejected: confirm the AWS profile selects the same environment shown by Kerrigan and has execute-api:Invoke permission for the claim route.
• Approval succeeds but Kerrigan stays pending: use Check approval or sudo kerrigan-ubuntu-stack pair poll, then inspect Fleet Manager logs for certificate or network validation errors.
• An old system remains visible: wait for its reported state to become stale, then retire it with delete-system; use --force only when intentionally deleting an identity that still appears current.

For endpoint configuration, see Configuration.