Skip to main content
Version: 0.7.0

Installing Weave GitOps​

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

Pre-requisites​

Kubernetes Cluster​

Weave GitOps is compatible with conformant Kubernetes distributions which match the minimum required version level of Flux.

Install Flux​

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

Configure access to the GitOps Dashboard web UI​

Weave GitOps includes a web UI which runs on your Kubernetes cluster. In order to allow users to access this, you must first configure an appropriate login mechanism. We support integration with OIDC providers, as well as an admin cluster user for getting started and emergencies. This cluster user can be disabled if preferred.

Follow the guide here to appropriately configure access : Securing access to the dashboard.

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 where marked <UPDATE> based on the previous step, 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: 1m0s
  values:
    adminUser:
      create: true
      passwordHash: <UPDATE>
      username: <UPDATE>
    namespace: flux-system
    rbac:
      create: true
---
apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: HelmRepository
metadata:
  name: ww-gitops
  namespace: flux-system
spec:
  interval: 1m0s
  url: https://helm.gitops.weave.works

Installing the gitops CLI​

The gitops command line interface provides a set of commands to make it easier to interact with Weave GitOps, including both the free open source project, and commercial Weave GitOps Enterprise product. It is currently supported on Mac (x86 and Arm), and Linux including WSL.

Windows support is a planned enhancement.

To install the gitops CLI, please follow the following steps:

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

You should see:

Current Version: v0.7.0-rc13-1-g3d246fd0
GitCommit: 3d246fd0
BuildTime: 2022-04-12_23:34:46
Branch: HEAD

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

BEFORE YOU START

Make sure the following software is installed before continuing with these instructions:

  • gitops >= 0.6.2 download a newer version of Weave GitOps from the releases page.

Also GITHUB_TOKEN or GITLAB_TOKEN should be set as an environment variable in the current shell. It should have permissions to create Pull Requests against the cluster config repo.

To upgrade to Weave GitOps Enterprise

1. Install Weave GitOps​

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.

  • The extraMounts are for the Docker CAPI provider (CAPD) to be able to talk to the host docker
  • extraPortMappings are for easily accessing NATS and the UI
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
    extraPortMappings:
      - containerPort: 30080
        hostPort: 30080
        listenAddress: "0.0.0.0" # Optional, defaults to "0.0.0.0"
        protocol: tcp # Optional, defaults to tcp
      - containerPort: 31490
        hostPort: 31490
        listenAddress: "0.0.0.0" # Optional, defaults to "0.0.0.0"
        protocol: tcp # Optional, defaults to tcp

Fire up cluster

kind create cluster --config kind-config.yaml

Create a new repo

gh repo create my-management-cluster --private --confirm
cd my-management-cluster
echo "# my-management-cluster" > README.md
git add README.md
git commit --all --message "init commit"
git push -u origin main

2. Install a CAPI provider​

clusterctl versions

The example templates provided in this guide have been tested with clusterctl version 1.0.1. 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. Upgrade​

gitops upgrade --version 0.0.18

A Pull Request will be created against your cluster repository. Review and merge this pull request to upgrade to Weave GitOps Enterprise.

6. Checking that WGE is installed​

You should now be able to load the WGE UI:

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

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

7. Connect the management cluster up to itself​

Connecting a cluster installs the agent which is responsible for detecting new clusters and reporting their status to the UI. We need to install the agent on our newly created management cluster. Check out How to: Connect a cluster. The agent should be loaded onto our new management cluster, give it a name like Management and leave the Ingress URL blank.

Head over to either:

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: wego-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 Usage Instructions, or download the file from the Deployment template to your workstation.

helm install wego <URL/PATH> \
  --set serviceAccountRole="$SA_ARN"

# if you changed the name of the service account
helm install wego <URL/PATH> \
  --set serviceAccountName='<name>' \
  --set serviceAccountRole="$SA_ARN"

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          image-automation-controller-5cf75fd555-zqm89        1/1     Running   0          53s
flux-system          image-reflector-controller-6787985855-l4q4g         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

Your Weave GitOps installation is now ready!