Workspace Lifecycle
A Workspace is the top-level environment for a tenant. It represents a dedicated Kubernetes cluster running on the tenant's own cloud account, along with all the applications and infrastructure deployed into it.
States
A workspace moves through a defined set of states from the moment it is created until it is decommissioned.
| State | Description |
|---|---|
| Provisioning | Cloud infrastructure is being stood up. Nothing can be deployed into the workspace yet. |
| Active | The cluster is running and the Cluster Agent has bootstrapped and connected. Ready for application deployments. |
| Failed | Something went wrong during provisioning or an update. The workspace may be partially provisioned. The tenant can retry. |
| Updating | A change to the workspace's underlying infrastructure is being applied. Application workloads continue running unless directly affected. |
| Destroyed | The workspace and all its resources have been torn down. Terminal state. |
Provisioning in Detail
When a tenant creates a workspace, the platform selects the appropriate workspace stack template for the chosen cloud provider and applies it automatically. Provisioning happens in two phases:
Phase 1 — Cloud Infrastructure. The Control Plane provisions the VPC and Kubernetes cluster through its Temporal worker, using the relevant Terraform modules. This phase runs entirely on the Cogrion side and talks directly to the cloud provider API.
Phase 2 — Agent Bootstrap. Once the cluster exists, the Cluster Agent is installed into it. The Control Plane issues a one-time bootstrap token. The agent exchanges this token for its mTLS credentials and begins polling for commands. When the Control Plane receives the first successful poll from the agent, the workspace transitions to Active.
Destroying a Workspace
Destroying a workspace tears down all resources in reverse dependency order — applications first, then infrastructure. Each resource's executor handles its own teardown: Helm charts are uninstalled, Kubernetes manifests are deleted, Terraform state is destroyed. The workspace itself is destroyed last.
Relationship to Stacks
Everything deployed into a workspace — applications, infra add-ons, observability tooling — lives as a Stack inside it. The workspace is the deployment target; stacks are the deployable units. A workspace can contain many stacks, each with its own independent lifecycle.
Go Deeper
- Platform Developer → What Is a Stack
- Platform Developer → Deployment Lifecycle
- Architecture → How It's Built