cluster.register-kubernetes-connection

Persist a generated Kubernetes credential payload as a Kubernetes CloudConnection.

Persist generated Kubernetes credentials as a Kubernetes CloudConnection.

Overview

Property	Value
Workflow type	Linear
Library	App-clusters
Version	1.0

Input Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	Yes	—	Organization UUID for tenant isolation.
cluster_uuid	uuid	No	—	Existing logical cluster UUID when registration is retried.
cluster_name	string	Yes	—	Human-friendly cluster name.
provider	string	Yes	—	Source provider key.
cluster_kind	string	Yes	—	eks, gke, aws-vm, or gcp-vm.
provider_connection_uuid	uuid	No	—	Cloud provider CloudConnection UUID used to manage the cluster.
provider_cluster_ref	string	Yes	—	Provider-side cluster identifier.
region	string	No	—	Primary provider region or location.
provider_config	json	No	—	Provider-specific status/delete inputs to persist on the logical Cluster row.
node_config	json	No	—	Provider-specific node pool or nodegroup metadata to persist on the logical Cluster row.
connection_uuid	uuid	No	—	Existing Kubernetes CloudConnection UUID when only the logical Cluster row needs metadata refresh.
credential_payload	json	No	—	Kubeconfig, api_server/bearer_token/ca_certificate, or a delegated (auth_mode + provider_connection_uuid + api_server + ca_certificate) payload. Required when connection_uuid is not supplied.
connection_name	string	No	—	Explicit Kubernetes CloudConnection name.
namespace_default	string	No	—	Default namespace for Kubernetes operations.
account_info	json	No	—	Provider account metadata to attach to the connection.
actor	string	No	—	Caller initiating registration.
workflow_run_id	string	No	—	Engine DAG run ID stamped onto child steps.

Output Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	No	—	Organization UUID echoed from input.
cluster_uuid	uuid	No	—	Logical cluster UUID created or reused by this workflow.
cluster_name	string	No	—	Cluster display name.
provider	string	No	—	Source provider key.
cluster_kind	string	No	—	Cluster kind.
provider_connection_uuid	uuid	No	—	Cloud provider CloudConnection UUID used to manage the cluster.
provider_cluster_ref	string	No	—	Provider-side cluster identifier.
region	string	No	—	Primary provider region or location.
provider_config	json	No	—	Provider-specific status/delete inputs persisted on the logical Cluster row.
node_config	json	No	—	Provider-specific node pool or nodegroup metadata persisted on the logical Cluster row.
connection_uuid	uuid	No	—	Persisted Kubernetes CloudConnection UUID.
persist_connection	json	No	—	Sanitized output from connection.persist_connection.
persisted	boolean	No	—	True when a CloudConnection row was written.
restored	boolean	No	—	True when a soft-deleted connection was restored.
cluster_record_persisted	boolean	No	—	True after the logical Cluster row was created or updated.
connection_compensated	boolean	No	—	True when failure cleanup disconnected the created Kubernetes CloudConnection.
connection_compensation	json	No	—	Sanitized output from connection.disconnect when failure cleanup runs.
connection_compensation_error	string	No	—	Cleanup error if the created Kubernetes CloudConnection could not be disconnected.
registered_at	string	No	—	ISO registration timestamp.
failure_reason	string	No	—	Human-readable failure reason.
failure_type	string	No	—	Failure category.
failed_action	string	No	—	Action that failed.
failed_step	json	No	—	Failed logical step or child workflow.
failed_layer	json	No	—	Engine failed layer when applicable.
failed_at_state	string	No	—	State where failure occurred.
error	string	No	—	Error message.
error_type	string	No	—	Error class.
failed_at	string	No	—	ISO failure timestamp.

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	persist_connection	—
persisting_cluster_record	No	No	—	complete	—
persisting_connection	No	No	—	persist_cluster_record	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	persist_connection	persisting_connection	—
persisting_connection	persist_cluster_record	persisting_cluster_record	—
persisting_cluster_record	complete	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "cluster.register-kubernetes-connection",
  "initial_data": {
    "organization_uuid": "value",
    "cluster_name": "value",
    "provider": "value",
    "cluster_kind": "value"
  }
}