Configuration Reference
About 1197 wordsAbout 4 min
2025-08-25
This page lists all configuration keys, their defaults, and effects. Sources: flags, environment (TKA_ prefix), or config files (config.yaml).
Conventions
- Env var mapping replaces
.with_and uppercases keys, prefixed withTKA_(e.g.,tailscale.hostname→TKA_TAILSCALE_HOSTNAME). - Default config search paths:
.,$HOME/.config/tka/,/etc/tka/.
Common
debug(bool, defaultfalse)- Enable debug logging.
otel.endpoint(string, default"")- OTLP gRPC endpoint; if empty, OTel spans/metrics exporters may be disabled.
otel.insecure(bool, defaulttrue)- Whether to use insecure transport to the OTLP endpoint.
Tailscale
tailscale.hostname(string, defaulttka)- Hostname for the tsnet node; also used by the CLI to build
https://{hostname}.{tailnet}.
- Hostname for the tsnet node; also used by the CLI to build
tailscale.port(int, default443)- API port. Scheme is
httpsif443, otherwisehttp.
- API port. Scheme is
tailscale.stateDir(string, default"")- Directory for tsnet state (keys, control data).
- If empty, a directory is selected automatically under
os.UserConfigDirbased on the name of the binary.
tailscale.tailnet(string, no default)- Tailnet domain, e.g.,
example.ts.net; used by CLI to compose the base URL.
- Tailnet domain, e.g.,
tailscale.capName(string, defaultspecht-labs.de/cap/tka)- Capability name the server requires from Tailscale ACLs.
Tailscale Environment variables
TS_AUTHKEY- Auth key used to register/login the node to your tailnet without an interactive browser flow.
- Recommended to use an ephemeral/reusable auth key generated from the Tailscale admin console.
- Example:
export TS_AUTHKEY=tskey-auth-XXXXXXXXXXXXXXXX - Security: treat like a secret. Prefer short-lived keys.
TSNET_FORCE_LOGIN- If set to
1,true, orTRUE, forces an interactive/browser login even if an auth key is present. - Useful for developer setups where you don’t want to depend on an auth key.
- Example:
export TSNET_FORCE_LOGIN=1
- If set to
Notes:
- TKA embeds Tailscale using
tsnet. These variables are read by Tailscale when bringing the embedded node up; TKA itself does not parse them. - Variables commonly used with the standalone
tailscaleddaemon (e.g.,TS_STATE_DIR,TAILSCALE_*) do not apply to the embeddedtsnetclient in this binary. Usetailscale.stateDirin TKA config or--dirto control state location.
Server HTTP timeouts
server.readTimeout(duration, default10s)server.readHeaderTimeout(duration, default5s)server.writeTimeout(duration, default20s)server.idleTimeout(duration, default120s)
These tune the embedded HTTP server created for tsnet.
Operator
Defaults from code: namespace=tka-dev, clusterName=tka-cluster, contextPrefix=tka-context-, userPrefix=tka-user-.
operator.namespace(string)- Namespace where SignIn and ServiceAccounts/Bindings are created.
operator.clusterName(string)- Name written into kubeconfig contexts.
operator.contextPrefix(string)- Prefix for per-user kubeconfig context name.
operator.userPrefix(string)- Prefix for kubeconfig user entry.
API behavior
api.retryAfterSeconds(int, default1)- Hint for clients polling async operations (e.g., kubeconfig provisioning).
CLI Output Settings
These settings control how the TKA CLI displays information and are used by client commands:
output.theme(string, defaulttokyo-night)- Color theme for CLI output. Available themes:
ascii,dark,dracula,light,markdown,notty,tokyo-night
- Color theme for CLI output. Available themes:
output.long(bool, defaulttrue)- Show detailed output by default when available
output.quiet(bool, defaultfalse)- Suppress non-essential output when available
output.markdownlint-fix(bool, defaultfalse)- Apply markdown formatting fixes to generated documentation
Cluster Information
The clusterInfo section configures the cluster connection details that TKA exposes to authenticated users through the cluster-info API endpoint. This information is used by users to configure their kubeconfig files and understand the cluster they're connecting to.
clusterInfo.apiEndpoint(string, required unlessconfigMapRef.enabledis true)- The Kubernetes API server URL or IP address that users should connect to
- This should be the externally accessible endpoint of the cluster's API server
- Examples:
"https://api.cluster.example.com:6443","https://192.168.1.100:6443" - Note: Must be set for TKA to start when not using
configMapRef.
clusterInfo.caData(string, base64-encoded, default"")- The base64-encoded Certificate Authority (CA) data for the Kubernetes cluster
- Used to verify the TLS certificate presented by the API server
- Should be the PEM-encoded CA certificate, encoded as base64
- If empty and
insecureSkipTLSVerifyis false, the system's root CA bundle will be used - Note: CA data is public information (not sensitive) and can be stored in ConfigMaps
- Source: Available from
cluster-infoConfigMap inkube-publicnamespace or kubeconfig - Purpose: Required for production clusters to verify server identity
clusterInfo.insecureSkipTLSVerify(bool, defaultfalse)- Controls whether TLS certificate verification should be skipped when connecting to the cluster
- When
true, clients will accept any certificate and ignore hostname mismatches - Security: Should only be set to
truefor development/testing with self-signed certificates - Production clusters should use valid certificates and keep this
false
clusterInfo.labels(map[string]string, default{})- Key-value pairs used to identify and categorize the cluster
- Helps users distinguish between different clusters and can be used for automation
- Common examples:
environment: production,region: us-west-2,project: webapp,team: platform - These labels are exposed in the cluster-info API response and can be used by client tools
ConfigMap Reference
Use a Kubernetes ConfigMap to supply cluster connection details. This is useful for kubeadm clusters which expose a cluster-info ConfigMap in the kube-public namespace.
clusterInfo.configMapRef.enabled(bool, defaultfalse)- When
true, TKA reads connection details from the specified ConfigMap - Mutually exclusive with explicit
clusterInfo.*connection settings
- When
clusterInfo.configMapRef.name(string, default"")- Name of the ConfigMap containing connection details
clusterInfo.configMapRef.namespace(string, default"")- Namespace where the ConfigMap is located
clusterInfo.configMapRef.keys.apiEndpoint(string, default"apiEndpoint")- Key within the ConfigMap data which contains the API endpoint
clusterInfo.configMapRef.keys.caData(string, default"caData")- Key within the ConfigMap data which contains base64-encoded CA certificate data
clusterInfo.configMapRef.keys.insecure(string, default"insecure")- Key within the ConfigMap data which contains a boolean-like string for insecure TLS (e.g.,
"true","1")
- Key within the ConfigMap data which contains a boolean-like string for insecure TLS (e.g.,
clusterInfo.configMapRef.keys.kubeconfig(string, default"kubeconfig")- Optional. If set and present, TKA will parse the embedded kubeconfig and extract the first cluster's
serverandcertificate-authority-data(kubeadmcluster-infostyle).
- Optional. If set and present, TKA will parse the embedded kubeconfig and extract the first cluster's
- Use
clusterInfo.labelsto add labels; they apply in both explicit and ConfigMap modes
Note
You must provide exactly one of: explicit clusterInfo.apiEndpoint or configMapRef.enabled: true with a valid reference. If both are provided, TKA will refuse to start.
Flags
Server and CLI share some flags via the root command:
--config, -c Path to config file
--debug Enable debug logging (maps to debug)
--server, -s Tailscale hostname (maps to tailscale.hostname)
--port, -p API port (HTTP) (maps to tailscale.port)Server-only flags:
--dir, -d tsnet state directory (maps to tailscale.stateDir)
--cap-name, -n Capability name to require (maps to tailscale.capName)
--health-port Port for local metrics and health server (maps to health.port)
--api-endpoint Kubernetes API endpoint URL (maps to clusterInfo.apiEndpoint)
--ca-data Base64-encoded cluster CA data (maps to clusterInfo.caData)
--insecure-skip-tls-verify Skip TLS verification (maps to clusterInfo.insecureSkipTLSVerify)
--labels Cluster labels key=value list (maps to clusterInfo.labels)Example config.yaml
# Enable debug logging (top-level, not under server)
debug: false
# CLI output settings
output:
theme: tokyo-night
long: true
quiet: false
markdownlint-fix: false
tailscale:
hostname: tka
port: 443
stateDir: /var/lib/tka/tsnet-state
tailnet: your-tailnet.ts.net
capName: specht-labs.de/cap/tka
server:
readTimeout: 10s
readHeaderTimeout: 5s
writeTimeout: 20s
idleTimeout: 120s
otel:
endpoint: ""
insecure: true
operator:
namespace: tka-system
clusterName: tka-cluster
contextPrefix: tka-context-
userPrefix: tka-user-
api:
retryAfterSeconds: 1
clusterInfo:
labels:
environment: production
region: us-west-2
project: webapp
team: platform
# Alternative: use a ConfigMap as the source of cluster connection details
# Enable and omit apiEndpoint above.
configMapRef:
enabled: false
name: "cluster-info"
namespace: "kube-public"
keys:
apiEndpoint: "apiEndpoint"
caData: "caData"
insecure: "insecure"