Light Dark Auto

Install greymatter on Kubernetes

Install the greymatter mesh on Kubernetes using GitOps

Get started by deploying greymatter on Kubernetes using a GitOps pattern, which is flexible enough to support simple quick starts to complex enterprise deployments. We supply a Kubernetes Operator to install the core components of the greymatter platform into a Kubernetes cluster.

Establish greymatter Core Git Repository

Let’s set up a GitHub repository for a base greymatter installation. You can use other Git providers like GitLab as well. Additional reading on our configuration management philosophy is recommended to help understand why we use Git and CUE for managing mesh configurations.

  1. Create a private repository named gitops-core in your GitHub organization. For simple dev-test deployments you can use your personal account as well. A private repository is important so you have full control over configuration changes.

  2. Initialize your new repository by running the following commands. Be sure to change git@github.com:<your-org>/gitops-core.git to contain your actual organization name. Note also that we are referencing the v0.10.0 tag which must match the operator version.

    # clones greymatter/gitops-core from a specific tag
    # also conveniently does *not* create branch `main`, which we create below
    git clone --branch v0.10.0 git@github.com:greymatter-io/gitops-core.git
    cd gitops-core
    # creates a new main branch with clean history
    git checkout --orphan main
    # switches remote repository to your organization
    git remote set-url origin git@github.com:<your-org>/gitops-core.git
    # creates an initial commit
    git commit -am "initial commit"
    # pushes main branch to your repository
    git push -u origin main
    

    If there are no errors during this process and you see <your-org>/gitops-core populated with greymatter Core CUE configurations then you're ready for the next step.

Install greymatter Base Fabric

Prepare Mesh Settings

Let's start by first discussing a couple of settings in <your-org>/gitops-core repository. By default, greymatter will install Prometheus into your Kubernetes cluster to support historical metrics visualization in our dashboard. If you want this feature, ensure your Kubernetes environment has enough resources. Please see the prerequisites for details.

If you choose to disable this feature before the mesh is installed, navigate to <your-org>/gitops-core repository and edit inputs.cue by changing enable_historical_metrics to false.

enable_historical_metrics: bool | *false @tag(enable_historical_metrics,type=bool)

Secondly, greymatter will install an audit pipeline that has a dependency on an external Elasticsearch. There is no requirement at install-time to have Elasticsearch available and you may configure the audit pipeline to use Elasticsearch after installation.

If you choose to disable this feature before the mesh is installed, navigate to <your-org>/gitops-core repository and edit inputs.cue by changing enable_audits to false.

enable_audits: bool | *false @tag(enable_audits,type=bool)

Another important note is that the operator watches namespaces for sidecar injection. This is an "opt-in" approach i.e. greymatter will only inject sidecars into pods in namespaces that you choose. To add namespaces that the operator watches, navigate to <your-org>/gitops-core repository and edit inputs.cue and additional namespaces to the list.

watch_namespaces: [...string] | *["default", “examples”]

We have taken the liberty of adding the examples namespace because it will be used later in these docs. If you don't need the operator to watch the default and examples namespaces, feel free to remove them. Greymatter does not deploy core resources to the default Kubernetes namespace but if you deploy your own resources to the default namespace and you would like the operator to inject sidecars, leave it in the list.

Install on Kubernetes

  1. Create the operator namespace

    kubectl create namespace gm-operator
    
  2. Create the SSH key secret, using the SSH key you set up earlier. This allows the operator to pull configurations from <your-org>/gitops-core repository. Change the path/name of your SSH key accordingly.

    kubectl create secret generic greymatter-sync-secret \
      --from-file=ssh_private_key=$HOME/.ssh/id_ed25519 \
      -n gm-operator
    
  3. Set quay.io Docker registry environment variables. If you don't have a quay.io account yet with access to the greymatterio organization, contact us for more information.

    export GREYMATTER_REGISTRY=quay.io
    export GREYMATTER_REGISTRY_USERNAME=YOUR_USERNAME
    export GREYMATTER_REGISTRY_PASSWORD=YOUR_PASSWORD
    
  4. Create the secret used for pulling Docker images from quay.io.

    kubectl create secret docker-registry gm-docker-secret \
      --docker-server=$GREYMATTER_REGISTRY \
      --docker-username=$GREYMATTER_REGISTRY_USERNAME \
      --docker-password=$GREYMATTER_REGISTRY_PASSWORD \
      --docker-email=$GREYMATTER_REGISTRY_USERNAME \
      -n gm-operator
    
  5. Open <your-org>/gitops-core/operator.yaml, search for the args block, and change the value of git@github.com:<your-org>/gitops-core.git to contain your GitHub organization and repository name.

    args:
      - -repo
      - git@github.com:<your-org>/gitops-core.git
      - -sshPrivateKeyPath
      - /app/.ssh/ssh_private_key
      - -branch
      - main
      # optional
      - -sshPrivateKeyPassword
      - YOUR_SSH_KEY_PASSWORD
    
  6. Now, apply the operator manifest to your Kubernetes cluster.

    kubectl apply -f operator.yaml
    

Verify Installation

At this point the operator should be deployed. It will take less then a minute to configure the mesh but you can tail the logs to monitor its activity.

kubectl logs -f greymatter-operator-0 -n gm-operator

When you see a log message that looks like the following, the operator will have begun the process of configuring the mesh.

{"level":"info","ts":1663338550.800288,"logger":"mesh_install","msg":"Installing Mesh","Name":"greymatter-mesh"}

Once completed, the operator will have downloaded the core mesh components, installed the service Catalog API, an Edge gateway, a Redis cache server, the dashboard application, and the service mesh Control Plane ensemble. Everything was configured from the configurations found in <your-org>/gitops-core Git repository and you have full control over these core services going forward.

You can run the below command to ensure that pods are deployed successfully. This process will take a moment, so no output is expected until the operator deploys the Kubernetes resources.

kubectl get pods -n greymatter -w

This will watch for pods in the greymatter namespace. When you see the following in your console you are ready to move onto the next step.

NAME                         READY   STATUS    RESTARTS   AGE
catalog-[random-pod-id]      2/2     Running   0          5m
controlensemble-0            3/3     Running   0          5m
dashboard-[random-pod-id]    2/2     Running   0          5m
edge-[random-pod-id]         1/1     Running   0          5m
redis-0                      2/2     Running   0          5m

If you have enabled historical metrics, you will also see:

prometheus-0                 2/2     Running   0          5m

If you have enabled audits, you will also see:

vector-agent-[random-pod-id]  0/1     CreateContainerConfigError   0          5m
observables-[random-pod-id]   1/2     CreateContainerConfigError   0          5m

You can finalize the audit pipeline configuration in the Prepare Audit Pipeline step

Once you see the above in your terminal, you need to run the below command to get the external IP exposed from the edge service.

kubectl get svc edge -n greymatter

You should see an output like:

NAME   TYPE           CLUSTER-IP   EXTERNAL-IP     PORT(S)           AGE
edge   LoadBalancer   x.x.x.x      x.x.x.x         10808:32021/TCP   48m

Navigate to http://{EXTERNAL-IP}:10808 in your web browser.

Congratulations! You should now have a fully operational greymatter.io enterprise microservices platform!

Prepare Audit Pipeline

The audit pipeline's only external dependency is Elasticsearch. If you do not have Elasticsearch you can skip this step.

There are a couple of things we need from your Elasticsearch configuration.

  1. Create the Elasticsearch basic auth password secret. This secret will be used by the audit pipeline to read/write audit messages from/to Elasticsearch.

    kubectl create secret generic elasticsearch-password \
      --from-literal=password=<ELASTICSEARCH_PASSWORD> \
      -n greymatter
    

    Once you have created the secret you should see that both pods have been created:

    NAME                          READY   STATUS    RESTARTS     AGE
    observables-[random-pod-id]   0/1     Running   0            6m7s
    vector-agent-[random-pod-id]  0/1     Error     3 (38s ago)  6m7s
    

    However, the vector-agent pod will be in an Error state because it's missing your Elasticsearch hostname.

  2. Update inputs.cue with Elasticsearch hostname and port and push the changes to <your-org>/gitops-core Git repository.

    audits: {
      elasticsearch_host: ""
      elasticsearch_port: 443
    }
    

Next Steps