Kubernetes with installation OIDC

An installation can manage Kubernetes using its OIDC identity. The target stores the cluster endpoint, its public CA certificate, and the public identity coordinates. You do not put access keys, client secrets, bearer tokens, or an authenticated kubeconfig in the target. This requires formae 0.90.2 or newer, Kubernetes plugin 0.1.13 or newer, and a compatible credential broker paired with K8S. For a hosted installation, confirm that a compatible broker is enabled before configuring these targets. An older self-hosted agent must be upgraded and configured with a broker before these targets can work. Installing the Kubernetes plugin alone does not establish an installation identity or grant cluster access.

How it relates to a cloud connection

Your AWS, Azure, or GCP target continues to provision cloud resources through its existing cloud plugin. A Kubernetes target is a separate, ordinary target. It does not inherit a cloud target’s credentials or call the cloud plugin for a token. You can reuse the cloud connection’s public role, client, or workload identity provider coordinates when that identity also has cluster access. The Kubernetes plugin asks the installation broker for a short-lived assertion and performs the appropriate exchange itself:

Target	Authentication path	Identity requiring cluster access
EKS	Installation assertion → AWS role session → EKS token	IAM role
AKS	Installation assertion → Entra access token for AKS	Service principal
GKE	Installation assertion → Google federated access token	Workload identity pool principal, or the explicitly selected service account
Direct OIDC	Installation assertion → Kubernetes API server	The API server’s username derived from the installation subject

Tokens are cached in memory and refreshed as operations need them. Explicit OIDC configuration does not fall back to the agent’s local cloud credentials if federation fails. The installation still has its managed identity and signing infrastructure; the absence of customer credentials in Pkl does not mean there are no credentials anywhere in the system.

Prepare access first

Create or identify the cluster and obtain its trusted HTTPS endpoint and base64-encoded PEM CA certificate.
Configure trust for https://oidc.cloud.formae.ai and the installation’s exact subject from connection setup. Do not derive the subject from an organization name or a guessed installation ID.
Grant that authenticated identity the Kubernetes permissions your resources need, and allow time for the grants to propagate.
Apply a new Kubernetes target and its workloads. The agent must be able to reach the cluster and, for cloud authentication, the provider’s token service.

Creating a cloud connection does not automatically grant Kubernetes access to every cluster in that account. Installing cloud provider plugins does not create cluster access grants either.

Target configurations

Add these schema dependencies to your PklProject and run pkl project resolve:

dependencies {
  ["formae"] {
    uri = "package://hub.platform.engineering/plugins/pkl/schema/pkl/formae/formae@0.90.2"
  }
  ["k8s"] {
    uri = "package://hub.platform.engineering/plugins/k8s/schema/pkl/k8s/k8s@0.1.13"
  }
}

Each authentication block below fits inside this target’s config. Replace the example coordinates and choose the Kubernetes minor version matching your cluster. The 1.34 import and kubernetesVersion must agree.

import "@formae/formae.pkl"
import "@k8s/v1.34/k8s.pkl" as k8s

target = new formae.Target {
  label = "application-cluster"
  config = new k8s.Config {
    kubernetesVersion = "1.34"
    // Insert one auth block below.
  }
}

AWS EKS

auth = new k8s.EKSAuth {
  endpoint = "https://eks.example.invalid"
  certificateAuthority = "REPLACE_WITH_BASE64_PEM_CLUSTER_CA"
  clusterName = "application-cluster"
  region = "us-west-2"
  credentials = new k8s.AwsOidcCredentials {
    roleArn = "arn:aws:iam::123456789012:role/formae-kubernetes"
  }
}

The role’s federation trust must admit the exact installation subject and audience sts.amazonaws.com. Separately, create an EKS access entry and permissions for that role, using an access policy or Kubernetes RBAC groups. The cluster must have an authentication mode supporting access entries. Role trust alone does not give the role access to Kubernetes. region is required with AwsOidcCredentials and does not default from AWS_REGION. This OIDC variant supports commercial AWS.

Azure AKS

auth = new k8s.AKSAuth {
  endpoint = "https://aks.example.invalid"
  certificateAuthority = "REPLACE_WITH_BASE64_PEM_CLUSTER_CA"
  credentials = new k8s.AzureOidcCredentials {
    tenantId = "11111111-1111-4111-8111-111111111111"
    clientId = "22222222-2222-4222-8222-222222222222"
  }
}

Configure an Entra federated identity credential for the exact installation subject and audience api://AzureADTokenExchange. The plugin requests an AKS access token, rather than an Azure Resource Manager token. Grant access through the cluster’s configured Azure RBAC or Kubernetes RBAC authorizer. Resolve the service principal’s object ID when creating its role assignment; clientId in Pkl identifies the application, not that object ID. This variant supports public Azure. Both endpoint and CA are mandatory with OIDC. The Kubernetes plugin does not fetch an admin or user kubeconfig in this mode. If a cloud resource does not expose the CA, have an administrator supply that public certificate from trusted cluster metadata. Do not copy the kubeconfig’s credentials into Pkl.

Google GKE

auth = new k8s.GKEAuth {
  endpoint = "https://gke.example.invalid"
  certificateAuthority = "REPLACE_WITH_BASE64_PEM_CLUSTER_CA"
  projectId = "example-project"
  location = "us-central1"
  clusterName = "application-cluster"
  credentials = new k8s.GcpOidcCredentials {
    workloadIdentityProvider = "//iam.googleapis.com/projects/123456789012/locations/global/workloadIdentityPools/formae/providers/installation"
  }
}

Configure the workload identity provider to trust the issuer, map google.subject to assertion.sub, and admit only the exact installation subject. Grant the resulting principal the required GKE and Kubernetes permissions. The provider path uses the project number. Direct federation is the default. To use service-account impersonation, add serviceAccountEmail = "formae-kubernetes@example-project.iam.gserviceaccount.com" inside GcpOidcCredentials. Grant the exact federated principal roles/iam.workloadIdentityUser on that service account, and grant the service account its own cluster access. Selecting this mode changes the identity seen by the cluster; it is not an automatic fallback.

Direct Kubernetes OIDC

This option needs no AWS, Azure, or GCP connection. Configure the Kubernetes API server to trust the formae issuer and a dedicated, stable audience:

auth = new k8s.OidcAuth {
  endpoint = "https://kubernetes.example.invalid"
  certificateAuthority = "REPLACE_WITH_BASE64_PEM_CLUSTER_CA"
  audience = "urn:formae:kubernetes:39c24d1d-3815-4817-9242-4032be46601b"
}

Generate a new UUID for your cluster and retain it; do not reuse the example. The audience must be urn:formae:kubernetes: followed by a canonical lowercase RFC 4122 UUID. The broker must allow that audience. For an API server using OIDC flags, the matching settings are:

--oidc-issuer-url=https://oidc.cloud.formae.ai
--oidc-client-id=urn:formae:kubernetes:YOUR-CLUSTER-UUID
--oidc-username-claim=sub
--oidc-username-prefix=formae:
--oidc-signing-algs=RS256

The API server must reach the issuer’s discovery and JWKS endpoints over trusted HTTPS. This is separate from the agent reaching the cluster. Bind Kubernetes RBAC to a User named formae:EXACT_INSTALLATION_SUBJECT, using the actual subject and the configured prefix. A valid token authenticates an identity; RBAC still decides what it can do.

Ordering and changes to existing targets

A Kubernetes target can reference the host cluster through resolvables without being nested under a cloud target. For example, use eksCluster.res.endpoint and eksCluster.res.certificateAuthorityData instead of the EKS literals above. Those references make the workload depend on the cluster’s metadata being available. They do not order separately configured access grants or guarantee their propagation. Establish those grants before applying workloads. Remove workloads while access remains available, before removing grants or the cluster.

Authentication is a create-only target setting. Changing it on an existing target can replace the target and recreate its managed resources across stacks. Use a new target for onboarding and review migration plans before changing an existing target’s authentication.

Helm permissions and long operations

Helm needs permission to manage its release Secrets and the resources in the chart. It also needs cluster-scoped permission to get the kube-system Namespace to identify the cluster before mutations and recovery. A RoleBinding limited to the workload namespace cannot grant that read. A narrowly scoped ClusterRole can use resources: ["namespaces"], resourceNames: ["kube-system"], and verbs: ["get"] in the core API group. Bind it to the same authenticated identity. Use a Helm timeoutSeconds of at least 300 with the default agent timing. Credential refresh is serviced during live operations and status polling; it depends on the agent and broker staying available. If the agent or plugin is killed, inspect the release and retry through formae’s recovery flow. The plugin’s complete EKS, AKS, GKE, and direct OIDC examples include target and workload definitions. These are also the examples available to AI assistants through the formae MCP.

Get started

Guides

Concepts

Reference

Kubernetes with installation OIDC

How it relates to a cloud connection

Prepare access first

Target configurations

AWS EKS

Azure AKS

Google GKE

Direct Kubernetes OIDC

Ordering and changes to existing targets

Helm permissions and long operations

​How it relates to a cloud connection

​Prepare access first

​Target configurations

​AWS EKS

​Azure AKS

​Google GKE

​Direct Kubernetes OIDC

​Ordering and changes to existing targets

​Helm permissions and long operations

How it relates to a cloud connection

Prepare access first

Target configurations

AWS EKS

Azure AKS

Google GKE

Direct Kubernetes OIDC

Ordering and changes to existing targets

Helm permissions and long operations