Custom Resources

FormalResource

Registers an in-cluster service as a Formal resource.

apiVersion: joinformal.com/v1
kind: FormalResource
metadata:
  name: orders-database
spec:
  technology: postgres
  hostname: postgres.default.svc.cluster.local
  port: 5432

Spec

Field	Type	Required	Description
`technology`	string	Yes	Protocol type (`postgres`, `mysql`, `mongodb`, `http`, etc.)
`hostname`	string	Yes	In-cluster hostname of the backend service
`port`	int	Yes	Port of the backend service
`spaceId`	string	No	ID of the Space to assign the resource to
`tls`	object	No	TLS configuration for the backend connection

TLS Configuration

spec:
  tls:
    mode: verify-full
    minVersion: "TLSv1.2"
    caSecretRef:
      name: my-ca-secret
      key: ca.crt

Field	Type	Required	Description
`tls.mode`	string	Yes	`disable`, `insecure-skip-verify`, `insecure-verify-ca-only` (verifies the chain but not the hostname), or `verify-full`
`tls.minVersion`	string	No	Minimum TLS version: `TLSv1.2` or `TLSv1.3`
`tls.caSecretRef.name`	string	No	Kubernetes Secret containing the CA certificate
`tls.caSecretRef.key`	string	No	Key within the Secret

tls.mode is required whenever you set tls.

FormalListener

Creates a listener on an existing Formal connector with routing rules.

apiVersion: joinformal.com/v1
kind: FormalListener
metadata:
  name: postgres
spec:
  connectorId: connector_abc123
  name: postgres
  port: 5432
  rules:
    - type: technology
      technology: postgres

Spec

Field	Type	Required	Description
`connectorId`	string	Yes	ID of the Formal connector
`name`	string	Yes	Display name of the listener
`port`	int	Yes	Port the listener binds to on the connector
`rules`	list	No	Routing rules for the listener

Rules

Each rule routes traffic to one or more resources:

Field	Type	Required	Description
`type`	string	Yes	`resource` or `technology`
`resourceRef`	string	No	Name of a FormalResource in the same namespace (for `resource` rules)
`technology`	string	No	Technology name (for `technology` rules)

When using resource rules, the operator resolves the resourceRef to the Formal resource ID automatically.

The connector itself is not managed by the operator. Create the connector via Terraform or the Control Plane, then reference its ID in FormalListener resources.

FormalNativeUser

Creates a legacy Native User on a Formal Resource. Credentials come from a Kubernetes Secret.

This CRD supports only legacy Native Users. See Legacy Native Users for the selection and identity-link model used here.

apiVersion: joinformal.com/v1
kind: FormalNativeUser
metadata:
  name: orders-database-default
spec:
  resourceRef: orders-database
  type: basic
  useAsDefault: true
  secretRef:
    name: postgres-credentials
    keys:
      username: username
      password: password

Spec

Field	Type	Required	Description
`resourceRef`	string	Yes	Name of a FormalResource in the same namespace
`type`	string	Yes	See supported types below
`useAsDefault`	bool	No	Whether this is the default native user for the resource
`identityLinks`	list	No	See identity links below

The operator watches referenced Secrets. When a Secret is updated, the operator automatically propagates the new credentials to Formal.

Supported Types

`basic`

Username and password credentials, sourced from a Kubernetes Secret.

Field	Type	Required	Description
`secretRef.name`	string	Yes	Name of the Kubernetes Secret
`secretRef.keys.username`	string	Yes	Key in the Secret containing the username
`secretRef.keys.password`	string	Yes	Key in the Secret containing the password

`iam`

Cloud IAM authentication.

Field	Type	Required	Description
`iam.cloudProvider`	string	Yes	Cloud provider (`aws` or `gcp`)
`iam.username`	string	Yes	IAM username for authentication
`iam.role`	string	No	IAM role ARN or identifier (if omitted, uses the environment’s ambient IAM credentials)

`kubernetes`

Kubernetes authentication via kubeconfig.

Field	Type	Required	Description
`kubernetes.kubeconfigEnv`	string	Yes	Environment variable name containing kubeconfig

`ssh_key`

SSH key authentication, with the private key sourced from a Kubernetes Secret.

Field	Type	Required	Description
`sshKey.username`	string	Yes	SSH username
`sshKey.secretRef.name`	string	Yes	Secret containing the private key
`sshKey.secretRef.key`	string	Yes	Key within the Secret

`snowflake_key`

Snowflake key-pair authentication, with the private key sourced from a Kubernetes Secret.

Field	Type	Required	Description
`snowflakeKey.username`	string	Yes	Snowflake username
`snowflakeKey.secretRef.name`	string	Yes	Secret containing the private key
`snowflakeKey.secretRef.key`	string	Yes	Key within the Secret

`http_basic`

HTTP Basic authentication, with credentials sourced from a Kubernetes Secret.

Field	Type	Required	Description
`httpBasic.header`	string	Yes	HTTP header name (e.g., `Authorization`)
`httpBasic.secretRef.name`	string	Yes	Name of the Kubernetes Secret
`httpBasic.secretRef.keys.username`	string	Yes	Key in the Secret containing the username
`httpBasic.secretRef.keys.password`	string	Yes	Key in the Secret containing the password

`http_bearer`

HTTP Bearer token authentication, with the token sourced from a Kubernetes Secret.

Field	Type	Required	Description
`httpBearer.header`	string	Yes	HTTP header name (e.g., `Authorization`)
`httpBearer.secretRef.name`	string	Yes	Secret containing the token
`httpBearer.secretRef.key`	string	Yes	Key within the Secret

`http_api_key`

HTTP API key authentication, with the value sourced from a Kubernetes Secret.

Field	Type	Required	Description
`httpApiKey.location`	string	Yes	`header` or `query_parameter`
`httpApiKey.key`	string	Yes	Header or query parameter name
`httpApiKey.secretRef.name`	string	Yes	Secret containing the API key value
`httpApiKey.secretRef.key`	string	Yes	Key within the Secret

Identity Links

identityLinks binds Formal identities to the native user. Each entry is resolved by name against the Formal control plane:

Field	Type	Required	Description
`type`	string	Yes	`user`, `group`, or `resource_hostname`
`name`	string	Yes	Name of the identity to link (see resolution rules below)
`terminationProtection`	bool	No	If `true`, the link cannot be deleted

Resolution rules per type:

group: matched against Group.name
user: matched against User.db_username
resource_hostname: matched against ResourceHostname.name within the parent resource

Links not present in identityLinks on reconcile are removed, so the spec is the source of truth.

spec:
  resourceRef: orders-database
  type: basic
  secretRef:
    name: postgres-credentials
    keys:
      username: username
      password: password
  identityLinks:
    - type: group
      name: db-readers
    - type: group
      name: orders-admins
      terminationProtection: true

FormalPolicy

Creates and manages a Formal policy from Rego code.

apiVersion: joinformal.com/v1
kind: FormalPolicy
metadata:
  name: data-eng-postgres-read
spec:
  description: Read-only Postgres access for the data-eng team
  status: active
  terminationProtection: false
  code: |
    package formal.v2

    import future.keywords.if
    import future.keywords.in

    session := {
      "action": "block",
      "type": "block_with_formal_message",
      "reason": "Access restricted to the data-eng team"
    } if {
      input.resource.technology == "postgres"
      input.resource.tags["team"] == "data-eng"
      not "data-eng" in input.user.groups
    }

    request := {
      "action": "block",
      "type": "block_with_formal_message",
      "reason": "Read-only access for the data-eng team"
    } if {
      input.resource.tags["team"] == "data-eng"
      input.query.statement_type != "SELECT"
    }

Spec

Field	Type	Required	Description
`description`	string	Yes	Description shown for the policy
`status`	string	Yes	Policy mode: `draft`, `dry-run`, or `active`
`code`	string	Yes	Policy logic written in Rego
`terminationProtection`	bool	No	Prevents policy deletion when `true`; defaults to `false`

The operator uses metadata.name as the Formal policy name. It synchronizes spec changes and stores the Formal policy ID in status.policyId. If the policy is deleted in Formal, the operator recreates it during reconciliation. Deleting the custom resource also deletes the policy from Formal. Disable terminationProtection before deleting a protected policy. Verify:

kubectl get formalpolicy data-eng-postgres-read \
  -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}{"\n"}'
# Expected: True

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

FormalResource

Spec

TLS Configuration

FormalListener

Spec

Rules

FormalNativeUser

Spec

Supported Types

`basic`

`iam`

`kubernetes`

`ssh_key`

`snowflake_key`

`http_basic`

`http_bearer`

`http_api_key`

Identity Links

FormalPolicy

Spec

​FormalResource

​Spec

​TLS Configuration

​FormalListener

​Spec

​Rules

​FormalNativeUser

​Spec

​Supported Types

​basic

​iam

​kubernetes

​ssh_key

​snowflake_key

​http_basic

​http_bearer

​http_api_key

​Identity Links

​FormalPolicy

​Spec

FormalResource

Spec

TLS Configuration

FormalListener

Spec

Rules

FormalNativeUser

Spec

Supported Types

`basic`

`iam`

`kubernetes`

`ssh_key`

`snowflake_key`

`http_basic`

`http_bearer`

`http_api_key`

Identity Links

FormalPolicy

Spec