Skip to main content
In this guide, you’ll:
  • Install the Infisical Kubernetes Operator and set up a Machine Identity with Kubernetes Auth.
  • Connect the operator to Infisical with the InfisicalConnection and InfisicalAuth CRDs.
  • Pull a secret from Infisical into your cluster with the InfisicalStaticSecret CRD and consume it from a demo app.
  • Push a Kubernetes Secret back to Infisical with the InfisicalStaticSecretPush CRD.
  • Generate a dynamic database credential in your cluster with the InfisicalDynamicSecret CRD.
This guide’s pull and push paths use the operator’s v1beta1 decoupled model: an InfisicalConnection says where your Infisical instance is, an InfisicalAuth says how the operator authenticates, and an InfisicalStaticSecret or InfisicalStaticSecretPush says which secrets sync where.Dynamic secrets have no v1beta1 equivalent yet, so that section uses the v1alpha1 InfisicalDynamicSecret CRD, which carries its own inline authentication block. See the Kubernetes Operator overview for the other CRDs and authentication methods.

Prerequisites

Before you begin, make sure you have:
  • helm, kubectl, and jq installed.
  • Access to a running Kubernetes cluster that kubectl is pointed at, with an API server reachable from your Infisical instance. Confirm with kubectl cluster-info.
  • Access to an Infisical instance, either Infisical Cloud or a self-hosted instance.
  • A PostgreSQL database reachable from your Infisical instance, for the dynamic-secret step.
Network reachability matters in both directions. Kubernetes Auth works by having the Infisical backend call your cluster’s TokenReview API at the Kubernetes Host URL you configure later, and the operator calls your Infisical instance’s API from inside the cluster.If you use Infisical Cloud, a local kind, minikube, or Docker Desktop cluster isn’t reachable and won’t work as-is. Use a cluster with a reachable API endpoint, or self-host Infisical somewhere that can reach the cluster. The same applies to the PostgreSQL database for the dynamic-secret step: it must be reachable from your Infisical instance, not just from your cluster, so use a database with a public or peered address.
Dynamic Secrets are available under the Pro Tier and Enterprise Tier on Infisical Cloud.If you’re self-hosting Infisical, contact [email protected] to purchase an enterprise license.

Set up the operator and identity groundwork

1

Install the Infisical Operator

The Infisical Operator runs inside your cluster and reconciles the secret-synchronization resources you create.
The Helm chart installs every operator CRD, including the v1beta1 InfisicalConnection, InfisicalAuth, InfisicalStaticSecret, and InfisicalStaticSecretPush kinds this guide uses for the pull and push paths.Confirm the operator pod is running:
You should see a pod whose name begins with infisical-opera-controller-manager- in the Running state with 1/1 ready:
The infisical-opera prefix comes from the Helm release and chart names truncated to 15 characters, so a different release name changes it. helm install also uses your current kubeconfig namespace: if the pod is not under -n default, run kubectl get pods -A | grep infisical to find it, and adjust the -n flag in later commands to match.
2

Create a Machine Identity

The operator authenticates to Infisical with a Machine Identity using the Kubernetes Auth method.
  1. Log in to Infisical.
  2. Select Access Control from the left navigation pane.
  3. Open the Machine Identities tab and create an identity. Give it a name and assign it the Member organization role. You grant it project-level access in the next step.
  4. Copy the Identity ID and record it. It lands in two different places later:
    • Pull and push: you store it in a Kubernetes Secret named kubernetes-credentials. The InfisicalAuth CRD reads it from there through identityIdRef. It’s never pasted inline for pull or push.
    • Dynamic: you paste it inline as identityId in the InfisicalDynamicSecret CRD’s authentication.kubernetesAuth block.
  5. Select the identity, then add a Kubernetes Auth method with these values:
    • Allowed Service Account Names: infisical-service-account
    • Allowed Namespaces: default
    • Kubernetes Host URL: the control-plane URL from kubectl cluster-info. It is the line beginning “Kubernetes control plane is running at”. This URL must be reachable from your Infisical instance, as covered in the prerequisites.
    • Token Reviewer JWT and CA Certificate: leave both blank for now. You generate these in the next steps and return to paste them in. The CA Certificate field is on the Advanced tab.
You will return to this Kubernetes Auth method in the “Wire up the Kubernetes Auth method” step. With this guide’s RBAC setup, authentication fails until you paste the Token Reviewer JWT. The CA certificate is optional but recommended.
3

Create a project and add a secret

  1. Navigate back to Overview and select Add New Project.
    • Enter a Project Name and select Secrets Management as the product type.
    • Add a description (optional).
  2. Open the project and add a secret. Use these values so they match the InfisicalStaticSecret CRD later in this guide:
  3. Record the Project Slug and confirm the environment slug; you need both for the CRDs.
    • In Project Settings, copy the Slug field (distinct from the project name). It fills the projectSlug field in every CRD.
    • In Project Settings > Environments, find the Production environment’s slug. It’s usually prod, but confirm it: each CRD’s environment field must match exactly, or the sync targets the wrong environment.
  4. Open the Project Access tab and add the Machine Identity you created. Grant it Admin permissions for this guide.
Admin is used here only to keep the guide simple. In production, scope the identity to the least privilege it needs.
4

Create service accounts, RBAC, and tokens

The Kubernetes Auth method needs two Kubernetes service accounts:
  • infisical-token-reviewer: its JWT lets the Infisical backend call the Kubernetes TokenReview API to validate tokens presented by the operator. It serves the pull, push, and dynamic paths.
  • infisical-service-account: the identity the operator presents when it authenticates to Infisical.
Create the token-reviewer service account:
Create a long-lived token secret for it:
Bind the token-reviewer service account to the built-in system:auth-delegator ClusterRole. This lets the Infisical backend, acting with this service account’s JWT, submit TokenReview requests. Without this binding, TokenReview calls are denied.
Create the operator’s working service account and its token secret:
Associate the token secret with the service account:
You should see serviceaccount/infisical-service-account patched.
The infisical-service-account-token Secret and the kubectl patch serve only the v1alpha1 dynamic CRD, which reads the service account’s stored token. The v1beta1 pull and push paths don’t use them: InfisicalAuth mints a short-lived token (10 minutes) through the Kubernetes TokenRequest API on every login.
The service-account names and namespaces above must match the Allowed Service Account Names (infisical-service-account) and Allowed Namespaces (default) you set on the Kubernetes Auth method. They must also match the serviceAccountRef in the InfisicalAuth CRD and in the dynamic CRD’s inline kubernetesAuth block. Do not rename them.
5

Verify the service accounts and tokens

Confirm the two service accounts exist:
You should see infisical-token-reviewer and infisical-service-account (alongside the operator’s own infisical-opera-controller-manager service account).Confirm the two token secrets exist:
You should see infisical-token-reviewer-token and infisical-service-account-token, each of type kubernetes.io/service-account-token. The operator’s own Helm release secret (sh.helm.release.v1.infisical-operator...) also matches the grep; ignore it.
6

Wire up the Kubernetes Auth method

Now retrieve the reviewer JWT and CA certificate, then paste them into the Machine Identity’s Kubernetes Auth method to complete the auth loop you left open earlier.Print the Token Reviewer JWT:
Print the cluster CA certificate:
Then, in Infisical:
  1. Open the Machine Identity and open its Kubernetes Auth method for editing.
  2. Paste the decoded JWT into the Token Reviewer JWT field.
  3. Switch to the Advanced tab and paste the decoded certificate into the CA Certificate field.
  4. Save the configuration.
The CA Certificate field is optional and pairs with the Verify TLS Certificate toggle on the Advanced tab. When that toggle is on, Infisical validates the Kubernetes API server’s TLS certificate against this CA. You can save with the CA left empty, but for production keep verification on and provide the cluster CA.
After saving, the Machine Identity can authenticate operator requests.

Connect the operator to Infisical

The v1beta1 pull and push paths split connection and authentication into two reusable objects. The InfisicalConnection records where your Infisical instance is. The InfisicalAuth records how the operator authenticates to it. Any number of InfisicalStaticSecret and InfisicalStaticSecretPush resources can then share the same pair.
1

Create the InfisicalConnection

Save the manifest below as infisical-connection.yaml:
If you self-host Infisical, set spec.address to your instance’s base URL instead, for example https://infisical.example.com. Provide the base URL only, without a trailing /api. The pull and push paths use spec.address exactly as written and append the API path themselves, so an address that ends in /api produces failing requests to /api/api/.... For the same reason, always set spec.address explicitly. The operator’s INFISICAL_HOST_API fallback, which the Helm chart sets to https://app.infisical.com/api, ends in /api and doesn’t work for the pull and push paths.
Apply the resource:
On each reconcile, the operator health-checks the instance by calling <address>/api/status and sets the secrets.infisical.com/IsReady condition on the result. Healthy connections are re-checked every 5 minutes. Confirm the connection is ready:
You should see True in the READY column:
If READY is not True, see the Troubleshooting section at the end of this guide.
2

Store the Identity ID in a Kubernetes Secret

In v1beta1, the Machine Identity ID is never written inline in a manifest. InfisicalAuth reads it from a Kubernetes Secret through a reference. Create that Secret now. Replace your-identity-id with the Identity ID you recorded:
Confirm the Secret exists and holds the identityId key:
You should see ["identityId"].
3

Create the InfisicalAuth

The InfisicalAuth ties everything together: it references the connection, names the auth method, points at the Identity ID Secret, and names the service account the operator presents. Save the manifest below as infisical-auth.yaml:
Field notes:
  • identityIdRef names the Secret (name, namespace) and the data key (key) holding the Identity ID. There is no inline identityId field in v1beta1.
  • serviceAccountRef must name the infisical-service-account you created. The operator mints a fresh 10-minute token for it via the TokenRequest API on every login.
  • method selects the authentication method; this guide uses kubernetes. See the InfisicalAuth reference for the other methods.
Apply the resource:
On reconcile, the operator performs a real login against the connection. The referenced InfisicalConnection must be ready first. Confirm the auth is ready:
You should see True in the READY column:
For detail, kubectl describe infisicalauth infisical-auth -n default shows the secrets.infisical.com/IsReady and secrets.infisical.com/AuthMethod conditions. If the login fails, this is where the error message lands; see Troubleshooting.

Pull a secret with the InfisicalStaticSecret CRD

The InfisicalStaticSecret CRD tells the operator to fetch secrets from Infisical (sources) and write them into native Kubernetes objects (targets). It authenticates through the InfisicalAuth you just created.
1

Create the InfisicalStaticSecret resource

Save the manifest below as infisical-static-secret.yaml. Replace your-project-slug and the environment slug you confirmed (prod unless yours differs).
Each recorded value now lands here:Field notes:
  • Each source sets exactly one of projectSlug or projectId, plus a required environmentSlug and secretPath. Setting both or neither project field makes the reconcile fail; the error surfaces in the resource’s status conditions.
  • syncOptions.refreshInterval is required. It takes the form <number><unit> with units s, m, h, d, or w, and must be at least 5 seconds. Set instantUpdates: true to also receive near-real-time updates over server-sent events; availability is plan-gated server-side.
  • Each target requires name, namespace, kind (Secret or ConfigMap), and creationPolicy. Owner marks the managed object as owned by the CRD, so it is deleted with it; Orphan leaves the object behind. Targets can also apply templates to transform the data.
Apply the resource:
2

Verify the InfisicalStaticSecret synced

Confirm the resource synced. If the SYNCED column is empty at first, wait a few seconds for the first reconcile and run it again:
You should see True in the SYNCED column:
Confirm the operator created the managed secret:
View the secret contents:
You should see a base64-encoded entry for SMTP_HOST.
3

Deploy a demo app that consumes the secret

Save this Deployment as demo-deployment.yaml. It mounts managed-secret as environment variables into an nginx pod.
Apply it:
Wait 15 to 20 seconds, then confirm the deployment and pod are ready:
4

Confirm the secret reached the pod

Check that the environment variable is present in the running pod:
You should see [email protected]. The pull sync from Infisical to Kubernetes now works end to end.

Push a secret with the InfisicalStaticSecretPush CRD

The InfisicalStaticSecretPush CRD does the reverse: it reads Kubernetes Secrets (sources) and writes their values into Infisical (targets). It authenticates through the same InfisicalAuth as the pull path.
1

Create the source Kubernetes Secret

Save this as source-secret.yaml:
Apply and verify it:
2

Create the InfisicalStaticSecretPush resource

Save the manifest below as push-secret.yaml. Replace your-project-slug, and set environmentSlug to the environment you want to push into (the slug you confirmed earlier).
Note the differences from the pull flow you built with InfisicalStaticSecret:
  • The direction reverses: sources.secrets names the Kubernetes Secrets to read from, and each entry in targets names the Infisical project, environment, and path to push to.
  • Each target sets exactly one of projectSlug or projectId. Setting both, or neither, makes the reconcile fail: kubectl apply still succeeds, and the error surfaces in the resource’s status conditions.
  • syncOptions.refreshInterval is optional. Without it, the operator pushes when you apply the resource and again whenever it or the source Secret changes.
  • updatePolicy: Replace makes the operator overwrite values that already exist in Infisical. Set it to None to leave pre-existing Infisical secrets untouched.
  • deletionPolicy: Delete makes the operator remove the pushed secrets from Infisical when you delete this CRD. This matters during cleanup.
  • Replace and Delete are the defaults, so you can leave both out. They’re set here to show what the cleanup step relies on.
  • sources.secrets[].name must match the source secret you created (push-secret-demo).
Apply the resource:
3

Verify the push reached Infisical

Confirm the resource synced. If the SYNCED column is empty at first, wait a few seconds for the first reconcile and run it again:
You should see True in the SYNCED column:
Then open your project in Infisical, select the environment you pushed to, and confirm API_KEY now appears. If SYNCED isn’t True or API_KEY is missing, see Troubleshooting.Infisical project secrets dashboard showing the pushed API_KEY secret

Generate a dynamic secret with the InfisicalDynamicSecret CRD

The InfisicalDynamicSecret CRD tells the operator to create and lease a Dynamic Secret, then write the lease credentials into a Kubernetes Secret that any workload can consume. Unlike the pull and push CRDs, it’s a v1alpha1 resource with its own inline authentication block; the shared connection and auth objects aren’t used here.
1

Create the dynamic secret in Infisical

  1. In your project, select Add New > Add Dynamic Secret.
  2. Select SQL Database, then PostgreSQL as the provider.
  3. Enter your database’s Host, Port, User, Password, and Database Name. The database must be network-reachable from your Infisical instance, as noted in the prerequisites.
  4. In the CA (SSL) section, upload your database’s CA certificate if it enforces TLS with a custom CA. If it doesn’t require a custom CA, leave this empty.
  5. Set the Secret Name to dynamic-secret-lease.
  6. Select the environment matching the slug you confirmed earlier. Infisical add dynamic secret modal with PostgreSQL connection fields
2

Create the InfisicalDynamicSecret resource

Three names are in play. Keep them straight:The verify command reads the Kubernetes Secret, so it uses managedSecretReference.secretName.Save the manifest below as dynamic-secret.yaml. Replace your-identity-id and your-project-slug, and set environmentSlug to your confirmed slug.
Note for this CRD:
  • Authentication is inline: authentication.kubernetesAuth holds the Identity ID as a plain identityId string and the same serviceAccountRef as the InfisicalAuth.
  • projectSlug, environmentSlug, and secretsPath live under spec.dynamicSecret.
  • leaseRevocationPolicy: Revoke revokes the lease when you delete the resource, which matters for cleanup. Omit it to leave leases in place.
  • leaseTTL is optional. When omitted, the operator sends no TTL and the lease uses the dynamic secret’s own default TTL configured in Infisical.
  • It doesn’t use the InfisicalConnection. If you self-host Infisical, point this CRD at your instance with the optional spec.hostAPI field, or set the hostAPI Helm value for the operator. When neither is set, the operator’s default is https://app.infisical.com/api.
Apply the resource:
3

Verify the lease was created

Confirm the operator created the Kubernetes Secret holding the lease credentials. If it isn’t there yet, wait a few seconds for the first reconcile and run the command again:
The data section should contain the generated database username and password for the lease. If you renamed managedSecretReference.secretName, substitute that name in the command above.Kubernetes Secret containing the generated dynamic secret lease credentials

Verify the result

Confirm the shared objects are healthy and all three workflows succeeded:
  • Connection: kubectl get infisicalconnection infisical-connection -n default shows True in the READY column.
  • Auth: kubectl get infisicalauth infisical-auth -n default shows True in the READY column.
  • Pull: kubectl exec -it $(kubectl get pod -l app=nginx -n default -o jsonpath='{.items[0].metadata.name}') -n default -- env | grep SMTP prints [email protected].
  • Push: kubectl get infisicalstaticsecretpush push-secret-demo -n default shows True in the SYNCED column, and API_KEY appears in your Infisical project’s environment.
  • Dynamic: kubectl get secret dynamic-secret-test -n default -o jsonpath='{.data}' | jq shows lease credentials.
If all five checks pass, you have synced secrets in both directions and generated a leased database credential from Kubernetes.

Troubleshooting

If a sync doesn’t produce the expected result, inspect the resources’ status conditions and the operator logs before changing anything. For the pull and push paths, diagnose in dependency order: connection first, then auth, then the static secret or push. Each resource only becomes ready after the one it references.
Describe the resource and read its conditions:
The operator sets secrets.infisical.com/IsReady from a health check: it calls <address>/api/status and expects a successful response. If IsReady is False, the condition message names the error. Common causes:
  • The address is wrong, or the Infisical instance is not reachable from inside the cluster (this direction is the operator calling Infisical).
  • spec.address is empty and the operator’s INFISICAL_HOST_API environment variable is not set. The error message says exactly this.
  • A self-hosted instance uses a custom CA the operator does not trust. Reference the CA via spec.tls.caCertificate.
Healthy connections are re-checked every 5 minutes, so a recovered instance can take a few minutes to show Ready again.
Describe the resource and read its conditions:
The operator sets secrets.infisical.com/IsReady (the login result) and secrets.infisical.com/AuthMethod (the method in use). If IsReady is False, check these causes in order:
  • The referenced InfisicalConnection is not ready. The auth cannot log in until the connection’s IsReady condition is True; fix the connection first.
  • identityIdRef points at a missing Secret or key, or the stored Identity ID is wrong. Confirm with kubectl get secret kubernetes-credentials -n default -o jsonpath='{.data.identityId}' | base64 -d.
  • The Kubernetes Auth method is not fully wired: the Token Reviewer JWT was never pasted, or the service-account name or namespace does not match the Allowed Service Account Names / Allowed Namespaces you configured.
  • The cluster’s API server is not reachable from the Infisical instance. Kubernetes Auth requires the Infisical backend to call your cluster’s TokenReview API at the Kubernetes Host URL. If you pasted a local address such as https://127.0.0.1:6443 while using Infisical Cloud, every login fails even though the JWT and names are correct. Revisit the prerequisites.
Describe the resource and read its conditions:
The operator sets secrets.infisical.com/LastReconcileStatus: True with reason OK on success, or False with a “Reconciliation failed” message naming the error. Common causes:
  • The referenced InfisicalAuth is not ready. The static secret cannot sync until the auth’s IsReady condition is True; work up the chain.
  • A wrong projectSlug, environmentSlug, or secretPath in sources, or the Machine Identity lacks access to the project.
  • A source sets both or neither of projectId/projectSlug; exactly one is required.
Then check the operator logs:
Describe the resource and read its conditions:
The operator sets secrets.infisical.com/LastReconcileStatus: True with reason OK on success, or False with a “Reconciliation failed” message naming the error. Common causes:
  • The referenced InfisicalAuth isn’t ready. The push can’t sync until the auth’s IsReady condition is True; work up the chain.
  • sources.secrets names a Kubernetes Secret that doesn’t exist.
  • A wrong projectSlug, environmentSlug, or secretPath in targets, or the Machine Identity lacks access to the project.
Then check the operator logs:
Describe the dynamic-secret resource:
The operator sets secrets.infisical.com/Authenticated, secrets.infisical.com/LeaseCreated, and secrets.infisical.com/LeaseRenewal. A failed LeaseCreated carries whatever error lease creation returned, commonly an unreachable database or wrong connection credentials. Confirm the database is reachable from your Infisical instance and that the connection details entered in the UI are correct.

Clean up

Remove the resources this guide created so you don’t leave an active database lease or orphaned objects behind. Delete consumers before the objects they reference, so nothing reconciles against a missing dependency.
  1. Delete the sync resources. Deleting the InfisicalDynamicSecret with leaseRevocationPolicy: Revoke revokes the active database lease.
    Because the InfisicalStaticSecretPush was created with deletionPolicy: Delete, deleting it also removes the pushed API_KEY secret from your Infisical project. If you pushed into a shared environment, make sure that is what you want.
    Because the static secret’s target used creationPolicy: Owner, the managed managed-secret is deleted along with the CRD.
  2. Delete the auth object, then the connection it references:
  3. Delete the demo app and the remaining secrets, including the Identity ID Secret:
  4. Delete the service accounts, their token secrets, and the ClusterRoleBinding:
  5. Uninstall the operator:
  6. In Infisical, delete the dynamic secret, the demo Machine Identity, and the demo Project if you no longer need them.

Next steps