# 0134. `ichor init --merge-kubeconfig` merges the new cluster into the user's kubeconfig

Status: Accepted · Date: 2026-11-06 · Design section: Bootstrap (`ichor init`) · Builds on: 0127

Decided: `ichor init --merge-kubeconfig` (opt-in) merges the cluster-admin kubeconfig into the kubeconfig kubectl would write to (the first existing file of `$KUBECONFIG`, else its first path, else `~/.kube/config`; `--kubeconfig` wins), as cluster `<name>`, user and context `admin@<name>`, renames on a collision instead of overwriting, and makes the new context current. The copy at `~/.ichor/clusters/<name>/kubeconfig` is written as before. Without the flag init touches nothing outside `~/.ichor` and prints the `export KUBECONFIG=` line.

## Context

init saves the kubeconfig under `~/.ichor/clusters/<name>/kubeconfig` and never touches `~/.kube/config`, so every later `ichor` or kubectl call needs `export KUBECONFIG=...`. `talosctl config merge` is the precedent for merging on request. A kubeconfig holds a client key, so the merge must not be silent.

## Decision

1. **Opt-in.** Rewriting a file the user keeps other clusters in is never a default.
2. **Target file.** The CLI's own resolution (`--kubeconfig`, `$KUBECONFIG`, `~/.kube/config`) with client-go v0.36.2's write target: `ClientConfigLoadingRules.GetDefaultFilename()` returns the explicit path, else the first existing file of `$KUBECONFIG`, else its first entry, else `~/.kube/config`. This is where `kubectl config set-context` would write. Only that one file is written; other files of a multi-path `$KUBECONFIG` are read (for name collisions) and left alone. The parent directory is created (0700).
3. **Names.** Cluster `<name>`, user and context `admin@<name>`. Talos writes the same names into the saved kubeconfig (`admin@<cluster>`), so the merged entry looks like the one `talosctl kubeconfig` makes.
4. **Collision.** If a cluster, user or context of that name exists (in any file of the loading chain) with different content, the cluster name gets the first free suffix (`demo-1`, `demo-2`, ...) and the user and context follow (`admin@demo-1`), as `talosctl config merge` renames. Nothing existing is overwritten or removed. If all three already exist with identical content (a repeated merge) nothing is rewritten. The final context name is printed.
5. **Current context.** Set to the merged context. The user asked for kubectl and ichor to talk to the new cluster; `ichor init` just built it, so it is what they want next, and it is said in the output. The alternative (leave it alone) would defeat the point of the flag, since `ichor` would still need `--context`.
6. **Write.** Load with `clientcmd.LoadFromFile`, edit the `api.Config`, `clientcmd.Write`, then write a temporary file in the same directory and rename it over the target (0600; `writeFileAtomic`). Credentials are never printed.
7. **Plan.** init's header says, before anything is applied, which context will be merged into which file, and the target is read and parsed then, so a malformed kubeconfig stops init before the irreversible apply.
8. **Next step.** init always ends with it: with the flag "kubectl and ichor now use context X"; without it the `export KUBECONFIG=` line and a hint about the flag.

## Alternatives rejected

- Merge by default: surprising writes to a shared file.
- Overwrite on a collision, or refuse: overwriting loses a user's entry; refusing after the node was applied leaves the user without a kubeconfig. Renaming is safe and reversible.
- Not setting current-context: kubectl keeps pointing at another cluster after the user asked for the merge.
- Writing to every file of `$KUBECONFIG`: kubectl itself writes new entries to one file.

## Risks

A later merge for a cluster with the same name after the old one was deleted adds `admin@demo-1`; the user deletes stale entries with `kubectl config delete-context`. A concurrent kubectl write between our read and rename can be lost (the rename is atomic, the read-modify-write is not locked, as in kubectl's own lock-file-less case).