Skip to main content
Version: 0.17.0

Get Started with GitOps Run

GitOps Run supports two different modes of operation - directly on a cluster or as sandboxed sessions. The sandboxed sessions are intended for shared environments where multiple users are running their own sessions, whereas the direct mode is intended for a local cluster.

Direct mode​

Prerequisites​

Required​

Optional​

  • This guide uses kubectl for demonstrations, but it is not required to use GitOps Run
  • The Flux CLI is the quickest way to generate resource definitions, but the files can also be created manually

Kubernetes cluster​

To get started with GitOps Run, you need a Kubernetes cluster. There are many tools to set up a local cluster for test and development purposes.

Note: this tutorial assumes you have full control of your cluster - we recommend a local cluster, but you can also use a remote cluster where you have full cluster-admin privileges.

Install kind and run

kind create cluster

Before you continue, make sure kubectl get nodes returns a node which is Ready.

Git repository​

You need to set up a Git repository to put your GitOps manifests in. Any Git repository would do, for example create a new github repository and clone that. We use podinfo-gitops-run as the repository name in this guide.

Set up GitOps Run​

To start GitOps Run, point it at the directory you want to keep your application manifests. In this example, we will install a small demo application podinfo.

We will start it with --no-session as it's a single user cluster which we want to use in direct mode. The port-forward points at the podinfo pod we will create later.

export GITHUB_USER=<your github username>

# you can ignore these two commands if you already created and cloned your repository
git clone git@github.com:$GITHUB_USER/podinfo-gitops-run.git

cd podinfo-gitops-run
gitops beta run ./podinfo --no-session --port-forward namespace=dev,resource=svc/dev-podinfo,port=9898:9898

You will now be asked if you want to install Flux and the GitOps dashboard. Answer yes and set a password, and shortly after you should be able to open the dashboard to see what's in your cluster - including the resources that GitOps Run is operating.

Start modifying​

GitOps Run will have created a directory podinfo in your current directory. Inside that directory, there will only be a single file kustomization.yaml.

To create the podinfo automation, we have to create the resources to run podinfo - we'll create a new Namespace, a HelmRepository that references the Helm repository where the manifests are stored, and a HelmRelease that references the chart and version. We can use the flux CLI to generate the resource definition, or we can just create the yaml files ourselves.

cat <<EOF > ./podinfo/namespace.yaml
---
apiVersion: v1
kind: Namespace
metadata:
  name: dev
EOF
flux create source helm podinfo --url=https://stefanprodan.github.io/podinfo --namespace=dev --export > ./podinfo/podinfo-source.yaml
flux create helmrelease podinfo --source=HelmRepository/podinfo --chart=podinfo --export --namespace=dev --target-namespace=dev > ./podinfo/podinfo-helmrelease.yaml

The only remaining step is to import these files in the auto-generated kustomization.yaml. Open it up, and you should see the following:

./podinfo/kustomization.yaml
---
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources: [] # 👋 Start adding the resources you want to sync here

Change the last line so it instead looks like the following:

./podinfo/kustomization.yaml
---
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - namespace.yaml
  - podinfo-source.yaml
  - podinfo-helmrelease.yaml

GitOps Run should now automatically upload these manifests and install them. The dashboard should show you how the resources are being reconciled, and when they're Ready you will be able to see podinfo here.

Update your app​

Now that GitOps Run is continuously watching and reconciling your local files onto your cluster, we can start modifying the resources.

We're going to be modifying the podinfo we set up in the previous step. Open the current podinfo and pay attention to the background color.

Now, open your HelmRelease file and add the values at the bottom, as indicated:

./podinfo/podinfo-helmrelease.yaml
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: podinfo
  namespace: dev
spec:
  chart:
    spec:
      chart: podinfo
      reconcileStrategy: ChartVersion
      sourceRef:
        kind: HelmRepository
        name: podinfo
  interval: 1m0s
  targetNamespace: dev
  values:
    ui:
      color: "#C32148"

When you hit save, you'll see GitOps Run upload new files, and once it's reconciled the podinfo has changed to a bright red.

Turn on GitOps Mode​

Now that we've used this interactive environment to set up the resources we want, we can switch over to full GitOps mode, where Flux is permanently pulling from your own Git repository.

The first run, when you turn off GitOps Run, it will ask you if you want to bootstrap your cluster into GitOps mode. If you answer yes, it will take you through a wizard to help you set up how you want it to run - what repository, which branch, etc.

When you hit submit, it will set up the repository and branch, add Flux manifests, as well as the files you were just working on. From this point on, you can make persistent changes by pushing them to this repository.