GCP, Kubernetes and OpenShift¶
Version boundary
This page describes the pre-0.12 authentication contract. See
Governed authority for v0.12.0
sources, separate ENGRT session, raw gh compatibility change and proof model.
For GitHub credentials inside GKE/Kubernetes (distinct from GCP/GKE
workload identity), follow the v0.12.0 GKE setup (not qualified in v0.12.0).
Goal: inspect native credential or configuration readiness without creating a Runtime credential store. The native tools own their credentials and may refresh their own caches. Runtime uses a credential only for the bounded check or the admitted request and never returns it in results or audit. Interactive login is never triggered.
The authentication modes below describe v0.9.9 on macOS and Linux. Windows is not supported in this release. Supported modes do not imply support for every provider configuration or cloud platform.
All three ship enabled: false. Enable one after native local login or after
provisioning its explicitly admitted workload source; a pod does not need a
developer's interactive login.
Invocation admission and native identity readiness are separate gates. Reviewed selectors are applied before command policy and unknown selectors refuse. Kubernetes configuration inspection does not execute credential plugins. See context precedence.
GCP¶
Validation: select a usable CLI account, then request an access token for it with the prepared configuration, impersonation, project and billing selectors. The token stays in memory for the check.
Credential readiness is not proof of an API principal
Native credential-file/token overrides and impersonation can supersede the
account setting. Runtime v0.9.9 reports proof=credential_ready and an
empty subject; it never labels this ADC. A readiness result cannot satisfy
an identity allow-list. Resource access is still tested by the requested
operation.
This is also why gcloud auth print-access-token is refused when you ask
for it through command run: a tool may use a credential, but may not turn
it into Runtime output.
Setup¶
Where the project comes from¶
gcloud invoked through the Command Engine gets --project= from
gcloud's own configuration — never from a
Runtime file:
gcloud config set project acme-staging # gcloud owns this
engrt command run gcloud compute instances list
Or pass it on the command, which wins for that invocation:
Runtime resolves the project and builds the final argument list before policy evaluates it, so the command policy judges is the command that runs.
Reading gcloud's configured project means running gcloud config get-value
project, which may write logs and configuration state. Runtime records a
context_probe intent before it happens; if it cannot, the project is left
unresolved rather than probed anyway.
Changes are refused today. gcloud ... delete through the Command Engine
stops with an explanation: Runtime pinned a project name that gcloud
re-resolves itself, which is not a strong enough binding to back a change.
Reviewed reads are allowed; unknown invocation forms refuse in v0.9.9.
Maintained read capabilities¶
Runtime v0.9.9's maintained gcloud capabilities require an explicit project
input and native JSON on each read. Enable GCP auth and the
command_providers.gcloud: gcp mapping for governed execution. A successful
project read proves neither a specific principal nor the absence of a
node-identity fallback. See the
GCP corpus contract.
Portable GCP sources — v0.9.9¶
authentication.gcp.source admits one native mechanism:
| Source | Preparation | Failure behavior |
|---|---|---|
native (default) |
Stored CLI account; an admitted CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE takes precedence |
No metadata fallback; policy-excluded selected configuration refuses |
credential_file |
Required native credential-file override, such as the file provisioned by CI workload identity federation tooling | Account-free; a missing file never switches to ADC or a stored user |
gke_metadata |
Exact workload_service_account GSA email (required) |
No user store, unrelated account or node-default fallback; conflicting selectors refuse |
An explicit account selector is incompatible with a credential-file override
because the SDK ignores it in that mode. CLI credentials and ADC are separate:
v0.9.9 never substitutes GOOGLE_APPLICATION_CREDENTIALS for the selected
gcloud source, and the source label does not verify the file's issuer or a
principal. If policy narrows the gcloud environment, it must keep the selected
CLOUDSDK_CONFIG, credential-file, active configuration, account,
impersonation and project variables; otherwise Runtime refuses before probes
or execution.
authentication:
gcp:
enabled: true
source: gke_metadata
workload_service_account: [email protected]
The GKE mode requires a KSA→GSA workload identity mapping that is distinct from the node service account, and no host networking. A successful read does not independently prove that mapping; confirm it with IAM/platform evidence and a denied-identity check.
Recognized Unix SDK launchers run with the SDK's bundled Python or a python3
found on Runtime's PATH; install a compatible interpreter there. Ambient
Python overrides and import paths are not forwarded.
engrt gcp project describe PROJECT_ID uses the same admitted source through
the REST Engine. No arbitrary GCP API is exposed. The required permission is
resourcemanager.projects.get; HTTP 403, native auth failure and pre-dispatch
Runtime denial are different outcomes.
Related binaries (native GCP)¶
The default config maps gsutil and bq to gcp, but in v0.9.9 those
invocations refuse: the GCP auth check covers gcloud only, and a mapping or
installed binary alone is not support.
Logout¶
Runtime refuses logout when a native credential override or impersonation is
in effect. Otherwise it selects one CLI account and runs
gcloud auth revoke <selected-account> --quiet. ADC is never revoked.
gcloud's credential type determines whether it revokes on the server or removes
only the local stored credential. Runtime does not revoke external identity
sources, service-account keys, or every configured account.
Kubernetes¶
Explicit in-cluster source — v0.9.9¶
The in-cluster source supports read-only kubectl. It is never selected
automatically from Kubernetes or CI markers; an absent source (or
kubeconfig) keeps the local path below. source: in_cluster cannot be
combined with kubeconfig_path.
It requires the standard projected service-account mount, a valid CA, the
namespace file, and the native KUBERNETES_SERVICE_HOST (IP) and
KUBERNETES_SERVICE_PORT. Runtime fixes endpoint, CA and namespace in a private
per-invocation configuration and references the mounted token file so kubectl
observes rotation. It never copies a developer kubeconfig or token bytes.
Explicit namespace selection is supported; another context, a configured
kubeconfig path, a missing mount, an invalid CA, or a policy that excludes
KUBECONFIG refuses without fallback. Cleanup never touches the mounted token.
The proof is configuration_ready, not verified service-account identity. The
target is strongly bound, but writes remain unsupported. Verify a permitted pod
read, an RBAC-denied read in another namespace, and a Runtime Secret/mutation
denial independently. Kubernetes RBAC for the service account is separate from
the same pod's Google IAM mapping.
Local kubeconfig source¶
Validation: reads the kubeconfig's current-context. There is no
shell-out and no kubectl dependency for the auth check itself.
The result is proof=configuration_ready, with no subject. It does not prove
that credentials are unexpired, that an exec plugin will succeed, or that the
API server permits a resource operation. Every merge file is parsed strictly
under size and structure bounds; duplicate keys and multiple documents refuse.
Your kubeconfig is in the File Engine's
protected set
— engrt files read ~/.kube/config is refused.
Setup¶
authentication:
kubernetes:
enabled: true
kubeconfig_path: "" # defaults to $KUBECONFIG, then ~/.kube/config
Kubeconfig resolution¶
The selected kubeconfig resolves in this order:
authentication.kubernetes.kubeconfig_pathinconfig.yaml$KUBECONFIG, as a merge list — the first file that setscurrent-contextwins~/.kube/config
Selected paths are made absolute and passed to the child together with the context and namespace. Runtime fingerprints every file in the list, so an edit that changes which file wins is detectable.
For a local GKE kubeconfig, gke-gcloud-auth-plugin obtains the user's token
by launching gcloud, which launches Python. That helper chain does not
inherit your shell PATH, so a valid context and configuration_ready proof
do not guarantee that the actual command can authenticate. Explicitly admit
the helpers for kubectl only:
Use your actual absolute paths and a Python version compatible with the
installed SDK. This example assumes the kubeconfig names the plugin by absolute
path; a relative plugin name needs its own helper admission. Do not forward the
whole caller PATH or put access tokens in kubeconfig to make a test pass. The
in-cluster source does not need this.
Where the namespace comes from¶
kubectl gets its context and namespace from your kubeconfig, which
Runtime reads and never writes:
kubectl config use-context staging
kubectl config set-context --current --namespace orders
engrt command run kubectl get pods
Or pass them on the command:
Runtime never switches kubeconfig contexts for you. Changes are refused
today: kubectl delete and kubectl apply stop with an explanation, while
reviewed reads run. --all-namespaces combined with an explicit namespace
refuses.
Related binaries¶
helm, flux and istioctl map to the kubernetes auth provider, but their
invocations refuse in v0.9.9 until their grammars are reviewed. kustomize is
deliberately unmapped: it only renders YAML to stdout.
Logout¶
There is no session to clear — a kubeconfig is a file. This prints guidance and is audited.
OpenShift¶
Validation: oc whoami.
Setup¶
server is stored as a hint. Login itself is still performed with oc login,
outside Runtime.
Selected native context¶
The command's context and namespace are resolved from explicit selectors and
native kubeconfig before policy. The credential check uses the same oc,
kubeconfig and --context, not an unrelated default session. A usable
oc whoami principal is reported as principal_verified.
Logout¶
This genuinely ends the session, via oc logout. Native logout output is not
returned verbatim. Disabled GCP/OpenShift adapters do not execute logout.
Evidence failures during login, logout and status¶
Explicit engrt auth login/logout/status record an intent before probing and
report a completion-record failure if one occurs. Runtime does not replay a
logout when evidence writing fails — check the native tool's state before
retrying.
Not yet implemented¶
| Provider | Intended approach |
|---|---|
| AWS | Validate the existing credential chain (env vars, ~/.aws/credentials, IAM role, SSO) — e.g. aws sts get-caller-identity |
| Azure | Reuse the az account show / Azure CLI token cache |
| Additional CI federation adapters | GCP's native credential-file source is implemented; other issuer/provider combinations are not |
Until adapters can bind their selected account or subscription, aws and az
remain context-unsupported through command run, even
though the compiled policy names them. vault is context-free and uses its own
credentials, subject to its command and environment policy.
OIDC is often already below a native CLI: kubeconfig exec plugins, workload identity federation, AWS role chains and Azure federated credentials obtain short-lived credentials without Runtime handling the exchange. Runtime preserves that native mechanism; it is not another identity provider.
Deliberately unmapped¶
docker and podman have their own daemon and registry logins. terraform
and pulumi resolve credentials through their own provider configuration.
sops uses its own KMS/PGP/age keys. packer only builds images. None of
these will gain an auth provider mapping — run their native login commands
yourself.
Operational examples on this site were verified against Runtime 0.14.0. After bootstrap, the version-exact files in Runtime Home win.