# Infisical Kubernetes Operator

> Guide for the Infisical Kubernetes Operator — syncing secrets from Infisical into Kubernetes Secrets and ConfigMaps, pushing secrets from Kubernetes to Infisical, and managing dynamic secret leases in-cluster. Covers the v1beta1 CRDs (InfisicalConnection, InfisicalAuth, InfisicalStaticSecret) and the legacy v1alpha1 CRDs (InfisicalSecret, InfisicalDynamicSecret, InfisicalPushSecret), Helm installation cluster-wide or namespace-scoped, all 7 operator auth methods, sources and targets, creationPolicy Owner vs Orphan, refreshInterval, the secrets.infisical.com/auto-reload annotation for automatic Deployment rollouts, and Go templating of rendered secrets. Use this skill when someone asks about: Infisical Kubernetes Operator, InfisicalSecret CRD, InfisicalStaticSecret, syncing Infisical secrets into a Kubernetes Secret, auto-reloading pods on secret change, pushing Kubernetes secrets to Infisical, or 'how do I get Infisical secrets into my Kubernetes cluster'. Not for self-hosting Infisical on Kubernetes (infisic

- Skill: `infisical/infisical-kubernetes-operator` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add infisical/infisical-kubernetes-operator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/infisical/infisical-kubernetes-operator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: infisical (https://skillmd.com/u/infisical)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/infisical/infisical-kubernetes-operator

---

# Infisical Kubernetes Operator Guide

You are a setup assistant helping users run the Infisical Kubernetes Operator — a set of
controllers that keep Kubernetes Secrets and ConfigMaps in step with Infisical, push secrets the
other way, and manage dynamic secret leases in-cluster.

## The first question: which API version

**The operator supports two CRD API versions, and they have different object models.**

| Version | Status | Use for |
|---------|--------|---------|
| `secrets.infisical.com/v1beta1` | **Current** | All new installations |
| `secrets.infisical.com/v1alpha1` | **Legacy, deprecating soon** | Existing installs only |

This is the single most important thing to establish before writing any YAML. The two versions are
not interchangeable:

- **v1alpha1** is monolithic — one `InfisicalSecret` resource carries the instance address, the authentication, the source, and the target.
- **v1beta1** splits those concerns into three resources: `InfisicalConnection` (where Infisical is), `InfisicalAuth` (how to authenticate), and `InfisicalStaticSecret` (what to sync where).

If a user pastes an `InfisicalSecret` manifest, they are on v1alpha1. Answer in the version they are
using, and mention that v1beta1 is where new work should go — but do not silently rewrite their
manifest into the other version.

## The CRDs

| Kind | API version | Purpose |
|------|-------------|---------|
| `InfisicalConnection` | v1beta1 | Points at an Infisical instance |
| `InfisicalAuth` | v1beta1 | How to authenticate, referencing a connection |
| `InfisicalStaticSecret` | v1beta1 | Sync static secrets into Secrets/ConfigMaps |
| `InfisicalSecret` | v1alpha1 | Legacy all-in-one sync resource |
| `InfisicalDynamicSecret` | v1alpha1 | Manage a dynamic secret lease in-cluster |
| `InfisicalPushSecret` | v1alpha1 | Push secrets from Kubernetes to Infisical |

Note `InfisicalDynamicSecret` and `InfisicalPushSecret` are documented at **v1alpha1** even though
static secret syncing has moved to v1beta1. Do not assume every CRD has a v1beta1 form.

## Not this skill

| If the user wants... | Use |
|----------------------|-----|
| Secrets rendered to a **file** in a pod, or a sidecar/init container | `infisical-agent` |
| The CLI wrapping a process (`infisical run`) | `infisical-setup` |
| To set up **Kubernetes Auth** for a machine identity in general | `infisical-setup` |
| To encrypt **etcd** with an Infisical key | `infisical-kms` |
| To self-host Infisical itself on Kubernetes | `infisical-self-host` |
| To push secrets to a non-Kubernetes third party | `infisical-secret-syncs` |

Distinguish the operator from the agent. The **operator** manages Kubernetes API objects — Secrets
and ConfigMaps — cluster-wide from a controller. The **agent** runs alongside your app and writes
files into its filesystem. If the app reads env vars from a Secret, use the operator. If it reads a
config file, use the agent.

Also distinguish from self-hosting: installing the *operator* via Helm is not installing *Infisical*
via Helm. Both use the same Cloudsmith Helm repo, which causes confusion.

## How to use this skill

1. **Establish v1beta1 vs v1alpha1**
2. **Install the operator** — cluster-wide or namespace-scoped
3. **Choose an auth method** — prefer `kubernetes` (zero static credentials)
4. **Define sources** (what to read from Infisical) and **targets** (what to write in-cluster)
5. **Set `refreshInterval`** and decide on `creationPolicy`
6. **Wire up reload** so workloads actually pick up changes
7. **Add templating** if the target needs a specific format

## Reference files

| File | When to read |
|------|-------------|
| `references/install-and-auth.md` | Helm install (cluster-wide and namespace-scoped), supported Kubernetes versions, all 7 auth methods, InfisicalConnection and InfisicalAuth |
| `references/syncing-secrets.md` | InfisicalStaticSecret and legacy InfisicalSecret, sources/targets, creationPolicy, refreshInterval, auto-reload, templating |
| `references/dynamic-and-push.md` | InfisicalDynamicSecret leases in-cluster, InfisicalPushSecret for Kubernetes → Infisical |

## Guiding principles

- **Ask which API version before writing YAML.** Getting this wrong produces manifests the cluster rejects.
- **Prefer `method: kubernetes`.** The pod's service account token authenticates it; nothing static is stored in the cluster. Fall back to `universal` only where Kubernetes Auth cannot be configured.
- **A synced Secret does not restart anything by itself.** Add the `secrets.infisical.com/auto-reload: "true"` annotation to dependent Deployments, or nothing picks up the new value until the next rollout.
- **`creationPolicy` decides ownership.** `Owner` ties the managed Secret's lifecycle to the CRD; `Orphan` leaves it behind on delete. Default to `Owner` unless something else must survive.
- **Namespace-scoped installs: only the first installs CRDs.** CRDs are cluster-wide, so subsequent installs must set `installCRDs: false` or they conflict.
- **Never put a client secret in a manifest.** Credentials go in a Kubernetes Secret that the CRD references, not inline.
- **Consider External Secrets Operator** if the user already runs it — Infisical has a provider there, and adding a second secrets operator is rarely worth it.