Kubernetes

Formal streamlines access and control for any Kubernetes clusters by providing:

Single Sign-On (SSO) integration with providers like Okta
Granular role-based access controls with MFA support
Session recording for compliance
Automatic cluster discovery (for EKS)

Requirements

To connect to a Kubernetes cluster through the Connector, you need the following:

The Formal Endpoint running and authenticated. You can find more information on how to achieve this in the documentation of the Formal Endpoint.
At least one Kubernetes cluster linked to the Formal Connector as a Resource, with its Native User set. For AWS EKS clusters, set the Resource name to the cluster name.

The Formal Endpoint will automatically update your local kubeconfig file and change the current context.

Configuration

Resource

When creating a Kubernetes resource, use the Kubernetes API endpoint URL with port 443 as the target port. The Connector uses the resource name to identify which cluster to target when a user tries to access a cluster. How the Connector finds the upstream cluster depends on the Native User:

AWS IAM and AWS IAM Role look up the EKS cluster by the Resource name.
Kubeconfig and Kubeconfig Path select the kubeconfig context whose cluster server URL matches the Resource hostname and port. Context names are ignored, and exactly one context must match.
Azure IAM and GCP IAM connect to the Resource hostname and port directly.

Native Users

The Connector supports the following Native User credential types for Kubernetes:

AWS IAM uses the Connector’s ambient AWS identity.
AWS IAM Role assumes the specified AWS role ARN.
Azure IAM uses the Connector’s ambient Microsoft Entra identity.
GCP IAM uses the Connector’s ambient Google identity.
Kubeconfig Path reads a kubeconfig file from the Connector.
Kubeconfig uses an inline kubeconfig YAML document.

Terraform

For Kubernetes-specific credentials, configure one of the following Native Users. Kubeconfig paths and documents can be literal values or references to environment variables available to the Connector.

Kubeconfig Path

resource "formal_native_user_v3" "kubeconfig_path" {
  resource_id = formal_resource.cluster.id
  label       = "kubeconfig-path"

  kubernetes_path {
    kubeconfig_path {
      literal = "/etc/formal/kubeconfig"
    }
  }
}

Kubeconfig

resource "formal_native_user_v3" "kubeconfig_inline" {
  resource_id = formal_resource.cluster.id
  label       = "kubeconfig-inline"

  kubernetes_inline {
    kubeconfig {
      environment_variable = "KUBECONFIG_YAML"
    }
  }
}

See Select a default Native User for selection examples.

AWS IAM permissions

When using AWS IAM or AWS IAM Role, the Connector needs the following AWS permissions to fetch the upstream cluster configuration:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["eks:DescribeCluster", "sts:GetCallerIdentity"],
      "Resource": "*"
    }
  ]
}

If the Connector is deployed in an AWS EKS cluster, grant these permissions to the Connector pod’s IAM role with EKS Pod Identity:

Create an IAM role trusted by pods.eks.amazonaws.com
Attach the AWS IAM policy above to that role
Associate the role with the Connector service account via EKS Pod Identity
Use that service account on the Connector pod

These steps are detailed in the AWS documentation and demonstrated in our example Terraform deployment.

Upstream Kubernetes permissions

When connected to the target Kubernetes cluster, the Connector inherits the permissions defined by its token’s username and groups (e.g. the matching ClusterRoleBinding and ClusterRole). If the credentials have limited permissions, the Formal app will show the access logs correctly but users will see errors when attempting kubectl commands. For example:

$ kubectl get pods
E0526 10:28:09.839098   25809 memcache.go:265] couldn't get current server API group list: the server has asked for the
client to provide credentials
E0526 10:28:10.715348   25809 memcache.go:265] couldn't get current server API group list: the server has asked for the
client to provide credentials
E0526 10:28:11.805740   25809 memcache.go:265] couldn't get current server API group list: the server has asked for the
client to provide credentials
E0526 10:28:12.912758   25809 memcache.go:265] couldn't get current server API group list: the server has asked for the
client to provide credentials
E0526 10:28:13.788519   25809 memcache.go:265] couldn't get current server API group list: the server has asked for the
client to provide credentials
error: You must be logged in to the server (the server has asked for the client to provide credentials)

On the opposite, if the permissions are set correctly, users will be able to run kubectl commands according to the Connector identity on the Kubernetes cluster. For example, for a ClusterRole that allows reading pods but not nodes:

$ kubectl get pods
No resources found in default namespace.
$ kubectl get nodes
Error from server (Forbidden): nodes is forbidden: User "arn:aws:sts::123456789012:assumed-role/formal-connector-20240101000000000000000001/1234567890123456789" cannot list resource "nodes" in API group "" at the cluster scope

As seen in the last error of the previous example, the Connector identity is used for all commands. If you want the end user identity to propagate, you should use impersonation (recommended) or synchronize end users and native users.

Upstream Kubernetes permissions (AWS EKS)

If your target Kubernetes resource is an AWS EKS cluster, you need to:

Allow your Connector role to connect to the EKS cluster with an Access Entry Configuration
Define its permissions with an Access Entry Policy Association that links your previously created Pod Identity IAM role with the cluster access policy of your choice (e.g. arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy).

Example Terraform deployment

For a complete example of deploying the Formal Connector in an EKS cluster that controls access to that cluster, see our example Terraform configuration. This example demonstrates:

Deploying the Formal Connector on AWS EKS
Setting up AWS IAM roles and policies for EKS API access
Configuring the Kubernetes cluster access permissions for the Connector

Impersonation

User impersonation provides two key benefits:

Improved audit logs: Actions in Kubernetes logs are attributed to individual users rather than showing all Formal-mediated actions under a single service account.
Granular access control: Users’ permissions are restricted to match what they would have when connecting directly to the cluster.

For more information about user impersonation, refer to the Kubernetes documentation.

Kubernetes RBAC

To allow user impersonation, the target Kubernetes cluster must have a specific RBAC configuration and allow the impersonate verb. While the cluster-admin role includes impersonation permissions by default, custom roles require explicit configuration. Here is an example ClusterRole and ClusterRoleBinding that will allow a Connector to impersonate end users:

ClusterRole
ClusterRoleBinding

ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations:
    rbac.authorization.kubernetes.io/autoupdate: "true"
  labels:
  name: impersonate
rules:
  - apiGroups:
      - ""
    resources:
      - "*"
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - extensions
    resources:
      - "*"
    verbs:
      - get
      - list
      - watch
  - apiGroups:
      - apps
    resources:
      - "*"
    verbs:
      - get
      - list
      - watch
  - apiGroups: # Ability to impersonate and review your own access
      - ""
    resources:
      - users
      - groups
    verbs:
      - impersonate
  - apiGroups:
      - "authorization.k8s.io"
    resources:
      - selfsubjectaccessreviews
    verbs:
      - create

ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: formal
subjects:
- kind: Group
  name: formal-connector # Name of the Connector group
  apiGroup: rbac.authorization.k8s.io
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: impersonate # Name of the ClusterRole you want the Connector to use

Formal policy

The Connector decides whether to impersonate users based on policies. This policy will grant the calling user access to resources defined by the groups in input.user.groups rather than the access level defined by the native user.

package formal.v2

import future.keywords.if

session := { "action": "impersonate", "user": input.user.username, "groups": input.user.groups } if {
  input.datastore.technology == "kubernetes"
}

When using impersonation, the Formal Connector adds two headers to the request made:

Impersonate-User: The user specified in the policy under user.
Impersonate-Group: The list of groups in the policy under groups. If using RBAC, it should match the groups used in your Kubernetes cluster.

Policy Evaluation

Formal supports the following policy evaluation stages for Kubernetes:

Session: Evaluate and enforce policies on every Kubernetes API request. input.kubernetes describes that request.

Kubernetes Input

The Connector populates the input.kubernetes object for policy evaluation. See the full reference in Policy Evaluation.

Field	Description	Example
`group`	API group (empty for core resources)	`apps`
`group_version`	API version	`v1`
`namespace`	Namespace (empty for cluster-scoped resources)	`default`
`kind`	Resource kind	`pods`
`name`	Resource name (empty for list/collection operations)	`my-pod`
`subresource`	Subresource	`exec`
`verb`	API verb, or lower-cased HTTP method for non-resource paths	`get`, `list`, `create`

Other policies

Additionally, you can apply access restrictions to Kubernetes Resources, similar to any other Resource. This includes the implementation of two additional filters, among others:

Kind: allow or block access to a specific Kubernetes Kind (e.g. secret)
Namespace: allow or block access to a specific Kubernetes Namespace

MFA for `kubectl exec`

This policy requires users to use MFA to run kubectl exec.

package formal.v2

import future.keywords.if

session := { "action": "mfa" } if {
  input.kubernetes.subresource == "exec"
}

Block `kube-*` namespaces

The following policy blocks every query to the Connector for namespaces that start with kube-.

package formal.v2

import future.keywords.if

session := { "action": "block", "type": "block_with_formal_message" } if {
  startswith(input.kubernetes.namespace, "kube-")
}

Recordings

The Formal Connector records kubectl exec and kubectl attach sessions. Other requests, including kubectl port-forward, are logged but not recorded. The session recordings can be accessed and reviewed in the Sessions application.

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Requirements

Configuration

Resource

Native Users

Terraform

Kubeconfig Path

Kubeconfig

AWS IAM permissions

Upstream Kubernetes permissions

Upstream Kubernetes permissions (AWS EKS)

Example Terraform deployment

Impersonation

Kubernetes RBAC

Formal policy

Policy Evaluation

Kubernetes Input

Other policies

MFA for `kubectl exec`

Block `kube-*` namespaces

Recordings

​Requirements

​Configuration

​Resource

​Native Users

​Terraform

Kubeconfig Path

Kubeconfig

​AWS IAM permissions

​Upstream Kubernetes permissions

​Upstream Kubernetes permissions (AWS EKS)

​Example Terraform deployment

​Impersonation

​Kubernetes RBAC

​Formal policy

​Policy Evaluation

​Kubernetes Input

​Other policies

​MFA for kubectl exec

​Block kube-* namespaces

​Recordings

Requirements

Configuration

Resource

Native Users

Terraform

AWS IAM permissions

Upstream Kubernetes permissions

Upstream Kubernetes permissions (AWS EKS)

Example Terraform deployment

Impersonation

Kubernetes RBAC

Formal policy

Policy Evaluation

Kubernetes Input

Other policies

MFA for `kubectl exec`

Block `kube-*` namespaces

Recordings