Selectors

A selector is the part of an object that says which workstations the object applies to. You put labels on workstations, and the selector names the labels it looks for. Every workstation that carries those labels gets the object, including workstations created later.

That is how one WorkstationConfig sets up a whole team’s workstations, and how one Integration gives them all the same API key. It also means one edit changes every workstation the selector matches, at once. So write each selector to match the workstations you mean, and no others.

Select workstations by label

1. Put a label on each workstation that should get the object:

   Copy

   apiVersion: workstations.ringleader.dev/v1
   kind: Workstation
   metadata:
     name: billing-dev
     namespace: acme
     labels:
       project: billing

2. Name that label in the object’s selector:

   Copy

   apiVersion: workstations.ringleader.dev/v1
   kind: WorkstationConfig
   metadata:
     name: billing-tools
     namespace: acme
   spec:
     selector:
       matchLabels:
         project: billing
     packages:
       - postgresql-client

The selector matches a workstation in its own namespace that carries every label it names. The workstation may carry other labels too.

If that is all you need, you are done. The rest of this page covers what a selector with no labels matches, whose workstations a selector reaches, how wide to make one, and the local runtime.

What a selector with no labels matches

The answer differs by kind, so check this table before you leave a selector empty:

Whose workstations a selector reaches

A selector never reaches a workstation in another namespace. Inside its namespace, how far a WorkstationConfig or an Integration reaches depends on who applied it:

• An ordinary member’s object reaches only the workstations that member owns. Labels narrow that further, and never widen it to a colleague’s workstation.
• A namespace administrator’s object reaches every workstation in the namespace that its labels match.
• ownerScope: true limits either one to the workstations its author owns.

Access control describes ownership and roles.

How wide to make a selector

A wide selector reaches workstations you were not thinking about when you wrote it: one that does a different job, or one somebody creates next month. Pick the narrowest of these that covers the workstations you mean:

• For one workstation, or a few you pick by hand, list the WorkstationConfig in each workstation’s spec.configs and give the config no selector. No other workstation gets it.
• For a group with a shared purpose, select a label that names the purpose, such as project: billing. A workstation joins the group when someone gives it the label.
• For every workstation you own, set ownerScope: true with no labels. Use this only for settings that are safe on any workstation, whatever it runs: your dotfiles, your shell, a few small packages.

Keep these two behind a label, because each one changes how a workstation reaches the network:

• An Integration of type: httpProxy, which adds a key to requests as they leave the workstation. What changes for a workstation lists what changes, for the workstation and for the containers it runs.
• A WorkstationConfig with an egress policy, which restricts outbound connections.

To see what a selector reaches, list the workstations that carry the label, then read what applies to one of them:

rl workstation get -n acme -l project=billing
rl workstation get-resolved-configuration billing-dev -n acme

The second command lists each config under appliedConfigs, with source: selector for a label match. An Integration appears there as integration-<name>. In rl tui, x on a workstation lists the configs, LocalBindings and SSHKeys whose selectors reach it.

The local runtime

The local runtime is the workstation that runs Docker on your own computer. It is named local-runtime, it is in the local namespace, and it carries one label, role: local-container-runtime. A selector treats it like any other workstation:

• A WorkstationConfig or an Integration in local with ownerScope: true and no labels reaches it, because you own it.
• A selector with labels reaches it only when the runtime carries every one of them.

So in the local namespace, give a WorkstationConfig or an Integration labels. A WorkstationConfig that reaches the runtime installs its packages and tools next to Docker. An Integration that adds a key there adds it for the runtime. The local runtime declares the docker and kind devtools, so its Docker containers get an Edge certificate when the runtime has one. The container guidance explains which connections reach the Edge and what a hand-created kind cluster needs.

To reach the local runtime on purpose, name its label:

spec:
  selector:
    matchLabels:
      role: local-container-runtime

See also

• WorkstationConfig: selectors, explicit references and the personal layer.
• Integration: who an Integration reaches.
• Access control: ownership, roles and what a member’s selector may reach.