GreyMatter.ioTwitterGitHubSupport

Quickstart Installation on AWS EKS

Prerequisites

  1. git installed

  2. helm v3 installed

  3. envsubst installed (a dependency of our helm charts)

  4. eksctl installed or an already running Kubernetes cluster.

Steps

1. Install a Kubernetes Cluster

NOTE: if you already have a Kubernetes cluster up and running, move to step 2. Just verify you can connect to the cluster with a command like kubectl get nodes

For this deployment, we'll use EKS to automatically provision a Kubernetes cluster for us. The eksctl will use our preconfigured AWS credentials to create master nodes and worker nodes to our specifications, and will leave us off with kubectl setup to manipulate the cluster.

The regions, node type/size, etc can all be tuned to your use case, the values given are simply examples.

eksctl create cluster \
    --name production \
    --version 1.17 \
    --nodegroup-name workers \
    --node-type m4.2xlarge \
    --nodes=2 \
    --node-ami auto \
    --region us-east-1 \
    --zones us-east-1a,us-east-1b \
    --profile default

Cluster provisioning usually takes between 10 and 15 minutes. When it is complete, you will see the follwing output:

When your cluster is ready, run the following to test that your kubectl configuration is correct:

2. Clone the Grey Matter Helm Charts Repo

Though Helm is not the only way to install Grey Matter into Kubernetes, it does make some things very easy and reduces a large number of individual configurations to a few charts. For this step, we'll clone the public git repository that holds Grey Matter and cd into the resulting directory.

NOTE: this tutorial is using a release candidate, so only a specific branch is being pulled. The entire repository can be cloned if desired.

3. Setup Credentials

Before running this step, determine whether or not you wish to install Grey Matter Data. If so, determine whether or not you will use S3 for backing. If you do want to configure Grey Matter Data with S3, follow the set up S3 for Grey Matter Data guide. You will need the AWS credentials from step 4 here.

To set up credentials, we need to create a credentials.yaml file that holds some secret information like usernames and passwords. The helm-charts repository contains some convenience scripts to make this easier.

Run:

and follow the prompts. The email and password you are prompted for should match your credentials to access the Decipher Nexus at https://nexus.greymatter.io/. If you have decided to install Grey Matter Data persisting to S3, indicate that when prompted, and provide the access credentials, region, and bucket name.

Note that if your credentials are not valid, you will see the following response:

4. Configurations

To see the default configurations, check the global.yaml file from the root directory of your cloned repo. In general for this tutorial, you should use the default options, but there are a couple of things to note.

  • If you would like to install a Grey Matter Data that is external and reachable from the dashboard, set global.data.external.enabled to true.

  • If you plan to update ingress certificates or modify RBAC configurations in the mesh, set global.rbac.edge to false. This turns off the default RBAC configuration and allows for more granular RBAC rules at the service level.

  • If you would like to install Grey Matter without SPIFFE/SPIRE, set global.spire.enabled to false.

You can set global.environment to eks instead of kubernetes for reference, but we will also override this value with a flag during the installation steps in step 5.

5. Install Grey Matter component Charts

Grey Matter is made up of a handful of components, each handling different pieces of the overall platform. Please follow each installation step in order.

  1. Add the charts to your local Helm repository, install the credentials file, and install the Spire server.

  2. Watch the Spire server pod.

    Watch it until the READY status is 2/2, then proceed to the next step.

  3. Install the Spire agent, and remaining Grey Matter charts.

    If you see a template error or Error: could not find tiller, verify that you are using Helm version 3.2.4 and try again. If you need to manage multiple versions of Helm, we highly recommend using helmenv to easily switch between versions.

    NOTE: Notice in the edge installation we are setting --set=edge.ingress.type=LoadBalancer, this value sets the service type for edge. The default is ClusterIP. In this example we want an AWS ELB to be created automatically for edge ingress (see below), thus we are setting it to LoadBalancer. See the Kubernetes publishing services docs for guidance on what this value should be in your specific installation.

    While these are being installed, you can use the kubectl command to check if everything is running. When all pods are Running or Completed, the install is finished and Grey Matter is ready to go.

6. Accessing the dashboard

NOTE: for easy setup, access to this deployment was provisioned with quickstart SSL certificates. They can be found in the helm chart repository at ./certs. For access to the dashboard via the public access point, import the ./certs/quickstart.p12 file into your browser of choice - the password is password.

An Amazon ELB will be created automatically when we specified the flag --set=global.environment=eks during installation. The ELB is accessible through the randomly created URL attached to the edge service:

You will need to use this value for EXTERNAL-IP in the next step.

Visit the url (e.g. https://a2832d300724811eaac960a7ca83e992-749721369.us-east-1.elb.amazonaws.com:10808/) in the browser to access the Intelligence 360 Application

Intelligence 360 Application

7. Configure the CLI

If you intend to move onto deploy a service into your installation, or otherwise modify/explore the Grey Matter configurations, you will need to configure the CLI.

For this installation, the configurations will be as follows. Fill in the value of the edge service's external IP from the previous step for <EDGE-EXTERNAL-IP>, and the path to your helm-charts directory in <path/to/helm-charts>:

Run these in your terminal, and you should be able to use the CLI, greymatter list cluster.

You have now successfully installed Grey Matter!

Cleanup

If you're ready to shut down your cluster:

Delete the Grey Matter Installation

Delete The EKS Cluster

NOTE: this deletion actually takes longer than the output would indicate to terminate all resources. Attempting to create a new cluster with the same name will fail for some time until all resources are purged from AWS.

PreviousGuidesNextInstall the Grey Matter CLI

Last updated

Was this helpful?