Managing applications across different environments is a critical aspect of ensuring reliability in transitions from development to production. A great tool that addresses the complexities of multi-environment deployments is Kluctl.

In this article, we will go through the strategies and best practices for effectively managing multi-environment deployments using Kluctl. From the initial setup to the intricacies of handling multiple environments, this guide aims to provide comprehensive guide into leveraging Kluctl.

You will learn how to use Kluctl to create environment for development and production and manage it with the Kluctl WebUI.

Create a cluster

Before we go further into the tutorial, we need a cluster that will be used to practice.
To create a Kubernetes cluster using the kind tool, follow the steps below:

1. Open a terminal and use the following command to create a Kubernetes cluster with kind:

sudo kind create cluster

This command creates a Kubernetes cluster with default settings and a context named kind-kind. The use of sudo might be necessary based on your system’s configuration.

2. After creating the cluster, you can verify the cluster information by running:

sudo kubectl cluster-info --context kind-kind

This command displays information about the created Kubernetes cluster, including the API server endpoint, controller manager, and DNS service. The --context kind-kind flag ensures that kubectl interacts with the correct cluster context.

After these steps, you’ll have a Kubernetes cluster running locally using kind.

A brief introduction to Kluctl

Kluctl is a powerful command-line tool designed to manage Kubernetes deployments. It acts as a unified interface, allowing you to deploy, diff, prune, delete, and manage various deployments seamlessly.

Kluctl excels at orchestrating both your own deployments and those of third-party tools, providing a declarative approach to Kubernetes deployment management. Kluctl configurations are defined in the .kluctl.yaml configuration file.

Running Kluctl locally

Before proceeding, you need to install Kluctl and the documentation can help you with that. Instead of building a project and deploying it from scratch, let us use an already made Helm chart.

git clone https://github.com/kluctl/kluctl-examples.git
cd kluctl-examples/simple-helm #choose simple-helm example 

In the simple-project, you are provided with the .kluctl.yaml containing the following code. In the code below, the discriminator is specified. It is used to uniquely identify specific deployed objects.

discriminator: kluctl-examples-simple-helm-{{ target.name }}

targets:
  - name: simple-helm
    context: kind-kind
    args:
      environment: simple-helm

args:
  - name: environment

A target specifies both a target cluster (using context) and a set of deployment parameters. Multiple targets can utilize the same cluster. You could also deploy across multiple clusters or environments.

args is used to list arguments that can or must be passed to most kluctl operations. args can be accessed almost the same way you accessed the target name, {{ args.environment }}. Here you are referencing the args name directly.

You can deploy the project with the following command:

sudo kluctl deploy -t simple-helm

You can see the newly deployed object by running the following command:

sudo kubectl -n simple-helm get pod

The kluctl deploy command above deploys a target (-t simple-helm) to the corresponding cluster. This command will also output a diff between the initial state and the state after deployment.

After running the commands above, the kluctl deploy command will perform a diff first and then ask for your confirmation to deploy it, type y and enter to deploy.

Running multi-environment deployments

“Multi-environment deployments” refers to the practice of deploying software applications or infrastructure across various environments, such as development, testing, staging, and production. In this context, “multi-environment” implies the ability to easily deploy and manage the same application or system in different stages of its lifecycle or across distinct operational settings.

In this section, we will modify the .kluctl.yaml file to create environments for staging and deployment environment, then deploy. Each environment will be specified using the target keyword, as I mentioned earlier.

Let’s incorporate two additional targets named “local” and “prod.” To achieve this, update the content of the .kluctl.yml file with the following configuration:

discriminator: kluctl-examples-simple-helm-{{ target.name }}

targets:
- name: local
  context: kind-kind
  args:
    environment: home
- name: prod
  context: kind-kind
  args:
    environment: prod

It’s important to note that, at the moment, all targets are directed towards the kind cluster. In a real-world project, this setup would be different, typically involving at least one production-ready cluster to serve as the deployment target for actual projects.

You may also need multiple helm charts while working on a real-world project.

The significance of commonLabels within your primary deployment.yml (provided in the project you fetched earlier) is crucial and requires careful comprehension for effective use. It is important to ensure that the combination of all commonLabels remains unique across all deployed targets on a cluster. This uniqueness extends to targets that may not currently exist and those originating from other kluctl projects.

This uniqueness is important because kluctl relies on these commonLabels to distinguish resources associated with the presently processed deployment or target. This distinction becomes critical during deletion or pruning operations.

To meet this requirement, modify the primary deployment.yml as follows:

commonLabels:
  examples.kluctl.io/environment: "{{ args.environment }}"
  examples.kluctl.io/deployment-project: k8s-deployment-simple-helm
  examples.kluctl.io/deployment-target: "{{ target.name }}"

Now deploy the targets you have created with the following commands:

$ kluctl deploy -t local
$ kluctl deploy -t prod

Following this, you will have two namespaces (prod and home) with an identical collection of microservices with two instances of Nginx. You can check out the instances with the following commands:

sudo kubectl -n home get pod
sudo kubectl -n prod get pod

Using Kluctl WebUI

The kluctl webui (still in development) serves as a user interface, providing the capability to visualize and manage your Kluctl deployments.

You have the option to either run the Webui locally on your machine or install it directly onto your Kubernetes cluster for convenient access and control. This web-based interface enhances the monitoring and administration of your deployments facilitated by Kluctl.

However, in this tutorial, I will show how to run it locally. You can do this by running the following command:

sudo kluctl webui run

After the command is run, you will be provided with the URL to access the webui. If everything goes well, you should see something like the following image.

Conclusion

Effective management of applications across multiple environments is crucial for ensuring consistency, and smooth transitions from development to production. Kluctl emerges as a valuable tool, addressing the complexities of multi-environment deployments.

We started the tutorial by creating a Kubernetes cluster using the **kind** tool and then proceeded to delve into the details of Kluctl.

By following this comprehensive guide, you are equipped with the background knowledge of leveraging Kluctl for controlling deployment workflows, making the management of multi-environment deployments easier.