Skip to content

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

gcloud auth login                           # native CLI account; Runtime never starts this
authentication:
  gcp:
    enabled: true
    binary: gcloud
engrt auth login gcp
engrt auth status

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:

engrt command run gcloud --project=acme-staging compute instances list

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.

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

engrt auth logout gcp

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

authentication:
  kubernetes:
    enabled: true
    source: in_cluster

command_providers:
  kubectl: kubernetes

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

kubectl config use-context <name>
authentication:
  kubernetes:
    enabled: true
    kubeconfig_path: ""     # defaults to $KUBECONFIG, then ~/.kube/config
engrt auth login kubernetes
engrt auth status

Kubeconfig resolution

The selected kubeconfig resolves in this order:

  1. authentication.kubernetes.kubeconfig_path in config.yaml
  2. $KUBECONFIG, as a merge list — the first file that sets current-context wins
  3. ~/.kube/config
export ENGRT_AUTHENTICATION_KUBERNETES_KUBECONFIG_PATH=/path/to/kubeconfig

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:

command_policy:
  admitted_helpers:
    kubectl:
      - /opt/homebrew/bin/gcloud
      - /opt/homebrew/bin/python3

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:

engrt command run kubectl --namespace orders get pods

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.

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

engrt auth logout kubernetes

There is no session to clear — a kubeconfig is a file. This prints guidance and is audited.


OpenShift

Validation: oc whoami.

Setup

oc login --token=<token> --server=https://api.openshift.example.com:6443
authentication:
  openshift:
    enabled: true
    binary: oc
    server: ""        # optional hint only
engrt auth login openshift
engrt auth status

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

engrt auth logout openshift

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.