Kubernetes Operator

The Infisical Operator is a collection of Kubernetes controllers that streamline how secrets are managed between Infisical and your Kubernetes cluster. It provides multiple Custom Resource Definitions (CRDs) which enable you to:

Sync secrets from Infisical into Kubernetes.
Push new secrets from Kubernetes to Infisical.
Manage dynamic secrets and automatically create time-bound leases.

When these CRDs are configured, the Infisical Operator will continuously monitor for changes and perform necessary updates to keep your Kubernetes secrets up to date. It can also automatically reload dependent Deployment resources whenever relevant secrets are updated. The short video below walks through how the Infisical Operator syncs secrets into your Kubernetes cluster.

The operator supports two CRD API versions: v1beta1 and v1alpha1. Use v1beta1 for new installations; v1alpha1 is legacy and will be deprecated soon.

If you are already using the External Secrets operator, you can view the integration documentation for it here.

Supported Kubernetes versions
Supported Kubernetes distributions

The following Kubernetes minor releases are currently supported. The latest operator version is tested against each Kubernetes version. It may work with other versions of Kubernetes, but those are not officially supported.

1.33
1.32
1.31
1.30
1.29

Install

The operator can be installed via Helm. Helm is a package manager for Kubernetes that allows you to define, install, and upgrade Kubernetes applications. Install the latest Helm repository

helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/' 

helm repo update

The operator can be installed either cluster-wide or restricted to a specific namespace. If you require stronger isolation and stricter access controls, a namespace-scoped installation may make more sense.

Cluster Wide Installation
Namespace Scoped Installation

When installing the operator cluster-wide, the operator will watch and manage CRDs across all namespaces in the cluster. This is the default installation method and the quickest way to get started with using the operator. Cluster-wide installations are useful for:

Simplified Management: A single operator instance manages secrets across all namespaces
Centralized Operations: One deployment to monitor, update, and maintain
Cross-Namespace Flexibility: Easily manage secrets for applications spanning multiple namespaces
Quick Setup: Works out of the box with no additional RBAC configuration required

helm install --generate-name infisical-helm-charts/secrets-operator

The operator can be configured to watch and manage secrets in a specific namespace instead of having cluster-wide access. This is useful for:

Enhanced Security: Limit the operator’s permissions to only specific namespaces instead of cluster-wide access
Multi-tenant Clusters: Run separate operator instances for different teams or applications
Resource Isolation: Ensure operators in different namespaces don’t interfere with each other
Development & Testing: Run development and production operators side by side in isolated namespaces

For multiple namespace-scoped installations, only the first installation should install CRDs. Subsequent installations should set installCRDs: false to avoid conflicts as CRDs are cluster-wide resources.

Single Namespace

# First namespace installation (with CRDs)
helm install operator-namespaced infisical-helm-charts/secrets-operator \
  --namespace single-namespace \
  --set scopedNamespaces=single-namespace \
  --set scopedRBAC=true

Using values.yaml file

values-operator1.yaml

  scopedNamespaces: single-namespace
  scopedRBAC: true
  installCRDs: true

Multiple Namespaces

 helm install operator-1 infisical-helm-charts/secrets-operator \
  --namespace ns1 \
  --set scopedNamespaces=ns1 \
  --set scopedRBAC=true \
  --set installCRDs=true # Only install CRDs once in the cluster (default is true)

helm install operator-namespace2 infisical-helm-charts/secrets-operator \
  --namespace ns2 \
  --set scopedNamespaces=ns2 \
  --set scopedRBAC=true \
  --set installCRDs=false # Do not install CRDs in subsequent namespace installations

Using values.yaml file

values-operator1.yaml

  scopedNamespaces: ns1
  scopedRBAC: true
  installCRDs: false

values-operator2.yaml

  scopedNamespaces: ns2
  scopedRBAC: true
  installCRDs: false

Multiple namespaces with one operator installation

  helm install operator infisical-helm-charts/secrets-operator \
  --namespace operator-namespace \
  --set "scopedNamespaces={ns1,ns2,ns3}" \
  --set scopedRBAC=true

Using values.yaml file

values.yaml

  scopedNamespaces:
    - ns1
    - ns2
    - ns3
  scopedRBAC: true

Using your own service account

By default a service account is created for the operator based on the operator release name. You can bring your own service account by setting controllerManager.serviceAccount.create to false and setting controllerManager.serviceAccount.name to the name of the service account you want to use in your values.yaml file. Example values.yaml file:

values.yaml

controllerManager:
  serviceAccount:
    create: false
    name: my-service-account
# other values...

Please note that if you set controllerManager.serviceAccount.create to false, the service account needs to already exist in the namespace you are installing the operator in.

Custom service accounts are supported in chart version 0.10.11 and above. Please upgrade your helm chart to 0.10.11 or above before attempting to use custom service accounts.

Custom Resource Definitions

v1beta1 (Recommended)
v1alpha1

The v1beta1 API separates authentication and connection configuration into their own reusable CRDs, making it easier to manage credentials across multiple secret resources.

CRD	Description
InfisicalConnection	Defines how to connect to an Infisical instance (host, TLS). Referenced by other CRDs.
InfisicalAuth	Defines authentication credentials for a machine identity. Referenced by other CRDs.
InfisicalStaticSecret	Sync secrets from Infisical to a Kubernetes secret. Replaces `InfisicalSecret`.

The v1alpha1 CRDs are legacy and are planned for deprecation.

CRD	Status	Description
InfisicalSecret	Deprecated	Sync secrets from Infisical to a Kubernetes secret. Use InfisicalStaticSecret (v1beta1) instead. See migration guide.
InfisicalPushSecret	Active	Push secrets from a Kubernetes secret to Infisical.
InfisicalDynamicSecret	Active	Sync dynamic secrets and create leases automatically in Kubernetes.

Metrics and Prometheus

The operator exposes Prometheus metrics on /metrics for monitoring reconciliation performance, errors, and resource utilization.

Configuration

Enable the ServiceMonitor during installation. This will create a prometheus ServiceMonitor resource in the same namespace as the operator.

values.yaml

telemetry:
  serviceMonitor:
    enabled: true
    # ... other telemetry configuration (optional) ...

telemetry.serviceMonitor.enabled

Enable ServiceMonitor for Prometheus Operator. Defaults to false.

telemetry.serviceMonitor.selectors

Additional labels for ServiceMonitor. Defaults to {}.

telemetry.serviceMonitor.scheme

Scheme to use for the ServiceMonitor. Defaults to https.

telemetry.serviceMonitor.port

Port to use for the ServiceMonitor. Defaults to https.

telemetry.serviceMonitor.path

Path to use for the ServiceMonitor. Defaults to /metrics.

telemetry.serviceMonitor.interval

Scrape interval. Defaults to 30s.

telemetry.serviceMonitor.scrapeTimeout

Scrape timeout. Defaults to 10s.

telemetry.serviceMonitor.bearerTokenFile

Bearer token file. Defaults to /var/run/secrets/kubernetes.io/serviceaccount/token.

full-example-values.yaml

telemetry:
  serviceMonitor:
    enabled: true

    selectors: {}
    scheme: https
    port: https
    path: /metrics
    bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
    interval: 30s
    scrapeTimeout: 10s

Available Metrics

The operator exposes standard controller-runtime metrics. For a complete list of available metrics, see the Kubebuilder metrics reference. Key metrics to monitor:

controller_runtime_reconcile_total - Reconciliation count
controller_runtime_reconcile_errors_total - Error count
controller_runtime_reconcile_time_seconds - Reconciliation duration

v1beta1 controllers: InfisicalStaticSecret, InfisicalAuth, InfisicalConnection v1alpha1 controllers: InfisicalSecret, InfisicalPushSecret, InfisicalDynamicSecret

Example Prometheus Setup

Install Prometheus Operator

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update

helm install prometheus prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace

Install Operator with Metrics Enabled

helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/'

helm install infisical-secrets-operator infisical-helm-charts/secrets-operator \
  --set telemetry.serviceMonitor.enabled=true

Verify ServiceMonitor

kubectl get servicemonitor

Check that the ServiceMonitor appears in your operator’s namespace.

Access Prometheus

kubectl port-forward -n monitoring svc/prometheus-kube-prometheus-prometheus 9090:9090

Open http://localhost:9090/targets and verify the operator target shows UP.

Example Queries

# Total reconciliations
controller_runtime_reconcile_total

# P99 latency
histogram_quantile(0.99, rate(controller_runtime_reconcile_time_seconds_bucket[5m]))

# Memory usage (MB)
process_resident_memory_bytes / 1024 / 1024

General Configuration

Private/self-signed certificate

To connect to Infisical instances behind a private/self-signed certificate, you can configure TLS settings to point to a CA certificate stored in a Kubernetes secret resource.

v1beta1 (Recommended)
v1alpha1

In v1beta1, TLS is configured on the InfisicalConnection resource:

apiVersion: secrets.infisical.com/v1beta1
kind: InfisicalConnection
metadata:
  name: my-infisical-connection
spec:
  address: https://infisical.mydomain.com
  tls:
    caCertificate:
      name: secret-containing-ca-certificate
      namespace: default
      key: ca.crt

All CRDs that reference this InfisicalConnection will automatically use the configured TLS settings.

In v1alpha1, TLS is configured inline on each CRD:

spec:
  hostAPI: https://app.infisical.com/api
  tls:
    caRef:
      secretName: custom-ca-certificate
      secretNamespace: default
      key: ca.crt

Templating

Fetching secrets from Infisical as-is via the operator may not be enough. This is where templating functionality may be helpful. Using Go templates, you can format, combine, and create new key-value pairs from secrets fetched from Infisical before storing them as Kubernetes Secrets or ConfigMaps. When a template is set, only the keys defined in template.data are included in the output. When no template is set, all fetched secrets are included as-is. Each secret is available in the template context as .SECRET_KEY, which is an object with two accessors:

.Value: the secret value.
.SecretPath: the path of the secret in Infisical.

Key/value template map

targets:
  - name: my-app-config
    namespace: default
    kind: Secret
    creationPolicy: Owner
    template:
      engineVersion: v1
      data:
        DSN: "{{ .SECRET.Value }}.namespace:{{ .SECRET2.Value }}"
        ANOTHER_ONE: "{{ .SECRET3.Value }}"

Bulk string template with a loop

targets:
  - name: all-secrets
    namespace: default
    kind: Secret
    creationPolicy: Owner
    template:
      engineVersion: v1
      data: |
        {{- range $key, $secret := . }}
        {{ $key }}: "{{ $secret.Value }}"
        {{- end }}

To help transform your secrets further, the operator provides a set of built-in functions that you can use in your templates.

Available helper functions

The Infisical Secrets Operator exposes a wide range of helper functions to make it easier to work with secrets in Kubernetes.

encodeBase64

Encodes a string to a base64-encoded string (e.g. hello world becomes aGVsbG8gd29ybGQ=).Signature

encodeBase64(plainString string) string

Template usage

template:
  data:
    ENCODED_SECRET: "{{ .MY_SECRET.Value | encodeBase64 }}"

decodeBase64ToBytes

Decodes a base64-encoded string back to its original value (e.g. aGVsbG8gd29ybGQ= becomes hello world).Signature

decodeBase64ToBytes(encodedString string) string

Template usage

template:
  data:
    DECODED_SECRET: "{{ .MY_BASE64_SECRET.Value | decodeBase64ToBytes }}"

pkcs12key

Extracts all private keys from a PKCS#12 archive and returns them as PKCS#8 PEM-encoded blocks (-----BEGIN PRIVATE KEY-----...). The archive must not be password-protected — use pkcs12keyPass for password-protected archives.Signature

pkcs12key(input string) string

Template usage

template:
  data:
    tls.key: "{{ .TLS_CERT_PKCS12.Value | pkcs12key }}"

pkcs12keyPass

Same as pkcs12key, but uses the provided password to decrypt the PKCS#12 archive.Signature

pkcs12keyPass(password string, input string) string

Template usage

template:
  data:
    tls.key: '{{ pkcs12keyPass "my-password" .TLS_CERT_PKCS12.Value }}'

pkcs12cert

Extracts all certificates from a PKCS#12 archive and returns them as an ordered PEM chain (-----BEGIN CERTIFICATE-----...). Sort order: leaf → intermediate(s) → root. If disjunct or multiple leaf certs are provided, they are returned as-is. The archive must not be password-protected — use pkcs12certPass for password-protected archives.Signature

pkcs12cert(input string) string

Template usage

template:
  data:
    tls.crt: "{{ .TLS_CERT_PKCS12.Value | pkcs12cert }}"

pkcs12certPass

Same as pkcs12cert, but uses the provided password to decrypt the PKCS#12 archive.Signature

pkcs12certPass(password string, input string) string

Template usage

template:
  data:
    tls.crt: '{{ pkcs12certPass "my-password" .TLS_CERT_PKCS12.Value }}'

pemToPkcs12

Takes a PEM-encoded certificate and private key and creates a base64-encoded PKCS#12 archive. The output is not password-protected — use pemToPkcs12Pass to set a password.Signature

pemToPkcs12(cert string, key string) string

Template usage

template:
  data:
    keystore.p12: '{{ pemToPkcs12 .TLS_CERT.Value .TLS_KEY.Value }}'

pemToPkcs12Pass

Same as pemToPkcs12, but encrypts the PKCS#12 archive with the provided password.Signature

pemToPkcs12Pass(cert string, key string, password string) string

Template usage

template:
  data:
    keystore.p12: '{{ pemToPkcs12Pass .TLS_CERT.Value .TLS_KEY.Value "my-password" }}'

fullPemToPkcs12

Takes a full PEM-encoded certificate chain (leaf + intermediates + root) and a private key, and creates a base64-encoded PKCS#12 archive that includes the entire chain. The output is not password-protected — use fullPemToPkcs12Pass to set a password.Signature

fullPemToPkcs12(cert string, key string) string

Template usage

template:
  data:
    keystore.p12: '{{ fullPemToPkcs12 .TLS_FULL_CHAIN.Value .TLS_KEY.Value }}'

fullPemToPkcs12Pass

Same as fullPemToPkcs12, but encrypts the PKCS#12 archive with the provided password.Signature

fullPemToPkcs12Pass(cert string, key string, password string) string

Template usage

template:
  data:
    keystore.p12: '{{ fullPemToPkcs12Pass .TLS_FULL_CHAIN.Value .TLS_KEY.Value "my-password" }}'

filterPEM

Filters PEM blocks by type from a bundle containing multiple PEM blocks (e.g. extract only CERTIFICATE or PRIVATE KEY blocks). Common PEM types: CERTIFICATE, PRIVATE KEY, PUBLIC KEY, RSA PRIVATE KEY.Signature

filterPEM(pemType string, input string) string

Template usage

template:
  data:
    ca.crt: '{{ filterPEM "CERTIFICATE" .TLS_BUNDLE.Value }}'
    tls.key: '{{ filterPEM "PRIVATE KEY" .TLS_BUNDLE.Value }}'

filterCertChain

Filters PEM certificates by their position in a certificate chain. The chain is automatically ordered before filtering. Accepted types: leaf (end-entity certificate), intermediate (all intermediate CA certificates), root (root CA certificate). Returns an empty string if the requested type is not present in the chain.Signature

filterCertChain(certType string, input string) string

Template usage

template:
  data:
    tls.crt: '{{ filterCertChain "leaf" .TLS_CHAIN.Value }}'
    ca.crt: '{{ filterCertChain "root" .TLS_CHAIN.Value }}'
    intermediate.crt: '{{ filterCertChain "intermediate" .TLS_CHAIN.Value }}'

jwkPublicKeyPem

Takes a JSON-serialized JWK and returns a PEM block of type PUBLIC KEY containing the public key. Uses x509.MarshalPKIXPublicKey internally.Signature

jwkPublicKeyPem(jwkJson string) string

Template usage

template:
  data:
    public.pem: "{{ .MY_JWK.Value | jwkPublicKeyPem }}"

jwkPrivateKeyPem

Takes a JSON-serialized JWK and returns a PEM block of type PRIVATE KEY containing the private key. Uses x509.MarshalPKCS8PrivateKey internally.Signature

jwkPrivateKeyPem(jwkJson string) string

Template usage

template:
  data:
    private.pem: "{{ .MY_JWK.Value | jwkPrivateKeyPem }}"

toYaml

Marshals a value to a YAML string. Returns an empty string on marshal error.Signature

toYaml(v any) string

Template usage

template:
  data:
    config.yaml: "{{ .APP_CONFIG.Value | fromYaml | toYaml }}"

fromYaml

Parses a YAML string into a map[string]any, useful for extracting individual fields from a YAML-formatted secret (e.g. (fromYaml .DB_CONFIG.Value).host returns the host field).Signature

fromYaml(str string) map[string]any

Template usage

template:
  data:
    DB_HOST: '{{ (fromYaml .DB_CONFIG.Value).host }}'
    DB_PORT: '{{ (fromYaml .DB_CONFIG.Value).port }}'

secretFrom

This function is only available in v1beta1 resources (e.g. InfisicalStaticSecret).

Resolves a secret from a specific folder path within the Infisical project. Takes a path and a secret name as parameters, and returns the secret’s value by default. You can optionally use .Value or .SecretPath accessors on the result — if omitted, .Value is used.This is especially useful when multiple secrets share the same key, either from recursive fetches across different paths or from multiple sources. In both cases, the merge strategy only keeps the first occurrence (read more here), so secretFrom lets you explicitly select the one you need by its full path.

If multiple sources contain a secret with the same name and path, the secret from the first source listed in the sources array will be used.

Signature

secretFrom(path string, secretName string) string

Template usage

template:
  data:
    # .Value is implicit when no accessor is specified
    DB_PASSWORD: '{{ secretFrom "/databases/postgres" "DB_PASSWORD" }}'
    # Explicit .Value accessor (same result as above)
    STRIPE_API_KEY: '{{ (secretFrom "/services/payments" "API_KEY").Value }}'
    # Using .SecretPath to get the folder path instead of the value
    DATADOG_API_KEY: '{{ (secretFrom "/services/observability" "API_KEY").Value }}'
    DATADOG_API_KEY_PATH: '{{ (secretFrom "/services/observability" "API_KEY").SecretPath }}'

Sprig functions

The Infisical Secrets Operator integrates with the Sprig library to provide additional helper functions.

We’ve removed expandEnv and env from the supported functions for security reasons.

Migrating from v1alpha1 to v1beta1

This migration guide applies to InfisicalSecret only. InfisicalPushSecret and InfisicalDynamicSecret do not have v1beta1 replacements yet and should continue to be used as-is.

The v1beta1 API introduces a cleaner separation of concerns. Instead of defining authentication and connection details inline in each secret CRD, you now create dedicated InfisicalConnection and InfisicalAuth resources that can be shared across multiple secret resources.

Key changes

Secret resource: InfisicalSecret -> InfisicalStaticSecret InfisicalStaticSecret replaces the v1alpha1 InfisicalSecret CRD. Instead of defining auth and connection settings inline, it references dedicated InfisicalAuth and InfisicalConnection resources.
Authentication: inline authentication -> InfisicalAuth Authentication config is now defined in a standalone InfisicalAuth resource that can be reused across CRDs. Authenticated credentials are cached and shared by all resources referencing the same InfisicalAuth.
Connection: inline hostAPI / tls -> InfisicalConnection Connection config is now defined in a standalone InfisicalConnection resource that can be reused by auth and secret resources.

Migration steps

Create an InfisicalConnection resource

Extract the hostAPI and tls settings from your existing CRD into a new InfisicalConnection resource. See the InfisicalConnection CRD documentation for the full spec.

Create an InfisicalAuth resource

Extract the authentication block from your existing CRD into a new InfisicalAuth resource. See the InfisicalAuth CRD documentation for the full spec.

Replace InfisicalSecret with InfisicalStaticSecret

Create a new InfisicalStaticSecret resource that references your InfisicalConnection and InfisicalAuth resources. See the InfisicalStaticSecret CRD documentation for the full spec.If you were using templates, note that engineVersion is now a required field and the only accepted value is v1. The includeAllSecrets option no longer exists. Instead, you can iterate over all secrets using a bulk string template with a range loop. See the Templating section for details and examples.

Delete the old v1alpha1 resource

Once you have verified that the new v1beta1 resources are working, delete the old InfisicalSecret CRD instance.

Uninstall Operator

The managed secret created by the operator will not be deleted when the operator is uninstalled. Uninstall Infisical Helm repository

  helm uninstall <release name>

​Install

​Single Namespace

​Multiple Namespaces

​Multiple namespaces with one operator installation

​Using your own service account

​Custom Resource Definitions

​Metrics and Prometheus

​Configuration

​Available Metrics

​Example Prometheus Setup

​Example Queries

​General Configuration

​Private/self-signed certificate

​Templating

​Key/value template map

​Bulk string template with a loop

​Available helper functions

​Sprig functions

​Migrating from v1alpha1 to v1beta1

​Key changes

​Migration steps

​Uninstall Operator

Install

Single Namespace

Multiple Namespaces

Multiple namespaces with one operator installation

Using your own service account

Custom Resource Definitions

Metrics and Prometheus

Configuration

Available Metrics

Example Prometheus Setup

Example Queries

General Configuration

Private/self-signed certificate

Templating

Key/value template map

Bulk string template with a loop

Available helper functions

Sprig functions

Migrating from v1alpha1 to v1beta1

Key changes

Migration steps

Uninstall Operator