cluster.provision

Provider-neutral Kubernetes cluster provisioning orchestration that returns a verified Kubernetes CloudConnection.

Provider-neutral Kubernetes cluster provisioning orchestration.

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.
provider	string	Yes	—	Provider key: aws, gcp, or magalucloud.
cluster_kind	string	Yes	—	eks, gke, aws-vm, gcp-vm, or mgc-kubernetes.
name	string	Yes	—	Desired cluster display name.
provider_connection_uuid	uuid	Yes	—	CloudConnection UUID for the cloud provider account.
region	string	No	—	Primary provider region.
zones	json	No	—	Provider zones for multi-zone clusters.
kubernetes_version	string	No	—	Requested Kubernetes version.
network_config	json	No	—	Provider-specific network inputs.
node_config	json	No	—	Node pool or VM sizing inputs.
provider_config	json	No	—	Provider-specific cluster options for supported provider workflows.
tags	json	No	—	Provider tags or labels.
bootstrap_orkestia_access	boolean	No	—	Whether to run cluster.bootstrap-orkestia-access after verification.
namespace	string	No	—	Namespace for optional Orkestia bootstrap; defaults to orkestia.
service_account_name	string	No	—	ServiceAccount for optional bootstrap.
cluster_role_name	string	No	—	ClusterRole to bind during optional bootstrap.
actor	string	No	—	Caller initiating the workflow.
timeout_seconds	integer	No	—	Provider and verification timeout.
poll_interval	integer	No	—	Provider polling interval.

Output Schema

Field	Type	Required	Default	Description
organization_uuid	uuid	No	—	Organization UUID echoed from input.
cluster_uuid	uuid	No	—	Persisted logical cluster UUID.
provider	string	No	—	Provider key.
cluster_kind	string	No	—	Cluster kind.
name	string	No	—	Cluster display name.
provider_connection_uuid	uuid	No	—	Cloud provider CloudConnection UUID.
provider_cluster_ref	string	No	—	Provider-side cluster identifier.
region	string	No	—	Primary provider region.
status	string	No	—	Normalized lifecycle status.
phase	string	No	—	Provider-specific phase.
connection_uuid	uuid	No	—	Persisted Kubernetes CloudConnection UUID.
provider_workflow	string	No	—	Provider provision workflow type.
provider_input	json	No	—	Input sent to the provider provision workflow.
provider_child_workflow_id	string	No	—	Workflow id for the provider provision child.
bootstrap_orkestia_access	boolean	No	—	Whether to run cluster.bootstrap-orkestia-access after verification.
namespace	string	No	—	Namespace for optional Orkestia bootstrap.
service_account_name	string	No	—	ServiceAccount for optional bootstrap.
cluster_role_name	string	No	—	ClusterRole to bind during optional bootstrap.
actor	string	No	—	Caller initiating the workflow.
provider_provision	json	No	—	Output from the selected provider provision workflow.
register_connection	json	No	—	Output from cluster.register-kubernetes-connection.
verification	json	No	—	Output from cluster.verify-kubernetes-connection.
bootstrap	json	No	—	Output from optional cluster.bootstrap-orkestia-access.
refresh_status	json	No	—	Output from cluster.refresh-status.
created	boolean	No	—	True when a new cluster record was created.
completed_at	string	No	—	ISO completion timestamp.
retried_from	string	No	—	Previous terminal state when a failed run was retried.
retry_count	integer	No	—	Number of retry attempts recorded by the workflow engine.
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	—	prepare_provider	—
finalizing	No	No	—	complete	—
provisioning_provider	No	No	—	—	—
registering_connection	No	No	—	register_connection	—
verifying_connection	No	No	—	finalize	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	prepare_provider	provisioning_provider	—
provisioning_provider	child_done	registering_connection	—
provisioning_provider	child_failed	failed	—
registering_connection	register_connection	verifying_connection	—
verifying_connection	finalize	finalizing	—
finalizing	complete	completed	—
* (any state)	fail	failed	—

API Usage

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

{
  "workflow_type": "cluster.provision",
  "initial_data": {
    "organization_uuid": "value",
    "provider": "value",
    "cluster_kind": "value",
    "name": "value"
  }
}