Prerequisites¶

Everything that must exist in your infrastructure before you install the tatara operator. Work through each section from top to bottom; the deploy runner and operator installation steps assume all items here are satisfied.

Summary¶

Prerequisite stack¶

The diagram below shows how the prerequisites compose. The operator sits at the top; everything below is a dependency that must be healthy before the first helmfile apply.

graph TD
    K8S["<b>Kubernetes 1.27+</b><br/>nginx Ingress &middot; Default StorageClass &middot; metrics-server"]
    DS["<b>Data Services</b><br/>CloudNativePG operator &middot; Neo4j &middot; S3 (optional)"]
    REG["<b>OCI Registry</b><br/>component images &middot; Helm charts &middot; regcred pull secret"]
    EXT["<b>External APIs</b><br/>Keycloak OIDC &middot; Anthropic &middot; OpenAI"]
    SCM["<b>SCM Provider</b><br/>GitHub / GitLab &middot; bot account &middot; PAT &middot; webhook secret"]
    ARC["<b>Deploy Runner</b><br/>GitHub Actions ARC &middot; cluster-admin SA &middot; GPG key"]

    K8S --> DS
    K8S --> ARC
    DS --> OP
    REG --> OP
    EXT --> OP
    SCM --> OP
    ARC -->|"helmfile apply"| OP["<b>tatara-operator</b>"]

1. Cluster¶

Kubernetes¶

tatara requires Kubernetes 1.27 or later. The operator runs its cron activities (issueScan, mrScan, brainstorm, per-repo re-ingest) in-process via a robfig/cron scheduler, not as batch/v1 CronJob objects; the only batch objects it creates are batch/v1 Jobs for repository ingest. It uses leader election via coordination.k8s.io/v1 leases and server-side apply for CRD management. The 1.27 floor is set by the CRD and apply machinery, not by any CronJob dependency.

The operator itself is lightweight: 100m CPU request, 128 Mi memory request, 256 Mi memory limit. Agent pods are spawned on demand; size your node pool to accommodate the expected concurrency (Project.spec.maxConcurrentTasks, default 3) at 250m CPU / 512 Mi memory each, plus LightRAG and Neo4j per enrolled Project.

nginx Ingress controller¶

The operator registers one webhook endpoint (for incoming SCM events) and manages one Ingress per enrolled Project for its memory stack. Both use nginx-specific rewrite annotations; the chart exposes ingressClassName and ingressRewriteTarget for customization, but nginx is the tested and supported controller.

The webhook Ingress must be publicly reachable from your SCM provider. Set externalWebhookBase in your helmfile values to the fully-qualified base URL including the /operator/webhooks path prefix, for example https://tatara.example.com/operator/webhooks. The operator appends /<projectName> for per-project webhook registration.

Default StorageClass (ReadWriteOnce)¶

Every enrolled Project provisions two PersistentVolumeClaims via the default StorageClass:

• CNPG Postgres: 10 Gi per replica (default 1 replica; see CNPG section below).
• Neo4j graph store: 10 Gi.

Plan for at least 20 Gi free capacity per Project you intend to enroll. ReadWriteOnce access mode is sufficient; ReadWriteMany is not required unless you share a cluster-level BuildKit cache volume across CI runners.

Both values are configurable per Project via spec.memory.pgStorage and spec.memory.neo4jStorage.

metrics-server (optional)¶

metrics-server is not a hard dependency. The operator ships no HorizontalPodAutoscaler, and the kube-scheduler places pods on their declared CPU/memory requests, not on live metrics, so tatara reconciles and schedules correctly without it. Install it if you want kubectl top for capacity debugging or intend to add your own HPA/VPA to the memory stack. It plays no role in scheduling, resource quotas, or admission.

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

2. Data services¶

CloudNativePG (CNPG) operator¶

The tatara operator spawns a CNPG Cluster resource for each enrolled Project. The CNPG operator must be installed cluster-wide before any Project is created.

Install with Helm:

helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg cnpg/cloudnative-pg \
  --namespace cnpg-system --create-namespace

Each Project gets one Postgres cluster:

Neo4j¶

The operator runs no Helm at reconcile time. For each Project it builds Neo4j directly as native Kubernetes objects: a single-replica community-edition StatefulSet plus a ClusterIP Service, both named mem-<project>-neo4j. There is no Neo4j Helm chart and no subchart. It serves as the LightRAG graph store.

Neo4j is memory-hungry. Allow at least 2 Gi of node memory headroom per Project beyond Postgres and LightRAG footprints. Neo4j page-cache poisoning after Ceph OSD restarts is a known failure mode; a pod restart clears it. The graph is a rebuildable projection: if the StatefulSet is lost, a full re-ingest of every enrolled repository reconstructs it from the source repos and the CNPG-backed document store.

S3-compatible object store (optional, recommended)¶

Conversation transcripts are stored in S3 so agent sessions resume across pod restarts. Without it, every new pod begins a fresh conversation.

Any S3-compatible backend works: AWS S3, Ceph RGW (Rook-Ceph OBC), or MinIO.

Required configuration in your helmfile secrets overlay:

s3Endpoint: "http://rook-ceph-rgw-ceph-objectstore.rook-ceph.svc:8080"  # omit for AWS
s3Bucket: "tatara-conversations"
s3Region: "us-east-1"
s3ForcePathStyle: true   # required for Ceph RGW / MinIO
s3SecretName: "tatara-s3-credentials"  # Secret with AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY

Conversation objects are retained for s3ConversationRetentionHours (default 72 h) after the associated task batch goes terminal, then reaped.

3. Registry¶

Tatara component images and Helm charts are distributed via an OCI registry. The reference deployment uses Harbor at harbor.szymonrichert.pl, but any OCI-compatible registry works if you mirror or rebuild the images.

Under semver push-CD the release pipeline publishes images at :vX.Y.Z and charts at the bare X.Y.Z (the legacy 0.0.0-g<shortSHA> scheme is retired). The pipeline propagates the new version into the tatara-helmfile pins automatically; you rarely hand-edit them. See Installing the Operator, section 6 for the full flow.

imagePullSecret¶

Create a regcred Secret in the tatara namespace with registry pull credentials:

kubectl create secret docker-registry regcred \
  --namespace tatara \
  --docker-server=<registry> \
  --docker-username=<username> \
  --docker-password=<password>

The tatara-helmfile bucket applies this secret cluster-wide via values/common.yaml. The operator also injects it into every spawned workload (Neo4j StatefulSet, LightRAG Deployment, tatara-memory Deployment, CNPG Cluster) via the imagePullSecret values key.

4. Identity (Keycloak)¶

All tatara APIs are OIDC-gated. You need a Keycloak realm with five clients. The realm name is arbitrary; you supply the issuer URL as oidcIssuer in the operator values. The canonical client inventory (IDs, types, audiences) is documented in Identity & OIDC.

OIDC clients¶

OIDC configuration in the operator¶

Set the following in your helmfile values:

oidcIssuer: "https://keycloak.example.com/realms/your-realm"
oidcAudience: "tatara-operator"
operatorOidcClientId: "tatara-operator"

And in the SOPS-encrypted secrets overlay:

operatorOidcClientSecret: "<client-secret-for-tatara-operator>"
cliOidcClientId: "tatara-cli"
cliOidcClientSecret: ""   # empty for public clients

5. Deploy runner (GitHub Actions ARC)¶

tatara is deployed exclusively through GitOps: the tatara-helmfile repository applies releases on merge to main via a GitHub Actions workflow running on an in-cluster ARC (Actions Runner Controller) runner. You need this runner infrastructure before you can run helmfile apply.

ARC scale set¶

Install the ARC controller and create a scale set named arc-runner-tatara-helmfile in your cluster. The runner pod runs helmfile apply using its in-cluster pod identity; no KUBECONFIG is mounted.

# Install ARC controller (once per cluster)
helm upgrade --install arc \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller \
  --namespace arc-systems --create-namespace

# Create the tatara-helmfile scale set
helm upgrade --install arc-runner-tatara-helmfile \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set \
  --namespace tatara \
  --set githubConfigUrl="https://github.com/your-org/tatara-helmfile" \
  --set githubConfigSecret.github_token="<PAT or app install token>"

ServiceAccount and RBAC¶

Create a ServiceAccount with a cluster-admin ClusterRoleBinding. This SA is bound to the runner pod and is the single highest-privilege element in the platform. Keep the tatara-helmfile repository private and restrict write access to bots and maintainers.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: tatara-helmfile-deployer
  namespace: tatara
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: tatara-helmfile-deployer
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
  - kind: ServiceAccount
    name: tatara-helmfile-deployer
    namespace: tatara

GitHub Actions secrets¶

The tatara-helmfile GitHub Actions workflows require three repository secrets:

The GPG key fingerprint must match the .sops.yaml in your tatara-helmfile repository. Generate a key pair, export the private key, base64-encode it, and store it in the secret:

gpg --gen-key
gpg --export-secret-keys --armor <fingerprint> | base64 | pbcopy

Add the public key fingerprint to .sops.yaml:

creation_rules:
  - pgp: "<YOUR_KEY_FINGERPRINT>"

6. SCM¶

Bot account¶

Create a dedicated SCM account separate from any human identity. The bot account is the author of all agent-generated issues, comments, and pull requests. tatara uses the bot identity as an approval gate: the operator reacts only to issues and comments authored by the bot, a maintainer, or an account on the reporterLogins allowlist (Project.spec.scm.reporterLogins).

Using a personal account as the bot breaks this security boundary and exposes your infrastructure to prompt-injection attacks via third-party issue content.

Personal Access Token (PAT)¶

The operator only reads and writes issues, comments, PRs, branches, commit statuses, and org membership. It never creates or manages webhooks (the SCM clients only verify inbound payloads), so no webhook-admin scope is needed. Grant the bot the minimum that covers those API calls. This is the authoritative, least-privilege scope set; Installing the Operator renders the same Secret.

Store the PAT in a SOPS-encrypted Secret and reference it via scmSecretName in your operator values. The Secret must contain key token (the PAT) and key webhookSecret (see below).

Webhook secret¶

Generate a random webhook secret (32+ bytes):

openssl rand -hex 32

The operator does not register webhooks. It only HMAC-SHA256-validates inbound payloads against this secret. You configure the webhook (payload URL, secret, event set) manually, once per enrolled repository or org, in your SCM provider's UI (see Your First Project, section 6). Use this same value as the webhook secret there. Store it in the same Secret as the PAT under key webhookSecret.

Claude Code OAuth token (Claude subscription)¶

Agent pods run Claude Code, which the operator drives with a Claude subscription OAuth token, not a metered console.anthropic.com API key. The operator injects it into every agent pod as env CLAUDE_CODE_OAUTH_TOKEN, sourced from the oauth-token key of the Anthropic Secret. The chart renders that Secret from the anthropicOauthToken value. This is deliberate: the claudeSubscription token-budget mode depends on the credential being a subscription (setup/OAuth) token, which meters against a subscription window rather than per-token API billing.

Generate the token from an authenticated Claude Code CLI (its setup-token / OAuth login flow), not from the Anthropic console. The default model is unset: spec.agent.model has no built-in default, so set it explicitly per Project (the live fleet runs claude-opus-4-8).

Plan capacity for Project.spec.maxConcurrentTasks simultaneous Claude Code sessions per enrolled Project. Each active Task holds one session for the duration of the task, which can span multiple turns over hours.

Store the token under key oauth-token in a Secret and reference it via anthropicSecretName (chart value anthropicOauthToken).

OpenAI API key¶

OpenAI is a hard dependency of every Project's memory stack, independent of semanticIngest. Each Project's LightRAG is wired to LLM_BINDING=openai and EMBEDDING_BINDING=openai (text-embedding-3-small); without the key, LightRAG document processing fails with KeyError 'OPENAI_API_KEY' and the memory graph never populates.

semanticIngest is a separate, per-repository knob. When true (default), the repo ingester runs an additional extraction pass through OpenAI (gpt-4o-mini by default, via SEMANTIC_MODEL) to emit richer entities and relationships. Setting it false removes only that extra pass; it does not remove the LightRAG OpenAI requirement.

Store the key in a Secret and reference it via openaiSecretName. The same Secret is consumed by the per-Project LightRAG Deployment.

Authoritative credential-to-env contract¶

To avoid re-deriving names, this is the single source of truth for the LLM and CLI credentials. Both this page and Installing the Operator render these exact keys.

Next steps¶

Once all prerequisites are satisfied, proceed to Installing the Operator to deploy the tatara-operator Helm release and configure your first Project.