Where operations run¶
Goal: understand where Runtime sends an operation, change it, and clear a
retired context.yaml if you are upgrading from an older install.
Runtime keeps no stored context profile of its own. The tool that runs an operation decides
where it goes — kubectl and oc read your kubeconfig, gcloud reads its own
configuration, and admitted gh modes read gh's host/account configuration.
An admitted explicit selector wins; conflicting or unreviewed selectors refuse.
v0.9.9 portability
Runtime observes where it is running (local, CI, Kubernetes), but those environment markers grant no permission and do not choose credentials. There is no context-switch command. Optional source configuration admits native GCP workload sources and an explicit in-cluster kubectl path; local kubeconfig behavior is unchanged. See portable source admission.
v0.9.9: stricter native admission
Command-family semantics replace the last-positional-token classifier.
Named reads such as gcloud projects describe PROJECT are admitted;
gcloud compute instances delete list is still a change and is denied.
Kubernetes Secret reads refuse for aliases, comma lists, interleaved flags
and secret/NAME. Unknown flags/families refuse before probes. This is a
security correction, not a new strong-binding or mutation capability.
Kubeconfig selection uses bounded YAML: one document per regular file,
first-wins merge order, unique keys/context names, no anchors or aliases.
Runtime never runs exec plugins while inspecting the configuration.
The configured authentication.kubernetes.kubeconfig_path takes precedence
over KUBECONFIG, then the native default. Selected paths are made absolute
and carried to the child together with context and selected namespace.
Policy excluding KUBECONFIG refuses instead of silently changing files.
--all-namespaces is distinct from a single namespace; combining it with
an explicit namespace refuses. Files remain mutable: binding is still weak.
gsutil, bq, helm, flux and istioctl retain registry entries but
command invocations refuse until their own grammars are reviewed. Kubernetes
output modes are limited to json, yaml, wide and name; file-backed
templates and raw API paths are not admitted.
context.yaml is retired and now blocks
Runtime used to keep a context.yaml in the Runtime Home holding an org,
project, cluster and namespace. If your Home still has one, every governed
command stops until you move it out. That is deliberate: a file that is
read but not obeyed would let you believe operations go one place while they
go another. Jump to Clearing a retired context.yaml.
Prerequisites¶
- Runtime installed. The first command prepares Runtime Home automatically;
engrt bootstrapis an optional explicit report. - For Kubernetes/OpenShift targets: a kubeconfig, i.e.
kubectlalready works. - For GCP targets:
gcloudinstalled and pointed at a project.
How a target is decided¶
Two sources, in order. There is no third.
- Selectors on the command.
--namespace,--context,--project— these are authoritative for that one invocation. - The tool's own state. Your kubeconfig's
current-context, gcloud's configured project.
Nothing is guessed. If a value cannot be resolved and the operation needs one, the operation is refused rather than sent somewhere plausible.
In v0.9.9, gcloud projects describe PROJECT selects
the positional project ID or number without probing the ambient project. If
--project is omitted, Runtime adds that same value before policy and native
authentication. If supplied, it must match the operand exactly. Different values
refuse before any native probe or requested operation, even if an operator believes
an ID and number refer to the same project; Runtime does not make an API call to
establish that equivalence. Explicit account/configuration, impersonation and
--billing-project selectors remain separate and unchanged. This is still
selector_bound, not credential/configuration immutability or a GCP mutation grant.
Steps: see where you are pointed¶
Expected output (from a machine with gcloud configured and no kubeconfig):
kubectl (kubernetes)
binding: selector_bound
learned: parser
unresolved: context
set it with: kubectl config use-context <name> · kubectl config set-context --current --namespace <ns>
oc (kubernetes)
binding: selector_bound
learned: parser
unresolved: context
set it with: oc project <name>
gcloud (gcp)
binding: selector_bound
learned: reserved_cli_probe
project: engineering-runtime-saas
set it with: gcloud config set project <id>
engrt context show --output json gives the same thing as stable JSON. It
contains no credentials.
Three fields are worth reading closely.
learned says how Runtime found out.
| Value | Meaning |
|---|---|
parser |
Runtime opened and parsed a documented file (your kubeconfig). No process ran. |
reserved_cli_probe |
Runtime asked the tool, after recording a context_probe intent in the audit journal first. |
unavailable |
A probe was the only way to answer and Runtime could not record one, so the value is left unresolved. |
none |
Nothing needed reading. |
Asking gcloud is treated as an effect, not a free read: gcloud config
get-value project may write logs and configuration state while answering. That
is why it is recorded before it happens.
binding says how firmly the target is held, and it decides what may run.
| Binding | Meaning | Can back a change? |
|---|---|---|
strong |
every value is pinned; the tool cannot re-interpret it | yes |
selector_bound |
Runtime pinned a name, and the tool resolves that name itself against a file it re-reads | no |
context_free |
the operation does not depend on where it runs | yes |
Read-only today for kubectl, oc and gcloud
No adapter can claim strong yet, so reviewed reads are allowed and changes are
refused for context-aware tools. kubectl get pods runs; kubectl delete
ns prod is refused with an explanation. The reason is not caution for its
own sake: Runtime approved "delete in namespace staging", and kubectl
would then go and look up what staging means in a file that may have
changed since. Reading from the wrong place shows up in the output; changing
the wrong place does not.
unresolved lists what could not be determined. A read that does not need
the value still works.
Steps: change where operations go¶
Use the tool that owns the answer. Runtime never runs these for you — selecting a context is that tool's operation, not Runtime's.
kubectl config use-context staging
kubectl config set-context --current --namespace orders
oc project staging
gcloud config set project acme-staging
Or name it on the command, which wins for that invocation and is the only form that shows up explicitly in the audit record:
engrt command run kubectl --namespace orders get pods
engrt command run gcloud --project=acme-staging compute instances list
Passing the same selector twice with different values is refused rather than
resolved — Runtime will not choose between --context a and --context b.
GitHub provider operations take an organization as an argument¶
GitHub has no native context for Runtime to read: there is no equivalent of a current kubeconfig context. So the organization is an argument.
engrt github repo list # your own repositories
engrt github repo list acme # an organization's
engrt github issue list acme
engrt github team list acme
issue list and team list require it. Capabilities that touch an
organization declare it as a required input:
This replaced a fallback that read the org from context.yaml. That fallback
made the same command mean one organization on a laptop and another in CI, with
nothing on the command line to show which.
The direct native mode engrt command run gh repo list [OWNER] follows gh's
own behaviour. An explicit owner is authoritative. Without one, gh uses the
authenticated account on GH_HOST (default github.com). Runtime records that
as a selector-bound github_account context and starts gh in a private working
directory, so it cannot infer a repository from the checkout where you invoked
Runtime.
Which tools are context-aware¶
Every tool is registered as one of three things, and an unregistered tool is treated as unsupported rather than assumed safe.
| Mode | Tools |
|---|---|
| Context-aware — Runtime observes native state | kubectl, oc, gcloud; gh.repo.list semantic mode. gsutil, bq, helm, flux and istioctl are registered context-aware but their invocations refuse in v0.9.9 |
| Context-free — coordinates come from arguments | git, terraform, pulumi, packer, kustomize, docker, podman, sops, vault, argocd |
Unsupported through command run |
every other direct gh mode; aws, az |
The unsupported modes select targets from ambient state Runtime cannot safely
bind — many gh modes take a repository from the working directory, aws picks
an account through its credential chain, and az keeps an active subscription.
Runtime will not approve an operation it cannot locate. Admission is per
semantic mode, so support for gh.repo.list does not grant the rest of gh.
Context-free tools run in a private, empty working directory, so their
coordinates must be on the command line — for example git -C DIR or
terraform -chdir=DIR. A command that depends on the directory you invoked
Runtime from is not supported through command run.
Clearing a retired context.yaml¶
If your Runtime Home still has one, commands stop with this:
engrt context: /Users/you/.engrt/context.yaml is a retired Runtime context document, and it is not in force.
Runtime no longer keeps its own context: the tool that runs the operation decides where it goes. Leaving this file readable but ignored would let you believe operations go one place while they go another, so it blocks instead.
Run this to see what each value maps to:
engrt context retire
Then move the file out of Runtime's way yourself:
mv /Users/you/.engrt/context.yaml /Users/you/.engrt/context.yaml.retired
Run the diagnostic. It is a dry run and changes nothing:
Expected output:
Retired context document: /Users/you/.engrt/context.yaml
Runtime no longer keeps its own context. Here is where each value lives now:
prod.kubernetes.context = prod-cluster
owned by kubectl
kubectl config use-context prod-cluster
prod.kubernetes.namespace = orders
owned by kubectl
kubectl config set-context --current --namespace orders
prod.cloud.project = acme-prod
owned by gcloud
gcloud config set project acme-prod
prod.github.organization = acme
GitHub has no native context. Pass the organization explicitly on the operation, or as a capability input
prod.environment = production
Runtime invented this field; no tool owns it. If it selected behaviour, that belongs in your policy document or the capability's inputs
Runtime will not move, rename or delete this file. Do it yourself:
mv /Users/you/.engrt/context.yaml /Users/you/.engrt/context.yaml.retired
Governed execution stays blocked until it is outside the Runtime Home.
Then, in order:
- Set each value with the native command the diagnostic printed.
- Add
organization(and any other invented field's replacement) to the commands or capability inputs that need it. - Move the file yourself. Runtime never moves, renames or deletes it — a runtime that tidies away governance documents is one you cannot audit.
engrt config validate keeps working the whole time, so you can diagnose
while execution is blocked.
RUNTIME_CONTEXT_FILE is retired the same way. If it is exported, unset it; it
selects a document that no longer exists as a concept.
Common failures¶
| Message | Cause | Fix |
|---|---|---|
is a retired Runtime context document |
context.yaml in the Runtime Home |
Run engrt context retire, then move the file |
RUNTIME_CONTEXT_FILE is set |
the retired override is exported | unset RUNTIME_CONTEXT_FILE |
needs a resolved target and none is bound |
the tool has no current context and none was passed | kubectl config use-context <name>, or pass --context/--namespace |
resolved its target as selector_bound … changes are not |
a change through a context-aware tool | Expected today — reads are allowed, changes are not. Use the tool directly if you accept the risk |
is registered as context-unsupported |
an unadmitted gh mode, aws or az through command run |
Use engrt github ... for GitHub or the admitted gh repo list; AWS and Azure have no supported direct path yet |
needs an organization |
issue list / team list with no org |
Pass it: engrt github issue list acme |
was given more than once with different values |
a repeated conflicting selector | Pass it once |
projects describe requires --project to match its positional project ID or number |
the resource operand and global project disagree | Use the same ID or number in both positions, or omit the redundant flag |
Exit codes¶
0 on success. Any refusal above exits non-zero and is written to the audit log
as a denial or failure — including the ones that never reached the platform.
Checking without executing¶
engrt resolve confirms a command line resolves to something real, with
zero side effects — no auth, no policy evaluation, no execution.
Next¶
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.