CI/CD / Development / Kubernetes

GitOps at Home: Automate Code Deploys with Kubernetes and Flux

31 May 2021 9:00am, by

Flux is a Cloud Native Computing Foundation-based open source stack of tools that make it possible to keep Kubernetes clusters in sync with external sources of configuration, such as repositories on GitHub. With this in place, you can set up the automation of updates when there is new code ready for deployment. With this “GitOps” approach, you experience the following benefits with Flux:

  • You won’t have to grant your continuous integration (CI) system  access to the Kubernetes cluster.
  • Every code change is atomic and transactional.
  • Your audit log will be saved in Git.
  • Every transaction will either succeed or fail cleanly.
  • Your DevOps lifecycle is completely code-centric, so you won’t need new infrastructure.

Flux can be deployed on Amazon Web Services, Google Cloud, Microsoft Azure, and even in your self-hosted data center. I want to walk you through the process of installing Flux on AlmaLinux 8. What you’ll need to make this work is a running instance of a Kubernetes cluster, as well as a GitHub account. To make the connection between the two, you’ll also have to generate a GitHub personal access token.

Let’s get Flux up and running, so you can empower your Kubernetes and GitHub connection with continuous deployment.

Create a GitHub Access Token

The first thing to do is generate a GitHub personal access token. To do that, log in to your GitHub account and click your profile image at the top right of the main window. Select Settings from the drop-down menu. In the Settings window, select Developer Settings from the left navigation and then click Personal access token (Figure 1).

Figure 1: The GitHub developer settings window, where you can select to generate a new personal access token.

In the resulting window, click Generate new token. You will then be prompted to give the new token a name and select the necessary options for the repository (Figure 2).

Figure 2: Configuring your new personal access token on GitHub.

Once you’ve selected the necessary options, scroll down and click Generate token. When the token generation is complete, make sure to copy the new token, as you’ll need it in a bit.

Install Flux

The next step is to install Flux. Remember, this must be installed within a Kubernetes cluster, so make sure to have that up and running, before you begin the Flux installation. Log into your Kubernetes controller and install Flux with the command:

curl -s https://fluxcd.io/install.sh | sudo bash

Once that’s installed, finish the installation with the command:

. <(flux completion bash)

At this point, there’s a software dependency that isn’t listed anywhere in the documentation. I spent about five hours trying to get Flux to work, only to have it constantly fail on me. It wasn’t until (on a whim), I attempted to install the modules manually that I discovered the tool required Go on the system. Once I installed Go, I was able to run the flux install command with success. This is yet another instance of a large company or project with documentation that does the users no favors. So to install Go, use the following commands:

You will also need to have Kind installed, so if your Kubernetes cluster doesn’t already include that tool, install it with the commands:

curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.11.0/kind-linux-amd64

chmod +x ./kind

mv ./kind /usr/bin/kind

Create the Kubernetes cluster with the command:

kind create cluster

The above command will take some time to complete.

Now, remember the personal access token you created earlier? Here’s where it’s needed. Set the token to your shell environment with the command:

export GITHUB_TOKEN=<your-token>

Set your GitHub username with the command:

export GITHUB_USER=<your-username>

Where your-token is the personal access token you copied from GitHub and your-user is your GitHub username.

Finally, install the necessary flux components with the command:

flux install

When this completes, you should see:

Run the Bootstrap Command

Next, we’re going to run the bootstrap command to connect Flux to your personal GitHub repository. This command looks like this:

flux bootstrap github --owner=$GITHUB_USER --repository=REPOSITORY --path=clusters/CLUSTER --personal

Where:

  • USERNAME is your GitHub username
  • REPOSITORY is the GitHub repository you want to sync
  • CLUSTER is the name you’ll give the local repository (which could be the same as what is used for REPOSITORY)

Let’s make this a bit more useful. The above command works for a personal repository. Chances are good you have a team repository, where more than one developer is working. The Flux command for bootstrapping an organizational repository looks like this:

flux bootstrap github --owner=ORGANIZATION --repository=REPOSITORY --team=TEAM1SLUG --team=TEAM2SLUG --path=clusters/CLUSTER

Where:

  • ORGANIZATION is the organization associated with the GitHub repository.
  • REPOSITORY is the name of the repository to be used.
  • TEAM*SLUG is the slug GitHug generated for each team (which is derived from the team name)

Getting Around Install Errors

You shouldn’t have any problems getting flux installed with the above steps. This is especially true if your Kubernetes cluster is hosted by a cloud service provider (such as AWS, Google Cloud, Azure, Linode, or Rackspace) and if you’ve installed all of the necessary components. If, however, you’ve deployed flux to an on-premise cluster, and you get component failure errors when running the bootstrap command, those can most likely be resolved by installing Flux without storing its manifests in a Git repository. This is done with the command:

kubectl apply -f https://github.com/fluxcd/flux2/releases/latest/download/install.yaml

If you’re still receiving errors, you might want to go the fluxctl route. This is done with the following steps.

First, install fluxctl with the command:

sudo snap install fluxctl

With fluxctl installed, export your GitHub username with the command:

export GHUSER="USER"

Now we can install flux to the cluster with the command:

fluxctl install --git-user=${GHUSER} --git-email=${GHUSER}@users.noreply.github.com --git-url=git@github.com:${GHUSER}/flux-get-started --git-path=namespaces,workloads --namespace=flux | kubectl apply -f -

Deploy flux with the command:

kubectl -n flux rollout status deployment/flux

Things You Can Do with Flux

Hopefully, flux has successfully installed and you can do things like pull manifests from your Git repository and update itself with the command:

flux reconcile source git flux-system

If you’ve made any changes to manifest, you can issue the command:

flux install

The above command will apply the new manifest changes to your cluster.

Let’s say you want to do automated image updates with Flux. For that, you must install flux with the necessary components with the following steps.

Export the necessary environment variables with the commands:

export GITHUB_TOKEN=<your-token>

export GITHUB_USER=<your-username>

Where your-token is your GitHub access token and your-username is your GitHub username.

Install flux with the automated image components with the command:

flux bootstrap github --components-extra=image-reflector-controller,image-automation-controller --owner=$GITHUB_USER --repository=flux-image-updates --branch=main --path=clusters/my-cluster --read-write-key --personal

Clone this demo repository with the command:

git clone git@github.com:@GITHUB_USER/flux-image-updates.git

Change into the newly created directory:

cd flux-image-updates

Make some changes to one of the files or add a README to the repository.

Next, commit and push the changes with the commands:

git add -A

git commit -m "Made changes to the test repository"

git push origin main

Flux will eventually detect the changes and apply them.

Of course, your mileage may vary with flux. It all depends on how you’ve deployed your Kubernetes cluster if you’ve deployed it correctly, and how you’ve implemented a GitOps and CI/CD strategy.

The New Stack is a wholly owned subsidiary of Insight Partners. TNS owner Insight Partners is an investor in the following companies: MADE, Bit.

A newsletter digest of the week’s most important stories & analyses.