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	No	`disable`, `verify-ca`, or `verify-full` (default)
`tls.minVersion`	string	No	Minimum TLS version (e.g., `TLSv1.2`)
`tls.caSecretRef.name`	string	No	Kubernetes Secret containing the CA certificate
`tls.caSecretRef.key`	string	No	Key within the Secret

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 web console, then reference its ID in FormalListener resources.

FormalNativeUser

Creates a native user on a Formal resource, with credentials sourced from a Kubernetes Secret.

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

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Example Use Cases

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

​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

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