Command-line Interface (CLI)

The Signadot CLI provides a command-line interface to the Signadot API.

Installation

To install the CLI, download and extract the latest release archive for your platform, or use Homebrew (on either macOS or Linux):

brew tap signadot/tap
brew install signadot-cli

The CLI can also be installed and run on-demand via its docker image, or via go run using Go 1.18 or later:

go run github.com/signadot/cli/cmd/signadot@latest

Configuration

In order to talk to the Signadot API, the CLI needs your Signadot org name as well as a Signadot API key, which you can generate in the dashboard.

These values can be provided in a file stored at $HOME/.signadot/config.yaml:

org: ...
api_key: ...

Or you can provide them as environment variables:

export SIGNADOT_ORG=...
export SIGNADOT_API_KEY=...

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

Note

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 Apply Sandbox API call.

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.

Sandbox Templates

Note

The examples here work with v0.3+ of the Signadot CLI.

Sandboxes yaml files can optionally take the form of templates, permitting the substitution of scalar values in the sandbox yaml file with values specified on the command line.

A variable reference in a sandbox file takes the form @{<variable>} and can occur in any string literal. For example

name: "@{dev}-@{team}-feature"

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.

The mechanism above also works with signadot sandbox delete -f SANDBOX_FILE, so that one can create and delete sandboxes based on templates uniformly.

Finally, one can specify ports in endpoints as string representations of integers, and they will be converted automatically to integers. For example

name: my-sandbox
spec:
  cluster: my-cluster
  description: Testing sandboxes
  forks:
  - forkOf:
      kind: Deployment
      namespace: example
      name: my-app
  defaultRouteGroup: # CLI v0.3.7+ required (see sandbox specification for details)
    endpoints:
    - name: my-endpoint       
      target: "http://my-app.example.svc:@{port}"

RouteGroups

Note

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 Apply RouteGroup API call.

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