Create a Tenant GSL Project

Tenants interact with Greymatter through projects. Tenant projects are created with the Greymatter CLI’s init command.

This guide will show you how to create a tenant project using the Greymatter CLI. At the end of the guide, you will have a newly generated project with its application edge node and sync service running inside the mesh.

This guide assumes you installed Greymatter using the Getting Started guide, which has Spire deployed by default.

Prerequisites

• A Greymatter v1.8.x installation.

• The Greymatter CLI.

• A Git repository.

• Git credentials in the form of an SSH key or an HTTP API token.

Tenant Basics

The greymatter init command is a versatile tool within the Greymatter CLI designed to streamline the process of setting up a new Greymatter project. This command is fundamental for users looking to deploy services using the Greymatter Specification Language (GSL).

Basic Command Structure:

greymatter init [options...] <project_name>

The command is used to initialize a Greymatter GSL project. This includes starter Kubernetes manifests, an initial Greymatter sync.yaml file, and the latest version of GSL.

For additional information, use the greymatter init —help command in the Greymatter CLI. This command provides detailed help information specifically for the init command.

When using the Greymatter CLI, the order of arguments is important. All options must precede the <project_name>.

GSL Git Projects

Greymatter features built-in GitOps support for GSL projects. Establishing and maintaining a Git repository for your Greymatter Specification Language (GSL) project is essential for version control and collaborative efforts. You can select any Git service to host your repository.

Let’s Setup a Project

Create or navigate to a directory where you want to store the project configurations and run:

greymatter init --spire examples

The Greymatter project name and the Kubernetes namespace must match.  For our tutorials, we will use the “examples” namespace which Greymatter sets up on core install.

After running the command, the contents of your project directory will look like:

├── README.md
├── TUTORIAL.md
├── cue.mod
├── greymatter
│   ├── policies
│   ├── core
│   │   └── edge.cue
│   ├── globals.cue
│   └── <project name>
└── k8s
    ├── manifests.yaml
    └── sync.yaml

At this point, you could commit your project to a git repository, assuming you set one up for your project.

What comes in a greymatter project?

Exploring the Project

Using the greymatter init --spire command and option flag in the Greymatter CLI is designed to leverage SPIRE for enhance security across the network. This configuration is critical for ensuring encrypted and authenticated communication within the network infrastructure.

SPIRE Configuration Security

The SPIRE configuration automatically applied by the greymatter init --spire command and option flag secures various network points:

1. Traffic from the Edge to the Service: SPIRE ensures that all data transmitted from the network edge to the service is both encrypted and authenticated, providing a secure entry point into the service environment.

2. All Traffic to/from the Service: Beyond the edge, SPIRE is also applied to all traffic to/from the service, ensuring that internal communications between services are secure and trusted.

3. Telemetry Traffic from the Service to the Health Check Subsystem: SPIRE also secures telemetry traffic, which includes monitoring and logging data sent from the service to the health check systems. This ensures that sensitive diagnostic data remains confidential and tamper-proof.

Expanding your greymatter working directory you will see three folders that are part of the directory structure for managing GSL configurations. They are important for organizing and deploying services within the Greymatter platform. Here's a more detailed breakdown of their significance:

/greymatter: This is the primary working folder for Greymatter configurations. It acts as the central repository for all the configurations necessary to run your Greymatter applications, APIs, services. This directory is crucial because it holds the settings that define how the Greymatter platform operates and interacts with other services in your environment.

/greymatter/core: This directory is specific to the core functionality of the Greymatter platform. It stores configurations for critical Greymatter platform nodes, including application edge nodes and bridge nodes. These nodes are essential for the platform's service connectivity network communication and policy capabilities. The configurations in this folder ensure that these nodes are properly set up to handle the traffic and policy they are responsible for in the network.

/greymatter/<project name>: This folder is designated for holding service connectivity files specific application stack playbooks for your projects. By organizing service files under specific project names, it becomes easier to manage and deploy services specific to each project. This structure supports better organization and isolation of project-specific configurations, which can help in troubleshooting, updating, and scaling individual projects without affecting others.

/k8s/manifests.yaml: This file is a Kubernetes manifest used to deploy a stateful set that manages the Greymatter edge service associated with your application stack playbook. The edge service is crucial as it acts as the entry and exit point for network traffic into your application stack. It routes and manages incoming and outgoing network communication, ensuring that requests are directed to the appropriate services within your microservices architecture. This file contains all the necessary configuration details to ensure that the edge service is deployed correctly and is scalable, segmented, and resilient.

/k8s/sync.yaml: This file is a Kubernetes manifest used to deploy the Greymatter sync service as a stateful set . The sync service plays a vital role in synchronizing configuration with the Git project you established for automatic GitOps. By ensuring that all parts of the system have up-to-date configuration data, the sync service helps maintain consistency and reliability across your deployments, particularly in dynamic environments where configurations might change frequently.

Overall, these directories and files play crucial roles in the configuration and management of the Greymatter platform, ensuring that it runs efficiently and meets the specific needs of different projects and core platform functionalities.

Deploy Project Resources

To ready the environment for deployment you need to create a sync secret that contains information about your git credentials.

Create Git Credential Secret

kubectl create secret generic greymatter-admin-sync \
  --from-literal=GREYMATTER_GIT_REMOTE="git@github.com:<org>/<repo>.git" \
  --from-literal=GREYMATTER_GIT_BRANCH="main" \
  --from-file=known_hosts=<file to known_hosts> \
  --from-literal=ssh_private_key_passphrase=<passphrase> \
  --namespace examples

envFrom:
  - secretRef:
      name: greymatter-admin-sync

kubectl create secret generic greymatter-admin-sync \
  --from-literal=GREYMATTER_GIT_REMOTE="http://github.com/<org>/<repo>.git" \
  --from-literal=GREYMATTER_GIT_BRANCH="main" \
  --from-literal=GREYMATTER_GIT_USER=<username accessing your Git repository> \
  --from-literal=GREYMATTER_GIT_PASSWORD=<password accessing your Git repository> \
  --from-literal=GREYMATTER_GIT_TLS_SKIP_VERIFY=false \
  -n examples

envFrom:
  - secretRef:
      name: greymatter-admin-sync

Apply the manifests

By default, when you use the greymatter init scaffolding framework the Greymatter edge deployments assume TLS. It's recommended to consider obtaining a TLS certificate from a trusted Certificate Authority (CA). If you do not have a TLS certificate on your edge, please open the k8s/manifests.yaml and comment out the following lines:

volumeMounts:
  # - name: tls-certs
  # mountPath: /etc/proxy/tls/sidecar
volumes:
  # - name: tls-certs
  #   secret:
  #     defaultMode: 420
  #     secretName: greymatter-edge-ingress

You are now ready to deploy the manifests for the edge proxy and sync. At the root of your GSL project run the following:

kubectl apply -f ./k8s

Verify Installation

To check the status of the pods you created in the examples namespace, you can use the follow kubectl command:

kubectl get pods -n examples-w

When you see the following in your console, you are ready to move on to the next step.

NAME                    READY   STATUS    RESTARTS   AGE
greymatter-sync-0       1/1     Running   0          16m
edge-6756d58bc9-kr4sr   1/1     Running   0          10m

You can also just monitor the Greymatter Dashboard and you will see the new Nginx Edge service come online and wired up for the service connectivity layer.