containerboot command

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 defined by an IP address.
• TS_EXPERIMENTAL_DEST_DNS_NAME: proxy all incoming Tailscale traffic to the given destination defined by a DNS name. The DNS name will be periodically resolved and firewall rules updated accordingly. This is currently intended to be used by the Kubernetes operator (ExternalName Services). This is an experimental env var and will likely change in the future.
• 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.
• TS_HEALTHCHECK_ADDR_PORT: deprecated, use TS_ENABLE_HEALTH_CHECK instead and optionally set TS_LOCAL_ADDR_PORT. Will be removed in 1.82.0.
• TS_LOCAL_ADDR_PORT: the address and port to serve local metrics and health check endpoints if enabled via TS_ENABLE_METRICS and/or TS_ENABLE_HEALTH_CHECK. Defaults to [::]:9002, serving on all available interfaces.
• TS_ENABLE_METRICS: if true, a metrics endpoint will be served at /metrics on the address specified by TS_LOCAL_ADDR_PORT. See https://tailscale.com/kb/1482/client-metrics for more information on the metrics exposed.
• TS_ENABLE_HEALTH_CHECK: if true, a health check endpoint will be served at /healthz on the address specified by TS_LOCAL_ADDR_PORT. The health endpoint will return 200 OK if this node has at least one tailnet IP address, otherwise returns 503. NB: the health criteria might change in the future.
• TS_EXPERIMENTAL_VERSIONED_CONFIG_DIR: if specified, a path to a directory that containers tailscaled config in file. The config file needs to be named cap-<current-tailscaled-cap>.hujson. 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! TS_EXPERIMENTAL_ENABLE_FORWARDING_OPTIMIZATIONS: set to true to autoconfigure the default network interface for optimal performance for Tailscale subnet router/exit node. https://tailscale.com/kb/1320/performance-best-practices#linux-optimizations-for-subnet-routers-and-exit-nodes 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.