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!