Install with Kubernetes

Install Grey Matter with Kubernetes.

This guide assumes that your target environment is a hosted Kubernetes based platform. If you want to test drive Grey Matter on your local machine, follow Deploy with Minikube.

Note: Grey Matter repositories are available to subscribers only. Contact us to discuss subscribing.


Using Helm

Follow the Helm install docs to install Helm locally. Once completed you should have the following tools installed:

  • helm

  • kubectl

Using OpenShift

If you're deploying to OpenShift, install the oc cli then login to your OpenShift environment.

# Example
oc login

Override Helm Charts

You can override our Helm charts with custom YAML files that are chained together during install. We've provided two examples:

.yaml FIle



Provides a primary set of overrides.


Provides a separate set of overrides specifically for passwords, secrets, and other sensitive data.

Copy these files to:

  • custom-greymatter.yaml

  • custom-greymatter-secrets.yaml

as you'll be making changes to them. They will not be picked up by Git.

Configure Global Variables

At the top of custom-greymatter.yaml, set the following four values according to your needs.

# used in our subcharts to apply platform specific settings, values can be `openshift` or `kubernetes` only
environment: openshift
# the domain you're deploying to
# a string that will be prefixed to the final hostname of the deployment
route_url_name: greymatter
# whether to include the virtual cluster namespace in the final hostname of the deployment
remove_namespace_from_url: false
# a map of information specific for Grey Matter observables
# the Kafka topic that the observables should be written to
topic: observables
# the Kafka server connection string

Configure Ingress

If you're using OpenShift, you can skip to the next section because OpenShift will create a route using the domain value.

For Kubernetes, we recommend the Voyager Ingress Controller, which automatically provisions a load balancer from a variety of supported cloud providers like EKS in AWS. This allows you to access the cluster at the provided load balancer URL. Add the following Voyager configuration to your custom-greymatter.yaml file.

Ensure that the value for cloudProvider is one of the supported providers.

cloudProvider: aws
enableAnalytics: false

Configure Voyager Ingress

At present, there's an issue specifying Voyager as a dependency, so we need to manually configure Voyager ingress as a prerequisite.

You can configure Voyager ingress with the following commands:

# PROVIDER should match `cloudProvider` value
export PROVIDER=aws
helm repo add appscode
helm repo update
helm install appscode/voyager --name voyager-operator --version 10.0.0 \
--namespace kube-system \
--set cloudProvider=$PROVIDER \
--set enableAnalytics=false \
--set apiserver.enableAdmissionWebhook=false

Once you've deployed the edge proxy, voyager-operator will create a custom ingress resource which will provision a load balancer for you.

See the Cluster IP and Port

Run the following command to see the cluster IP and port:

kubectl get svc voyager-edge

Read Ingress for further details.

Enable Observables

Note: the Grey Matter Helm chart lets you enable observables in the mesh, but they are disabled by default.

To enable observables, modify the following settings in your local custom values file. The kafkaServerConnection should be a reference to a Kafka ensemble that is available in the mesh. The format is:


These are the global settings for all observables:

topic: observables

You can enable or disable observables for each service. Enable observables by setting:<service>.observablesEnabled to true or false

Set Docker Credentials

At the top of your custom-greymatter-secrets.yaml file, set your Docker credentials so Helm can pull the necessary Grey Matter images. If you need credentials please contact Grey Matter Support.


Set AWS Credentials (optional)

Set AWS credentials for gm-data to authenticate and push content to S3. This step is optional because gm-data stores files on disk or in S3. If you need credentials please contact Grey Matter Support.

region: us-east-1
bucket: decipher-quickstart-helm

Load Certificates

To access anything in the mesh, your request will pass through the edge proxy, which performs Mutual TLS (mTLS) authentication. Both the client and server must authenticate themselves and your browser (or other HTTPS client like curl or wget) will require you to load the appropriate certificates.

Note: a large section of the custom-greymatter-secrets.yaml file contains TLS certificates with public and private keys. These are used in various services like gm-jwt-security, the Grey Matter sidecar, and edge proxy.

For production deployments, we recommend using certificates generated from a secure Certificate Authority (CA).

Configure SPIRE

We also support using SPIFFE/SPIRE as a way to enable zero-trust attestation of different "workloads" (services). Read SPIRE for further details.

Enable TLS

We support multiple TLS options both for ingress/egress (north/south traffic) to the edge proxy, and between the sidecar proxies (east/west traffic) within the mesh. For ingress, we support mTLS or non-TLS. To do this, enable the following:

enableTLS: true
certPath: /etc/proxy/tls/edge

Certs are volume mounted to the edge proxy Docker container at the location specified by certPath.

For securing communication between the sidecar proxies in the mesh, we support:

  • Non-TLS

  • Static mTLS (two-way TLS)

  • SPIFFE/SPIRE mTLS with certificate rotation

If you want to disable TLS in the mesh, don't enable either of the following options. For both of the following options, you need:

enabled: true

Enable Static mTLS

This configures static mTLS between each proxy by mounting the appropriate certs and setting up the configuration in gm-control-api. Read Control API for further details.

To enable it, set the following values in your custom-greymatter.yaml file:

enabled: true
use_provided_certs: true

Currently, this uses the certificates mounted at the path /etc/proxy/tls/sidecar/, but in the future this path may be configurable.


Enables the spire subchart, which creates the SPIRE agent and server. Also creates appropriate SPIRE registration entries automatically, and adds SPIRE secrets to the proxy and cluster configuration in gm-control-api

To enable it, set the following in your custom-greymatter.yaml:

enabled: true
enabled: true

Enable Single-service Deployments

If you want to deploy a Helm chart for a single service without the entire service mesh, you need to make sure that your custom-greymatter.yaml globals.sidecar.envvars key contains all of the necessary global defaults for the sidecar. Otherwise, the sidecar will contain inappropriate environment variables for that deployment and will lead to your sidecar being mis-configured.


Prepare Tiller

Tiller requires permissions to run installations in the cluster. Depending on your setup and security requirements, these particular permissions will change. Please see the official Helm docs to prepare your production setup, but we do provide highlights in our Multi-tenant Helm guide.

Note: for development deployments with Minikube, you can skip these steps and proceed on. Full Tiller access should be granted by default when installing with Minikube.

Quick Setup

For a quick setup, giving Tiller full cluster-wide access, have an admin apply the helm-service-account.yaml found in this repository. This will enable Tiller to act and install across the entire Kubernetes cluster.

For Openshift

oc apply -f ./helm-service-account.yaml

For Kubernetes

kubectl apply -f ./helm-service-account.yaml

You'll then be able to initialize Helm using this account:

helm init --service-account tiller

Prepare Service Accounts

For production deployments, we recommend that an admin setup service accounts first following our Service Accounts guide because some of our services require cluster resources, such as read access to Kubernetes Pods. If Tiller has full cluster access then it will install the service accounts. This would be the default when installing in a simple fashion with Minikube.

Get the Latest Helm Charts Release

To install Helm charts representing the latest version of Grey Matter, you'll need to add the Grey Matter Helm repository to your local helm CLI. Run the following command, replacing username/password with credentials previously provided to you. These are the same as your Docker credentials.

Add the Grey Matter Helm Repository to Your Local Helm CLI

helm repo add decipher --username <username> --password '<password>'
helm repo update

Install Grey Matter from Latest Charts

Once the repository has successfully been added to your helm CLI, you can install Grey Matter from the latest charts.

Note: before installing Helm charts do a dry-run first to ensure your custom YAML is correct. You can do this by adding the --dry-run flag to the below helm install command. If you receive no errors then you can confidently drop the --dry-run flag.

helm install decipher/greymatter --namespace <project_namespace> --name <release_name> -f custom-greymatter.yaml -f custom-greymatter-secrets.yaml --tiller-namespace <tiller_namespace>

Local Helm charts

If you've cloned this project and are changing charts locally, you'll need to modify the repository paths in requirements.yaml to point to the relative chart paths of this GitHub project.

- name: dashboard
version: '2.0.1'
repository: 'file://../dashboard'

Update and Install Local Charts

Then you can run the following commands to update the local charts and then install them.

helm dep up greymatter
helm install greymatter --namespace <project_namespace> --name <release_name> -f custom-greymatter.yaml -f custom-greymatter-secrets.yaml --tiller-namespace <tiller_namespace>

The helm dep up greymatter command will create a ./greymatter/charts directory with tarballs of each sub-chart that the parent greymatter chart will use to install Grey Matter.

Additional Helm install flags

Here are some additional parameters we often use when running helm install.




Allows you to pass in a file with values that can override the chart's defaults (relative path).


The release version of the project, service, etc.


The namespace provided by the OpenShift/Kubernetes environment, e.g. fabric-development


The namespace of the Tiller pod in OpenShift/Kubernetes.


Prints out the deployment YAML to the terminal.


With debug will print out the deployment YAML without actually deploying to OpenShift/Kubernetes environment.


Will create new deployments if they are undefined or replace old ones if they exist.

Verify Installation

Once all pods, containers, and services start successfully you can confirm that the Grey Matter service mesh is running by navigating to its dashboard.

Construct URL

Construct the URL from your global values in custom-greymatter.yamlwith the following configuration (as an example):

environment: openshift
route_url_name: greymatter
remove_namespace_from_url: false

The URL will be:

greymatter.{{ Release.Namespace }},

Example URL with OpenShift or Kubernetes Namespace

If you deployed into a OpenShift or Kubernetes namespace with a command like:

helm install decipher/greymatter --namespace mesh

The final URL would be:

A successful URL will route you to Grey Matter Intelligence 360, where you can monitor and manage your core services.


Installation Issues? Contact us at