Light Dark Auto

Register A Service

Greymatter Version

  • v1.8.0

Once you've generated a project with greymatter init, the next step is to get your service configs generated! Let's check out our helpful guide init and see what it has to offer with service config generation.

greymatter init service --help   

Initialize A Service

Service initialization is as easy as providing a service type, an output directory, a target CUE package, and a name.

From the root of your greymatter project, run the following command overriding values as necessary:

greymatter init service --type=http --dir=greymatter/$PROJECT_NAME --package=$PROJECT_NAME kiwi

A fully functional, base kiwi.cue file is created in the greymatter/$MY_PROJECT directory using the default values for a service of type http.

Types Of Services

init has support for generating service configurations for various types of services. This can mean various things such as default enabled filters, SNI, TLS configurations, and more. A full list can be found in the help command but here are some of the supported types:

  • HTTP: --type=http
  • TCP: --type=tcp
  • AWS Lambda: --type=lambda
  • Mongo: --type=mongo
  • Redis: --type=redis

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 \

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 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 \


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" \

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 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!

Deploying Your Custom Manifests

Given you have an existing manifest for your service, first deploy it into an operator watched namespace with the proper sidecar annotations in the Kubernetes object metadata field:

# Deployment metadata
  name: kiwi
  namespace: my-namespace
  annotations: 10808

# Container spec metadata 
# This is required to associate your service with the defined upstream in greymatter.
# Note that the value provided on this annotation should be 
# the key defined in your services proxy object.
  labels: kiwi

Your kubernetes manifest file should live in your greymatter project under the k8s/ folder. Once you've added the annotations to your manifests, make a commit to your remote repository that you pointed the deployed sync service to and push! After a few moments your service should show up in the intelligence dashboard and go green once the sidecar can reach the upstream service.

Next Steps