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​

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

Upgrading the CLI​

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

brew update
brew upgrade signadot-cli

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​

Note

Local configuration is intended for versions v0.5.0+ of the Signadot CLI.

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: staging # signadot cluster name
    kubeContext: staging-context # kubecontext name for the cluster

It is 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​

type​

type defines the connection method. It can be one of PortForward 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: 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

outbound​

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

inbound​

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

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
%