containerboot

Documentation

Overview

The containerboot binary is a wrapper for starting tailscaled in a container. It handles reading the desired mode of operation out of environment variables, bringing up and authenticating Tailscale, and any other kubernetes-specific side jobs.

As with most container things, configuration is passed through environment variables. All configuration is optional.

• TS_AUTHKEY: the authkey to use for login.
• TS_HOSTNAME: the hostname to request for the node.
• TS_ROUTES: subnet routes to advertise. Explicitly setting it to an empty value will cause containerboot to stop acting as a subnet router for any previously advertised routes. To accept routes, use TS_EXTRA_ARGS to pass in --accept-routes.
• TS_DEST_IP: proxy all incoming Tailscale traffic to the given destination.
• TS_TAILNET_TARGET_IP: proxy all incoming non-Tailscale traffic to the given destination defined by an IP.
• TS_TAILNET_TARGET_FQDN: proxy all incoming non-Tailscale traffic to the given destination defined by a MagicDNS name.
• TS_TAILSCALED_EXTRA_ARGS: extra arguments to 'tailscaled'.
• TS_EXTRA_ARGS: extra arguments to 'tailscale up'.
• TS_USERSPACE: run with userspace networking (the default) instead of kernel networking.
• TS_STATE_DIR: the directory in which to store tailscaled state. The data should persist across container restarts.
• TS_ACCEPT_DNS: whether to use the tailnet's DNS configuration.
• TS_KUBE_SECRET: the name of the Kubernetes secret in which to store tailscaled state.
• TS_SOCKS5_SERVER: the address on which to listen for SOCKS5 proxying into the tailnet.
• TS_OUTBOUND_HTTP_PROXY_LISTEN: the address on which to listen for HTTP proxying into the tailnet.
• TS_SOCKET: the path where the tailscaled LocalAPI socket should be created.
• TS_AUTH_ONCE: if true, only attempt to log in if not already logged in. If false (the default, for backwards compatibility), forcibly log in every time the container starts.
• TS_SERVE_CONFIG: if specified, is the file path where the ipn.ServeConfig is located. It will be applied once tailscaled is up and running. If the file contains ${TS_CERT_DOMAIN}, it will be replaced with the value of the available FQDN. It cannot be used in conjunction with TS_DEST_IP. The file is watched for changes, and will be re-applied when it changes.
• EXPERIMENTAL_TS_CONFIGFILE_PATH: if specified, a path to tailscaled config. If this is set, TS_HOSTNAME, TS_EXTRA_ARGS, TS_AUTHKEY, TS_ROUTES, TS_ACCEPT_DNS env vars must not be set. If this is set, containerboot only runs `tailscaled --config <path-to-this-configfile>` and not `tailscale up` or `tailscale set`. The config file contents are currently read once on container start. NB: This env var is currently experimental and the logic will likely change!
• EXPERIMENTAL_ALLOW_PROXYING_CLUSTER_TRAFFIC_VIA_INGRESS: if set to true and if this containerboot instance is an L7 ingress proxy (created by the Kubernetes operator), set up rules to allow proxying cluster traffic, received on the Pod IP of this node, to the ingress target in the cluster. This, in conjunction with MagicDNS name resolution in cluster, can be useful for cases where a cluster workload needs to access a target in cluster using the same hostname (in this case, the MagicDNS name of the ingress proxy) as a non-cluster workload on tailnet. This is only meant to be configured by the Kubernetes operator.

When running on Kubernetes, containerboot defaults to storing state in the "tailscale" kube secret. To store state on local disk instead, set TS_KUBE_SECRET="" and TS_STATE_DIR=/path/to/storage/dir. The state dir should be persistent storage.

Additionally, if TS_AUTHKEY is not set and the TS_KUBE_SECRET contains an "authkey" field, that key is used as the tailscale authkey.