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 |
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) |
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.
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 |
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 |
