Skip to main content

What is the Kubernetes Operator?

The Formal Kubernetes Operator watches for custom resources in your cluster and automatically manages the corresponding Formal resources, listeners, native users, and policies via the Formal API. This removes the need to manually configure resources via Terraform or the Control Plane when your services already live in Kubernetes.
FormalNativeUser creates legacy Native Users, which are deprecated. See the migration guide.
The operator introduces the following Custom Resource Definitions (CRDs):
  • FormalResource: Declares a backend service (e.g., a PostgreSQL database) that should be registered as a Formal resource
  • FormalListener: Declares a listener on an existing Formal connector with routing rules that point to resources
  • FormalNativeUser: Declares a legacy Native User, with credentials sourced from a Kubernetes Secret
  • FormalNativeUserV3: Declares a Native User V3 on a resource that has nativeUsersV3Enabled: true
  • FormalNativeUserSelection: Chooses which Native User V3 a session connects as
  • FormalPolicy: Declares a Formal policy from Rego code
  • FormalConnectorHostname: Declares the hostname of an existing Formal connector, either Formal-Managed or with its TLS certificate sourced from a Kubernetes Secret
When you create, update, or delete these custom resources, the operator reconciles the desired state with the Formal Control Plane. Finalizers ensure that Formal-side resources are cleaned up when Kubernetes resources are deleted.

How It Works

The operator continuously watches for changes and keeps Formal in sync with your cluster state. Secret updates (e.g., rotated database credentials) are automatically propagated to the corresponding native users in Formal.

Prerequisites

  • A Kubernetes cluster (v1.28+)
  • A Formal API key, or an OIDC integration
  • An existing Formal connector (the operator manages listeners and resources, not connectors themselves)