Skip to main content
Version: 0.9.5

Installing Weave GitOps​

This section details the steps required to install Weave GitOps on a Kubernetes cluster.

Pre-requisites​

Kubernetes Cluster​

This version of Weave GitOps is tested against the following Kubernetes releases:

  • 1.22
  • 1.23
  • 1.24
  • 1.25

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

Install Flux​

Weave GitOps is an extension to Flux and therefore requires that Flux 0.32 or later has already been installed on your Kubernetes cluster. Full documentation is avilable at: https://fluxcd.io/docs/installation/.

This version of Weave GitOps is tested against the following Flux releases:

  • 0.32
  • 0.33
  • 0.34

Install the Helm Chart​

Weave GitOps is provided through a Helm Chart and installed as a Flux resource through a HelmRepository and HelmRelease. To install on your cluster, adjust the following so that username is the username you want and passwordHash is a bcrypt hash of your password, and commit the file to the location bootstrapped with Flux so that it is synchronized to your Cluster.

apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: ww-gitops
  namespace: flux-system
spec:
  chart:
    spec:
      chart: weave-gitops
      sourceRef:
        kind: HelmRepository
        name: ww-gitops
  interval: 1h0m0s
  values:
    adminUser:
      create: true
      username: <UPDATE>
      passwordHash: <UPDATE>
---
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  name: ww-gitops
  namespace: flux-system
spec:
  interval: 1h0m0s
  type: oci
  url: oci://ghcr.io/weaveworks/charts

There are many other values you can configure - for more information, see our value file reference.

Installing Weave GitOps Enterpriseenterprise​

Weave GitOps Enterprise (WGE) provides ops teams with an easy way to assess the health of multiple clusters in a single place. It shows cluster information such as Kubernetes version and number of nodes and provides details about the GitOps operations on those clusters, such as Git repositories and recent commits. Additionally, it aggregates Prometheus alerts to assist with troubleshooting.

To purchase entitlement to Weave GitOps Enterprise please contact sales@weave.works

note

There is no need to install Weave GitOps (Core) before installing Weave GitOps Enterprise

To install Weave GitOps Enterprise

1. Set up a Management Cluster with flux​

To get you started in this document we'll cover:

  • kind as our management cluster with the CAPD provider
  • EKS as our management cluster with the CAPA provider

However Weave GitOps Enterprise supports any combination of management cluster and CAPI provider.

1.1 We start with creating a kind-config.​
kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraMounts:
      - hostPath: /var/run/docker.sock
        containerPath: /var/run/docker.sock

The extraMounts are for the Docker CAPI provider (CAPD) to be able to talk to the host docker

1.2 Start your kind cluster using the configuration above and Kubernetes v1.23.6​
kind create cluster --config kind-config.yaml --image=kindest/node:v1.23.6
Install Flux onto your cluster with the flux bootstrap command.​
flux bootstrap github \
  --owner=<github username> \
  --repository=fleet-infra \
  --branch=main \
  --path=./clusters/management \
  --personal
  • owner - The username (or organization) of the git repository
  • repository - Git repository name
  • branch - Git branch (default "main")
  • path - path relative to the repository root, when specified the cluster sync will be scoped to this path
  • personal - if set, the owner is assumed to be a repo user

More information about flux and the flux bootstrap command can be found here

At this point a few things have occurred:
  • Your Flux management cluster is now running
  • A new git repo was created based on the parameters you set in the flux bootstrap command. Take a look at your repositories.

2. Install a CAPI provider​

clusterctl versions

The example templates provided in this guide have been tested with clusterctl version 1.1.3. However you might need to use an older or newer version depending on the capi-providers you plan on using.

Download a specific version of clusterctl from the releases page.

In order to be able to provision Kubernetes clusters, a CAPI provider needs to be installed. See Cluster API Providers page for more details on providers. Here we'll continue with our example instructions for CAPD and CAPA.

# Enable support for `ClusterResourceSet`s for automatically installing CNIs
export EXP_CLUSTER_RESOURCE_SET=true

clusterctl init --infrastructure docker

3. Apply the entitlements secret​

Contact sales@weave.works for a valid entitlements secret. Then apply it to the cluster:

kubectl apply -f entitlements.yaml

4. Configure access for writing to git from the UI​

GitHub requires no additional configuration for OAuth git access

5. Configure and commit​

We deploy WGE via a Helm chart. We'll save and adapt the below template, before commiting it to git to a flux-reconciled path.

Clone the newly created repo locally as we're gonna add some things!

git clone git@<provider>:<username>/fleet-infra
cd fleet-infra

Download the helm-release to clusters/management/weave-gitops-enterprise.yaml and tweak:

clusters/management/weave-gitops-enterprise.yaml
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  name: weave-gitops-enterprise-charts
  namespace: flux-system
spec:
  interval: 60m
  secretRef:
    name: weave-gitops-enterprise-credentials
  url: https://charts.dev.wkp.weave.works/releases/charts-v3
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: weave-gitops-enterprise
  namespace: flux-system
spec:
  chart:
    spec:
      interval: 65m
      chart: mccp
      sourceRef:
        kind: HelmRepository
        name: weave-gitops-enterprise-charts
        namespace: flux-system
      version: 0.9.5
  install:
    crds: CreateReplace
  upgrade:
    crds: CreateReplace
  interval: 50m
  values:
    # -- Configure TLS settings if needed
    # tls:
      # -- Can be disabled if TLS is handled by a user-provided ingress controller
      # enabled: true
      # -- optionally specify a TLS secret
      # secretName: null
    config:
      capi:
        repositoryURL: https://github.com/$GITHUB_USER/fleet-infra
        # -- Can be changed depending on your git repo structure
        # repositoryPath: ./clusters/management/clusters
        # repositoryClustersPath: ./cluster
      git:
        type: github
        # -- Change if using on-prem github/gitlab
        # hostname: https://github.com

values.config.capi.repositoryURL​

Ensure this has been set to your repository URL.

values.config.capi.repositoryPath​

By default, WGE will create new clusters in the clusters/management/clusters path. This can be configured with values.config.capi.repositoryPath. For example you might what to change it to clusters/my-cluster/cluster if you configured flux to reconcile ./clusters/my-cluster instead.

values.config.capi.repositoryClustersPath​

The other important path to configure is where applications and workloads that will be run on the new cluster will be stored. By default this is ./clusters. When a new cluster is specified any profiles that have been selected will be written to ./clusters/{.namespace}/{.clusterName}/profiles.yaml. When the new cluster is bootstrapped, flux will be sync the ./clusters/{.namespace}/{.clusterName} path.

(Optional) Install policy agent​

Policy agent comes packaged with the WGE chart. To install it you need to set the following values:

  • values.policy-agent.enabled: set to true to install the agent with WGE
  • values.policy-agent.config.accountId: organization name, used as identifier
  • values.policy-agent.config.clusterId: unique identifier for the cluster

Commit and push all the files

git add clusters/management/weave-gitops-enterprise.yaml
git commit -m "Deploy Weave GitOps Enterprise"
git push

Flux will reconcile the helm-release and WGE will be deployed into the cluster. You can check the flux-system namespace to verify all pods are running.

6. Configure password​

In order to login to the WGE UI, you need to generate a bcrypt hash for your chosen password and store it as a secret in the Kubernetes cluster.

There are several different ways to generate a bcrypt hash, this guide uses gitops get bcrypt-hash from our CLI, which can be installed by following the instructions here.

PASSWORD="<your password>"
echo -n $PASSWORD | gitops get bcrypt-hash
$2a$10$OS5NJmPNEb13UgTOSKnMxOWlmS7mlxX77hv4yAiISvZ71Dc7IuN3q

Use the hashed output to create a Kubernetes username/password secret.

kubectl create secret generic cluster-user-auth \
  --namespace flux-system \
  --from-literal=username=wego-admin \
  --from-literal=password='$2a$.......'

7. Check that WGE is installed​

You should now be able to load the WGE UI by port forwarding. 

kubectl port-forward --namespace flux-system svc/clusters-service 8000:8000

The WGE UI should now be accessible at https://localhost:8000.

Use the username above and regular password (not the hashed version) to login.

Head over to either:

(Optional) Install the TF-Controller​

The TF-Controller is a controller for Flux to reconcile Terraform resources in a GitOps way.

With Flux and the TF-Controller, Weave GitOps Enterprise makes it easy to add Terraform templates to clusters and continuously reconcile any changes made to the Terraform source manifest.

Check out our guide on how to use Terraform templates, and why not try your hands at using it with the RDS example!

Install the TF-Controller to a cluster using Helm:

# Add tf-controller helm repository
helm repo add tf-controller https://weaveworks.github.io/tf-controller/

# Install tf-controller
helm upgrade -i tf-controller tf-controller/tf-controller \
    --namespace flux-system

Consult the TF-Controller Installation documentation for more details on which parameters are configurable and how to install a specific version.

Install CLI​

Install the Weave GitOps Enterprise CLI tool. You can use brew or curl

brew install weaveworks/tap/gitops-ee
curl -O https://artifacts.wge.dev.weave.works/releases/bin/0.9.5/gitops-linux-x86_64.tar.gz

AWS Marketplace​

Weave GitOps is also available via the AWS Marketplace.

The following steps will allow you to deploy the Weave GitOps product to an EKS cluster via a Helm Chart.

These instructions presume you already have installed kubectl, eksctl, helm and the Helm S3 Plugin.

Step 1: Subscribe to Weave GitOps on the AWS Marketplace​

To deploy the managed Weave GitOps solution, first subscribe to the product on AWS Marketplace. This subscription is only available for deployment on EKS versions 1.17-1.21.

Note: it may take ~20 minutes for your Subscription to become live and deployable.

[Optional] Step 2: Create an EKS cluster​

If you already have an EKS cluster, you can skip ahead to Step 3.

If you do not have a cluster on EKS, you can use eksctl to create one.

Copy the contents of the sample file below into cluster-config.yaml and replace the placeholder values with your settings. See the eksctl documentation for more configuration options.

---
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
  name: CLUSTER_NAME # Change this
  region: REGION # Change this

# This section is required
iam:
  withOIDC: true
  serviceAccounts:
  - metadata:
      name: wego-service-account # Altering this will require a corresponding change in a later command
      namespace: flux-system
    roleOnly: true
    attachPolicy:
      Version: "2012-10-17"
      Statement:
      - Effect: Allow
        Action:
        - "aws-marketplace:RegisterUsage"
        Resource: '*'

# This section will create a single Managed nodegroup with one node.
# Edit or remove as desired.
managedNodeGroups:
- name: ng1
  instanceType: m5.large
  desiredCapacity: 1

Create the cluster:

eksctl create cluster -f cluster-config.yaml

[Optional] Step 3: Update your EKS cluster​

If you created your cluster using the configuration file in Step 2, your cluster is already configured correctly and you can skip ahead to Step 4.

In order to use the Weave GitOps container product, your cluster must be configured to run containers with the correct IAM Policies.

The recommended way to do this is via IRSA.

Use this eksctl configuration below (replacing the placeholder values) to:

  • Associate an OIDC provider
  • Create the required service account ARN

Save the example below as oidc-config.yaml

---
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
  name: CLUSTER_NAME # Change this
  region: REGION # Change this

# This section is required
iam:
  withOIDC: true
  serviceAccounts:
  - metadata:
      name: wego-service-account # Altering this will require a corresponding change in a later command
      namespace: flux-system
    roleOnly: true
    attachPolicy:
      Version: "2012-10-17"
      Statement:
      - Effect: Allow
        Action:
        - "aws-marketplace:RegisterUsage"
        Resource: '*'

eksctl utils associate-iam-oidc-provider -f oidc-config.yaml --approve
eksctl create iamserviceaccount -f oidc-config.yaml --approve

Step 4: Fetch the Service Account Role ARN​

First retrieve the ARN of the IAM role which you created for the wego-service-account:

# replace the placeholder values with your configuration
# if you changed the service account name from wego-service-account, update that in the command
export SA_ARN=$(eksctl get iamserviceaccount --cluster <cluster-name> --region <region> | awk '/wego-service-account/ {print $3}')

echo $SA_ARN
# should return
# arn:aws:iam::<account-id>:role/eksctl-<cluster-name>-addon-iamserviceaccount-xxx-Role1-1N41MLVQEWUOF

This value will also be discoverable in your IAM console, and in the Outputs of the Cloud Formation template which created it.

Step 5: Install Weave GitOps​

Copy the Chart URL from the Usage Instructions in AWS Marketplace, or download the file from the Deployment template to your workstation.

To be able to log in to your new installation, you need to set up authentication. Create a new file values.yaml where you set your username, and a bcrypt hash of your desired password, like so:

./values.yaml
gitops:
  adminUser:
    create: true
    username: <UPDATE>
    passwordHash: <UPDATE>

Then install it:

helm install wego <URL/PATH> \
  --namespace=flux-system \
  --create-namespace \
  --set serviceAccountRole="$SA_ARN" \
  --values ./values.yaml

# if you changed the name of the service account
helm install wego <URL/PATH> \
  --namespace=flux-system \
  --create-namespace \
  --set serviceAccountName='<name>' \
  --set serviceAccountRole="$SA_ARN" \
  --values ./values.yaml

Step 6: Check your installation​

Run the following from your workstation:

kubectl get pods -n flux-system
# you should see something like the following returned
flux-system          helm-controller-5b96d94c7f-tds9n                    1/1     Running   0          53s
flux-system          kustomize-controller-8467b8b884-x2cpd               1/1     Running   0          53s
flux-system          notification-controller-55f94bc746-ggmwc            1/1     Running   0          53s
flux-system          source-controller-78bfb8576-stnr5                   1/1     Running   0          53s
flux-system          wego-metering-f7jqp                                 1/1     Running   0          53s
flux-system          ww-gitops-weave-gitops-5bdc9f7744-vkh65             1/1     Running   0          53s

Your Weave GitOps installation is now ready!

The quickest way to access your dashboard is by setting up a port forward:

kubectl port-forward svc/ww-gitops-weave-gitops -n flux-system 9001:9001

Then, open the dashboard.

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.

To install:

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

Alternatively, users can use Homebrew:

brew tap weaveworks/tap
brew install weaveworks/tap/gitops