Signadot Operator
- Signadot account (No account yet? Sign up here).
- A Kubernetes cluster into which you will install the Signadot Operator.
- If you don't have a Kubernetes cluster available for installing the Signadot Operator yet, you can try Signadot on a Playground Cluster that you can self-provision from the Dashboard. See Quick Start for details.
- If you want to run Sandboxes with local workloads, you will need a Linux or MacOS machine onto which you will install the CLI.
Introduction
In this guide, we will walk you through the process of installing Signadot into your Kubernetes cluster. We will also cover how to configure request routing and address other infrastructure concerns. By the end of this guide, you will have a fully configured Signadot setup, ready for creating sandboxes within your cluster. This will enable you to manage and control your sandboxes directly from your cluster, ensuring a seamless and efficient workflow.
Install Signadot Operator into your cluster
To get started with Signadot, you first need to install the Signadot Operator into your cluster. This will allow you to manage and control your sandboxes directly from your cluster.
To install Signadot into your cluster, you will need to use Helm. If you haven't installed Helm yet, you can find the installation instructions here.
Before you can install Signadot, you need to generate a cluster token. This token is used to authenticate your Kubernetes cluster with Signadot. To generate a cluster token, you need to create an account on Signadot Dashboard. Once you have an account, navigate to Clusters > Connect Cluster, and then supply a name that identifies the cluster you are connecting. After creating the connection, the dashboard will present you with installation instructions that include your cluster token.
Installing the Operator
You need to install the Signadot Operator in one or more Kubernetes clusters where you wish to create Sandboxes. You need to authenticate your Kubernetes cluster to Signadot using a cluster token that can be generated using the Signadot Dashboard. Copy the cluster token value for the next installation step.
In the Signadot Dashboard, navigate to Clusters > Connect Cluster, and then supply a name that identifies the cluster you are connecting. Once you create the connection, the dashboard will present you with installation instructions that you can copy and paste.
Note that these install instructions contain your cluster token and as a result will not be shown again. For reference, the install instructions (without a cluster token) follow.
kubectl create ns signadot
kubectl -n signadot create secret generic cluster-agent --from-literal=token='<cluster-token>'
helm repo add signadot https://charts.signadot.com
helm install signadot-operator signadot/operator
Upgrading the Operator
You upgrade an existing installation by running the following Helm commands.
# To upgrade an existing release
helm repo update
helm upgrade signadot-operator signadot/operator
Uninstalling the Operator
To uninstall the operator, first, remove the Helm chart, and then delete the signadot
namespace.
helm uninstall signadot-operator
kubectl delete ns signadot
Configuration
You can optionally specify additional parameters to customize your operator
installation. This can be done through a Helm values.yaml
file or on the
command line. For getting the full list of customizable parameters please check
helm parameters
documentation.
This is an example of how to specify custom parameters:
# Add custom labels to all deployed objects
helm install signadot-operator signadot/operator \
--set 'commonLabels.some-label=value1' \
--set 'commonLabels.other-label=value2'
Or create a values.yaml
file with the following content:
# Add these labels to all objects deployed by this chart.
commonLabels:
some-label: value1
other-label: value2
And run the following command
helm install signadot-operator signadot/operator -f values.yaml
That will apply the some-label
and other-label
labels to all deployed objects including namespaces, CRDs, ClusterRoles, etc.
While installing, one of the key considerations is how you will set up routing for sandboxes. See the next section for more details on the different ways and considerations when setting up Sandbox routing.
Set up Routing
Using Istio
If your application is running in an Istio mesh, you can enable sandbox routing
using Istio by setting the istio.enabled
helm value to true
during the
installation of the operator. This will cause the Signadot Operator to manage
routes in the Istio VirtualService for each service that is opted into Signadot.
When using Istio for routing, it is important to note that each baseline microservice or "workload" that will be tested using Signadot must have an associated VirtualService. This is because Signadot sets routing rules on these VirtualServices to direct traffic to the appropriate sandboxes as needed.
Signadot mutates VirtualServices within the cluster to manage these routing rules. This means that if you have a GitOps based system that overwrites VirtualServices, you will need to configure it to ignore the changes made by Signadot.
For more detailed instructions on how to set up routing using Istio, please refer to our Using Istio Guide.
Using DevMesh
If your application is not running in a service mesh like Istio, you can set up routing using Signadot's DevMesh. DevMesh is a system of envoy-based sidecars that are built into the Signadot Operator and offer lightweight request routing functionality.
To enable DevMesh, you need to opt each service into Signadot DevMesh injection. This can be done by adding an annotation to each pod. If for example, the pods are created by a deployment, the annotation can be added to the deployment template.
For more detailed instructions on how to set up routing using Signadot's DevMesh, please refer to our Using the Signadot DevMesh Guide.
Verifying the Setup
Firstly, you should check from the Signadot dashboard that the cluster has successfully connected and is healthy. This verifies that the operator installation has been successful.
Secondly if you are using DevMesh for routing, to verify that the
routing is set up correctly, you should check that the pods associated with your
baseline deployments or workloads are now running an extra container, called the
sd-sidecar
.
To test the setup, you can use a simple sandbox specification such as the following on any of the baseline workloads for which you're setting up sandboxes.
name: test-sandbox-routing
spec:
description: Test Sandbox Routing
cluster: "@{cluster}"
forks:
- forkOf:
kind: Deployment
namespace: "@{namespace}"
name: "@{name}"
- Run with UI
- Run with CLI
Click the button below to open and run this spec on Create Sandbox UI.
Run the below command using Signadot CLI.
# Save the sandbox spec as `test-sandbox-routing.yaml`.
# Note that @{cluster} must be replaced with the name of the linked cluster in
# signadot, under https://app.signadot.com/settings/clusters.
% signadot sandbox apply -f ./test-sandbox-routing.yaml \
--set cluster=<cluster> \
--set namespace=<namespace> \
--set name=<name>
Created sandbox "test-sandbox-routing" (routing key: d8n7tsy1hvd4j) in cluster "<cluster name>".
Waiting (up to --wait-timeout=3m0s) for sandbox to be ready...
✓ Sandbox status: Ready: All desired workloads are available.
Dashboard page: https://app.signadot.com/sandbox/id/d8n7tsy1hvd4j
The sandbox "test-sandbox-routing" was applied and is ready.
Once the sandbox created above reaches a healthy state, this signifies the successful completion of the setup.