Build your first Internal Developer Platform with Konstruct on Civo

An internal developer platform gives development teams a consistent way to provision infrastructure and deploy applications without managing every underlying resource themselves. It can standardize application environments while reducing the amount of infrastructure work required for each deployment.

Konstruct provides a way to build this workflow on Civo by managing workload clusters, environments, and application deployments through GitOps.

In this tutorial, we'll build a basic internal developer platform with Konstruct on Civo. We'll connect a GitHub repository, configure a Civo cloud account, create a management cluster, provision a workload cluster, create a development environment, and deploy a sample application. By the end of the tutorial, you'll have a working Konstruct environment with a sample application deployed to a Civo Kubernetes workload cluster.

Prerequisites

Before getting started, make sure you have the following:

• A Civo account with access to create Kubernetes clusters. Your Civo account should be part of a Civo organization, rather than a personal account.
• The Civo CLI installed and authenticated.
• kubectl and Git installed and configured.
• A GitHub organization. Use a GitHub organization rather than a repository under your personal GitHub account. You can create a GitHub organization from your existing GitHub account. This tutorial uses GitHub, but Konstruct also supports GitLab. 
• A repository inside the GitHub organization for storing the Konstruct GitOps configuration.
• The sample application repository, which you'll fork into your GitHub organization.
• A Konstruct account. You can sign in to Konstruct using your Civo account credentials.
• A basic understanding of Kubernetes, Helm, and GitOps.

For more information, see the Konstruct Quickstart, which covers creating clusters, connecting Git repositories, configuring environments, and deploying applications.

Konstruct Architecture

Konstruct uses a management cluster to provision and manage workload clusters. The management cluster contains the components required to manage the infrastructure and applications running on the workload clusters.

In this tutorial, we'll use one management cluster and one workload cluster. The workload cluster will host a development environment where we'll deploy the sample application.

The setup includes the following components:

• Management cluster: Hosts the Konstruct components used to manage the platform.
• Workload cluster: A Civo Kubernetes cluster where the application workloads run.
• GitHub repository: Stores the GitOps configuration used to manage the platform and application resources.
• Argo CD: Synchronizes the configuration from the GitHub repository with the Kubernetes cluster.
• Development environment: Provides an environment for deploying the sample application.
• Sample application: A simple application that we'll deploy to the development environment.

Connect your GitHub repository

From the Konstruct dashboard, navigate to Organizations. You should see the organization associated with your Civo account.

Click your organization name to open its settings. Then select the Git Connection tab and click Connect.

Konstruct will ask you to authorize access to your GitHub organization. Grant the required permissions to connect the organization.

Make sure you authorize the GitHub organization, not your personal GitHub account. The GitOps repository used by Konstruct must belong to the GitHub organization.

After granting the required permissions, Konstruct will show the GitHub organization as connected.

Create a cloud account

Before creating the management cluster, you need to connect your Civo account to Konstruct.

From the Konstruct dashboard, navigate to Cloud Accounts under Administration.

Click Add Cloud Account and select Civo as the cloud provider.

Enter a name for the cloud account and provide your Civo API key.

If you don't already have an API key, you can generate one from your Civo dashboard by going to your Profile section.

After entering the required details, save the cloud account. Konstruct will show the Civo account as connected.

Create the management cluster

Click Clusters under the Cluster Management section.

Select the organization you want to use for the cluster.

Click Add Management Cluster to start creating the management cluster.

For this tutorial, we'll use the following configuration:

Keep the remaining configuration options at their default values.

Click Create Management Cluster to start the provisioning process.

Konstruct will provision the management cluster using the selected Civo configuration. You can monitor the cluster creation progress from the Konstruct dashboard, including the provisioning logs. 

Create the workload cluster

After the management cluster finishes provisioning, return to the Clusters page. Click Add Workload Cluster to start creating a workload cluster. 

Konstruct will open the workload cluster configuration page. Select Create a new and choose the Workload Cluster template.

For this tutorial, use the following configuration:

Keep the remaining configuration options at their default values.

Create your environment

After the workload cluster is created, navigate to Environments under App Management.

Click Create Environment. 

Give the environment a name and specify the namespace that will be created for it.

Select the Prerelease option and enable the Immediate Use toggle. 

The Prerelease option marks the environment for pre-release deployments, which is suitable for the development environment used in this tutorial. The Immediate Use option allows the environment to be used as soon as it is created. 

After entering the required details, create the environment.

Once the environment is created, it will be available in Konstruct for deploying applications to the workload cluster. In the next section, we'll register and deploy our sample application.

Register and deploy a sample application

Now that the development environment is ready, you can register the sample application repository with Konstruct.

For this tutorial, we'll use the sample application repository. Fork the repository into the GitHub organization you connected to Konstruct.

From the Konstruct dashboard, navigate to App Repositories under App Management and click Register App Repo.

Select the GitHub organization where you forked the sample application repository, then provide the URL of your forked repository. 

Enter a name for the application.

For Pipelines, select gh-actions. For the Helm chart, keep the Default template selected. Finally, select the development environment you created earlier.

After providing the required details, register the application repository.

Once the repository is registered, return to App Repositories. Find the application you just registered and click the three-dot menu next to it.

Select the workload cluster and environment, then provide an instance name for the deployment.

Select Deploy to start deploying the application.

Verify the deployment

After deploying the application, you can verify that it is running correctly from the workload cluster.

First, download the kubeconfig file for the workload cluster. Do not use the management cluster kubeconfig for these checks because the sample application is running on the workload cluster.

Once you have downloaded the kubeconfig file, use it to connect kubectl to the workload cluster.

Check the pods in the development namespace:

1KUBECONFIG=~/wc-1-kubeconfig.yaml kubectl get pods -n development

You should see the sample application's pod with a Running status.

Next, check the Service created for the application:

1KUBECONFIG=~/wc-1-kubeconfig.yaml kubectl get svc -n development

This confirms that the application has a Kubernetes Service.

You can also check the application logs to make sure the application started successfully:

1KUBECONFIG=~/wc-1-kubeconfig.yaml kubectl logs -n development <pod-name>

Replace <pod-name> with the name of your application pod.

You should see output confirming that the application is listening on port 3000.

To verify the application itself, you can forward the pod's port to your local machine:

1KUBECONFIG=~/wc-1-kubeconfig.yaml kubectl port-forward \
2  -n development \
3  pod/<pod-name> \
4  3000:3000

Keep the command running and open http://localhost:3000 in your browser.

If the application loads successfully, the deployment is working as expected. You have now verified the pod, Service, application logs, and application itself.

In the next section, we'll look at the GitOps workflow behind this deployment and how Konstruct manages these resources.

Understanding the GitOps workflow behind the scenes

Konstruct uses GitOps to manage the application deployed to the workload cluster. The application configuration is stored in Git, while Argo CD synchronizes that configuration with the cluster.

After deploying the application, open Argo CD and select the application created by Konstruct.

The application should show Synced and Healthy. This confirms that Argo CD has synchronized the application configuration with the workload cluster and that the deployed resources are healthy.

This GitOps workflow allows Konstruct to manage application deployments consistently while keeping the workload cluster synchronized with the desired configuration.

Clean up resources

After verifying the deployment, you can remove the resources created during this tutorial to avoid leaving unused Civo resources running.

Start by deleting the workload cluster from the Clusters page in Konstruct.

Select the workload cluster you created for this tutorial and delete it. Confirm the deletion when prompted.

You can also remove the development environment and the registered application repository if you no longer need them.

Navigate to Environments under App Management and remove the development environment.

Then return to App Repositories and remove the sample application repository registration.

Finally, if you created the management cluster only for this tutorial, return to Clusters and delete it after the workload cluster has been removed.

Once these resources are removed, the Civo resources created for this tutorial will no longer be running.

Conclusion

In this tutorial, you built a basic internal developer platform with Konstruct on Civo. You connected a GitHub organization, configured a Civo cloud account, created a management cluster, provisioned a workload cluster, created a development environment, and deployed a sample application. 

You also verified the application from the workload cluster using kubectl and confirmed that it was running successfully.

With this setup, you have a simple foundation for managing Kubernetes applications through GitOps with Konstruct and Civo.