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:
Via Script
Or you can install the CLI using a script, run:
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.
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 sandboxes with local mappings. Some parameters in this file can also be
set via environment variables.
Authentication
Auth Commands (v0.9.1+)
Starting with CLI v0.9.1, the recommended way to authenticate is using the signadot auth commands:
signadot auth status- Check current authentication statussignadot auth login --with-api-key <api-key>- Login using an API key
Environment Variables
You can provide authentication via environment variables:
export SIGNADOT_ORG=...
export SIGNADOT_API_KEY=...
Config File (Deprecated)
Prior to v0.9.1, authentication was configured using a file stored at $HOME/.signadot/config.yaml which required both org name and API key:
org: ...
api_key: ...
The config file method is deprecated in favor of the new auth commands.
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
clusterfield 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
kubeContextfield specifies the name of the corresponding context in your kubeConfig file.
Advanced Local Configuration
virtualIPNet
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.
type: PortForward uses Kubernetes Port
Forwarding
to access the cluster. Under the hood, it accesses a SOCKS5 proxy running as
part of the Signadot Operator. This connection method requires specifying
the kubeContext field and one may also specify the kubeConfig field.
If kubeConfig is not specified, the default kube-config file as determined without setting
any environment variables is used, normally ~/.kube/config. An example follows.
local:
connections:
- cluster: staging
type: PortForward
kubeContext: staging
kubeConfig: /Users/me/.kube/config-staging # optional
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
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
%