helm-external-secrets/docs/introduction/prerequisites.md

Prerequisites

To collaborate on the External Secrets Operator (ESO) project, you need to install some tools on your computer. This guide explains what each tool is, why it is needed, the recommended version, and how to install it on the corresponding operating system.

Supported Operating Systems

To collaborate on the External Secrets Operator (ESO) project, it is recommended to use Unix-based operating systems, such as Linux and macOS. ESO's development environment is primarily designed for these systems, and many of the tools and scripts used during development are built to work on them.

Can You Develop on Windows?

It is possible to use Windows for development, but there are important considerations to keep in mind. Since ESO's development environment is not optimized for Windows, compatibility issues may arise with tools like Make, Tilt, and shell scripts. The project's automation scripts and commands are written for Unix environments, using bash scripting, which might not be compatible with Windows without adaptations. This tutorial will not cover the installation and configuration of tools on Windows due to its complexity and lack of testing.

---

Install Go (Golang)

About Golang

What is Go?

Go, also known as Golang, is a programming language design at Google by Robert Griesemer, Rob Pike, and Ken Thompson. It is known for being efficient, easy to learn, and excellent for developing fast and scalable applications.

Why is Go needed?

In the External Secrets Operator project, Go is used to develop core parts of the code. It is required to compile, run, and contribute to the project's source code.

Golang Installation

Required Version

Minimum version: Go 1.20 or higher.

Recommended version: Go 1.24.1

As of this writing, the latest version of Go is 1.24.1As of this writing, the latest version of Go is 1.24.1 , which worked perfectly with the External Secrets Operator project. Previous versions failed to test the application. Before testing the project, check your Go version.

How to Install Go

Please consult the official documentation.

Install Helm

About Helm

What is Helm?

Helm is a package manager for Kubernetes, the platform that automates deployment, scaling, and management of containerized applications.

Why is Helm necessary?

In the External Secrets Operator project, Helm is used to simplify the installation and management of applications within Kubernetes, automating complex configuration and deployment processes.

Installing Helm

Required Version

Recommended version: Helm 3 (latest version of Helm 3).

How to Install Helm

Please consult the official Helm installation guide.

---

Install yq

About yq

What is yq?

yq is a command-line tool for reading, manipulating, and writing YAML files, which are widely used for configurations.

Why is yq necessary?

In the External Secrets Operator project, yq is used to automate the editing of YAML configuration files, facilitating adjustments and implementations.

Installing yq

Required Version

Recommended version: yq v4.44.3 or higher.

How to Install yq

Please consult the official yq repository.

---

Install jq

About jq

What is jq?

jq is a command-line tool for processing and manipulating JSON data.

Why is jq needed?

In the External Secrets Operator project, jq is essential for working with JSON data, enabling efficient filtering and transformation of information.

Installing jq

Required Version

Recommended version: jq 1.6 or later.

How to Install jq

Please consult the official jq website.

Kubernetes

About Kubernetes

What is Kubernetes?

Kubernetes is an open-source platform for automating the deployment, scaling, and management of containerized applications. It orchestrates containerized workloads across a cluster of machines, ensuring high availability and efficient resource utilization.

Why is Kubernetes needed?

In the External Secrets Operator project, Kubernetes provides the infrastructure to deploy and manage containerized applications. It allows integration with cloud-native services, enabling scalability, fault tolerance, and streamlined operations in dynamic environments.

To work with Kubernetes, we need to install and configure some tools first. This will be explained in the sections below.

For more details, check the official documentation.

---

Install Docker

About Docker

What is Docker?

Docker is a platform for building, deploying, and running applications in containers. Containers package an application with all its dependencies into a standard unit for development and deployment.

Why is Docker needed?

In the External Secrets Operator project, Docker is used to create container images and run services in isolated environments. It is essential for developing, testing, and deploying the application within a Kubernetes environment.

Installing Docker

How to Install Docker

Please consult the official Docker documentation.

Required Docker Configuration

Configure Docker for Non-Root Usage

By default, Docker requires superuser (root) privileges to run. To simplify usage, it is recommended to add the current user to the docker group to execute commands without sudo.

<summary>Steps to configure Docker without root on Linux</summary>
<h3>1. Create the docker group (if it doesn't exist):</h3>
<pre><code>sudo groupadd docker</code></pre>
<h3>2. Add the current user to the docker group:</h3>
<pre><code>sudo usermod -aG docker $USER</code></pre>
<h3>3. Apply group changes without logging out:</h3>
<pre><code>newgrp docker</code></pre>
<h3>4. Verify Docker can run without sudo:</h3>
<pre><code>docker run hello-world</code></pre>
<p>If the command works without errors, the configuration is successful.</p>

---

Install kubectl

About kubectl

What is kubectl?

kubectl is the command-line tool for managing Kubernetes clusters. It enables running commands on the cluster, managing resources, and debugging applications.

Why is kubectl needed?

In the External Secrets Operator project, kubectl is used to interact with local or remote Kubernetes clusters, apply configurations, and check the state of deployed resources.

Installing kubectl

Required Version

A version compatible with the installed Kubernetes version (usually the latest stable version).

How to Install kubectl

Please consult the official kubectl documentation.

---

Install ctlptl and Create a Kind Cluster with Local Registry

About ctlptl

What is ctlptl?

ctlptl (Control Plane Tool) is a tool for managing local Kubernetes development clusters. It simplifies the creation and management of clusters like Kind (Kubernetes in Docker) and the configuration of local container registries.

Why is ctlptl necessary?

In the External Secrets Operator project, ctlptl is used to create and manage a local Kubernetes cluster using Kind, as well as to configure a local container registry to store Docker images during development.

Installing ctlptl

Required Version

The latest available version of ctlptl.

How to Install ctlptl

<p>Please consult the <a href="https://github.com/tilt-dev/ctlptl/blob/main/INSTALL.md
">official ctlptl installation guide</a>.</p>

Create a Kind Cluster with Local Registry

About Kind

Kind (Kubernetes in Docker) is a tool to run local Kubernetes clusters using Docker containers as cluster nodes.

How to Create a Kind Cluster with Local Registry

1. Create a local container registry:

docker run -d --restart=always -p "5000:5000" --name kind-registry registry:2

2. Create a Kind cluster using ctlptl and connect it to the local registry:

ctlptl create cluster kind --registry=kind-registry

This will create a Kind cluster configured to use the local registry at localhost:5000.

3. Verify the cluster is running:

kubectl cluster-info --context kind-kind

4. List clusters managed by ctlptl:

ctlptl get clusters

---

Install Tilt

About Tilt

What is Tilt?

Tilt is a tool that accelerates development in Kubernetes environments. It automates building, deploying, and monitoring code, enabling a faster development cycle.

Why is Tilt necessary?

In the External Secrets Operator project, Tilt is used to develop and test code changes efficiently, reflecting updates almost instantly in the local Kubernetes environment.

Installing Tilt

Required Version

<li><strong>Prerequisites:</strong> Install Docker, kubectl, Kind, and ctlptl.</li>
<li><strong>Recommended version:</strong> Latest available version.</li>

How to Install Tilt

Please consult the official Tilt installation guide.