k3s/docs/sharing-clusters.md

Sharing Cluster Access

Client access to a running kubernetes cluster can be shared by copying the kubectl client config bundle (.kubeconfig). This config bundle lives in $HOME/.kube/.kubeconfig, and is generated by cluster/kube-up.sh. Sample steps for sharing .kubeconfig below.

1. Create a cluster

cluster/kube-up.sh

2. Copy .kubeconfig to new host

scp $HOME/.kube/.kubeconfig user@remotehost:/path/to/.kubeconfig

3. On new host, make copied .kubeconfig available to kubectl

• Option A: copy to default location

mv /path/to/.kubeconfig $HOME/.kube/.kubeconfig

• Option B: copy to working directory (from which kubectl is run)

mv /path/to/.kubeconfig $PWD

• Option C: manually pass .kubeconfig location to .kubectl

# via environment variable
export KUBECONFIG=/path/to/.kubeconfig

# via commandline flag
kubectl ... --kubeconfig=/path/to/.kubeconfig

Manually Generating .kubeconfig

.kubeconfig is generated by kube-up but you can generate your own using (any desired subset of) the following commands.

# create kubeconfig entry
kubectl config set-cluster $CLUSTER_NICK
    --server=https://1.1.1.1 \
    --certificate-authority=/path/to/apiserver/ca_file \
    --embed-certs=true \
    # Or if tls not needed, replace --certificate-authority and --embed-certs with
    --insecure-skip-tls-verify=true
    --kubeconfig=/path/to/standalone/.kubeconfig

# create user entry
kubectl config set-credentials $USER_NICK
    # basic auth credentials, generated on kube master
    --username=$username \
    --password=$password \
    # use either username|password or token, not both
    --token=$token \
    --client-certificate=/path/to/crt_file \
    --client-key=/path/to/key_file \
    --embed-certs=true
    --kubeconfig=/path/to/standalone/.kubeconfig

# create context entry
kubectl config set-context $CONTEXT_NAME --cluster=$CLUSTER_NICKNAME --user=$USER_NICK

Notes:

• The --embed-certs flag is needed to generate a standalone .kubeconfig, that will work as-is on another host.
• --kubeconfig is both the preferred file to load config from and the file to save config too. In the above commands the --kubeconfig file could be omitted if you first run

export KUBECONFIG=/path/to/standalone/.kubeconfig

• The ca_file, key_file, and cert_file referrenced above are generated on the kube master at cluster turnup. They can be found on the master under /srv/kubernetes. Basic auth/token are also generated on the kube master.

For more details on .kubeconfig see kubeconfig-file.md, and/or run kubectl config -h.

Merging .kubeconfig Example

kubectl loads and merges config from the following locations (in order)

1. --kubeconfig=path/to/kubeconfig commandline flag
2. KUBECONFIG=path/to/kubeconfig env variable
3. $PWD/.kubeconfig
4. $HOME/.kube/.kubeconfig

If you create clusters A, B on host1, and clusters C, D on host2, you can make all four clusters available on both hosts by running

# on host2, copy host1's default kubeconfig, and merge it from env
scp host1:/path/to/home1/.kube/.kubeconfig path/to/other/.kubeconfig

export $KUBECONFIG=path/to/other/.kubeconfig

# on host1, copy host2's default kubeconfig and merge it from env
scp host2:/path/to/home2/.kube/.kubeconfig path/to/other/.kubeconfig

export $KUBECONFIG=path/to/other/.kubeconfig

Detailed examples and explanation of .kubeconfig loading/merging rules can be found in kubeconfig-file.md.