Skip to main content
Version: 0.38.0

Step 1: Install Weave GitOps Open Source on Your Cluster

tip

These instructions only apply to Weave GitOps Open Source. To install Weave GitOps Enterprise, go here.

This page covers Weave GitOps Open Source installation and is adapted from the Flux - Getting Started guide.

If you haven't already, please check out our Introduction to Weave GitOps page for additional information about Weave GitOps Open Source as well as our Enterprise version.

Prerequisites​

Before you can install Weave GitOps Open Source, you will need:

  • An account with a Git provider like GitHub or GitLab, along with a personal access token with repo permissions; if you're using GitHub, for example, go here
  • Your Git client configured properly (if using GitHub, for example, then review their docs on setting your username and your email address)
  • Docker Desktop
  • A Kubernetes cluster such as Kind
  • kubectl
  • A public GitHub repo called fleet-infra. To create this, follow GitHub’s instructions—using fleet-infra instead of hello-world.

We also recommend taking a look at the Flux Core Concepts page if you need to brush up on terminology.

Check your Cluster's Kubernetes Version​

No matter which version of Weave GitOps you install, you need to have a Kubernetes cluster up and running. We test Weave GitOps against the latest supported Kubernetes releases.

Note that the version of Flux that you use might impose further minimum version requirements.

Install Flux​

Weave GitOps is an extension to Flux. Therefore, it requires that Flux 0.32 or a later version has already been installed on your Kubernetes cluster. Full documentation is available here.

In this section we are going to do the following:

  • Add Flux component manifests to the repository
  • Deploy Flux components to your Kubernetes cluster
  • Configure the Flux components to track the path ./clusters/my-cluster/ in the repository

Let's get into it... ✨

Install the Flux CLI​

brew install fluxcd/tap/flux

To upgrade to the latest version, run this command:

brew upgrade fluxcd/tap/flux

We recommend upgrading the CLI before running bootstrap to upgrade the controllers with flux bootstrap.

Find which version is installed with flux -v, and use that for flux bootstrap --version=v<CLI-VERSION>.

With Bash, you can run sudo curl -s https://fluxcd.io/install.sh | sudo FLUX_VERSION=<VERSION> bash.

tip

If you want to install an older version of Flux CLI, you can download the binary for your OS from the releases page.

For other installation methods, see the relevant Flux documentation.

Export your credentials​

Ensure your PAT has repo scope.

export GITHUB_TOKEN=<your-token>
export GITHUB_USER=<your-username>

Check your Kubernetes cluster​

flux check --pre

The output is similar to:

► checking prerequisites
✔ kubernetes 1.22.2 >=1.20.6
✔ prerequisites checks passed

Install Flux onto your cluster with the flux bootstrap command​

flux bootstrap creates a flux system folder in your repository that includes the manifests Flux needs to operate. It also generates a key value pair for Flux to access the repo.

The command below assumes the Git provider is github. If you would rather use GitLab, change this to gitlab.

flux bootstrap github \
  --owner=$GITHUB_USER \
  --repository=fleet-infra \
  --branch=main \
  --path=./clusters/my-cluster \
  --personal \
  --components-extra image-reflector-controller,image-automation-controller

Full installation documentation, including how to work with other Git providers, is available here.

Install the gitops CLI​

Weave GitOps includes a command-line interface to help users create and manage resources. The gitops CLI is currently supported on Mac (x86 and Arm) and Linux, including Windows Subsystem for Linux (WSL). Windows support is a planned enhancement.

There are multiple ways to install the gitops CLI:

curl --silent --location "https://github.com/weaveworks/weave-gitops/releases/download/v0.38.0/gitops-$(uname)-$(uname -m).tar.gz" | tar xz -C /tmp
sudo mv /tmp/gitops /usr/local/bin
gitops version

Deploy Weave GitOps​

In this section we will:

  • use the GitOps CLI tool to generate HelmRelease and HelmRepository objects.
  • create some login credentials to access the dashboard. This is a simple but insecure method of protecting and accessing your GitOps dashboard.
  • commit the generated yamls to our fleet-infra repo.
  • observe that they are synced to the cluster.

Clone your Git repository where Flux has been bootstrapped​

git clone https://github.com/$GITHUB_USER/fleet-infra
cd fleet-infra

If you have difficulty saving the YAML to the correct path, run the command mkdir -p ./clusters/my-cluster.

Deploy​

Run the following command, which will create a HelmRepository and HelmRelease to deploy Weave GitOps:

PASSWORD="<A new password you create, removing the brackets and including the quotation marks>"
gitops create dashboard ww-gitops \
  --password=$PASSWORD \
  --export > ./clusters/my-cluster/weave-gitops-dashboard.yaml
danger

This command stores a hash of a password. This is relatively safe for demo and testing purposes, but we strongly recommend using a more secure method of storing secrets (such as Flux's SOPS integration) for production systems.

Our docs on securing access to the dashboard provide additional guidance and alternative login methods.

You will use the password you've just created when you've finished Weave GitOps Open Source installation and are ready to login to the dashboard UI.

danger

Currently, we do not have a persistent session storage, this means that if you scale to multiple replicas, logins will not be persisted.

tip

If you need to customize the Weave GitOps Helm release, you can use the --values CLI flag to supply one or more values files.

Commit and push the weave-gitops-dashboard.yaml to the fleet-infra repository​

git add -A && git commit -m "Add Weave GitOps Dashboard"
git push

Validate that Weave GitOps and Flux are installed​

Note: this wont be instantaneous. Give the Flux controllers a couple of minutes to pull the latest commit.

kubectl get pods -n flux-system

You should see something similar to:

NAME                                       READY   STATUS    RESTARTS   AGE
helm-controller-5bfd65cd5f-gj5sz           1/1     Running   0          10m
kustomize-controller-6f44c8d499-s425n      1/1     Running   0          10m
notification-controller-844df5f694-2pfcs   1/1     Running   0          10m
source-controller-6b6c7bc4bb-ng96p         1/1     Running   0          10m
ww-gitops-weave-gitops-86b645c9c6-k9ftg    1/1     Running   0          5m

If you wait for a while and still nothing happens, it might be that your manifests haven’t been exported to the repository. This means that Weave GitOps won't install.

tip

You can use the Weave GitOps Helm Chart to customize your installation. Find the full Chart reference here.

Next steps​

Now let's explore the Weave GitOps Open Source UI. Then, we'll deploy an application.