> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Automatically register in-cluster services as Formal resources

## What is the Kubernetes Operator?

The Formal Kubernetes Operator watches for custom resources in your cluster and automatically manages the corresponding Formal resources, listeners, and native users via the Formal API. This removes the need to manually configure resources via Terraform or the web console when your services already live in Kubernetes.

The operator introduces three 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 native user on a Formal resource, with credentials 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

```mermaid theme={null}
sequenceDiagram
    participant K8s as Kubernetes
    participant Op as Operator
    participant CP as Formal Control Plane

    K8s->>Op: FormalResource created
    Op->>CP: Create resource
    CP-->>Op: Resource ID
    Op->>K8s: Update status

    K8s->>Op: FormalListener created
    Op->>CP: Create listener + rules
    CP-->>Op: Listener ID
    Op->>K8s: Update status

    K8s->>Op: FormalResource deleted
    Op->>CP: Delete resource
    Op->>K8s: Remove finalizer
```

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
* An existing Formal connector (the operator manages listeners and resources, not connectors themselves)