Command-line Interface (CLI)
Installation
Installation and configuration instructions are available here.
Usage
Use the help
command to see a list of all available "root" commands and global flags:
signadot help
Each command may have command-specific flags and nested sub-commands, which you can see by running:
signadot help <command>
Examples
The examples here work with v0.2+ of the Signadot CLI. If you're upgrading from v0.1, please note that the sandbox file format and the names of some commands have changed.
Clusters
You can use the cluster add
command to begin the process of connecting a Kubernetes cluster to Signadot:
signadot cluster add --name my-cluster
The --name
that you specify is only used within Signadot. It's the value you'll pass back in other commands to tell Signadot which Kubernetes cluster you want to work with.
The cluster add
command will generate the first auth token for that cluster and provide an example kubectl
command to install the cluster token as a Secret.
You can use signadot cluster list
to see the names of clusters already registered with Signadot.
You can also create a new auth token for an existing cluster with:
signadot cluster token create --cluster my-cluster
Sandboxes
To create a sandbox, first write a YAML or JSON file containing the name
and
spec
for the sandbox. The available fields within spec
are documented in the
Sandbox spec reference
For example:
name: my-sandbox
spec:
cluster: my-cluster
description: Testing sandboxes
forks:
- forkOf:
kind: Deployment
namespace: example
name: my-app
customizations:
images:
- image: example.com/my-app:dev-abcdef
env:
- name: EXTRA_ENV
value: foo
defaultRouteGroup: # CLI v0.3.7+ required (see sandbox specification for details)
endpoints:
- name: my-endpoint
target: http://my-app.example.svc:8080
Then submit this sandbox by passing the filename to the sandbox apply
command:
signadot sandbox apply -f my-sandbox.yaml
You can use signadot sandbox list
to see all existing sandboxes,
and signadot sandbox get
to see details about a single sandbox.
# List all sandboxes
signadot sandbox list
# Get one sandbox by name
signadot sandbox get my-sandbox
Each of the above commands can also produce meachine-readable output (JSON or YAML). For example:
# List all sandboxes in machine-readable format
signadot sandbox list -o json
# Get one sandbox in machine-readable format
signadot sandbox get my-sandbox -o yaml
You can delete a sandbox either by name, or by pointing at the same file that was used to create it:
# Delete sandbox by name
signadot sandbox delete my-sandbox
# Delete sandbox specified in a file
signadot sandbox delete -f my-sandbox.yaml
Also, the sandbox spec supports automatic deletion with time to live.
Local Workloads
The examples here work with v0.5.0+ of the Signadot CLI.
To run Local Workloads within sandboxes, one first connects to the cluster:
% signadot local connect
signadot local connect needs root privileges for:
- updating /etc/hosts with cluster service names
- configuring networking to direct cluster traffic to the cluster
Password:
signadot local connect has been started ✓
you can check its status with: signadot local status
%
% signadot local status
* runtime config: cluster demo, running with root-daemon
✓ Local connection healthy!
* port-forward listening at ":59933"
* localnet has been configured
* 45 hosts accessible via /etc/hosts
* Connected Sandboxes:
- No active sandbox
In the event several connections are specified, you will be asked to provide the signadot cluster name of the cluster to which you want to connect:
% signadot local connect
Error: must specify --cluster=... (one of [air signadot-staging])
% signadot local connect --cluster=air
signadot local connect needs root privileges for:
- updating /etc/hosts with cluster service names
- configuring networking to direct cluster traffic to the cluster
Password:
signadot local connect has been started ✓
you can check its status with: signadot local status
Once connected, you can run workloads locally which will receive requests from
the cluster and, if that workload communicates with other services in the
cluster, all of its outbound requests will be directed to the cluster. This is
accomplished simply by running signadot sandbox apply
using sandbox specs with
a local section.
To disconnect, run:
% signadot local disconnect
RouteGroups
The examples here work with v0.3.7+ of the Signadot CLI.
To create a RouteGroup, first write a YAML or JSON file containing the name
and
spec
. The available fields within spec
are documented in the
RouteGroup spec reference
For example:
name: my-routegroup
spec:
cluster: my-cluster
description: "route group for testing multiple sandboxes together"
match:
any:
- label:
key: feature
value: new-feature-x-*
endpoints:
- name: frontend-endpoint
target: http://frontend.hotrod.svc:8080
Then submit this routegroup by passing the filename to the routegroup apply
command:
signadot routegroup apply -f my-routegroup.yaml
You can use signadot routegroup list
to see all existing routegroups,
and signadot routegroup get
to see details about a single routegroup.
# List all routegroups
signadot routegroup list
# Get one routegroup by name
signadot routegroup get my-routegroup
You can delete a routegroup either by name, or by pointing at the same file that was used to create it:
# Delete routegroup by name
signadot routegroup delete my-routegroup
# Delete routegroup specified in a file
signadot routegroup delete -f my-routegroup.yaml
ResourcePlugins
The examples here work with v0.4.0+ of the Signadot CLI.
To create a ResourcePlugin, first write a YAML or JSON file containing the name
and
spec
. The available fields within spec
are documented in the
ResourcePlugin spec reference
For example:
name: my-plugin
spec:
runner:
image: ubuntu
create:
- name: say-hello
script: |
#!/usr/bin/env bash
echo hello
delete:
- name: say-goodbye
script: |
#!/usr/bin/env bash
echo good-bye
Then submit this plugin by passing the filename to the resourceplugin apply
command:
signadot resourceplugin apply -f my-resourceplugin.yaml
You can use signadot resourceplugin list
to see all existing resourceplugins,
and signadot resourceplugin get
to see details about a single resourceplugin.
# List all resourceplugins
signadot resourceplugin list
# Get one resource plugin by name
signadot resourceplugin get my-plugin
You can delete a resourceplugin either by name, or by pointing at the same file that was used to create it:
# Delete resourceplugin by name
signadot resourceplugin delete my-resourceplugin
# Delete resourceplugin specified in a file
signadot resourceplugin delete -f my-resourceplugin.yaml
YAML/JSON Templates
The examples here work with v0.4.0+ of the Signadot CLI.
Sandboxes, RouteGroups, and ResourcePlugins support yaml and json templating which allows substituting values provided in the spec files with values specified on the command line or in other files.
Templating helps with CI automation where some values come from the environment
and it also helps with spec organisation, such as allowing a script to be
edited in a file with extension .sh
while having it automatically embedded
into the spec.
A template file is a yaml file with template directives in strings. A template
directive takes the form @{<value-spec>}
.
A value spec specifies something to put in place of the template directive, which may be a variable reference or an embedding:
<value-spec> ::= <variable-ref> | <embedding>
Variables
A variable in a template directive takes the form @{<variable>}
and
can occur in any string literal. For example
name: "@{dev}-@{team}-feature"
city: "@{city}"
A variable must match the regular expression ^[a-zA-Z][a-zA-Z0-9._-]*$
.
Variable values are then supplied on the command line in the form
--set <variable>=<value>
. For example
signadot sandbox apply -f SANDBOX_FILE --set dev=jane --set team=plumbers
If a variable reference occurs in a sandbox file and no value for that variable is provided, then an error is flagged and the operation is aborted.
Embeddings
An embedding takes the form @{embed: <file>}
. <file>
is a path
to another file. Relative paths are interpreted relative to the directory
in which the template file lives, or relative to the current working directory
if the template file is stdin.
The contents of <file>
are then placed in the string in the resulting document.
For example, with template
name: "@{embed: name.txt}"
and if name.txt contains
Jane
Plumb
Then the expanded file would be
name: "Jane\nPlumb"
Perhaps rendered to yaml as
name: |
Jane
Plumb
Expansion Encodings
Both variable references and embeddings can be expanded in a few different ways.
By default, the value of a variable or the contents of a file are simply placed in the string in which the directive occurs. This replacement occurs by means of operations on the yaml/json string in which the directive occurs, rather than by means of operations on the containing document, so there is no problem with quoting or indentation. This expansion encoding is called a raw expansion encoding and it is the default.
Alternative expansion encodings can be specified for variables or embeddings by
appending [<encoding>]
to the variable name or the operation. raw
, yaml
,
and binary
expansion encodings are supported.
Expansion encodings other than raw
cannot occur properly within a string, nor can
one have multiple template directives in one string when one of them is a non-raw
expansion encoding.
Below are examples of the input and output of raw
, yaml
, and binary
expansion encodings.
For example:
# illegal template
name: " @{embed[yaml]: file.yaml}"
# ^ (contains a space outside the directive)
---
# ok embedding, nothing outside the directive
name: "@{embed[yaml]: file.yaml}"
raw
expansion encoding
# both dev and team are expanded with the raw expansion encoding,
# which is just string interpolation.
name: "@{dev[raw]}-@{team}"
---
# output
name: "jane-plumbers"
yaml
expansion encoding
# the value of the field 'podTemplate' will be the full yaml (not a string)
# defined by the contents of pod-template.yaml
podTemplate: "@{embed[yaml]: pod-template.yaml}"
---
# output
podTemplate:
spec:
containers:
raw
expansion encoding of yaml
# the value of the field 'podTemplateString' will be a string containing
# yaml defined by the contents of pod-template.yaml
podTemplateString: "@{embed[raw]: pod-template.yaml}"
---
# output
podTemplateString: |
spec:
containers:
yaml
expansion encoding of a port number
# with --set port=123, port will be a yaml number
port: "@{port[yaml]}"
---
# output
port: 123
binary
expansion encoding
# with --set data="$(dd if=/dev/urandom count=1)"
data: "@{data[binary]}"
---
# output
data: "mj3cLyX8B5yiL0S9jOm2WKapDD8a56WyJW0nyg7ufiL8w8KZ4mEM0z7eCnBAlqBuDpJPjIwy7Am3X5yQSv7MHZK0Ui+QRCL0D53blHAcFS8WV9bZSRkTBtBAyaeF0tH0HLRKPyXuJPDoZC1NmQIPdsW/el5gmf9nXjtYegjd8oNiN4bayDULXEOjeYkKNyVGGCvCn6TAQ3UeCmfckIcad7Ek1Vvm4EETDF4OFAL6hsYBujeZXdjn/vIquWtMWCq8iVPlLJQ0sMyzCCsNJvx170RSNF6/xh7zeI+RsfFBD/b71Kg0GdFz8zSOSSxsRZqAZBZGdUmYmJvQOyhYOq5Z9sumwSnqgBHjP3gnUaVS4jyaQuhcJJoLlTwHTd6X0WLPknctDGZWCLMd10XVLvKJoPEL99GDhWKyDpXwB2PNNWtZBa8UGrr6YYRsrttlgFkKd/tcSc/zYc8rjsdWARBPSvntSAzKPy459niet+OtpW8SpBuykmT60OZdRUYkntdEvmn7YP88e4aQxT3hZJx+qQGaJUT00w/MdtPL9JUZ63LVKvyDzCf3FGEtDipZZemveNQmyzTg/3mAIBHljS7QZdzeZtZ4ITh+Nxjm30I/Hedkd1qrPBZtoTqMgyVtXYCU+HVLMbiDLUj/9Jc0XL8VHwQoaCJ9M/V+ORZYSOdlDYY="
CLI Config
The CLI reads configuration from a file stored at $HOME/.signadot/config.yaml.
This location can be overridden with the --config
flag. This file contains
information for using the CLI as an interface to Signadot API and also for
running Local Sandboxes. Some parameters in this file can also be set via
environment variables. See the config file
reference.