Skip to main content

Signadot CLI

The Signadot CLI provides a command-line interface to the Signadot API and support for running Local Workloads within Sandboxes.

Installing the CLI​

Via Homebrew​

You can use Homebrew (on either macOS or Linux) to install the CLI:

brew tap signadot/tap
brew install signadot-cli

Via Script​

Or you can install the CLI using a script, run:

curl -sSLf https://raw.githubusercontent.com/signadot/cli/main/scripts/install.sh | sh

Via Release Download​

Or, you can download and extract the latest release archive for your platform.

Via Docker​

The CLI can also be installed and run on-demand via its docker image

Upgrading the CLI​

If you used brew, you can run the following commands to upgrade the CLI installation.

brew update
brew upgrade signadot-cli

If you used the script, you can just re-run it and it will upgrade the CLI to the latest version.

Configuration​

The CLI reads configuration from a file stored at $HOME/.signadot/config.yaml. 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.

API Credentials​

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=...

Local Configuration​

To configure the CLI for running Local Workloads as part of sandboxes, you will need to add a section local to your config file. Here is a minimal local section to get up and running:

local: 
  connections:
  - cluster: <cluster-name> # signadot cluster name
    kubeContext: <kube-context-name> # kubecontext name for the cluster

It is principally comprised of a list of connections, each of which defines parameters for communicating directly with a single Kubernetes cluster.

  • The cluster field specifies the name of the Signadot cluster. You can find this value via the dashboard. This field will also correspond to the cluster field in the sandbox specification.
  • The kubeContext field specifies the name of the corresponding context in your kubeConfig file.

Advanced Local Configuration​

virtualIPNet​

Note

virtualIPNet is intended for versions >= v0.7.0 of the Signadot CLI only when interacting with versions >= v0.16.0 of the Signadot Operator In earlier versions, virtual IPs are not used; rather clusterIPs are used.

While connected to a Kubernetes cluster, the CLI will appropriate a block of virtual IPv4 addresses whose TCP traffic will be routed to the cluster. These IP addresses should not interfere with existing IP address blocks on the machine and the address block should be large enough to accomodate all the services in the cluster, plus IP addresses for pods in StatefulSets which have an associated Service.

By default, this address block is 242.242.0.0/16, which is an address block reserved for future use, and unlikely to conflict with other networks on the host of the CLI.

One can specify this value in the config file in CIDR notation as follows:

local:
  virtualIPNet: 10.22.1.1/16

Connection Configs​

This section outlines what can be configured for every cluster connection configuration in the local section.

type​

For a given connection, type defines the connection method. It can be one of PortForward or ControlPlaneProxy or ProxyAddress. If unspecified, it defaults to PortForward. PortForward uses Kubernetes Port Forwarding to access the cluster. Under the hood, it accesses a SOCKS5 proxy running as part of the Signadot Operator.

type: ControlPlaneProxy provides access to the specified cluster which passes through the Signadot Control Plane instead of directly to the cluster. This is intended for situations where the user does not have kubectl access to port-forward to the cluster or an exposed Signadot Operator tunnel-proxy. This method has associated rate limitations. However, since kubectl access is not required, and one does not need to expose the Signadot Operator tunnel-proxy, it can be easier to set up. ControlPlaneProxy is only available with CLI versions >= v0.7.0 for connecting to clusters running Signadot Operator >= v0.16.0.

As an example, one can use the ControlPlaneProxy connection type as follows

local:
  connections:
  - cluster: staging
    type: ControlPlaneProxy

type: ProxyAddress is intended for a case where a cluster administrator makes the SOCKS5 proxy available to the local machine, for example by exposing a LoadBalancer pointing to the SOCKS5 proxy within a VPN. When doing so, the SOCKS5 proxy is given a TCP address. With type: ProxyAddress, one does not need to specify kubeContext.

For example, assuming a the SOCKS5 proxy is available at socks5-signadot.my.company:1080

local:
  connections:
  - cluster: staging
    type: ProxyAddress
    proxyAddress: socks5-signadot.my.company:1080

inbound​

For a given connection, inbound defines the protocol used for tunneling requests to the local workstation. It can be one of xap or ssh. xap is a Signadot developped tunneling protocol and ssh uses the on-the-wire protocol that the ssh command uses for reverse tunneling.

For example,

local:
  connections
  - cluster: ...
    inbound:
      protocol: xap # or ssh (default)

outbound​

Note

outbound is intended for versions < v0.7.0 of the Signadot CLI or when the Signadot CLI is interacting with versions < v0.16.0 of the Signadot Operator.

For a given connection, outbound defines a parameter for excluding traffic destined to certain addresses in the cluster from being routed to the cluster.

For example,

local:
  connections:
  - cluster: ...
    outbound:
      excludeCIDRs: 
      - 10.43.0.1/32

MacOS Considerations​

MacOS Performance Bug​

MacOS has a subtle bug with the performance of its packet filter pf when redirecting traffic, related to TCP segmentation offloading, which is an optimization to compute tcp segments on a network device instead of with the CPU.

By default, TCP segmentation offloading is on on MacOS. However when MacOS is configured to redirect traffic with pf, such offloading causes severe performance penalties, particularly in the latency of setting up TCP connections.

The Signadot CLI support for local workloads in sandboxes uses pf to redirect traffic and is impacted by this bug.

If you are seeing performance issues on MacOS traffic from a workstation to a connected cluster, the fix is to disable TCP segmentation offloading, which can be done as follows:

sudo sysctl -w net.inet.tcp.tso=0

However, the above command only disables TSO until the next reboot. We recommend turning off TSO permanently on the machine, since testing has shown no negative impact in doing so.

To turn off TSO permanently on MacOS create a file /Library/LaunchDaemons/sysctl.plist (or add to it):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>sysctl</string>
	<key>ProgramArguments</key>
	<array>
		<string>/usr/sbin/sysctl</string>
		<string>net.inet.tcp.tso=0</string>
	</array>
	<key>RunAtLoad</key>
	<true/>
</dict>
</plist>

And then run

sudo launchctl load /Library/LaunchDaemons/sysctl.plist

VPN​

On MacOS, if the cluster to which you'd like to connect is on a VPN which uses a network interface other than en0, you will need to specify the VPN interface in the CLI configuration:

local:
- cluster: cluster-on-vpn
  ...
  outbound:
    macOSVPNInterface: utun6

You can find the VPN interface on MacOS using ifconfig. It is typically a utunN interface which is up and has a peer defined. For example

% ifconfig utun6
utun6: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
	inet 10.6.1.2 --> 10.6.1.1 netmask 0xffffffe0
%