greymatter.io Documentation | Initialize a Tenant Project

Greymatter Version

v1.8.0

The greymatter CLI provides an init command that will initialize a tenant GitOps repository. init will allow teams to quickly generate a basic project configuration scaffold that will hook into the greater greymatter mesh.

Initializing A Project

To see how to use greymatter init and all of its available options, run the help command.

greymatter init help

greymatter init instantiates a new greymatter project with bundled resources such as a starter application edge node, an initial greymatter sync Kubernetes StatefulSet file (which must be edited), and the latest of the GSL (greymatter Specification Language) CUE.

To create a project in your current working directory, provide init with a project name and execute.

greymatter init $PROJECT_NAME

Init will initialize your target directory with a new project structure.

├── .greymatter
├── README.md
├── TUTORIAL.md
├── cue.mod
├── greymatter
│   ├── policies
│   ├── core
│   │   └── edge.cue
│   ├── globals.cue
│   └── $MY_PROJECT
└── k8s
    ├── manifests.yaml
    └── sync.yaml

Check out the README of your newly created scaffold to learn about what each component means and what can be done with them.

What comes in a greymatter project?

Here are some core features worth noting:

You’ll receive your own application edge node.
Kubernetes manifests for the the application edge node as well as a StatefulSet for greymatter sync.
A helpful CUE tutorial for beginners.
A fully baked cue module with all necessary dependencies utilizing GSL.

If you haven’t done so already, we recommend changing the namespaces for your projects deployment target in all generated Kubernetes manifests. This includes the k8s/manifests.yaml file as well as k8s/sync.yaml.

Now that you’ve got your project initialized, let’s learn how to get your services into the mesh. Check out the next steps for further reading.

Securing With mTLS

By default, greymatter init will inject your service configurations with full mutual TLS termination happening at the sidecar. This means we’ll have to create some certificates and mount them in a specific location on disk of each data-plane proxy container. We recommend using Kubernetes secrets and volume mounts to independently manage certificates for sidecars in their respective namespaces.

Securing Your Gateway

A hook is provided for setting up TLS on the given edge gateway for your project. Please create a secret at the following location:

kubectl create secret generic greymatter-$PROJECT_NAME-edge-certs \
	--from-file=ca.crt=./ca.crt \
	--from-file=server.crt=./server.crt \
	--from-file=server.key=./server.key \
	-n $MY_NAMESPACE

Securing Services

Certificates are required at the following locations in individual sidecar containers:

Trust: /etc/proxy/tls/sidecar/ca.crt
Certificate: /etc/proxy/tls/sidecar/server.crt
Key: /etc/proxy/tls/sidecar/server.key

Greymatter mesh configurations have been setup for your service to look at these paths. It is up to you to get them there! Following the pattern defined in the k8s/manifests.yaml - edge-$PROJECT_NAME Deployment manifest is a great way to get your certs mounted and available to the greymatter.io data plane.

Sidecar Injection

Sidecar injection requires a secret in place in accordance with your mesh administrators TLS secret name. The default location is: gm-edge-ingress-certs but please check with your mesh administrators:

kubectl create secret generic gm-edge-ingress-certs \
	--from-file=ca.crt=./ca.crt \
	--from-file=server.crt=./server.crt \
	--from-file=server.key=./server.key \
	-n $MY_NAMESPACE

Deployment

Greymatter supports GitOPs as a first-class function. Deploying new services is as easy applying a manifest and committing!

Deploying Sync

To apply the configurations provided through this project scaffold, we recommend deploying the bundled sync service. There are a few things to do before we launch that sync StatefulSet:

Install the SSH key secret

# GitOps SSH key
# EDIT THIS to reflect your own, or some other SSH private key with access,
# to the repository you would like the operator to use for GitOps.
kubectl create secret generic greymatter-sync-secret \
    --from-file=ssh-private-key=$HOME/.ssh/id_ed25519 \
    --from-literal=password="REDACTED" \
    -n $MY_NAMESPACE

Make sure to modify the namespaces in the k8s/sync.yaml to your target namespace. Once changed, apply the starter k8s manifests in the ./k8s folder.

kubectl apply -f ./k8s/manifests.yaml -n $MY_NAMESPACE # this file contains your project edge
kubectl apply -f ./k8s/sync.yaml -n $MY_NAMESPACE # this deploys the greymatter.io sync service

Now that you’ve deployed your manifests, retrieve the Kubernetes ingress service for your project’s edge node:

kubectl get svc edge-$PROJECT_NAME -n $MY_NAMESPACE

Retrieve the hostname entry and port and populate the value in greymatter/globals.cue: globals.edge_host. This will become the dns entry that traffic will flow through to your services.

Commit the change, push to your repo, and happy requesting!

Next Steps

Adding Services To A Project