The Signadot Operator is the in-cluster component of the Signadot Platform. To
see a high-level view of all components, visit the
architecture page. The operator is installed into the
Kubernetes cluster using
signadot namespace. Once authorized, it connects and maintains a
persistent & TLS secured connection with the Signadot Control Plane.
It provides the following functionality:
- Creating and managing in-cluster workloads (Kubernetes Deployments, Rollouts, etc) associated with a Sandbox.
- Creating and managing resources associated with Sandboxes.
- Supporting workstation-local development by:
- Managing connections to workloads running on a workstation.
- Proxying requests from a local workstation to within the cluster.
- Serving a gRPC API for configuration and management of connections.
- Managing routing for requests between services within the cluster.
The agent is a deployment which maintains a secure persistent connection to
the Signadot Control Plane at
tunnel.signadot.com:443. This connection is used
- Provide access to the Kubernetes API to the Signadot Control Plane.
- Proxy requests from Endpoint URLs to services within the cluster, including performing in-cluster DNS resolution.
Since the agent provides access to the cluster Kubernetes API server, it tends to have scaled down read-only permissions for resources not owned by Signadot, and read-write permissions for Signadot owned objects. You can learn more about the permissions that are requested by the agent here.
The controller manager implements Kubernetes controllers for various Signadot Custom Resources, including
- Sandboxes (sds)
- Route Groups (sdrg)
- Forked Workloads (sdfw)
- External Workloads (sdxw)
- Resources (sdmr)
- RoutingConfig (sdrc)
- IstioRoutes (sdir)
- Signadot Object Lifecycle Methods (solm)
The high-level interactions between these objects are depicted below:
The controller-manager needs read-write permissions for any resources which are manipulated on behalf of sandboxes. You can learn more about the permissions that are requested by the controller manager here.
In versions of the operator prior < v0.14, there was an additional Signadot Routes (sdr) Custom Resource and Controller in use, which are now not in use anymore and scheduled for removal in a future release.
Signadot custom resource names are generally derived from concatenation, truncation where needed, and hashing for uniqueness. The names nonetheless often contain information provided in Sandboxes and RouteGroups at the control plane layer, including references to baseline workloads. We do not recommend using the custom resource Kubernetes object names to identify related objects, as this information can become lost. The presentation of such information in custom resource names is only best-effort and can not be relied upon.
Sandbox Custom Resource & Controller
The Sandbox Custom Resource (CR) is a low-level implementation of the Signadot Sandbox specification. The controller for a Sandbox performs all the important actions associated with creating a Sandbox such as:
- Creating and finalizing ForkedWorkload CRs running within the cluster.
- Creating and finalizing ExternalWorkload CRs used for local development.
- Creating and finalizing Resources CRs.
- Creating and finalizing RoutingConfig CRs.
RouteGroup Custom Resource & Controller
A RouteGroup CR represents a set of sandboxes added into a single routing context. As such, a RouteGroup CR represents a way to route requests to a set of sandboxes. The RouteGroup controller creates RoutingConfig CRs and coordinates RouteGroup status with the constituent Sandboxes.
Resource Custom Resource & Controllers
A Resource CR represents the state of a resource associated with a sandbox. Controlling a resource entails making it available to sandboxed workloads according to the associated resource plugin spec, and deleting the resource when the associated sandbox is terminated.
The Object Lifecycle Methods CR is a low-level implementation of a workflow manager attached to the lifecycle of a target object. In the context of Resources, its controller is responsible for the execution of the defined workflows for the create and delete phases.
ForkedWorkload Custom Resource & Controller
A ForkedWorkload CR represents a modification to a baseline workload running as part of a Sandbox. The ForkedWorkload controller is responsible for:
- Applying customizations specified to create a sandboxed workload from the baseline.
- Creating and finalizing the sandboxed workload.
- Watching all services which match the baseline workload and creating corresponding services for routing requests to the sandboxed workload.
Note that each service that matches the baseline workload will have a corresponding service for the sandboxed workload. The newly created services will map the same ports as the baseline workload services, but to the sandboxed workload instead.
ExternalWorkload Custom Resource & Controller
An ExternalWorkload CR represents the state of a workload run outside of the Kubernetes cluster as part of a Sandbox. It is used for local development, where the state of the associated workload amounts only to the state of a tunnel used to direct traffic destined for the workload to the connected workstation. The controller performs health checks on the tunnel and garbage collection of unhealthy tunnels.
Like the ForkedWorkload controller, the ExternalWorkload controller finds all services which match the baseline workload and creates corresponding services for the external workload. Unlike the ForkedWorkload controller, those services do not have selectors for matching pods. Rather, the ExternalWorkload controller also creates Endpoints associated with each created Service in order to direct traffic to the associated tunnel running on the tunnel-proxy pods.
RoutingConfig Custom Resource & Controller
A RoutingConfig CR represents the desired routing associated with a given routing key. A routing key, in turn, is either associated with a Sandbox or a RouteGroup. The primary information in a RoutingConfig is a list of references to Forked or External workloads. The RoutingConfig controller checks the status of the ForkedWorkload and ExternalWorkload CRs to see what associated services have been created. With this information, it:
- Produces any associated mesh-specific CRs (such as IstioRoute) if enabled, one for each service matching some ForkedWorkload or ExternalWorkload in the Spec.
- If the Signadot DevMesh is in use, it will not create any additional CRs, but instead use its own status to supply routing configuration to the RouteServer running as part of the operator.
- Generates a status representing the state of the routing for the associated routing key, by observing any associated CRs.
IstioRoute Custom Resource & Controller
IstioRoute CRs represent the desired and observed state of Istio VirtualServices with respect to a single Service. This service is presented to the RoutingConfig controller by a ForkedWorkload CR or an ExternalWorkload CR and passed on to the RoutingConfig which owns the IstioRoute. The controller finds matching Istio VirtualServices and reconciles them with respect to the Service. One Istio HTTPRoute is maintained for each port in the associated service.
More information about using Istio with Signadot is available here.
route server is a Kubernetes Deployment that is tasked with keeping track
of where to route requests provided the destination address and associated
sandbox. To accomplish this, the
route server watches RoutingConfigs.
route server is currently intended for internal Signadot use, and serves
an HTTP API for use by Signadot DevMesh sidecars. For performance reasons, the
route server is not intended to intervene on every request. Rather, it expects
its clients to cache the results periodically.
Signadot DevMesh Sidecars
The Signadot Operator also contains optional built-in functionality to add a DevMesh sidecar to each baseline pod. The injection occurs into pods using a Kubernetes Mutating Webhook. The sidecar integrates with the Route Server and provides dynamic request routing capabilities in a cluster that does not have a Service Mesh such as Istio installed.
The Tunnel API deployment hosts a gRPC server which workstations consume to coordinate in-cluster state with workstation connection state. The Tunnel API provides information about Kubernetes Service network addresses and DNS, and Sandbox state.
The Tunnel Proxy is a Deployment responsible for providing access to the Tunnel API, proxying requests from workstations to the cluster, proxying traffic from the cluster to workstations, and providing an audit log of all connections. It also hosts a metrics server providing statistics about active and total connections.
IO Context Server
io context server (aka ICS) is a Kubernetes Deployment responsible for
storing and serving intermediate results produced by the execution of the work
units defined within a Signadot Object Lifecycle Methods workflow. In simple
words, whenever a Resource is being created or deleted, a workflow of work units
is executed. Each of those work units may produce outputs, which will be stored
in ICS. Apart from that, work units may also consume inputs from other work
units, those inputs will be read from ICS and injected into the work unit main
IO Init Container
io init container, is an init container that is appended to the work unit
pods. It is responsible for reading the required inputs from ICS and injecting
them into the main container.
IO Sidecar Container
io sidecar container, is a container that run along side with the main
container, whose purpose is to collect the generated outputs from the work unit
and store them in ICS.