docs/integrations/platforms/kubernetes/overview.mdx
import KubernetesOperatorTemplating from "/snippets/kubernetes-operator-v1beta1-templating.mdx";
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:
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.
<Info> The operator supports two CRD API versions: **v1beta1** and **v1alpha1**. Use **v1beta1** for new installations; **v1alpha1** is legacy and will be deprecated soon. </Info> <Note> If you are already using the External Secrets operator, you can view the integration documentation for it [here](https://external-secrets.io/latest/provider/infisical/). </Note> <Tabs> <Tab title="Supported Kubernetes versions"> The following [Kubernetes minor releases](https://kubernetes.io/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
- Amazon Elastic Kubernetes Service (EKS)
- Google Kubernetes Engine (GKE)
- Microsoft Azure Kubernetes Service (AKS)
- Oracle Container Engine for Kubernetes (OKE)
- Red Hat OpenShift
It may work in other Kubernetes distributions, but those are not officially supported. Please report any issues [here](https://github.com/Infisical/infisical/issues).
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.
<Tabs> <Tab title="Cluster Wide 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```bash
helm install --generate-name infisical-helm-charts/secrets-operator
```
- **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
<Note>
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.
</Note>
### Single Namespace
```bash
# First namespace installation (with CRDs)
helm install operator-namespaced infisical-helm-charts/secrets-operator \
--namespace single-namespace \
--set scopedNamespaces=single-namespace \
--set scopedRBAC=true
```
<Accordion title="Using values.yaml file">
```yaml values-operator1.yaml
scopedNamespaces: single-namespace
scopedRBAC: true
installCRDs: true
```
</Accordion>
### Multiple Namespaces
```bash
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
```
<Accordion title="Using values.yaml file">
```yaml values-operator1.yaml
scopedNamespaces: ns1
scopedRBAC: true
installCRDs: false
```
```yaml values-operator2.yaml
scopedNamespaces: ns2
scopedRBAC: true
installCRDs: false
```
</Accordion>
### Multiple namespaces with one operator installation
```bash
helm install operator infisical-helm-charts/secrets-operator \
--namespace operator-namespace \
--set "scopedNamespaces={ns1,ns2,ns3}" \
--set scopedRBAC=true
```
<Accordion title="Using values.yaml file">
```yaml values.yaml
scopedNamespaces:
- ns1
- ns2
- ns3
scopedRBAC: true
```
</Accordion>
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:
controllerManager:
serviceAccount:
create: false
name: my-service-account
# other values...
| CRD | Description |
| --- | ----------- |
| [InfisicalConnection](/integrations/platforms/kubernetes/infisical-connection-crd) | Defines how to connect to an Infisical instance (host, TLS). Referenced by other CRDs. |
| [InfisicalAuth](/integrations/platforms/kubernetes/infisical-auth-crd) | Defines authentication credentials for a machine identity. Referenced by other CRDs. |
| [InfisicalStaticSecret](/integrations/platforms/kubernetes/infisical-static-secret-crd) | Sync secrets from Infisical to a Kubernetes secret. Replaces `InfisicalSecret`. |
| CRD | Status | Description |
| --- | ------ | ----------- |
| [InfisicalSecret](/integrations/platforms/kubernetes/infisical-secret-crd) | Deprecated | Sync secrets from Infisical to a Kubernetes secret. Use [InfisicalStaticSecret](/integrations/platforms/kubernetes/infisical-static-secret-crd) (v1beta1) instead. See [migration guide](#migrating-from-v1alpha1-to-v1beta1). |
| [InfisicalPushSecret](/integrations/platforms/kubernetes/infisical-push-secret-crd) | Active | Push secrets from a Kubernetes secret to Infisical. |
| [InfisicalDynamicSecret](/integrations/platforms/kubernetes/infisical-dynamic-secret-crd) | Active | Sync dynamic secrets and create leases automatically in Kubernetes. |
The operator exposes Prometheus metrics on /metrics for monitoring reconciliation performance, errors, and resource utilization.
Enable the ServiceMonitor during installation. This will create a prometheus ServiceMonitor resource in the same namespace as the operator.
telemetry:
serviceMonitor:
enabled: true
# ... other telemetry configuration (optional) ...
telemetry:
serviceMonitor:
enabled: true
selectors: {}
scheme: https
port: https
path: /metrics
bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
interval: 30s
scrapeTimeout: 10s
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 countcontroller_runtime_reconcile_errors_total - Error countcontroller_runtime_reconcile_time_seconds - Reconciliation durationv1beta1 controllers: InfisicalStaticSecret, InfisicalAuth, InfisicalConnection
v1alpha1 controllers: InfisicalSecret, InfisicalPushSecret, InfisicalDynamicSecret
helm install prometheus prometheus-community/kube-prometheus-stack \
--namespace monitoring \
--create-namespace
```
helm install infisical-secrets-operator infisical-helm-charts/secrets-operator \
--set telemetry.serviceMonitor.enabled=true
```
Check that the ServiceMonitor appears in your operator's namespace.
Open [http://localhost:9090/targets](http://localhost:9090/targets) and verify the operator target shows **UP**.
# 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
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.
<Tabs> <Tab title="v1beta1 (Recommended)"> In v1beta1, TLS is configured on the [InfisicalConnection](/integrations/platforms/kubernetes/infisical-connection-crd) resource:```yaml
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.
```yaml
spec:
hostAPI: https://app.infisical.com/api
tls:
caRef:
secretName: custom-ca-certificate
secretNamespace: default
key: ca.crt
```
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.
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.
The managed secret created by the operator will not be deleted when the operator is uninstalled.
Uninstall Infisical Helm repository
helm uninstall <release name>