Skip to content
Flui Documentation

Multi-context: many installations from one workstation

Multi-cluster topology described a single Flui installation that operates many clusters. This chapter covers the layer above: one workstation driving several Flui installations, each with its own control cluster, credentials and state. The CLI calls each of these connections a context.

Multi-context is not multi-cluster

The two ideas are easy to mix up:

  • Multi-cluster means one installation governing many clusters. You move between clusters within an installation by saying which cluster the operation is for, or by letting the CLI choose when only one is available.
  • Multi-context means one workstation talking to several installations. A consultant operating Flui for three customers, a developer with separate local, staging and prod installations, or a platform team running Flui for two unrelated business units each works with separate contexts.

Every installation has its own API, identity provider, admin credentials, database and SSH trust root. Switching between installations replaces the entire connection state the CLI uses, so it is not a flag on a command.

A context is the unit of switching

A context bundles everything the CLI needs to talk to one installation: the URL of that installation’s API, the credentials to authenticate against it, the provider tokens it stores, the trust anchor it uses to reach cluster nodes, and the local view of the clusters, nodes and operations that installation knows about.

The CLI stores each context on disk. Switching between them is a single command and takes effect at once. Nothing is copied or fetched again; the CLI changes which context’s on-disk state it reads from. A one-off command can also use a different context for a single invocation without changing the active one.

What a context isolates

Contexts share nothing operational:

  • Credentials don’t cross. The provider tokens you added to one context are not visible to another. The same is true of the admin keys used to talk to the API.
  • Secrets are sealed per context. Every context’s stored secrets are encrypted, and each context has its own key. The next section explains where that key comes from.
  • Local caches are per context. The cluster list you see, the recent operations and the SSH trust all belong to the active context. Switching to another context replaces them with that context’s view.

A command typed in the wrong context cannot reach into another installation, because that context does not hold the credentials to do it.

On disk, each context is a separate directory under ~/.flui/profiles/, holding its own configuration, secrets, caches and trust material:

~/.flui/profiles/
├── default/
└── another-context/

The exact layout of each directory, and the commands that create, inspect and switch contexts, are in CLI: Profiles & Configuration.

The vault: one passphrase over every context

A context’s secrets are encrypted, and the key is not stored beside them. Anyone who could read a folder holding both the data and its key could read both. Instead, the key comes from a passphrase you know and the machine does not keep. That is the vault, and there is one per workstation:

Terminal window
flui vault init      # once per machine
flui vault unlock    # once per session
flui vault status    # is it open, and for how long
flui vault lock      # close it now

The passphrase is never stored, never derived back from anything and cannot be reset. Losing it means losing every credential this machine has sealed. That is why flui vault init suggests a five-word passphrase: you need one you can write down and reproduce.

One passphrase, still one key per context. The vault does not put every context under the same key. Each context gets its own, derived from the passphrase and that context’s name. A command working in one context cannot open another context’s stored secrets, even though both were sealed under the same passphrase, so a mistake stays inside the context that made it.

The key is held in memory, not written down. After unlock, a small background helper holds the key for the session and hands it to commands that ask. Nothing goes to disk. On lock the key is overwritten in memory and the helper exits. It also closes on its own after thirty minutes of inactivity, and after eight hours no matter how busy you were.

A locked vault is not an error on its own. Most commands read a preference or an API URL, which are plain text, and never ask for anything. Only a command that opens a stored credential stops. When it does, it says the vault is closed and names flui vault unlock, instead of reporting a decryption failure that would send you looking for corrupt data.

A context for an installation you did not create

A context is normally written by the machine that provisioned the installation. That machine is not always the one that will run it. Somebody can provision Flui on your behalf and keep nothing: no key of their own left on the servers, and so no context for you to copy.

Adoption rebuilds a context on the owner’s machine instead. On the installation, someone allowed to manage its clusters issues a token:

Terminal window
flui env adoption-token

The token is single use, valid for one hour, and tied to that one installation. Anyone holding it can register a trust anchor there, so treat it as a password when you hand it over.

On the owner’s machine:

Terminal window
flui env adopt <token>

The CLI asks the installation to describe itself, writes a local context pointing at it, then creates the SSH trust root on this machine and registers only its public half with the installation. The private key that opens those servers is created on the owner’s workstation, when the owner chooses, and the installation never has one to give away or lose.

--skip-ca rebuilds the context and stops there, leaving SSH unused. Use it if you only intend to use the dashboard.

Adoption rebuilds a connection, not somebody else’s credentials. The provider tokens the builder used stay on the builder’s machine. The adopted context knows where the installation is, and you sign in to it as yourself.

How the CLI shows which context is active

Most commands that act on an installation print a short header before their output, naming the context and the API they are using. If you forgot to switch, the header shows it at the top of the output, so a command run against the wrong installation does not go unnoticed.

Where this chapter goes from here