Light Dark Auto


Version-controlled mesh configuration

This guide explains the basic GitOps pattern necessary to have (multiple) version-controlled mesh configuration repositories feeding deployed Grey Matter mesh. It will assume a local set up, but the general pattern is applicable to production environments as well.

The Pattern

GitOps is the generic term for a method of managing live environments from Git repositories so that the usual Git workflow for managing changes to software can apply operationally as well. This works by having the central source of truth for the live environment be a Git repository, with a synchronization process watching the repository for changes to some protected branch. When that branch is updated, differences from the live environment are automatically reconciled, and the live environment is updated to match the description in the repository. Proposed changes to the environment follow a Pull Request / Merge Request process that may differ between organizations, but when changes are deemed worthy, it suffices to merge the change in to apply it to the live environment.


1. Set up your local environment

Before following the rest of this guide, please take a moment to deploy a mesh locally using the install a mesh locally guide. It's expected that you will be using this local mesh to set up GitOps.

2. Fork the gitops-examples repository

Gitops Examples is a public GitHub repository with example configuration. Create a fork of this repository in your personal or organization account to use as an example GitOps repository. The goal is for changes to this repository to take effect in your local Grey Matter mesh.

Going forward, we will assume you have a copy of this repository with an SSH clone url of, and that your fork is still public.

3. Launch the Grey Matter Sync container

Although any trusted synchronization process capable of watching a Git repository and executing the CLI would suffice to establish a GitOps process, Grey Matter provides [functionality for this in the CLI itself](/configuration/ There is also a Kubernetes-ready Docker container which wraps the continuous synchronization functions of the CLI. The CLI itself can be used to launch this container.

Since you needed the Grey Matter CLI 4.0.6+ for the local development installation, we shall assume you already have it available, though it may still be unconfigured.

Start by running the following to generate the starter manifest for the sync container. In the future these manifests will be immediately applicable to Kubernetes, but right now they require patching. Replace the private key path with the path to your own key, and replace the git remote with your own fork. In future the private key will not be necessary for your public fork, but at the moment the sync container requires it.

greymatter k8s sync \
    --git-remote="" \
    --ssh-private-key="$HOME/.ssh/id_ed25519" \
    --image="" \
    > sync_container_manifest.yaml

Now edit the manifest. The only changes we need to make are to add two arguments to the command run by the sync container, both of which are to accommodate the gitops-examples repository for this guide:

  • "--relative-path", "1.7"
  • "--branch", "gitops_guide"

Your arguments should look as follows:

args: ["-c", "/etc/greymatter/config.toml", "sync", "--cue", "--git", "--forever", "--interval", "10s", "--git-dir", "/var/lib/greymatter/checkout", "--relative-path", "1.7", "--branch", "gitops_guide"]

You may now run the sync container by applying this manifest.

kubectl apply -f sync_container_manifest.yaml

While you wait for that to start up, and for its sidecar configuration to stabilize, clone your fork of the gitops examples repository locally, and enter the repo directory.

git clone
cd gitops-examples
git checkout gitops_guide

We are going to apply the manifests for four services from the manifests directory. They all look similar to this:

apiVersion: apps/v1
kind: Deployment
  name: apple
  namespace: examples
  annotations: "8080" "true"
      app: apple
        app: apple
        - name: apple
          image: python:3
          command: ["python"]
          args: ["-m", "http.server", "8080"]

Each one is a simple Deployment, with only one container. The Grey Matter Operator will inject a sidecar, but because of the "false" annotation, it will be unconfigured other than the minimum necessary to connect it to Grey Matter Control and set up its certificates.

Apply them all at once, from inside the gitops-examples repository directory:

kubectl apply -f manifests/

Once everything has stabilized, you should be able to get to http://localhost:10808/services/apple/latest/, according to the CUE configuration in gitops-examples/1.7/. If you were to modify the configuration in the gitops_guide branch of your gitops-examples fork and push the change to GitHub, your new configuration would automatically be applied to your mesh.