Skip to main content
Version: 0.3 (Next)

Create a Management Cluster

Provision a management cluster to enable workload cluster creation for your organization.

Summary​

A management cluster is the foundation for your organization's Kubernetes infrastructure in Konstruct. It hosts the control plane components that manage your workload clusters. Each organization needs one management cluster before you can create workload clusters.

Prerequisites​

  • Platform Admin or Team Admin role
  • Access to the Konstruct UI
  • A cloud account configured in your organization

When You Need a Management Cluster​

You need to create a management cluster when:

  • Your organization is newly created and has no clusters
  • You see the Create management cluster button on the Clusters page
Auto-Generated Screenshot

This image is automatically generated from Cypress tests.

Clusters page showing Create management cluster button

Create Management Cluster​

  1. Navigate to Clusters in the left sidebar

  2. Select your organization from the ORGANIZATION dropdown

  3. Click Create management cluster

  4. Choose a template:

    • Konstruct template: Use the default Konstruct cluster configuration
    • Custom template: Use your own pre-defined custom template

  5. Configure the cluster settings:

    FieldDescription
    Cluster nameEnter a name for your cluster (e.g., team-mgmt-your-company-io)
    Cloud accountSelect the AWS account to provision the cluster in
    Cloud regionChoose the AWS region (e.g., us-west-2)
    AMI typeSelect the Amazon Machine Image type (e.g., AL2_x86_64)
    Instance sizeChoose the EC2 instance type (e.g., m5.2xlarge)
    Number of nodesSet the node count based on your control plane requirements
    Resource Planning

    The default team management cluster configuration includes ArgoCD specifications that require nodes with a minimum of 6 CPU. If you're using the default Konstruct template, 3 m5.2xlarge instances is a good minimal default to accommodate the necessary control plane system load.

    If you need to stay extremely slim, you can adjust these defaults by creating a custom cluster template with reduced resource requirements.

Auto-Generated Screenshot

This image is automatically generated from Cypress tests.

Management cluster creation form

  1. Expand Advanced options to configure additional settings if needed

  2. Click Create cluster to start provisioning

Monitor Provisioning Progress​

Management cluster provisioning takes approximately 20-30 minutes. You can monitor the progress in real-time:

  1. On the Clusters page, click on your management cluster in the graph view
  2. In the details panel, click the Logs tab
  3. Select the log stream from the dropdown to view live provisioning logs
Auto-Generated Screenshot

This image is automatically generated from Cypress tests.

Management cluster provisioning logs

The logs show real-time output from the infrastructure provisioning process, including Terraform operations and cluster setup steps.

View Bootstrapping in ArgoCD​

You can also monitor the cluster bootstrapping progress in ArgoCD:

  1. Navigate to your ArgoCD instance (typically at argocd.<your-domain>)
  2. Log in via Vault using your Konstruct credentials
  3. View the konstruct-clusters application to see the bootstrapping status
Auto-Generated Screenshot

This image is automatically generated from Cypress tests.

ArgoCD konstruct-clusters application

The ArgoCD view shows:

  • App Health: Overall health of the cluster bootstrapping
  • Sync Status: Whether the cluster configuration is in sync
  • Resource Tree: Visual representation of cluster components being deployed

Explore Registry Sync Waves​

Click on the registry application tile in the konstruct-clusters view to see detailed sync wave progress. This shows each component being deployed in order:

  1. From the konstruct-clusters application, click the registry-mgmt-your-company-io tile
  2. The tree view displays all resources being deployed with their sync status
Auto-Generated Screenshot

This image is automatically generated from Cypress tests.

ArgoCD registry sync waves

During bootstrapping, you'll see:

  • Synced (green): Components that have been successfully deployed
  • OutOfSync (yellow): Components waiting to sync in later waves
  • Progressing (blue): Components currently being deployed
Don't Panic

During provisioning, it's normal for apps to temporarily fall into a failed state. The bootstrapping process has built-in circuit breaking and retry logic in the provisioning sequence. If you see an error state for a brief period, be patient—the system will automatically retry and recover.

The sync waves ensure dependencies are deployed in the correct order, with foundational components like cert-manager and external-dns deploying before applications that depend on them.

Cluster Fully Synced​

Once all components have finished deploying, the konstruct-clusters application will show a Synced status with all resources healthy:

Auto-Generated Screenshot

This image is automatically generated from Cypress tests.

ArgoCD konstruct-clusters fully synced

The registry application will also show all components synced and healthy:

Auto-Generated Screenshot

This image is automatically generated from Cypress tests.

ArgoCD registry application fully synced

When you see all applications in a Healthy and Synced state, your management cluster is ready to use. You can now:

  • Create your first workload cluster - Provision clusters where your applications will run
  • View your applications in Konstruct - Navigate to the Applications page in the Konstruct UI to manage deployments

What's Next?​

After your management cluster is provisioned: