Connecting Jenkins to Kubernetes: A Step-by-Step Guide

In this blog, we’ll walk through the process of connecting Jenkins to a Kubernetes cluster. Specifically, we’ll demonstrate how to integrate Jenkins with a local K3s cluster, allowing you to run Jenkins jobs on Kubernetes pods. By the end of this guide, you’ll be able to set up the connection and run a Jenkins job in Kubernetes, enhancing your CI/CD pipeline.

Prerequisites

Before we begin, ensure that you have the following:

• A local K3s cluster: K3s is a lightweight Kubernetes distribution, ideal for local development.
• A running Jenkins instance: Jenkins should be up and running, with access to the Kubernetes cluster.
• Basic knowledge of Jenkins and Kubernetes: Familiarity with Jenkins jobs, plugins, and Kubernetes concepts is required.

Step 1: Retrieve Kubernetes Configuration

First, we need to obtain the Kubernetes configuration file from your K3s cluster. This file contains critical information that Jenkins needs to connect to Kubernetes, such as the server endpoint and the certificate authority data.

1. Access your Kubernetes server. If you're using a local K3s cluster, connect to the server where K3s is installed.
   • Server endpoint: This is the URL Jenkins will use to connect to Kubernetes.
   • Certificate authority data: This is used to establish a secure connection.
2. Copy the entire configuration file. We’ll need it when setting up Jenkins.

Retrieve the K3s configuration file by running the following command:

cat /etc/rancher/k3s/k3s.yaml

This command will output the full YAML configuration file. The key sections we’ll focus on are:

Step 2: Install the Kubernetes Plugin in Jenkins

Next, we’ll install the Kubernetes plugin in Jenkins, which enables Jenkins to deploy and manage jobs on Kubernetes pods.

1. Navigate to Jenkins Dashboard and go to Manage Jenkins > Manage Plugins.
2. Search for the Kubernetes plugin under the Available Plugins tab.
3. Install the plugin and restart Jenkins if required.

Step 3: Configure Kubernetes in Jenkins

With the Kubernetes plugin installed, we can now configure Jenkins to connect to our K3s cluster.

1. Go to Manage Jenkins > Manage Clouds > Add a New Cloud.
2. Select Kubernetes from the list of available cloud providers.
3. Give your cloud a name (e.g., K3s-Cluster).
4. Paste the Kubernetes server endpoint in the Kubernetes URL field. This is the server: value from the k3s.yaml file (e.g., https://<ip-address>:6443).
5. Skip the Kubernetes server certificate key section if you plan to upload the k3s.yaml file directly (see below). If not, you’ll need to manually paste the certificate-authority-data here.

Step 4: Upload the K3s Configuration File

Now we’ll upload the k3s.yaml file to Jenkins, so it can use the credentials stored within it.

1. Scroll down to the Credentials section and click on +Add > Jenkins > Secret file.
2. Choose the k3s.yaml file you retrieved earlier and upload it.
3. Assign an ID and Description to this secret file for easy reference.
4. Click Add to save the credentials.
5. In the Credentials dropdown menu, select the ID of the file you just uploaded.
6. Test the connection by clicking the Test Connection button. If everything is configured correctly, you’ll see a “Connected to Kubernetes” message.
   • Note: If you directly upload the k3s.yaml file, there’s no need to separately specify the server endpoint and certificate authority data, as Jenkins will extract these automatically.

Step 5: Running a Jenkins Job on Kubernetes

With Jenkins now connected to your Kubernetes cluster, you can run jobs directly on Kubernetes pods. Here’s how to do it:

1. Create a new Jenkins job (e.g., a Freestyle project).
2. In the build configuration section, add a Kubernetes Pod Template by navigating to Build Environment > Kubernetes Pod Template.
3. Specify the pod template details, such as the container image and resource requests.
4. Add build steps as you normally would for your Jenkins job.
5. Save the job and click Build Now.Jenkins will now schedule the job on a Kubernetes pod. You can monitor the job’s progress through the Jenkins console and Kubernetes dashboard.

Conclusion

By following this guide, you’ve successfully connected Jenkins to a Kubernetes cluster using the Kubernetes plugin. This setup allows you to leverage Kubernetes' scalability and flexibility to run Jenkins jobs efficiently on containerized pods. Whether you’re running a local K3s cluster or a larger Kubernetes environment, this integration is a powerful addition to your CI/CD pipeline.

Feel free to explore further by adding more pod templates or integrating with other Kubernetes features to enhance your automation workflows. Happy building!