Skip to main content
Version: 0.5

Quickstart

Get from zero to a running application in under 30 minutes using the Konstruct Hosted Control Plane.

Summary​

This guide walks you through signing up for hosted Konstruct, connecting your cloud and Git accounts, provisioning management and workload clusters, creating environments, and deploying your first application.

Prerequisites​

  • A Civo account (sign up at Civo.com)
  • A Civo API key — see Civo Account Setup for instructions
  • A GitHub account for your GitOps repository (GitLab coming)
  • An application repository with a Dockerfile (or use a sample app)

Step 1: Sign Up and Associate an Organization​

  1. Go to Civo.com and create an account if you do not have one.
  2. On the Migrate your account into an Organization page, review your team and click Continue with migration.

This associates your Civo account with an organization in Civo.

Step 2: Log In to Konstruct​

  1. Go to konstruct.saas.konstruct.io.
  2. Click Login with Civo.
  3. On the Select your organization page, find your organization and click Enter.

You land on the Konstruct dashboard for that organization.

tip

If you belong to multiple organizations, you can switch between them by navigating to /select-organization in the URL bar.

Step 3: Connect Your Git Account​

Konstruct needs access to your GitHub organization to create and manage a GitOps repository for your platform configuration.

  1. In the left sidebar under Administration, click Organizations.
  2. Select your organization.
  3. Click the Git connection tab.
  4. Click Connect.
  5. Follow the GitHub authorization flow to grant Konstruct access to your GitHub organization.

Once connected, you see GitHub connected — All repositories with a link to your Konstruct GitOps repository (for example, https://github.com/your-org/your-org-gitops). The repository starts with a README and is populated with configuration when you create your first management cluster.

Step 4: Connect Your Civo Cloud Account​

Konstruct needs your Civo API key to provision clusters on your behalf.

  1. In the left sidebar under Administration, click Cloud accounts.
  2. Click Add Cloud Account.
  3. Select Civo as the provider.
  4. Enter a name for this account (for example, civo-production).
  5. Paste your Civo API key.
  6. Click Save.

Konstruct validates the key and confirms the connection. If you do not have an API key yet, see Civo Account Setup.

Step 5: Create a Management Cluster​

The management cluster hosts Argo CD, Crossplane, and your platform tooling. It is the control point for all workload clusters in your organization.

  1. In the left sidebar under Cluster Management, click Clusters.
  2. Click Create management cluster.
  3. Select Custom template.
  4. From the template dropdown, select civo-mgmt.
  5. Click Connect.
  6. Fill in the cluster details:
    • Cluster name — a short identifier, for example mgmt-prod
    • Cloud account — select the Civo account you connected in Step 4
    • Region — choose a Civo region (for example, NYC1)
    • Node size — g4s.kube.medium or larger
    • Number of nodes — minimum 3 for high-availability Argo CD
  7. Click Create cluster.

Konstruct provisions the Civo Kubernetes cluster and bootstraps it with Argo CD and the platform tools. Provisioning takes approximately 8–12 minutes.

note

You can monitor progress from the cluster detail page. The cluster status moves through Provisioning > Bootstrapping > Ready.

DNS Propagation

After provisioning, your Argo CD domain may take a few minutes to propagate via DNS. If the Argo CD URL does not resolve immediately, wait 2–3 minutes and try again.

Once the management cluster is ready, your GitOps repository is populated with the platform configuration including Argo CD applications, Crossplane providers, and infrastructure definitions.

Step 6: Register a Workload Cluster Template​

A workload cluster template defines how workload clusters are provisioned. Register a template before creating your first workload cluster.

  1. In the left sidebar under Cluster Management, click Cluster templates.
  2. Click Add Template.
  3. Select Workload Cluster as the template type.
  4. Fill in the template details:
    • Name — for example civo-workload
    • Repository URL — your GitOps repository URL (for example, https://github.com/your-org/your-org-gitops)
    • Path — templates/workload-cluster
    • Branch — main
  5. Click Connect.

Konstruct validates the template repository and registers it for use during cluster creation.

tip

You can also create your own custom templates. See Cluster Templates for details on building templates with custom Terraform modules and input variables.

Step 7: Create a Workload Cluster​

Workload clusters run your applications. They are managed through the management cluster.

  1. On the Clusters page, click Create cluster.
  2. Select Workload Cluster as the cluster type.
  3. Select the management cluster you created in Step 5 as the Parent Cluster.
  4. Choose the workload cluster template you registered in Step 6.
  5. Fill in the cluster details:
    • Name — for example dev-workloads
    • Cloud account — select your Civo account
    • Region — choose a region
    • Node size — g4s.kube.medium is sufficient for testing
    • Number of nodes — 1 is fine for a test cluster
  6. Click Create cluster.

The workload cluster provisions in approximately 5–8 minutes. You can track progress in Argo CD on your management cluster. Once ready, the cluster registers automatically with your management cluster.

Step 8: Create an Environment​

Environments define deployment targets for your applications. Create at least one environment before deploying.

  1. In the left sidebar under App Management, click Environments.
  2. Click Add Environment.
  3. Fill in the environment details:
    • Environment name — for example development
    • Namespace — for example development
    • Environment type — select Pre-release
    • Environment available for immediate use — toggle on
  4. Click Create environment.

After creating the environment, associate it with a workload cluster:

  1. On the Environments page, click the environment you just created.
  2. Click Edit.
  3. Select your provisioned workload cluster from the cluster dropdown.
  4. Click Save.

Step 9: Register an Application​

Register your application repository so Konstruct can set up CI/CD and deploy it to your environments.

  1. In the left sidebar under App Management, click App repositories.
  2. Click Register application.
  3. Fill in the application details:
    • Organization — select your organization
    • Repository — select your application repository from the dropdown
    • Application name — for example my-app
  4. Configure the pipeline:
    • Pipelines — select the pre-registered gh-actions pipeline template
    • Helm template — select the pre-registered default Helm template
  5. Configure the deployment stages:
    • Add development as a deployment stage
  6. Click Register application.

After registration, Konstruct commits GitHub Actions workflows and Helm charts to your application repository:

  • .github/workflows/ — CI/CD automation for building and deploying
  • charts/ — Helm chart for Kubernetes deployment

Step 10: Deploy the Application​

With your application registered and environments configured, deploy it.

  1. On the App repositories page, find your registered application.
  2. Click the three-dot menu on the application.
  3. Select Deploy.
  4. Choose the cluster, environment, and version to deploy.
  5. Click Deploy.

Verify the Deployment​

  1. In the Konstruct UI, go to Applications and confirm the application status shows Synced and Healthy.
  2. Open your Argo CD instance on the management cluster to view the sync status and pod health.
tip

You can access Argo CD from the cluster detail page in the Konstruct UI. Click the Argo CD link to open it directly.

What's Next?​