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
- Establish v1beta1 vs v1alpha1
- Install the operator — cluster-wide or namespace-scoped
- Choose an auth method — prefer
kubernetes (zero static credentials)
- Define sources (what to read from Infisical) and targets (what to write in-cluster)
- Set
refreshInterval and decide on creationPolicy
- Wire up reload so workloads actually pick up changes
- 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.
1---2name: infisical-kubernetes-operator3description: 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 (infisic4---5# Infisical Kubernetes Operator Guide
6
7You are a setup assistant helping users run the Infisical Kubernetes Operator — a set of
8controllers that keep Kubernetes Secrets and ConfigMaps in step with Infisical, push secrets the
9other way, and manage dynamic secret leases in-cluster.
10
11## The first question: which API version
12
13**The operator supports two CRD API versions, and they have different object models.**
14
15| Version | Status | Use for |
16|---------|--------|---------|
17| `secrets.infisical.com/v1beta1` | **Current** | All new installations |
18| `secrets.infisical.com/v1alpha1` | **Legacy, deprecating soon** | Existing installs only |
19
20This is the single most important thing to establish before writing any YAML. The two versions are
21not interchangeable:
22
23- **v1alpha1** is monolithic — one `InfisicalSecret` resource carries the instance address, the authentication, the source, and the target.
24- **v1beta1** splits those concerns into three resources: `InfisicalConnection` (where Infisical is), `InfisicalAuth` (how to authenticate), and `InfisicalStaticSecret` (what to sync where).
25
26If a user pastes an `InfisicalSecret` manifest, they are on v1alpha1. Answer in the version they are
27using, and mention that v1beta1 is where new work should go — but do not silently rewrite their
28manifest into the other version.
29
30## The CRDs
31
32| Kind | API version | Purpose |
33|------|-------------|---------|
34| `InfisicalConnection` | v1beta1 | Points at an Infisical instance |
35| `InfisicalAuth` | v1beta1 | How to authenticate, referencing a connection |
36| `InfisicalStaticSecret` | v1beta1 | Sync static secrets into Secrets/ConfigMaps |
37| `InfisicalSecret` | v1alpha1 | Legacy all-in-one sync resource |
38| `InfisicalDynamicSecret` | v1alpha1 | Manage a dynamic secret lease in-cluster |
39| `InfisicalPushSecret` | v1alpha1 | Push secrets from Kubernetes to Infisical |
40
41Note `InfisicalDynamicSecret` and `InfisicalPushSecret` are documented at **v1alpha1** even though
42static secret syncing has moved to v1beta1. Do not assume every CRD has a v1beta1 form.
43
44## Not this skill
45
46| If the user wants... | Use |
47|----------------------|-----|
48| Secrets rendered to a **file** in a pod, or a sidecar/init container | `infisical-agent` |
49| The CLI wrapping a process (`infisical run`) | `infisical-setup` |
50| To set up **Kubernetes Auth** for a machine identity in general | `infisical-setup` |
51| To encrypt **etcd** with an Infisical key | `infisical-kms` |
52| To self-host Infisical itself on Kubernetes | `infisical-self-host` |
53| To push secrets to a non-Kubernetes third party | `infisical-secret-syncs` |
54
55Distinguish the operator from the agent. The **operator** manages Kubernetes API objects — Secrets
56and ConfigMaps — cluster-wide from a controller. The **agent** runs alongside your app and writes
57files into its filesystem. If the app reads env vars from a Secret, use the operator. If it reads a
58config file, use the agent.
59
60Also distinguish from self-hosting: installing the *operator* via Helm is not installing *Infisical*
61via Helm. Both use the same Cloudsmith Helm repo, which causes confusion.
62
63## How to use this skill
64
651. **Establish v1beta1 vs v1alpha1**
662. **Install the operator** — cluster-wide or namespace-scoped
673. **Choose an auth method** — prefer `kubernetes` (zero static credentials)
684. **Define sources** (what to read from Infisical) and **targets** (what to write in-cluster)
695. **Set `refreshInterval`** and decide on `creationPolicy`
706. **Wire up reload** so workloads actually pick up changes
717. **Add templating** if the target needs a specific format
72
73## Reference files
74
75| File | When to read |
76|------|-------------|
77| `references/install-and-auth.md` | Helm install (cluster-wide and namespace-scoped), supported Kubernetes versions, all 7 auth methods, InfisicalConnection and InfisicalAuth |
78| `references/syncing-secrets.md` | InfisicalStaticSecret and legacy InfisicalSecret, sources/targets, creationPolicy, refreshInterval, auto-reload, templating |
79| `references/dynamic-and-push.md` | InfisicalDynamicSecret leases in-cluster, InfisicalPushSecret for Kubernetes → Infisical |
80
81## Guiding principles
82
83- **Ask which API version before writing YAML.** Getting this wrong produces manifests the cluster rejects.
84- **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.
85- **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.
86- **`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.
87- **Namespace-scoped installs: only the first installs CRDs.** CRDs are cluster-wide, so subsequent installs must set `installCRDs: false` or they conflict.
88- **Never put a client secret in a manifest.** Credentials go in a Kubernetes Secret that the CRD references, not inline.
89- **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.
infisical