diff --git a/docs/integrations/platforms/kubernetes.mdx b/docs/integrations/platforms/kubernetes.mdx deleted file mode 100644 index 4f835c4f7..000000000 --- a/docs/integrations/platforms/kubernetes.mdx +++ /dev/null @@ -1,1995 +0,0 @@ ---- -title: "Kubernetes Operator" -description: "How to use Infisical to inject secrets into Kubernetes clusters." ---- - -![title](../../images/k8-diagram.png) - -The Infisical Secrets Operator is a Kubernetes controller that retrieves secrets from Infisical and stores them in a designated cluster. -It uses an `InfisicalSecret` resource to specify authentication and storage methods. -The operator continuously updates secrets and can also reload dependent deployments automatically. - - - 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/). - - -## Install Operator - -The operator can be install via [Helm](https://helm.sh) or [kubectl](https://github.com/kubernetes/kubectl) - - - - **Install the latest Infisical Helm repository** - ```bash - helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/' - - helm repo update - ``` - - **Install the Helm chart** - - To select a specific version, view the application versions [here](https://hub.docker.com/r/infisical/kubernetes-operator/tags) and chart versions [here](https://cloudsmith.io/~infisical/repos/helm-charts/packages/detail/helm/secrets-operator/#versions) - - ```bash - helm install --generate-name infisical-helm-charts/secrets-operator - ``` - - ```bash - # Example installing app version v0.2.0 and chart version 0.1.4 - helm install --generate-name infisical-helm-charts/secrets-operator --version=0.1.4 --set controllerManager.manager.image.tag=v0.2.0 - ``` - - **Namespace-scoped Installation** - - 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 - - **Note**: For multiple namespace-scoped installations, only the first installation should install CRDs. Subsequent installations should set `installCRDs: false` to avoid conflicts. - - ```bash - # First namespace installation (with CRDs) - helm install operator-namespace1 infisical-helm-charts/secrets-operator \ - --namespace first-namespace \ - --set scopedNamespace=first-namespace \ - --set scopedRBAC=true - - # Subsequent namespace installations - helm install operator-namespace2 infisical-helm-charts/secrets-operator \ - --namespace another-namespace \ - --set scopedNamespace=another-namespace \ - --set scopedRBAC=true \ - --set installCRDs=false - ``` - - When scoped to a namespace, the operator will: - - - Only watch InfisicalSecrets in the specified namespace - - Only create/update Kubernetes secrets in that namespace - - Only access deployments in that namespace - - The default configuration gives cluster-wide access: - - ```yaml - installCRDs: true # Install CRDs (set to false for additional namespace installations) - scopedNamespace: "" # Empty for cluster-wide access - scopedRBAC: false # Cluster-wide permissions - ``` - - If you want to install operators in multiple namespaces simultaneously: - - Make sure to set `installCRDs: false` for all but one of the installations to avoid conflicts, as CRDs are cluster-wide resources. - - Use unique release names for each installation (e.g., operator-namespace1, operator-namespace2). - - - - For production deployments, it is highly recommended to set the version of the Kubernetes operator manually instead of pointing to the latest version. - Doing so will help you avoid accidental updates to the newest release which may introduce unintended breaking changes. View all application versions [here](https://hub.docker.com/r/infisical/kubernetes-operator/tags). - -The command below will install the most recent version of the Kubernetes operator. -However, to set the version manually, download the manifest and set the image tag version of `infisical/kubernetes-operator` according to your desired version. - -Once you apply the manifest, the operator will be installed in `infisical-operator-system` namespace. - - ``` - kubectl apply -f https://raw.githubusercontent.com/Infisical/infisical/main/k8-operator/kubectl-install/install-secrets-operator.yaml - ``` - - - - - -## Custom Resource Definitions (CRD's) - -Currently the operator supports the following CRD's. We are constantly expanding the functionality of the operator, and this list will be updated as new CRD's are added. - -1. [InfisicalSecret](#sync-infisical-secrets-to-your-cluster): Sync secrets from Infisical to a Kubernetes secret. -2. [InfisicalPushSecret](#push-secrets-to-infisical): Push secrets from a Kubernetes secret to Infisical. -3. [InfisicalDynamicSecret](#sync-dynamic-secrets-to-your-cluster): Sync dynamic secrets and create leases automatically in Kubernetes. - - -## Sync Infisical Secrets to your cluster - -Once you have installed the operator to your cluster, you'll need to create a `InfisicalSecret` custom resource definition (CRD). - -```yaml example-infisical-secret-crd.yaml -apiVersion: secrets.infisical.com/v1alpha1 -kind: InfisicalSecret -metadata: - name: infisicalsecret-sample - labels: - label-to-be-passed-to-managed-secret: sample-value - annotations: - example.com/annotation-to-be-passed-to-managed-secret: "sample-value" -spec: - hostAPI: https://app.infisical.com/api - resyncInterval: 10 - authentication: - # Make sure to only have 1 authentication method defined, serviceToken/universalAuth. - # If you have multiple authentication methods defined, it may cause issues. - - # (Deprecated) Service Token Auth - serviceToken: - serviceTokenSecretReference: - secretName: service-token - secretNamespace: default - secretsScope: - envSlug: - secretsPath: - recursive: true - - # Universal Auth - universalAuth: - secretsScope: - projectSlug: new-ob-em - envSlug: dev # "dev", "staging", "prod", etc.. - secretsPath: "/" # Root is "/" - recursive: true # Whether or not to use recursive mode (Fetches all secrets in an environment from a given secret path, and all folders inside the path) / defaults to false - credentialsRef: - secretName: universal-auth-credentials - secretNamespace: default - - # Native Kubernetes Auth - kubernetesAuth: - identityId: - serviceAccountRef: - name: - namespace: - - # secretsScope is identical to the secrets scope in the universalAuth field in this sample. - secretsScope: - projectSlug: your-project-slug - envSlug: prod - secretsPath: "/path" - recursive: true - - # AWS IAM Auth - awsIamAuth: - identityId: - - # secretsScope is identical to the secrets scope in the universalAuth field in this sample. - secretsScope: - projectSlug: your-project-slug - envSlug: prod - secretsPath: "/path" - recursive: true - - # Azure Auth - azureAuth: - identityId: - resource: https://management.azure.com/&client_id=CLIENT_ID # (Optional) This is the Azure resource that you want to access. For example, "https://management.azure.com/". If no value is provided, it will default to "https://management.azure.com/" - - # secretsScope is identical to the secrets scope in the universalAuth field in this sample. - secretsScope: - projectSlug: your-project-slug - envSlug: prod - secretsPath: "/path" - recursive: true - - # GCP ID Token Auth - gcpIdTokenAuth: - identityId: - - # secretsScope is identical to the secrets scope in the universalAuth field in this sample. - secretsScope: - projectSlug: your-project-slug - envSlug: prod - secretsPath: "/path" - recursive: true - - # GCP IAM Auth - gcpIamAuth: - identityId: - - # secretsScope is identical to the secrets scope in the universalAuth field in this sample. - secretsScope: - projectSlug: your-project-slug - envSlug: prod - secretsPath: "/path" - recursive: true - - managedSecretReference: - secretName: managed-secret - secretNamespace: default - creationPolicy: "Orphan" ## Owner | Orphan - # template: - # includeAllSecrets: true - # data: - # CUSTOM_KEY: "{{ .KEY.SecretPath }} {{ .KEY.Value }}" - # secretType: kubernetes.io/dockerconfigjson -``` - -### InfisicalSecret CRD properties - - - If you are fetching secrets from a self-hosted instance of Infisical set the value of `hostAPI` to - ` https://your-self-hosted-instace.com/api` - -When `hostAPI` is not defined the operator fetches secrets from Infisical Cloud. - - - If you have installed your Infisical instance within the same cluster as the Infisical operator, you can optionally access the Infisical backend's service directly without having to route through the public internet. - To achieve this, use the following address for the hostAPI field: - - ``` bash - http://..svc.cluster.local:4000/api - ``` - - Make sure to replace `` and `` with the appropriate values for your backend service and namespace. - - - - - - This property defines the time in seconds between each secret re-sync from - Infisical. Shorter time between re-syncs will require higher rate limits only - available on paid plans. Default re-sync interval is every 1 minute. - - - - This block defines the TLS settings to use for connecting to the Infisical - instance. - - - - This block defines the reference to the CA certificate to use for connecting - to the Infisical instance with SSL/TLS. - - - - The name of the Kubernetes secret containing the CA certificate to use for - connecting to the Infisical instance with SSL/TLS. - - - - The namespace of the Kubernetes secret containing the CA certificate to use - for connecting to the Infisical instance with SSL/TLS. - - - - The name of the key in the Kubernetes secret which contains the value of the - CA certificate to use for connecting to the Infisical instance with SSL/TLS. - - - - This block defines the method that will be used to authenticate with Infisical - so that secrets can be fetched - - - - The universal machine identity authentication method is used to authenticate with Infisical. The client ID and client secret needs to be stored in a Kubernetes secret. This block defines the reference to the name and namespace of secret that stores these credentials. - - - - You need to create a machine identity, and give it access to the project(s) you want to interact with. You can [read more about machine identities here](/documentation/platform/identities/universal-auth). - - - Once you have created your machine identity and added it to your project(s), you will need to create a Kubernetes secret containing the identity credentials. - To quickly create a Kubernetes secret containing the identity credentials, you can run the command below. - - Make sure you replace `` with the identity client ID and `` with the identity client secret. - - ``` bash - kubectl create secret generic universal-auth-credentials --from-literal=clientId="" --from-literal=clientSecret="" - ``` - - - - Once the secret is created, add the `secretName` and `secretNamespace` of the secret that was just created under `authentication.universalAuth.credentialsRef` field in the InfisicalSecret resource. - - - - - - Make sure to also populate the `secretsScope` field with the project slug - _`projectSlug`_, environment slug _`envSlug`_, and secrets path - _`secretsPath`_ that you want to fetch secrets from. Please see the example - below. - - -## Example - -```yaml -apiVersion: secrets.infisical.com/v1alpha1 -kind: InfisicalSecret -metadata: - name: infisicalsecret-sample-crd -spec: - authentication: - universalAuth: - secretsScope: - projectSlug: # <-- project slug - envSlug: # "dev", "staging", "prod", etc.. - secretsPath: "" # Root is "/" - credentialsRef: - secretName: universal-auth-credentials # <-- name of the Kubernetes secret that stores our machine identity credentials - secretNamespace: default # <-- namespace of the Kubernetes secret that stores our machine identity credentials - ... -``` - - - - - The Kubernetes machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within a Kubernetes environment. - - - - 1.1. Start by creating a service account in your Kubernetes cluster that will be used by Infisical to authenticate with the Kubernetes API Server. - - ```yaml infisical-service-account.yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: infisical-auth - namespace: default - - ``` - - ``` - kubectl apply -f infisical-service-account.yaml - ``` - - 1.2. Bind the service account to the `system:auth-delegator` cluster role. As described [here](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#other-component-roles), this role allows delegated authentication and authorization checks, specifically for Infisical to access the [TokenReview API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/). You can apply the following configuration file: - - ```yaml cluster-role-binding.yaml - apiVersion: rbac.authorization.k8s.io/v1 - kind: ClusterRoleBinding - metadata: - name: role-tokenreview-binding - namespace: default - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: system:auth-delegator - subjects: - - kind: ServiceAccount - name: infisical-auth - namespace: default - ``` - - ``` - kubectl apply -f cluster-role-binding.yaml - ``` - - 1.3. Next, create a long-lived service account JWT token (i.e. the token reviewer JWT token) for the service account using this configuration file for a new `Secret` resource: - - ```yaml service-account-token.yaml - apiVersion: v1 - kind: Secret - type: kubernetes.io/service-account-token - metadata: - name: infisical-auth-token - annotations: - kubernetes.io/service-account.name: "infisical-auth" - ``` - - - ``` - kubectl apply -f service-account-token.yaml - ``` - - 1.4. Link the secret in step 1.3 to the service account in step 1.1: - - ```bash - kubectl patch serviceaccount infisical-auth -p '{"secrets": [{"name": "infisical-auth-token"}]}' -n default - ``` - - 1.5. Finally, retrieve the token reviewer JWT token from the secret. - - ```bash - kubectl get secret infisical-auth-token -n default -o=jsonpath='{.data.token}' | base64 --decode - ``` - - Keep this JWT token handy as you will need it for the **Token Reviewer JWT** field when configuring the Kubernetes Auth authentication method for the identity in step 2. - - - - - To create an identity, head to your Organization Settings > Access Control > Machine Identities and press **Create identity**. - - ![identities organization](/images/platform/identities/identities-org.png) - - When creating an identity, you specify an organization level [role](/documentation/platform/role-based-access-controls) for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles. - - ![identities organization create](/images/platform/identities/identities-org-create.png) - - Now input a few details for your new identity. Here's some guidance for each field: - - - Name (required): A friendly name for the identity. - - Role (required): A role from the **Organization Roles** tab for the identity to assume. The organization role assigned will determine what organization level resources this identity can have access to. - - Once you've created an identity, you'll be prompted to configure the authentication method for it. Here, select **Kubernetes Auth**. - - - To learn more about each field of the Kubernetes native authentication method, see step 2 of [guide](/documentation/platform/identities/kubernetes-auth#guide). - - - ![identities organization create auth method](/images/platform/identities/identities-org-create-kubernetes-auth-method.png) - - - - - To allow the operator to use the given identity to access secrets, you will need to add the identity to project(s) that you would like to grant it access to. - - To do this, head over to the project you want to add the identity to and go to Project Settings > Access Control > Machine Identities and press **Add identity**. - - Next, select the identity you want to add to the project and the project level role you want to allow it to assume. The project role assigned will determine what project level resources this identity can have access to. - - ![identities project](/images/platform/identities/identities-project.png) - - ![identities project create](/images/platform/identities/identities-project-create.png) - - - - Once you have created your machine identity and added it to your project(s), you will need to add the identity ID to your InfisicalSecret resource. - In the `authentication.kubernetesAuth.identityId` field, add the identity ID of the machine identity you created. - See the example below for more details. - - - Add the service account details from the previous steps under `authentication.kubernetesAuth.serviceAccountRef`. - Here you will need to enter the name and namespace of the service account. - The example below shows a complete InfisicalSecret resource with all required fields defined. - - - - - - Make sure to also populate the `secretsScope` field with the project slug - _`projectSlug`_, environment slug _`envSlug`_, and secrets path - _`secretsPath`_ that you want to fetch secrets from. Please see the example - below. - - -## Example - -```yaml example-kubernetes-auth.yaml -apiVersion: secrets.infisical.com/v1alpha1 -kind: InfisicalSecret -metadata: - name: infisicalsecret-sample-crd -spec: - authentication: - kubernetesAuth: - identityId: - serviceAccountRef: - name: - namespace: - - # secretsScope is identical to the secrets scope in the universalAuth field in this sample. - secretsScope: - projectSlug: your-project-slug - envSlug: prod - secretsPath: "/path" - recursive: true - ... -``` - - - - - The AWS IAM machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within an AWS environment like an EC2 or a Lambda function. - - - - You need to create a machine identity, and give it access to the project(s) you want to interact with. You can [read more about AWS machine identities here](/documentation/platform/identities/aws-auth). - - - Once you have created your machine identity and added it to your project(s), you will need to add the identity ID to your InfisicalSecret resource. In the `authentication.awsIamAuth.identityId` field, add the identity ID of the machine identity you created. See the example below for more details. - - - - - - Make sure to also populate the `secretsScope` field with the project slug - _`projectSlug`_, environment slug _`envSlug`_, and secrets path - _`secretsPath`_ that you want to fetch secrets from. Please see the example - below. - - -## Example - -```yaml example-aws-iam-auth.yaml -apiVersion: secrets.infisical.com/v1alpha1 -kind: InfisicalSecret -metadata: - name: infisicalsecret-sample-crd -spec: - authentication: - awsIamAuth: - identityId: - - # secretsScope is identical to the secrets scope in the universalAuth field in this sample. - secretsScope: - projectSlug: your-project-slug - envSlug: prod - secretsPath: "/path" - recursive: true - ... -``` - - - - - The Azure machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within an Azure environment. - - - - You need to create a machine identity, and give it access to the project(s) you want to interact with. You can [read more about Azure machine identities here](/documentation/platform/identities/azure-auth). - - - Once you have created your machine identity and added it to your project(s), you will need to add the identity ID to your InfisicalSecret resource. In the `authentication.azureAuth.identityId` field, add the identity ID of the machine identity you created. See the example below for more details. - - - - - - Make sure to also populate the `secretsScope` field with the project slug - _`projectSlug`_, environment slug _`envSlug`_, and secrets path - _`secretsPath`_ that you want to fetch secrets from. Please see the example - below. - - -## Example - -```yaml example-azure-auth.yaml -apiVersion: secrets.infisical.com/v1alpha1 -kind: InfisicalSecret -metadata: - name: infisicalsecret-sample-crd -spec: - authentication: - azureAuth: - identityId: - - # secretsScope is identical to the secrets scope in the universalAuth field in this sample. - secretsScope: - projectSlug: your-project-slug - envSlug: prod - secretsPath: "/path" - recursive: true - ... -``` - - - - - The GCP ID Token machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within GCP environments. - - - - You need to create a machine identity, and give it access to the project(s) you want to interact with. You can [read more about GCP machine identities here](/documentation/platform/identities/gcp-auth). - - - Once you have created your machine identity and added it to your project(s), you will need to add the identity ID to your InfisicalSecret resource. In the `authentication.gcpIdTokenAuth.identityId` field, add the identity ID of the machine identity you created. See the example below for more details. - - - - - - Make sure to also populate the `secretsScope` field with the project slug - _`projectSlug`_, environment slug _`envSlug`_, and secrets path - _`secretsPath`_ that you want to fetch secrets from. Please see the example - below. - - -## Example - -```yaml example-gcp-id-token-auth.yaml -apiVersion: secrets.infisical.com/v1alpha1 -kind: InfisicalSecret -metadata: - name: infisicalsecret-sample-crd -spec: - authentication: - gcpIdTokenAuth: - identityId: - - # secretsScope is identical to the secrets scope in the universalAuth field in this sample. - secretsScope: - projectSlug: your-project-slug - envSlug: prod - secretsPath: "/path" - recursive: true - ... -``` - - - - - The GCP IAM machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used both within and outside GCP environments. - - - - You need to create a machine identity, and give it access to the project(s) you want to interact with. You can [read more about GCP machine identities here](/documentation/platform/identities/gcp-auth). - - - Once you have created your machine identity and added it to your project(s), you will need to add the identity ID to your InfisicalSecret resource. In the `authentication.gcpIamAuth.identityId` field, add the identity ID of the machine identity you created. - You'll also need to add the service account key file path to your InfisicalSecret resource. In the `authentication.gcpIamAuth.serviceAccountKeyFilePath` field, add the path to your service account key file path. Please see the example below for more details. - - - - - - Make sure to also populate the `secretsScope` field with the project slug - _`projectSlug`_, environment slug _`envSlug`_, and secrets path - _`secretsPath`_ that you want to fetch secrets from. Please see the example - below. - - -## Example - -```yaml example-gcp-id-token-auth.yaml -apiVersion: secrets.infisical.com/v1alpha1 -kind: InfisicalSecret -metadata: - name: infisicalsecret-sample-crd -spec: - authentication: - gcpIamAuth: - identityId: - serviceAccountKeyFilePath: "/path/to-service-account-key-file-path.json" - - # secretsScope is identical to the secrets scope in the universalAuth field in this sample. - secretsScope: - projectSlug: your-project-slug - envSlug: prod - secretsPath: "/path" - recursive: true - ... -``` - - - - - -The service token required to authenticate with Infisical needs to be stored in a Kubernetes secret. This block defines the reference to the name and namespace of secret that stores this service token. -Follow the instructions below to create and store the service token in a Kubernetes secrets and reference it in your CRD. - -#### 1. Generate service token - -You can generate a [service token](../../documentation/platform/token) for an Infisical project by heading over to the Infisical dashboard then to Project Settings. - -#### 2. Create Kubernetes secret containing service token - -Once you have generated the service token, you will need to create a Kubernetes secret containing the service token you generated. -To quickly create a Kubernetes secret containing the generated service token, you can run the command below. Make sure you replace `` with your service token. - -```bash -kubectl create secret generic service-token --from-literal=infisicalToken="" -``` - -#### 3. Add reference for the Kubernetes secret containing service token - -Once the secret is created, add the name and namespace of the secret that was just created under `authentication.serviceToken.serviceTokenSecretReference` field in the InfisicalSecret resource. - -{" "} - - - Make sure to also populate the `secretsScope` field with the, environment slug - _`envSlug`_, and secrets path _`secretsPath`_ that you want to fetch secrets - from. Please see the example below. - - -## Example - -```yaml -apiVersion: secrets.infisical.com/v1alpha1 -kind: InfisicalSecret -metadata: - name: infisicalsecret-sample-crd -spec: - authentication: - serviceToken: - serviceTokenSecretReference: - secretName: service-token # <-- name of the Kubernetes secret that stores our service token - secretNamespace: option # <-- namespace of the Kubernetes secret that stores our service token - secretsScope: - envSlug: # "dev", "staging", "prod", etc.. - secretsPath: # Root is "/" - ... -``` - - - - -The `managedSecretReference` field is used to define the target location for storing secrets retrieved from an Infisical project. -This field requires specifying both the name and namespace of the Kubernetes secret that will hold these secrets. -The Infisical operator will automatically create the Kubernetes secret with the specified name/namespace and keep it continuously updated. - -Note: The managed secret be should be created in the same namespace as the deployment that will use it. - - - -The name of the managed Kubernetes secret to be created - - -The namespace of the managed Kubernetes secret to be created. - - -Override the default Opaque type for managed secrets with this field. Useful for creating kubernetes.io/dockerconfigjson secrets. - - -Templates enable you to transform data from Infisical before storing it as a Kubernetes Secret. - - -When set to true, this option injects all secrets retrieved from Infisical into your configuration. -Secrets defined in the template will override the automatically injected secrets. - - -Define secret keys and their corresponding templates. -Each data value uses a Golang template with access to all secrets retrieved from the specified scope. - -Secrets are structured as follows: - -```golang -type TemplateSecret struct { - Value string `json:"value"` - SecretPath string `json:"secretPath"` -} -``` - -#### Example template configuration: - -```golang - managedSecretReference: - secretName: managed-secret - secretNamespace: default - template: - includeAllSecrets: true - data: - NEW_KEY: "{{ .KEY1.SecretPath }} {{ .KEY1.Value }}" -``` - -When you run the following command: - -```bash -kubectl get secret managed-secret -o jsonpath='{.data}' -``` - -You'll receive Kubernetes secrets output that includes the NEW_KEY: - -```bash -{... "KEY":"d29ybGQ=","NEW_KEY":"LyBoZWxsbw=="} -``` - -When you set `includeAllSecrets` as `false` the Kubernetes secrets outputs will be: - -```bash -{"NEW_KEY":"LyBoZWxsbw=="} -``` - - - -Creation polices allow you to control whether or not owner references should be added to the managed Kubernetes secret that is generated by the Infisical operator. -This is useful for tools such as ArgoCD, where every resource requires an owner reference; otherwise, it will be pruned automatically. - -#### Available options - -- `Orphan` (default) -- `Owner` - - - When creation policy is set to `Owner`, the `InfisicalSecret` CRD must be in - the same namespace as where the managed kubernetes secret. - - - - -### Propagating labels & annotations - -The operator will transfer all labels & annotations present on the `InfisicalSecret` CRD to the managed Kubernetes secret to be created. -Thus, if a specific label is required on the resulting secret, it can be applied as demonstrated in the following example: - - -```yaml -apiVersion: secrets.infisical.com/v1alpha1 -kind: InfisicalSecret -metadata: - name: infisicalsecret-sample - labels: - label-to-be-passed-to-managed-secret: sample-value - annotations: - example.com/annotation-to-be-passed-to-managed-secret: "sample-value" -spec: - .. - authentication: - ... - managedSecretReference: - ... -``` - -This would result in the following managed secret to be created: - -```yaml -apiVersion: v1 -data: ... -kind: Secret -metadata: - annotations: - example.com/annotation-to-be-passed-to-managed-secret: sample-value - secrets.infisical.com/version: W/"3f1-ZyOSsrCLGSkAhhCkY2USPu2ivRw" - labels: - label-to-be-passed-to-managed-secret: sample-value - name: managed-token - namespace: default -type: Opaque -``` - - - -### Apply the InfisicalSecret CRD to your cluster - -Once you have configured the InfisicalSecret CRD with the required fields, you can apply it to your cluster. -After applying, you should notice that the managed secret has been created in the desired namespace your specified. - -``` -kubectl apply -f example-infisical-secret-crd.yaml -``` - -### Verify managed secret creation - -To verify that the operator has successfully created the managed secret, you can check the secrets in the namespace that was specified. - -```bash -# Verify managed secret is created -kubectl get secrets -n -``` - - - The Infisical secrets will be synced and stored into the managed secret every - 1 minutes. - - -### Using managed secret in your deployment - -Incorporating the managed secret created by the operator into your deployment can be achieved through several methods. -Here, we will highlight three of the most common ways to utilize it. Learn more about Kubernetes secrets [here](https://kubernetes.io/docs/concepts/configuration/secret/) - - - This will take all the secrets from your managed secret and expose them to your container - -````yaml - envFrom: - - secretRef: - name: managed-secret # managed secret name - ``` - - Example usage in a deployment - ```yaml - apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-deployment - labels: - app: nginx -spec: - replicas: 1 - selector: - matchLabels: - app: nginx - template: - metadata: - labels: - app: nginx - spec: - containers: - - name: nginx - image: nginx:1.14.2 - envFrom: - - secretRef: - name: managed-secret # <- name of managed secret - ports: - - containerPort: 80 -```` - - - - - This will allow you to select individual secrets by key name from your managed secret and expose them to your container - - ```yaml - env: - - name: SECRET_NAME # The environment variable's name which is made available in the container - valueFrom: - secretKeyRef: - name: managed-secret # managed secret name - key: SOME_SECRET_KEY # The name of the key which exists in the managed secret - ``` - -Example usage in a deployment - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: -name: nginx-deployment -labels: -app: nginx -spec: -replicas: 1 -selector: -matchLabels: -app: nginx -template: -metadata: -labels: -app: nginx -spec: -containers: - name: nginx -image: nginx:1.14.2 -env: - name: STRIPE_API_SECRET -valueFrom: -secretKeyRef: -name: managed-secret # <- name of managed secret -key: STRIPE_API_SECRET -ports: - containerPort: 80 - -``` - - - - -This will allow you to create a volume on your container which comprises of files holding the secrets in your managed kubernetes secret -```yaml -volumes: - - name: secrets-volume-name # The name of the volume under which secrets will be stored - secret: - secretName: managed-secret # managed secret name -```` - -You can then mount this volume to the container's filesystem so that your deployment can access the files containing the managed secrets - -```yaml -volumeMounts: - - name: secrets-volume-name - mountPath: /etc/secrets - readOnly: true -``` - -Example usage in a deployment - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-deployment - labels: - app: nginx -spec: - replicas: 1 - selector: - matchLabels: - app: nginx - template: - metadata: - labels: - app: nginx - spec: - containers: - - name: nginx - image: nginx:1.14.2 - volumeMounts: - - name: secrets-volume-name - mountPath: /etc/secrets - readOnly: true - ports: - - containerPort: 80 - volumes: - - name: secrets-volume-name - secret: - secretName: managed-secret # <- managed secrets -``` - - - -The definition file of the Kubernetes secret for the CA certificate can be structured like the following: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: custom-ca-certificate -type: Opaque -stringData: - ca.crt: | - -----BEGIN CERTIFICATE----- - MIIEZzCCA0+gAwIBAgIUDk9+HZcMHppiNy0TvoBg8/aMEqIwDQYJKoZIhvcNAQEL - ... - BQAwDTELMAkGA1UEChMCUEgwHhcNMjQxMDI1MTU0MjAzWhcNMjUxMDI1MjE0MjAz - -----END CERTIFICATE----- -``` - -### Auto redeployment - -Deployments using managed secrets don't reload automatically on updates, so they may use outdated secrets unless manually redeployed. -To address this, we added functionality to automatically redeploy your deployment when its managed secret updates. - -#### Enabling auto redeploy - -To enable auto redeployment you simply have to add the following annotation to the deployment that consumes a managed secret - -```yaml -secrets.infisical.com/auto-reload: "true" -``` - - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-deployment - labels: - app: nginx - annotations: - secrets.infisical.com/auto-reload: "true" # <- redeployment annotation -spec: - replicas: 1 - selector: - matchLabels: - app: nginx - template: - metadata: - labels: - app: nginx - spec: - containers: - - name: nginx - image: nginx:1.14.2 - envFrom: - - secretRef: - name: managed-secret - ports: - - containerPort: 80 -``` - - - #### How it works - When a secret change occurs, the operator will check to see which deployments are using the operator-managed Kubernetes secret that received the update. - Then, for each deployment that has this annotation present, a rolling update will be triggered. - - -## Push Secrets to Infisical - - -### Example usage - -Below is a sample InfisicalPushSecret CRD that pushes secrets defined in a Kubernetes secret to Infisical. - -After filling out the fields in the InfisicalPushSecret CRD, you can apply it directly to your cluster. - -Before applying the InfisicalPushSecret CRD, you need to create a Kubernetes secret containing the secrets you want to push to Infisical. An example can be seen below the InfisicalPushSecret CRD. - -```yaml infisical-push-secret.yaml - apiVersion: secrets.infisical.com/v1alpha1 - kind: InfisicalPushSecret - metadata: - name: infisical-push-secret-demo - spec: - resyncInterval: 1m - hostAPI: https://app.infisical.com/api - - # Optional, defaults to no replacement. - updatePolicy: Replace # If set to replace, existing secrets inside Infisical will be replaced by the value of the PushSecret on sync. - - # Optional, defaults to no deletion. - deletionPolicy: Delete # If set to delete, the secret(s) inside Infisical managed by the operator, will be deleted if the InfisicalPushSecret CRD is deleted. - - destination: - projectId: - environmentSlug: - secretsPath: - - push: - secret: - secretName: push-secret-demo # Secret CRD - secretNamespace: default - - # Only have one authentication method defined or you are likely to run into authentication issues. - # Remove all except one authentication method. - authentication: - awsIamAuth: - identityId: - azureAuth: - identityId: - gcpIamAuth: - identityId: - serviceAccountKeyFilePath: - gcpIdTokenAuth: - identityId: - kubernetesAuth: - identityId: - serviceAccountRef: - name: - namespace: - universalAuth: - credentialsRef: - secretName: # universal-auth-credentials - secretNamespace: # default -``` - -```yaml source-secret.yaml - apiVersion: v1 - kind: Secret - metadata: - name: push-secret-demo - namespace: default - stringData: # can also be "data", but needs to be base64 encoded - API_KEY: some-api-key - DATABASE_URL: postgres://127.0.0.1:5432 - ENCRYPTION_KEY: fabcc12-a22-facbaa4-11aa568aab -``` - -```bash - kubectl apply -f source-secret.yaml -``` - -After applying the soruce-secret.yaml file, you are ready to apply the InfisicalPushSecret CRD. - -```bash - kubectl apply -f infisical-push-secret.yaml -``` - -After applying the InfisicalPushSecret CRD, you should notice that the secrets you have defined in your source-secret.yaml file have been pushed to your specified destination in Infisical. - - -### InfisicalPushSecret CRD properties - - - If you are fetching secrets from a self-hosted instance of Infisical set the value of `hostAPI` to - ` https://your-self-hosted-instace.com/api` - - When `hostAPI` is not defined the operator fetches secrets from Infisical Cloud. - - - If you have installed your Infisical instance within the same cluster as the Infisical operator, you can optionally access the Infisical backend's service directly without having to route through the public internet. - To achieve this, use the following address for the hostAPI field: - - ``` bash - http://..svc.cluster.local:4000/api - ``` - - Make sure to replace `` and `` with the appropriate values for your backend service and namespace. - - - - - - - The `resyncInterval` is a string-formatted duration that defines the time between each resync. - - The format of the field is `[duration][unit]` where `duration` is a number and `unit` is a string representing the unit of time. - - The following units are supported: - - `s` for seconds (must be at least 5 seconds) - - `m` for minutes - - `h` for hours - - `d` for days - - `w` for weeks - - The default value is `1m` (1 minute). - - Valid intervals examples: - ```yaml - resyncInterval: 5s # 10 seconds - resyncInterval: 10s # 10 seconds - resyncInterval: 5m # 5 minutes - resyncInterval: 1h # 1 hour - resyncInterval: 1d # 1 day - ``` - - - - - The field is optional and will default to `None` if not defined. - - The update policy defines how the operator should handle conflicting secrets when pushing secrets to Infisical. - - Valid values are `None` and `Replace`. - - Behavior of each policy: - - `None`: The operator will not override existing secrets in Infisical. If a secret with the same key already exists, the operator will skip pushing that secret, and the secret will not be managed by the operator. - - `Replace`: The operator will replace existing secrets in Infisical with the new secrets. If a secret with the same key already exists, the operator will update the secret with the new value. - - ```yaml - spec: - updatePolicy: Replace - ``` - - - - - This field is optional and will default to `None` if not defined. - - The deletion policy defines what the operator should do in case the InfisicalPushSecret CRD is deleted. - - Valid values are `None` and `Delete`. - - Behavior of each policy: - - `None`: The operator will not delete the secrets in Infisical when the InfisicalPushSecret CRD is deleted. - - `Delete`: The operator will delete the secrets in Infisical that are managed by the operator when the InfisicalPushSecret CRD is deleted. - - ```yaml - spec: - deletionPolicy: Delete - ``` - - - - The `destination` field is used to specify where you want to create the secrets in Infisical. The required fields are `projectId`, `environmentSlug`, and `secretsPath`. - - ```yaml - spec: - destination: - projectId: - environmentSlug: - secretsPath: - ``` - - - The project ID where you want to create the secrets in Infisical. - - - - The environment slug where you want to create the secrets in Infisical. - - - - The path where you want to create the secrets in Infisical. The root path is `/`. - - - - - - The `push` field is used to define what you want to push to Infisical. Currently the operator only supports pushing Kubernetes secrets to Infisical. An example of the `push` field is shown below. - - - - - The `secret` field is used to define the Kubernetes secret you want to push to Infisical. The required fields are `secretName` and `secretNamespace`. - - - - Example usage of the `push.secret` field: - - ```yaml infisical-push-secret.yaml - push: - secret: - secretName: push-secret-demo - secretNamespace: default - ``` - - ```yaml push-secret-demo.yaml - apiVersion: v1 - kind: Secret - metadata: - name: push-secret-demo - namespace: default - # Pass in the secrets you wish to push to Infisical - stringData: - API_KEY: some-api-key - DATABASE_URL: postgres://127.0.0.1:5432 - ENCRYPTION_KEY: fabcc12-a22-facbaa4-11aa568aab - ``` - - - - - - - The `authentication` field dictates which authentication method to use when pushing secrets to Infisical. - The available authentication methods are `universalAuth`, `kubernetesAuth`, `awsIamAuth`, `azureAuth`, `gcpIdTokenAuth`, and `gcpIamAuth`. - - - - The universal authentication method is one of the easiest ways to get started with Infisical. Universal Auth works anywhere and is not tied to any specific cloud provider. - [Read more about Universal Auth](/documentation/platform/identities/universal-auth). - - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - `credentialsRef`: The name and namespace of the Kubernetes secret that stores the service token. - - `credentialsRef.secretName`: The name of the Kubernetes secret. - - `credentialsRef.secretNamespace`: The namespace of the Kubernetes secret. - - Example: - - ```yaml - # infisical-push-secret.yaml - spec: - universalAuth: - credentialsRef: - secretName: - secretNamespace: - ``` - - ```yaml - # machine-identity-credentials.yaml - apiVersion: v1 - kind: Secret - metadata: - name: universal-auth-credentials - type: Opaque - stringData: - clientId: - clientSecret: - ``` - - - - The Kubernetes machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within a Kubernetes environment. - [Read more about Kubernetes Auth](/documentation/platform/identities/kubernetes-auth). - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - `serviceAccountRef`: The name and namespace of the service account that will be used to authenticate with Infisical. - - `serviceAccountRef.name`: The name of the service account. - - `serviceAccountRef.namespace`: The namespace of the service account. - - Example: - - ```yaml - spec: - kubernetesAuth: - identityId: - serviceAccountRef: - name: - namespace: - ``` - - - - The AWS IAM machine identity authentication method is used to authenticate with Infisical. - [Read more about AWS IAM Auth](/documentation/platform/identities/aws-auth). - - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - Example: - - ```yaml - spec: - authentication: - awsIamAuth: - identityId: - ``` - - - - The AWS IAM machine identity authentication method is used to authenticate with Infisical. Azure Auth can only be used from within an Azure environment. - [Read more about Azure Auth](/documentation/platform/identities/azure-auth). - - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - Example: - - ```yaml - spec: - authentication: - azureAuth: - identityId: - ``` - - - The GCP IAM machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used both within and outside GCP environments. - [Read more about Azure Auth](/documentation/platform/identities/gcp-auth). - - - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - `serviceAccountKeyFilePath`: The path to the GCP service account key file. - - Example: - - ```yaml - spec: - gcpIamAuth: - identityId: - serviceAccountKeyFilePath: - ``` - - - The GCP ID Token machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within GCP environments. - [Read more about Azure Auth](/documentation/platform/identities/gcp-auth). - - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - Example: - - ```yaml - spec: - gcpIdTokenAuth: - identityId: - ``` - - - - - - - This block defines the TLS settings to use for connecting to the Infisical - instance. - - Fields: - - This block defines the reference to the CA certificate to use for connecting to the Infisical instance with SSL/TLS. - - Valid fields: - - `secretName`: The name of the Kubernetes secret containing the CA certificate to use for connecting to the Infisical instance with SSL/TLS. - - `secretNamespace`: The namespace of the Kubernetes secret containing the CA certificate to use for connecting to the Infisical instance with SSL/TLS. - - `key`: The name of the key in the Kubernetes secret which contains the value of the CA certificate to use for connecting to the Infisical instance with SSL/TLS. - - Example: - - ```yaml - tls: - caRef: - secretName: custom-ca-certificate - secretNamespace: default - key: ca.crt - ``` - - - - - -### Applying the InfisicalPushSecret CRD to your cluster - -Once you have configured the `InfisicalPushSecret` CRD with the required fields, you can apply it to your cluster. -After applying, you should notice that the secrets have been pushed to Infisical. - -```bash - kubectl apply -f source-push-secret.yaml # The secret that you're referencing in the InfisicalPushSecret CRD push.secret field - kubectl apply -f example-infisical-push-secret-crd.yaml # The InfisicalPushSecret CRD itself -``` - -## Sync Dynamic Secrets to your cluster - -### Example usage - -The example below demonstrates a sample InfisicalDynamicSecret CRD that creates a dynamic secret lease in Infisical, and syncs the lease to your Kubernetes cluster. - -```yaml dynamic-secret-crd.yaml -apiVersion: secrets.infisical.com/v1alpha1 -kind: InfisicalDynamicSecret -metadata: - name: infisicaldynamicsecret -spec: - hostAPI: https://app.infisical.com/api # Optional, defaults to https://app.infisical.com/api - - dynamicSecret: - secretName: - projectId: - secretsPath: # Root directory is / - environmentSlug: - - # Lease revocation policy defines what should happen to leases created by the operator if the CRD is deleted. - # If set to "Revoke", leases will be revoked when the InfisicalDynamicSecret CRD is deleted. - leaseRevocationPolicy: Revoke - - # Lease TTL defines how long the lease should last for the dynamic secret. - # This value must be less than 1 day, and if a max TTL is defined on the dynamic secret, it must be below the max TTL. - leaseTTL: 1m - - # A reference to the secret that the dynamic secret lease should be stored in. - # If the secret doesn't exist, it will automatically be created. - managedSecretReference: - secretName: - secretNamespace: default # Must be the same namespace as the InfisicalDynamicSecret CRD. - creationPolicy: Orphan - - # Only have one authentication method defined or you are likely to run into authentication issues. - # Remove all except one authentication method. - authentication: - awsIamAuth: - identityId: - azureAuth: - identityId: - gcpIamAuth: - identityId: - serviceAccountKeyFilePath: - gcpIdTokenAuth: - identityId: - kubernetesAuth: - identityId: - serviceAccountRef: - name: - namespace: - universalAuth: - credentialsRef: - secretName: # universal-auth-credentials - secretNamespace: # default -``` - -Apply the InfisicalDynamicSecret CRD to your cluster. -```bash -kubectl apply -f dynamic-secret-crd.yaml -``` - -After applying the InfisicalDynamicSecret CRD, you should notice that the dynamic secret lease has been created in Infisical and synced to your Kubernetes cluster. You can verify that the lease has been created by doing: -```bash -kubectl get secret -o yaml -``` - -After getting the secret, you should should see that the secret has data that contains the lease credentials. -```yaml -apiVersion: v1 -data: - DB_PASSWORD: VHhETjZ4c2xsTXpOSWdPYW5LLlRyNEc2alVKYml6WiQjQS0tNTdodyREM3ZLZWtYSi4hTkdyS0F+TVFsLU9CSA== - DB_USERNAME: cHg4Z0dJTUVBcHdtTW1aYnV3ZWRsekJRRll6cW4wFEE= -kind: Secret -# ..... -``` - -### InfisicalDynamicSecret CRD properties - - - If you are fetching secrets from a self-hosted instance of Infisical set the value of `hostAPI` to - ` https://your-self-hosted-instace.com/api` - - When `hostAPI` is not defined the operator fetches secrets from Infisical Cloud. - - - If you have installed your Infisical instance within the same cluster as the Infisical operator, you can optionally access the Infisical backend's service directly without having to route through the public internet. - To achieve this, use the following address for the hostAPI field: - - ``` bash - http://..svc.cluster.local:4000/api - ``` - - Make sure to replace `` and `` with the appropriate values for your backend service and namespace. - - - - - - The `leaseTTL` is a string-formatted duration that defines the time the lease should last for the dynamic secret. - - The format of the field is `[duration][unit]` where `duration` is a number and `unit` is a string representing the unit of time. - - The following units are supported: - - `s` for seconds (must be at least 5 seconds) - - `m` for minutes - - `h` for hours - - `d` for days - - - The lease duration at most be 1 day (24 hours). And the TTL must be less than the max TTL defined on the dynamic secret. - - - - - The `managedSecretReference` field is used to define the Kubernetes secret where the dynamic secret lease should be stored. The required fields are `secretName` and `secretNamespace`. - - ```yaml - spec: - managedSecretReference: - secretName: - secretNamespace: default - ``` - - - The name of the Kubernetes secret where the dynamic secret lease should be stored. - - - - The namespace of the Kubernetes secret where the dynamic secret lease should be stored. - - - - Creation polices allow you to control whether or not owner references should be added to the managed Kubernetes secret that is generated by the Infisical operator. - This is useful for tools such as ArgoCD, where every resource requires an owner reference; otherwise, it will be pruned automatically. - - #### Available options - - `Orphan` (default) - - `Owner` - - - When creation policy is set to `Owner`, the `InfisicalSecret` CRD must be in - the same namespace as where the managed kubernetes secret. - - - This field is optional. - - - - Override the default Opaque type for managed secrets with this field. Useful for creating kubernetes.io/dockerconfigjson secrets. - - This field is optional. - - - - - - - The field is optional and will default to `None` if not defined. - - The lease revocation policy defines what the operator should do with the leases created by the operator, when the InfisicalDynamicSecret CRD is deleted. - - Valid values are `None` and `Revoke`. - - Behavior of each policy: - - `None`: The operator will not override existing secrets in Infisical. If a secret with the same key already exists, the operator will skip pushing that secret, and the secret will not be managed by the operator. - - `Revoke`: The operator will revoke the leases created by the operator when the InfisicalDynamicSecret CRD is deleted. - - ```yaml - spec: - leaseRevocationPolicy: Revoke - ``` - - - - The `dynamicSecret` field is used to specify which dynamic secret to create leases for. The required fields are `secretName`, `projectId`, `secretsPath`, and `environmentSlug`. - - ```yaml - spec: - dynamicSecret: - secretName: - projectId: - environmentSlug: - secretsPath: - ``` - - - The name of the dynamic secret. - - - - The project ID of where the dynamic secret is stored in Infisical. - - - - The environment slug of where the dynamic secret is stored in Infisical. - - - - The path of where the dynamic secret is stored in Infisical. The root path is `/`. - - - - - - - The `authentication` field dictates which authentication method to use when pushing secrets to Infisical. - The available authentication methods are `universalAuth`, `kubernetesAuth`, `awsIamAuth`, `azureAuth`, `gcpIdTokenAuth`, and `gcpIamAuth`. - - - - The universal authentication method is one of the easiest ways to get started with Infisical. Universal Auth works anywhere and is not tied to any specific cloud provider. - [Read more about Universal Auth](/documentation/platform/identities/universal-auth). - - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - `credentialsRef`: The name and namespace of the Kubernetes secret that stores the service token. - - `credentialsRef.secretName`: The name of the Kubernetes secret. - - `credentialsRef.secretNamespace`: The namespace of the Kubernetes secret. - - Example: - - ```yaml - # infisical-push-secret.yaml - spec: - universalAuth: - credentialsRef: - secretName: - secretNamespace: - ``` - - ```yaml - # machine-identity-credentials.yaml - apiVersion: v1 - kind: Secret - metadata: - name: universal-auth-credentials - type: Opaque - stringData: - clientId: - clientSecret: - ``` - - - - The Kubernetes machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within a Kubernetes environment. - [Read more about Kubernetes Auth](/documentation/platform/identities/kubernetes-auth). - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - `serviceAccountRef`: The name and namespace of the service account that will be used to authenticate with Infisical. - - `serviceAccountRef.name`: The name of the service account. - - `serviceAccountRef.namespace`: The namespace of the service account. - - Example: - - ```yaml - spec: - kubernetesAuth: - identityId: - serviceAccountRef: - name: - namespace: - ``` - - - - The AWS IAM machine identity authentication method is used to authenticate with Infisical. - [Read more about AWS IAM Auth](/documentation/platform/identities/aws-auth). - - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - Example: - - ```yaml - spec: - authentication: - awsIamAuth: - identityId: - ``` - - - - The AWS IAM machine identity authentication method is used to authenticate with Infisical. Azure Auth can only be used from within an Azure environment. - [Read more about Azure Auth](/documentation/platform/identities/azure-auth). - - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - Example: - - ```yaml - spec: - authentication: - azureAuth: - identityId: - ``` - - - The GCP IAM machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used both within and outside GCP environments. - [Read more about Azure Auth](/documentation/platform/identities/gcp-auth). - - - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - `serviceAccountKeyFilePath`: The path to the GCP service account key file. - - Example: - - ```yaml - spec: - gcpIamAuth: - identityId: - serviceAccountKeyFilePath: - ``` - - - The GCP ID Token machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within GCP environments. - [Read more about Azure Auth](/documentation/platform/identities/gcp-auth). - - Valid fields: - - `identityId`: The identity ID of the machine identity you created. - - Example: - - ```yaml - spec: - gcpIdTokenAuth: - identityId: - ``` - - - - - - - This block defines the TLS settings to use for connecting to the Infisical - instance. - - Fields: - - This block defines the reference to the CA certificate to use for connecting to the Infisical instance with SSL/TLS. - - Valid fields: - - `secretName`: The name of the Kubernetes secret containing the CA certificate to use for connecting to the Infisical instance with SSL/TLS. - - `secretNamespace`: The namespace of the Kubernetes secret containing the CA certificate to use for connecting to the Infisical instance with SSL/TLS. - - `key`: The name of the key in the Kubernetes secret which contains the value of the CA certificate to use for connecting to the Infisical instance with SSL/TLS. - - Example: - - ```yaml - tls: - caRef: - secretName: custom-ca-certificate - secretNamespace: default - key: ca.crt - ``` - - - - - -### Applying the InfisicalDynamicSecret CRD to your cluster - -Once you have configured the `InfisicalDynamicSecret` CRD with the required fields, you can apply it to your cluster. After applying, you should notice that a lease has been created in Infisical and synced to your Kubernetes cluster. - -```bash -kubectl apply -f dynamic-secret-crd.yaml -``` - -### Auto redeployment - -Deployments using managed secrets don't reload automatically on updates, so they may use outdated secrets unless manually redeployed. -To address this, we added functionality to automatically redeploy your deployment when its managed secret updates. - -#### Enabling auto redeploy - -To enable auto redeployment you simply have to add the following annotation to the deployment that consumes a managed secret - -```yaml -secrets.infisical.com/auto-reload: "true" -``` - - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: nginx-deployment - labels: - app: nginx - annotations: - secrets.infisical.com/auto-reload: "true" # <- redeployment annotation -spec: - replicas: 1 - selector: - matchLabels: - app: nginx - template: - metadata: - labels: - app: nginx - spec: - containers: - - name: nginx - image: nginx:1.14.2 - envFrom: - - secretRef: - name: managed-secret # The name of your managed secret, the same that you're using in your InfisicalDynamicSecret CRD (spec.managedSecretReference.secretName) - ports: - - containerPort: 80 -``` - - - #### How it works - When the lease changes, the operator will check to see which deployments are using the operator-managed Kubernetes secret that received the update. - Then, for each deployment that has this annotation present, a rolling update will be triggered. A redeployment won't happen if the lease is renewed, only if it's recreated. - - - -## Connecting to instances with private/self-signed certificate - -To connect to Infisical instances behind a private/self-signed certificate, you can configure the TLS settings in the CRD -to point to a CA certificate stored in a Kubernetes secret resource. - -```yaml ---- -spec: - hostAPI: https://app.infisical.com/api - tls: - caRef: - secretName: custom-ca-certificate - secretNamespace: default - key: ca.crt ---- -``` - - -## Global configuration - -To configure global settings that will apply to all instances of `InfisicalSecret`, you can define these configurations in a Kubernetes ConfigMap. -For example, you can configure all `InfisicalSecret` instances to fetch secrets from a single backend API without specifying the `hostAPI` parameter for each instance. - -### Available global properties - -| Property | Description | Default value | -| -------- | --------------------------------------------------------------------------------- | ----------------------------- | -| hostAPI | If `hostAPI` in `InfisicalSecret` instance is left empty, this value will be used | https://app.infisical.com/api | - -### Applying global configurations - -All global configurations must reside in a Kubernetes ConfigMap named `infisical-config` in the namespace `infisical-operator-system`. -To apply global configuration to the operator, copy the following yaml into `infisical-config.yaml` file. - -```yaml infisical-config.yaml -apiVersion: v1 -kind: Namespace -metadata: - name: infisical-operator-system ---- -apiVersion: v1 -kind: ConfigMap -metadata: - name: infisical-config - namespace: infisical-operator-system -data: - hostAPI: https://example.com/api # <-- global hostAPI -``` - -Then apply this change via kubectl by running the following - -```bash -kubectl apply -f infisical-config.yaml -``` - -## Troubleshoot operator - -If the operator is unable to fetch secrets from the API, it will not affect the managed Kubernetes secret. -It will continue attempting to reconnect to the API indefinitely. -The InfisicalSecret resource uses the `status.conditions` field to report its current state and any errors encountered. - -```yaml -$ kubectl get infisicalSecrets -NAME AGE -infisicalsecret-sample 12s - -$ kubectl describe infisicalSecret infisicalsecret-sample -... -Spec: -... -Status: - Conditions: - Last Transition Time: 2022-12-18T04:29:09Z - Message: Infisical controller has located the Infisical token in provided Kubernetes secret - Reason: OK - Status: True - Type: secrets.infisical.com/LoadedInfisicalToken - Last Transition Time: 2022-12-18T04:29:10Z - Message: Failed to update secret because: 400 Bad Request - Reason: Error - Status: False - Type: secrets.infisical.com/ReadyToSyncSecrets -Events: -``` - -## Uninstall Operator - -The managed secret created by the operator will not be deleted when the operator is uninstalled. - - - - Install Infisical Helm repository - ```bash - helm uninstall - ``` - - - ``` - kubectl delete -f https://raw.githubusercontent.com/Infisical/infisical/main/k8-operator/kubectl-install/install-secrets-operator.yaml - ``` - - - -## Useful Articles - -- [Managing secrets in OpenShift with Infisical](https://xphyr.net/post/infisical_ocp/) diff --git a/docs/integrations/platforms/kubernetes/infisical-dynamic-secret-crd.mdx b/docs/integrations/platforms/kubernetes/infisical-dynamic-secret-crd.mdx new file mode 100644 index 000000000..52df2ceb0 --- /dev/null +++ b/docs/integrations/platforms/kubernetes/infisical-dynamic-secret-crd.mdx @@ -0,0 +1,425 @@ +--- +sidebarTitle: "InfisicalDynamicSecret CRD" +title: "Using the InfisicalDynamicSecret CRD" +description: "Learn how to use the InfisicalDynamicSecret CRD to create dynamic secret leases in Infisical and sync them to your Kubernetes cluster." +--- + +## Sync Dynamic Secrets to your cluster + +### Example usage + +The example below demonstrates a sample InfisicalDynamicSecret CRD that creates a dynamic secret lease in Infisical, and syncs the lease to your Kubernetes cluster. + +```yaml dynamic-secret-crd.yaml +apiVersion: secrets.infisical.com/v1alpha1 +kind: InfisicalDynamicSecret +metadata: + name: infisicaldynamicsecret +spec: + hostAPI: https://app.infisical.com/api # Optional, defaults to https://app.infisical.com/api + + dynamicSecret: + secretName: + projectId: + secretsPath: # Root directory is / + environmentSlug: + + # Lease revocation policy defines what should happen to leases created by the operator if the CRD is deleted. + # If set to "Revoke", leases will be revoked when the InfisicalDynamicSecret CRD is deleted. + leaseRevocationPolicy: Revoke + + # Lease TTL defines how long the lease should last for the dynamic secret. + # This value must be less than 1 day, and if a max TTL is defined on the dynamic secret, it must be below the max TTL. + leaseTTL: 1m + + # A reference to the secret that the dynamic secret lease should be stored in. + # If the secret doesn't exist, it will automatically be created. + managedSecretReference: + secretName: + secretNamespace: default # Must be the same namespace as the InfisicalDynamicSecret CRD. + creationPolicy: Orphan + + # Only have one authentication method defined or you are likely to run into authentication issues. + # Remove all except one authentication method. + authentication: + awsIamAuth: + identityId: + azureAuth: + identityId: + gcpIamAuth: + identityId: + serviceAccountKeyFilePath: + gcpIdTokenAuth: + identityId: + kubernetesAuth: + identityId: + serviceAccountRef: + name: + namespace: + universalAuth: + credentialsRef: + secretName: # universal-auth-credentials + secretNamespace: # default +``` + +Apply the InfisicalDynamicSecret CRD to your cluster. +```bash +kubectl apply -f dynamic-secret-crd.yaml +``` + +After applying the InfisicalDynamicSecret CRD, you should notice that the dynamic secret lease has been created in Infisical and synced to your Kubernetes cluster. You can verify that the lease has been created by doing: +```bash +kubectl get secret -o yaml +``` + +After getting the secret, you should should see that the secret has data that contains the lease credentials. +```yaml +apiVersion: v1 +data: + DB_PASSWORD: VHhETjZ4c2xsTXpOSWdPYW5LLlRyNEc2alVKYml6WiQjQS0tNTdodyREM3ZLZWtYSi4hTkdyS0F+TVFsLU9CSA== + DB_USERNAME: cHg4Z0dJTUVBcHdtTW1aYnV3ZWRsekJRRll6cW4wFEE= +kind: Secret +# ..... +``` + +### InfisicalDynamicSecret CRD properties + + + If you are fetching secrets from a self-hosted instance of Infisical set the value of `hostAPI` to + ` https://your-self-hosted-instace.com/api` + + When `hostAPI` is not defined the operator fetches secrets from Infisical Cloud. + + + If you have installed your Infisical instance within the same cluster as the Infisical operator, you can optionally access the Infisical backend's service directly without having to route through the public internet. + To achieve this, use the following address for the hostAPI field: + + ``` bash + http://..svc.cluster.local:4000/api + ``` + + Make sure to replace `` and `` with the appropriate values for your backend service and namespace. + + + + + + The `leaseTTL` is a string-formatted duration that defines the time the lease should last for the dynamic secret. + + The format of the field is `[duration][unit]` where `duration` is a number and `unit` is a string representing the unit of time. + + The following units are supported: + - `s` for seconds (must be at least 5 seconds) + - `m` for minutes + - `h` for hours + - `d` for days + + + The lease duration at most be 1 day (24 hours). And the TTL must be less than the max TTL defined on the dynamic secret. + + + + + The `managedSecretReference` field is used to define the Kubernetes secret where the dynamic secret lease should be stored. The required fields are `secretName` and `secretNamespace`. + + ```yaml + spec: + managedSecretReference: + secretName: + secretNamespace: default + ``` + + + The name of the Kubernetes secret where the dynamic secret lease should be stored. + + + + The namespace of the Kubernetes secret where the dynamic secret lease should be stored. + + + + Creation polices allow you to control whether or not owner references should be added to the managed Kubernetes secret that is generated by the Infisical operator. + This is useful for tools such as ArgoCD, where every resource requires an owner reference; otherwise, it will be pruned automatically. + + #### Available options + - `Orphan` (default) + - `Owner` + + + When creation policy is set to `Owner`, the `InfisicalSecret` CRD must be in + the same namespace as where the managed kubernetes secret. + + + This field is optional. + + + + Override the default Opaque type for managed secrets with this field. Useful for creating kubernetes.io/dockerconfigjson secrets. + + This field is optional. + + + + + + + The field is optional and will default to `None` if not defined. + + The lease revocation policy defines what the operator should do with the leases created by the operator, when the InfisicalDynamicSecret CRD is deleted. + + Valid values are `None` and `Revoke`. + + Behavior of each policy: + - `None`: The operator will not override existing secrets in Infisical. If a secret with the same key already exists, the operator will skip pushing that secret, and the secret will not be managed by the operator. + - `Revoke`: The operator will revoke the leases created by the operator when the InfisicalDynamicSecret CRD is deleted. + + ```yaml + spec: + leaseRevocationPolicy: Revoke + ``` + + + + The `dynamicSecret` field is used to specify which dynamic secret to create leases for. The required fields are `secretName`, `projectId`, `secretsPath`, and `environmentSlug`. + + ```yaml + spec: + dynamicSecret: + secretName: + projectId: + environmentSlug: + secretsPath: + ``` + + + The name of the dynamic secret. + + + + The project ID of where the dynamic secret is stored in Infisical. + + + + The environment slug of where the dynamic secret is stored in Infisical. + + + + The path of where the dynamic secret is stored in Infisical. The root path is `/`. + + + + + + + The `authentication` field dictates which authentication method to use when pushing secrets to Infisical. + The available authentication methods are `universalAuth`, `kubernetesAuth`, `awsIamAuth`, `azureAuth`, `gcpIdTokenAuth`, and `gcpIamAuth`. + + + + The universal authentication method is one of the easiest ways to get started with Infisical. Universal Auth works anywhere and is not tied to any specific cloud provider. + [Read more about Universal Auth](/documentation/platform/identities/universal-auth). + + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + - `credentialsRef`: The name and namespace of the Kubernetes secret that stores the service token. + - `credentialsRef.secretName`: The name of the Kubernetes secret. + - `credentialsRef.secretNamespace`: The namespace of the Kubernetes secret. + + Example: + + ```yaml + # infisical-push-secret.yaml + spec: + universalAuth: + credentialsRef: + secretName: + secretNamespace: + ``` + + ```yaml + # machine-identity-credentials.yaml + apiVersion: v1 + kind: Secret + metadata: + name: universal-auth-credentials + type: Opaque + stringData: + clientId: + clientSecret: + ``` + + + + The Kubernetes machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within a Kubernetes environment. + [Read more about Kubernetes Auth](/documentation/platform/identities/kubernetes-auth). + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + - `serviceAccountRef`: The name and namespace of the service account that will be used to authenticate with Infisical. + - `serviceAccountRef.name`: The name of the service account. + - `serviceAccountRef.namespace`: The namespace of the service account. + + Example: + + ```yaml + spec: + kubernetesAuth: + identityId: + serviceAccountRef: + name: + namespace: + ``` + + + + The AWS IAM machine identity authentication method is used to authenticate with Infisical. + [Read more about AWS IAM Auth](/documentation/platform/identities/aws-auth). + + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + + Example: + + ```yaml + spec: + authentication: + awsIamAuth: + identityId: + ``` + + + + The AWS IAM machine identity authentication method is used to authenticate with Infisical. Azure Auth can only be used from within an Azure environment. + [Read more about Azure Auth](/documentation/platform/identities/azure-auth). + + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + + Example: + + ```yaml + spec: + authentication: + azureAuth: + identityId: + ``` + + + The GCP IAM machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used both within and outside GCP environments. + [Read more about Azure Auth](/documentation/platform/identities/gcp-auth). + + + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + - `serviceAccountKeyFilePath`: The path to the GCP service account key file. + + Example: + + ```yaml + spec: + gcpIamAuth: + identityId: + serviceAccountKeyFilePath: + ``` + + + The GCP ID Token machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within GCP environments. + [Read more about Azure Auth](/documentation/platform/identities/gcp-auth). + + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + + Example: + + ```yaml + spec: + gcpIdTokenAuth: + identityId: + ``` + + + + + + + This block defines the TLS settings to use for connecting to the Infisical + instance. + + Fields: + + This block defines the reference to the CA certificate to use for connecting to the Infisical instance with SSL/TLS. + + Valid fields: + - `secretName`: The name of the Kubernetes secret containing the CA certificate to use for connecting to the Infisical instance with SSL/TLS. + - `secretNamespace`: The namespace of the Kubernetes secret containing the CA certificate to use for connecting to the Infisical instance with SSL/TLS. + - `key`: The name of the key in the Kubernetes secret which contains the value of the CA certificate to use for connecting to the Infisical instance with SSL/TLS. + + Example: + + ```yaml + tls: + caRef: + secretName: custom-ca-certificate + secretNamespace: default + key: ca.crt + ``` + + + + + +### Applying the InfisicalDynamicSecret CRD to your cluster + +Once you have configured the `InfisicalDynamicSecret` CRD with the required fields, you can apply it to your cluster. After applying, you should notice that a lease has been created in Infisical and synced to your Kubernetes cluster. + +```bash +kubectl apply -f dynamic-secret-crd.yaml +``` + +### Auto redeployment + +Deployments using managed secrets don't reload automatically on updates, so they may use outdated secrets unless manually redeployed. +To address this, we added functionality to automatically redeploy your deployment when its managed secret updates. + +#### Enabling auto redeploy + +To enable auto redeployment you simply have to add the following annotation to the deployment that consumes a managed secret + +```yaml +secrets.infisical.com/auto-reload: "true" +``` + + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-deployment + labels: + app: nginx + annotations: + secrets.infisical.com/auto-reload: "true" # <- redeployment annotation +spec: + replicas: 1 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.14.2 + envFrom: + - secretRef: + name: managed-secret # The name of your managed secret, the same that you're using in your InfisicalDynamicSecret CRD (spec.managedSecretReference.secretName) + ports: + - containerPort: 80 +``` + + + #### How it works + When the lease changes, the operator will check to see which deployments are using the operator-managed Kubernetes secret that received the update. + Then, for each deployment that has this annotation present, a rolling update will be triggered. A redeployment won't happen if the lease is renewed, only if it's recreated. + diff --git a/docs/integrations/platforms/kubernetes/infisical-push-secret-crd.mdx b/docs/integrations/platforms/kubernetes/infisical-push-secret-crd.mdx new file mode 100644 index 000000000..eb226e7b8 --- /dev/null +++ b/docs/integrations/platforms/kubernetes/infisical-push-secret-crd.mdx @@ -0,0 +1,400 @@ +--- +sidebarTitle: "InfisicalPushSecret CRD" +title: "Using the InfisicalPushSecret CRD" +description: "Learn how to use the InfisicalPushSecret CRD to push and manage secrets in Infisical." +--- + + +## Push Secrets to Infisical + + +### Example usage + +Below is a sample InfisicalPushSecret CRD that pushes secrets defined in a Kubernetes secret to Infisical. + +After filling out the fields in the InfisicalPushSecret CRD, you can apply it directly to your cluster. + +Before applying the InfisicalPushSecret CRD, you need to create a Kubernetes secret containing the secrets you want to push to Infisical. An example can be seen below the InfisicalPushSecret CRD. + +```yaml infisical-push-secret.yaml + apiVersion: secrets.infisical.com/v1alpha1 + kind: InfisicalPushSecret + metadata: + name: infisical-push-secret-demo + spec: + resyncInterval: 1m + hostAPI: https://app.infisical.com/api + + # Optional, defaults to no replacement. + updatePolicy: Replace # If set to replace, existing secrets inside Infisical will be replaced by the value of the PushSecret on sync. + + # Optional, defaults to no deletion. + deletionPolicy: Delete # If set to delete, the secret(s) inside Infisical managed by the operator, will be deleted if the InfisicalPushSecret CRD is deleted. + + destination: + projectId: + environmentSlug: + secretsPath: + + push: + secret: + secretName: push-secret-demo # Secret CRD + secretNamespace: default + + # Only have one authentication method defined or you are likely to run into authentication issues. + # Remove all except one authentication method. + authentication: + awsIamAuth: + identityId: + azureAuth: + identityId: + gcpIamAuth: + identityId: + serviceAccountKeyFilePath: + gcpIdTokenAuth: + identityId: + kubernetesAuth: + identityId: + serviceAccountRef: + name: + namespace: + universalAuth: + credentialsRef: + secretName: # universal-auth-credentials + secretNamespace: # default +``` + +```yaml source-secret.yaml + apiVersion: v1 + kind: Secret + metadata: + name: push-secret-demo + namespace: default + stringData: # can also be "data", but needs to be base64 encoded + API_KEY: some-api-key + DATABASE_URL: postgres://127.0.0.1:5432 + ENCRYPTION_KEY: fabcc12-a22-facbaa4-11aa568aab +``` + +```bash + kubectl apply -f source-secret.yaml +``` + +After applying the soruce-secret.yaml file, you are ready to apply the InfisicalPushSecret CRD. + +```bash + kubectl apply -f infisical-push-secret.yaml +``` + +After applying the InfisicalPushSecret CRD, you should notice that the secrets you have defined in your source-secret.yaml file have been pushed to your specified destination in Infisical. + + +### InfisicalPushSecret CRD properties + + + If you are fetching secrets from a self-hosted instance of Infisical set the value of `hostAPI` to + ` https://your-self-hosted-instace.com/api` + + When `hostAPI` is not defined the operator fetches secrets from Infisical Cloud. + + + If you have installed your Infisical instance within the same cluster as the Infisical operator, you can optionally access the Infisical backend's service directly without having to route through the public internet. + To achieve this, use the following address for the hostAPI field: + + ``` bash + http://..svc.cluster.local:4000/api + ``` + + Make sure to replace `` and `` with the appropriate values for your backend service and namespace. + + + + + + + The `resyncInterval` is a string-formatted duration that defines the time between each resync. + + The format of the field is `[duration][unit]` where `duration` is a number and `unit` is a string representing the unit of time. + + The following units are supported: + - `s` for seconds (must be at least 5 seconds) + - `m` for minutes + - `h` for hours + - `d` for days + - `w` for weeks + + The default value is `1m` (1 minute). + + Valid intervals examples: + ```yaml + resyncInterval: 5s # 10 seconds + resyncInterval: 10s # 10 seconds + resyncInterval: 5m # 5 minutes + resyncInterval: 1h # 1 hour + resyncInterval: 1d # 1 day + ``` + + + + + The field is optional and will default to `None` if not defined. + + The update policy defines how the operator should handle conflicting secrets when pushing secrets to Infisical. + + Valid values are `None` and `Replace`. + + Behavior of each policy: + - `None`: The operator will not override existing secrets in Infisical. If a secret with the same key already exists, the operator will skip pushing that secret, and the secret will not be managed by the operator. + - `Replace`: The operator will replace existing secrets in Infisical with the new secrets. If a secret with the same key already exists, the operator will update the secret with the new value. + + ```yaml + spec: + updatePolicy: Replace + ``` + + + + + This field is optional and will default to `None` if not defined. + + The deletion policy defines what the operator should do in case the InfisicalPushSecret CRD is deleted. + + Valid values are `None` and `Delete`. + + Behavior of each policy: + - `None`: The operator will not delete the secrets in Infisical when the InfisicalPushSecret CRD is deleted. + - `Delete`: The operator will delete the secrets in Infisical that are managed by the operator when the InfisicalPushSecret CRD is deleted. + + ```yaml + spec: + deletionPolicy: Delete + ``` + + + + The `destination` field is used to specify where you want to create the secrets in Infisical. The required fields are `projectId`, `environmentSlug`, and `secretsPath`. + + ```yaml + spec: + destination: + projectId: + environmentSlug: + secretsPath: + ``` + + + The project ID where you want to create the secrets in Infisical. + + + + The environment slug where you want to create the secrets in Infisical. + + + + The path where you want to create the secrets in Infisical. The root path is `/`. + + + + + + The `push` field is used to define what you want to push to Infisical. Currently the operator only supports pushing Kubernetes secrets to Infisical. An example of the `push` field is shown below. + + + + + The `secret` field is used to define the Kubernetes secret you want to push to Infisical. The required fields are `secretName` and `secretNamespace`. + + + + Example usage of the `push.secret` field: + + ```yaml infisical-push-secret.yaml + push: + secret: + secretName: push-secret-demo + secretNamespace: default + ``` + + ```yaml push-secret-demo.yaml + apiVersion: v1 + kind: Secret + metadata: + name: push-secret-demo + namespace: default + # Pass in the secrets you wish to push to Infisical + stringData: + API_KEY: some-api-key + DATABASE_URL: postgres://127.0.0.1:5432 + ENCRYPTION_KEY: fabcc12-a22-facbaa4-11aa568aab + ``` + + + + + + + The `authentication` field dictates which authentication method to use when pushing secrets to Infisical. + The available authentication methods are `universalAuth`, `kubernetesAuth`, `awsIamAuth`, `azureAuth`, `gcpIdTokenAuth`, and `gcpIamAuth`. + + + + The universal authentication method is one of the easiest ways to get started with Infisical. Universal Auth works anywhere and is not tied to any specific cloud provider. + [Read more about Universal Auth](/documentation/platform/identities/universal-auth). + + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + - `credentialsRef`: The name and namespace of the Kubernetes secret that stores the service token. + - `credentialsRef.secretName`: The name of the Kubernetes secret. + - `credentialsRef.secretNamespace`: The namespace of the Kubernetes secret. + + Example: + + ```yaml + # infisical-push-secret.yaml + spec: + universalAuth: + credentialsRef: + secretName: + secretNamespace: + ``` + + ```yaml + # machine-identity-credentials.yaml + apiVersion: v1 + kind: Secret + metadata: + name: universal-auth-credentials + type: Opaque + stringData: + clientId: + clientSecret: + ``` + + + + The Kubernetes machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within a Kubernetes environment. + [Read more about Kubernetes Auth](/documentation/platform/identities/kubernetes-auth). + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + - `serviceAccountRef`: The name and namespace of the service account that will be used to authenticate with Infisical. + - `serviceAccountRef.name`: The name of the service account. + - `serviceAccountRef.namespace`: The namespace of the service account. + + Example: + + ```yaml + spec: + kubernetesAuth: + identityId: + serviceAccountRef: + name: + namespace: + ``` + + + + The AWS IAM machine identity authentication method is used to authenticate with Infisical. + [Read more about AWS IAM Auth](/documentation/platform/identities/aws-auth). + + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + + Example: + + ```yaml + spec: + authentication: + awsIamAuth: + identityId: + ``` + + + + The AWS IAM machine identity authentication method is used to authenticate with Infisical. Azure Auth can only be used from within an Azure environment. + [Read more about Azure Auth](/documentation/platform/identities/azure-auth). + + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + + Example: + + ```yaml + spec: + authentication: + azureAuth: + identityId: + ``` + + + The GCP IAM machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used both within and outside GCP environments. + [Read more about Azure Auth](/documentation/platform/identities/gcp-auth). + + + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + - `serviceAccountKeyFilePath`: The path to the GCP service account key file. + + Example: + + ```yaml + spec: + gcpIamAuth: + identityId: + serviceAccountKeyFilePath: + ``` + + + The GCP ID Token machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within GCP environments. + [Read more about Azure Auth](/documentation/platform/identities/gcp-auth). + + Valid fields: + - `identityId`: The identity ID of the machine identity you created. + + Example: + + ```yaml + spec: + gcpIdTokenAuth: + identityId: + ``` + + + + + + + This block defines the TLS settings to use for connecting to the Infisical + instance. + + Fields: + + This block defines the reference to the CA certificate to use for connecting to the Infisical instance with SSL/TLS. + + Valid fields: + - `secretName`: The name of the Kubernetes secret containing the CA certificate to use for connecting to the Infisical instance with SSL/TLS. + - `secretNamespace`: The namespace of the Kubernetes secret containing the CA certificate to use for connecting to the Infisical instance with SSL/TLS. + - `key`: The name of the key in the Kubernetes secret which contains the value of the CA certificate to use for connecting to the Infisical instance with SSL/TLS. + + Example: + + ```yaml + tls: + caRef: + secretName: custom-ca-certificate + secretNamespace: default + key: ca.crt + ``` + + + + + +### Applying the InfisicalPushSecret CRD to your cluster + +Once you have configured the `InfisicalPushSecret` CRD with the required fields, you can apply it to your cluster. +After applying, you should notice that the secrets have been pushed to Infisical. + +```bash + kubectl apply -f source-push-secret.yaml # The secret that you're referencing in the InfisicalPushSecret CRD push.secret field + kubectl apply -f example-infisical-push-secret-crd.yaml # The InfisicalPushSecret CRD itself +``` \ No newline at end of file diff --git a/docs/integrations/platforms/kubernetes/infisical-secret-crd.mdx b/docs/integrations/platforms/kubernetes/infisical-secret-crd.mdx new file mode 100644 index 000000000..4efda567e --- /dev/null +++ b/docs/integrations/platforms/kubernetes/infisical-secret-crd.mdx @@ -0,0 +1,965 @@ +--- +sidebarTitle: "InfisicalSecret CRD" +title: "Using the InfisicalSecret CRD" +description: "Learn how to use the InfisicalSecret CRD to fetch secrets from Infisical and store them in a Kubernetes secret" +--- + +## Sync Infisical Secrets to your cluster + +Once you have installed the operator to your cluster, you'll need to create a `InfisicalSecret` custom resource definition (CRD). + +```yaml example-infisical-secret-crd.yaml +apiVersion: secrets.infisical.com/v1alpha1 +kind: InfisicalSecret +metadata: + name: infisicalsecret-sample + labels: + label-to-be-passed-to-managed-secret: sample-value + annotations: + example.com/annotation-to-be-passed-to-managed-secret: "sample-value" +spec: + hostAPI: https://app.infisical.com/api + resyncInterval: 10 + authentication: + # Make sure to only have 1 authentication method defined, serviceToken/universalAuth. + # If you have multiple authentication methods defined, it may cause issues. + + # (Deprecated) Service Token Auth + serviceToken: + serviceTokenSecretReference: + secretName: service-token + secretNamespace: default + secretsScope: + envSlug: + secretsPath: + recursive: true + + # Universal Auth + universalAuth: + secretsScope: + projectSlug: new-ob-em + envSlug: dev # "dev", "staging", "prod", etc.. + secretsPath: "/" # Root is "/" + recursive: true # Whether or not to use recursive mode (Fetches all secrets in an environment from a given secret path, and all folders inside the path) / defaults to false + credentialsRef: + secretName: universal-auth-credentials + secretNamespace: default + + # Native Kubernetes Auth + kubernetesAuth: + identityId: + serviceAccountRef: + name: + namespace: + + # secretsScope is identical to the secrets scope in the universalAuth field in this sample. + secretsScope: + projectSlug: your-project-slug + envSlug: prod + secretsPath: "/path" + recursive: true + + # AWS IAM Auth + awsIamAuth: + identityId: + + # secretsScope is identical to the secrets scope in the universalAuth field in this sample. + secretsScope: + projectSlug: your-project-slug + envSlug: prod + secretsPath: "/path" + recursive: true + + # Azure Auth + azureAuth: + identityId: + resource: https://management.azure.com/&client_id=CLIENT_ID # (Optional) This is the Azure resource that you want to access. For example, "https://management.azure.com/". If no value is provided, it will default to "https://management.azure.com/" + + # secretsScope is identical to the secrets scope in the universalAuth field in this sample. + secretsScope: + projectSlug: your-project-slug + envSlug: prod + secretsPath: "/path" + recursive: true + + # GCP ID Token Auth + gcpIdTokenAuth: + identityId: + + # secretsScope is identical to the secrets scope in the universalAuth field in this sample. + secretsScope: + projectSlug: your-project-slug + envSlug: prod + secretsPath: "/path" + recursive: true + + # GCP IAM Auth + gcpIamAuth: + identityId: + + # secretsScope is identical to the secrets scope in the universalAuth field in this sample. + secretsScope: + projectSlug: your-project-slug + envSlug: prod + secretsPath: "/path" + recursive: true + + managedSecretReference: + secretName: managed-secret + secretNamespace: default + creationPolicy: "Orphan" ## Owner | Orphan + # template: + # includeAllSecrets: true + # data: + # CUSTOM_KEY: "{{ .KEY.SecretPath }} {{ .KEY.Value }}" + # secretType: kubernetes.io/dockerconfigjson +``` + +### InfisicalSecret CRD properties + + + If you are fetching secrets from a self-hosted instance of Infisical set the value of `hostAPI` to + ` https://your-self-hosted-instace.com/api` + +When `hostAPI` is not defined the operator fetches secrets from Infisical Cloud. + + + If you have installed your Infisical instance within the same cluster as the Infisical operator, you can optionally access the Infisical backend's service directly without having to route through the public internet. + To achieve this, use the following address for the hostAPI field: + + ``` bash + http://..svc.cluster.local:4000/api + ``` + + Make sure to replace `` and `` with the appropriate values for your backend service and namespace. + + + + + + This property defines the time in seconds between each secret re-sync from + Infisical. Shorter time between re-syncs will require higher rate limits only + available on paid plans. Default re-sync interval is every 1 minute. + + + + This block defines the TLS settings to use for connecting to the Infisical + instance. + + + + This block defines the reference to the CA certificate to use for connecting + to the Infisical instance with SSL/TLS. + + + + The name of the Kubernetes secret containing the CA certificate to use for + connecting to the Infisical instance with SSL/TLS. + + + + The namespace of the Kubernetes secret containing the CA certificate to use + for connecting to the Infisical instance with SSL/TLS. + + + + The name of the key in the Kubernetes secret which contains the value of the + CA certificate to use for connecting to the Infisical instance with SSL/TLS. + + + + This block defines the method that will be used to authenticate with Infisical + so that secrets can be fetched + + + + The universal machine identity authentication method is used to authenticate with Infisical. The client ID and client secret needs to be stored in a Kubernetes secret. This block defines the reference to the name and namespace of secret that stores these credentials. + + + + You need to create a machine identity, and give it access to the project(s) you want to interact with. You can [read more about machine identities here](/documentation/platform/identities/universal-auth). + + + Once you have created your machine identity and added it to your project(s), you will need to create a Kubernetes secret containing the identity credentials. + To quickly create a Kubernetes secret containing the identity credentials, you can run the command below. + + Make sure you replace `` with the identity client ID and `` with the identity client secret. + + ``` bash + kubectl create secret generic universal-auth-credentials --from-literal=clientId="" --from-literal=clientSecret="" + ``` + + + + Once the secret is created, add the `secretName` and `secretNamespace` of the secret that was just created under `authentication.universalAuth.credentialsRef` field in the InfisicalSecret resource. + + + + + + Make sure to also populate the `secretsScope` field with the project slug + _`projectSlug`_, environment slug _`envSlug`_, and secrets path + _`secretsPath`_ that you want to fetch secrets from. Please see the example + below. + + +## Example + +```yaml +apiVersion: secrets.infisical.com/v1alpha1 +kind: InfisicalSecret +metadata: + name: infisicalsecret-sample-crd +spec: + authentication: + universalAuth: + secretsScope: + projectSlug: # <-- project slug + envSlug: # "dev", "staging", "prod", etc.. + secretsPath: "" # Root is "/" + credentialsRef: + secretName: universal-auth-credentials # <-- name of the Kubernetes secret that stores our machine identity credentials + secretNamespace: default # <-- namespace of the Kubernetes secret that stores our machine identity credentials + ... +``` + + + + + The Kubernetes machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within a Kubernetes environment. + + + + 1.1. Start by creating a service account in your Kubernetes cluster that will be used by Infisical to authenticate with the Kubernetes API Server. + + ```yaml infisical-service-account.yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: infisical-auth + namespace: default + + ``` + + ``` + kubectl apply -f infisical-service-account.yaml + ``` + + 1.2. Bind the service account to the `system:auth-delegator` cluster role. As described [here](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#other-component-roles), this role allows delegated authentication and authorization checks, specifically for Infisical to access the [TokenReview API](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/). You can apply the following configuration file: + + ```yaml cluster-role-binding.yaml + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: role-tokenreview-binding + namespace: default + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: system:auth-delegator + subjects: + - kind: ServiceAccount + name: infisical-auth + namespace: default + ``` + + ``` + kubectl apply -f cluster-role-binding.yaml + ``` + + 1.3. Next, create a long-lived service account JWT token (i.e. the token reviewer JWT token) for the service account using this configuration file for a new `Secret` resource: + + ```yaml service-account-token.yaml + apiVersion: v1 + kind: Secret + type: kubernetes.io/service-account-token + metadata: + name: infisical-auth-token + annotations: + kubernetes.io/service-account.name: "infisical-auth" + ``` + + + ``` + kubectl apply -f service-account-token.yaml + ``` + + 1.4. Link the secret in step 1.3 to the service account in step 1.1: + + ```bash + kubectl patch serviceaccount infisical-auth -p '{"secrets": [{"name": "infisical-auth-token"}]}' -n default + ``` + + 1.5. Finally, retrieve the token reviewer JWT token from the secret. + + ```bash + kubectl get secret infisical-auth-token -n default -o=jsonpath='{.data.token}' | base64 --decode + ``` + + Keep this JWT token handy as you will need it for the **Token Reviewer JWT** field when configuring the Kubernetes Auth authentication method for the identity in step 2. + + + + + To create an identity, head to your Organization Settings > Access Control > Machine Identities and press **Create identity**. + + ![identities organization](/images/platform/identities/identities-org.png) + + When creating an identity, you specify an organization level [role](/documentation/platform/role-based-access-controls) for it to assume; you can configure roles in Organization Settings > Access Control > Organization Roles. + + ![identities organization create](/images/platform/identities/identities-org-create.png) + + Now input a few details for your new identity. Here's some guidance for each field: + + - Name (required): A friendly name for the identity. + - Role (required): A role from the **Organization Roles** tab for the identity to assume. The organization role assigned will determine what organization level resources this identity can have access to. + + Once you've created an identity, you'll be prompted to configure the authentication method for it. Here, select **Kubernetes Auth**. + + + To learn more about each field of the Kubernetes native authentication method, see step 2 of [guide](/documentation/platform/identities/kubernetes-auth#guide). + + + ![identities organization create auth method](/images/platform/identities/identities-org-create-kubernetes-auth-method.png) + + + + + To allow the operator to use the given identity to access secrets, you will need to add the identity to project(s) that you would like to grant it access to. + + To do this, head over to the project you want to add the identity to and go to Project Settings > Access Control > Machine Identities and press **Add identity**. + + Next, select the identity you want to add to the project and the project level role you want to allow it to assume. The project role assigned will determine what project level resources this identity can have access to. + + ![identities project](/images/platform/identities/identities-project.png) + + ![identities project create](/images/platform/identities/identities-project-create.png) + + + + Once you have created your machine identity and added it to your project(s), you will need to add the identity ID to your InfisicalSecret resource. + In the `authentication.kubernetesAuth.identityId` field, add the identity ID of the machine identity you created. + See the example below for more details. + + + Add the service account details from the previous steps under `authentication.kubernetesAuth.serviceAccountRef`. + Here you will need to enter the name and namespace of the service account. + The example below shows a complete InfisicalSecret resource with all required fields defined. + + + + + + Make sure to also populate the `secretsScope` field with the project slug + _`projectSlug`_, environment slug _`envSlug`_, and secrets path + _`secretsPath`_ that you want to fetch secrets from. Please see the example + below. + + +## Example + +```yaml example-kubernetes-auth.yaml +apiVersion: secrets.infisical.com/v1alpha1 +kind: InfisicalSecret +metadata: + name: infisicalsecret-sample-crd +spec: + authentication: + kubernetesAuth: + identityId: + serviceAccountRef: + name: + namespace: + + # secretsScope is identical to the secrets scope in the universalAuth field in this sample. + secretsScope: + projectSlug: your-project-slug + envSlug: prod + secretsPath: "/path" + recursive: true + ... +``` + + + + + The AWS IAM machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within an AWS environment like an EC2 or a Lambda function. + + + + You need to create a machine identity, and give it access to the project(s) you want to interact with. You can [read more about AWS machine identities here](/documentation/platform/identities/aws-auth). + + + Once you have created your machine identity and added it to your project(s), you will need to add the identity ID to your InfisicalSecret resource. In the `authentication.awsIamAuth.identityId` field, add the identity ID of the machine identity you created. See the example below for more details. + + + + + + Make sure to also populate the `secretsScope` field with the project slug + _`projectSlug`_, environment slug _`envSlug`_, and secrets path + _`secretsPath`_ that you want to fetch secrets from. Please see the example + below. + + +## Example + +```yaml example-aws-iam-auth.yaml +apiVersion: secrets.infisical.com/v1alpha1 +kind: InfisicalSecret +metadata: + name: infisicalsecret-sample-crd +spec: + authentication: + awsIamAuth: + identityId: + + # secretsScope is identical to the secrets scope in the universalAuth field in this sample. + secretsScope: + projectSlug: your-project-slug + envSlug: prod + secretsPath: "/path" + recursive: true + ... +``` + + + + + The Azure machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within an Azure environment. + + + + You need to create a machine identity, and give it access to the project(s) you want to interact with. You can [read more about Azure machine identities here](/documentation/platform/identities/azure-auth). + + + Once you have created your machine identity and added it to your project(s), you will need to add the identity ID to your InfisicalSecret resource. In the `authentication.azureAuth.identityId` field, add the identity ID of the machine identity you created. See the example below for more details. + + + + + + Make sure to also populate the `secretsScope` field with the project slug + _`projectSlug`_, environment slug _`envSlug`_, and secrets path + _`secretsPath`_ that you want to fetch secrets from. Please see the example + below. + + +## Example + +```yaml example-azure-auth.yaml +apiVersion: secrets.infisical.com/v1alpha1 +kind: InfisicalSecret +metadata: + name: infisicalsecret-sample-crd +spec: + authentication: + azureAuth: + identityId: + + # secretsScope is identical to the secrets scope in the universalAuth field in this sample. + secretsScope: + projectSlug: your-project-slug + envSlug: prod + secretsPath: "/path" + recursive: true + ... +``` + + + + + The GCP ID Token machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used within GCP environments. + + + + You need to create a machine identity, and give it access to the project(s) you want to interact with. You can [read more about GCP machine identities here](/documentation/platform/identities/gcp-auth). + + + Once you have created your machine identity and added it to your project(s), you will need to add the identity ID to your InfisicalSecret resource. In the `authentication.gcpIdTokenAuth.identityId` field, add the identity ID of the machine identity you created. See the example below for more details. + + + + + + Make sure to also populate the `secretsScope` field with the project slug + _`projectSlug`_, environment slug _`envSlug`_, and secrets path + _`secretsPath`_ that you want to fetch secrets from. Please see the example + below. + + +## Example + +```yaml example-gcp-id-token-auth.yaml +apiVersion: secrets.infisical.com/v1alpha1 +kind: InfisicalSecret +metadata: + name: infisicalsecret-sample-crd +spec: + authentication: + gcpIdTokenAuth: + identityId: + + # secretsScope is identical to the secrets scope in the universalAuth field in this sample. + secretsScope: + projectSlug: your-project-slug + envSlug: prod + secretsPath: "/path" + recursive: true + ... +``` + + + + + The GCP IAM machine identity authentication method is used to authenticate with Infisical. The identity ID is stored in a field in the InfisicalSecret resource. This authentication method can only be used both within and outside GCP environments. + + + + You need to create a machine identity, and give it access to the project(s) you want to interact with. You can [read more about GCP machine identities here](/documentation/platform/identities/gcp-auth). + + + Once you have created your machine identity and added it to your project(s), you will need to add the identity ID to your InfisicalSecret resource. In the `authentication.gcpIamAuth.identityId` field, add the identity ID of the machine identity you created. + You'll also need to add the service account key file path to your InfisicalSecret resource. In the `authentication.gcpIamAuth.serviceAccountKeyFilePath` field, add the path to your service account key file path. Please see the example below for more details. + + + + + + Make sure to also populate the `secretsScope` field with the project slug + _`projectSlug`_, environment slug _`envSlug`_, and secrets path + _`secretsPath`_ that you want to fetch secrets from. Please see the example + below. + + +## Example + +```yaml example-gcp-id-token-auth.yaml +apiVersion: secrets.infisical.com/v1alpha1 +kind: InfisicalSecret +metadata: + name: infisicalsecret-sample-crd +spec: + authentication: + gcpIamAuth: + identityId: + serviceAccountKeyFilePath: "/path/to-service-account-key-file-path.json" + + # secretsScope is identical to the secrets scope in the universalAuth field in this sample. + secretsScope: + projectSlug: your-project-slug + envSlug: prod + secretsPath: "/path" + recursive: true + ... +``` + + + + + +The service token required to authenticate with Infisical needs to be stored in a Kubernetes secret. This block defines the reference to the name and namespace of secret that stores this service token. +Follow the instructions below to create and store the service token in a Kubernetes secrets and reference it in your CRD. + +#### 1. Generate service token + +You can generate a [service token](../../documentation/platform/token) for an Infisical project by heading over to the Infisical dashboard then to Project Settings. + +#### 2. Create Kubernetes secret containing service token + +Once you have generated the service token, you will need to create a Kubernetes secret containing the service token you generated. +To quickly create a Kubernetes secret containing the generated service token, you can run the command below. Make sure you replace `` with your service token. + +```bash +kubectl create secret generic service-token --from-literal=infisicalToken="" +``` + +#### 3. Add reference for the Kubernetes secret containing service token + +Once the secret is created, add the name and namespace of the secret that was just created under `authentication.serviceToken.serviceTokenSecretReference` field in the InfisicalSecret resource. + +{" "} + + + Make sure to also populate the `secretsScope` field with the, environment slug + _`envSlug`_, and secrets path _`secretsPath`_ that you want to fetch secrets + from. Please see the example below. + + +## Example + +```yaml +apiVersion: secrets.infisical.com/v1alpha1 +kind: InfisicalSecret +metadata: + name: infisicalsecret-sample-crd +spec: + authentication: + serviceToken: + serviceTokenSecretReference: + secretName: service-token # <-- name of the Kubernetes secret that stores our service token + secretNamespace: option # <-- namespace of the Kubernetes secret that stores our service token + secretsScope: + envSlug: # "dev", "staging", "prod", etc.. + secretsPath: # Root is "/" + ... +``` + + + + +The `managedSecretReference` field is used to define the target location for storing secrets retrieved from an Infisical project. +This field requires specifying both the name and namespace of the Kubernetes secret that will hold these secrets. +The Infisical operator will automatically create the Kubernetes secret with the specified name/namespace and keep it continuously updated. + +Note: The managed secret be should be created in the same namespace as the deployment that will use it. + + + +The name of the managed Kubernetes secret to be created + + +The namespace of the managed Kubernetes secret to be created. + + +Override the default Opaque type for managed secrets with this field. Useful for creating kubernetes.io/dockerconfigjson secrets. + + +Templates enable you to transform data from Infisical before storing it as a Kubernetes Secret. + + +When set to true, this option injects all secrets retrieved from Infisical into your configuration. +Secrets defined in the template will override the automatically injected secrets. + + +Define secret keys and their corresponding templates. +Each data value uses a Golang template with access to all secrets retrieved from the specified scope. + +Secrets are structured as follows: + +```golang +type TemplateSecret struct { + Value string `json:"value"` + SecretPath string `json:"secretPath"` +} +``` + +#### Example template configuration: + +```golang + managedSecretReference: + secretName: managed-secret + secretNamespace: default + template: + includeAllSecrets: true + data: + NEW_KEY: "{{ .KEY1.SecretPath }} {{ .KEY1.Value }}" +``` + +When you run the following command: + +```bash +kubectl get secret managed-secret -o jsonpath='{.data}' +``` + +You'll receive Kubernetes secrets output that includes the NEW_KEY: + +```bash +{... "KEY":"d29ybGQ=","NEW_KEY":"LyBoZWxsbw=="} +``` + +When you set `includeAllSecrets` as `false` the Kubernetes secrets outputs will be: + +```bash +{"NEW_KEY":"LyBoZWxsbw=="} +``` + + + +Creation polices allow you to control whether or not owner references should be added to the managed Kubernetes secret that is generated by the Infisical operator. +This is useful for tools such as ArgoCD, where every resource requires an owner reference; otherwise, it will be pruned automatically. + +#### Available options + +- `Orphan` (default) +- `Owner` + + + When creation policy is set to `Owner`, the `InfisicalSecret` CRD must be in + the same namespace as where the managed kubernetes secret. + + + + +### Propagating labels & annotations + +The operator will transfer all labels & annotations present on the `InfisicalSecret` CRD to the managed Kubernetes secret to be created. +Thus, if a specific label is required on the resulting secret, it can be applied as demonstrated in the following example: + + +```yaml +apiVersion: secrets.infisical.com/v1alpha1 +kind: InfisicalSecret +metadata: + name: infisicalsecret-sample + labels: + label-to-be-passed-to-managed-secret: sample-value + annotations: + example.com/annotation-to-be-passed-to-managed-secret: "sample-value" +spec: + .. + authentication: + ... + managedSecretReference: + ... +``` + +This would result in the following managed secret to be created: + +```yaml +apiVersion: v1 +data: ... +kind: Secret +metadata: + annotations: + example.com/annotation-to-be-passed-to-managed-secret: sample-value + secrets.infisical.com/version: W/"3f1-ZyOSsrCLGSkAhhCkY2USPu2ivRw" + labels: + label-to-be-passed-to-managed-secret: sample-value + name: managed-token + namespace: default +type: Opaque +``` + + + +### Apply the InfisicalSecret CRD to your cluster + +Once you have configured the InfisicalSecret CRD with the required fields, you can apply it to your cluster. +After applying, you should notice that the managed secret has been created in the desired namespace your specified. + +``` +kubectl apply -f example-infisical-secret-crd.yaml +``` + +### Verify managed secret creation + +To verify that the operator has successfully created the managed secret, you can check the secrets in the namespace that was specified. + +```bash +# Verify managed secret is created +kubectl get secrets -n +``` + + + The Infisical secrets will be synced and stored into the managed secret every + 1 minutes. + + +### Using managed secret in your deployment + +Incorporating the managed secret created by the operator into your deployment can be achieved through several methods. +Here, we will highlight three of the most common ways to utilize it. Learn more about Kubernetes secrets [here](https://kubernetes.io/docs/concepts/configuration/secret/) + + + This will take all the secrets from your managed secret and expose them to your container + +````yaml + envFrom: + - secretRef: + name: managed-secret # managed secret name + ``` + + Example usage in a deployment + ```yaml + apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-deployment + labels: + app: nginx +spec: + replicas: 1 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.14.2 + envFrom: + - secretRef: + name: managed-secret # <- name of managed secret + ports: + - containerPort: 80 +```` + + + + + This will allow you to select individual secrets by key name from your managed secret and expose them to your container + + ```yaml + env: + - name: SECRET_NAME # The environment variable's name which is made available in the container + valueFrom: + secretKeyRef: + name: managed-secret # managed secret name + key: SOME_SECRET_KEY # The name of the key which exists in the managed secret + ``` + +Example usage in a deployment + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: +name: nginx-deployment +labels: +app: nginx +spec: +replicas: 1 +selector: +matchLabels: +app: nginx +template: +metadata: +labels: +app: nginx +spec: +containers: - name: nginx +image: nginx:1.14.2 +env: - name: STRIPE_API_SECRET +valueFrom: +secretKeyRef: +name: managed-secret # <- name of managed secret +key: STRIPE_API_SECRET +ports: - containerPort: 80 + +``` + + + + +This will allow you to create a volume on your container which comprises of files holding the secrets in your managed kubernetes secret +```yaml +volumes: + - name: secrets-volume-name # The name of the volume under which secrets will be stored + secret: + secretName: managed-secret # managed secret name +```` + +You can then mount this volume to the container's filesystem so that your deployment can access the files containing the managed secrets + +```yaml +volumeMounts: + - name: secrets-volume-name + mountPath: /etc/secrets + readOnly: true +``` + +Example usage in a deployment + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-deployment + labels: + app: nginx +spec: + replicas: 1 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.14.2 + volumeMounts: + - name: secrets-volume-name + mountPath: /etc/secrets + readOnly: true + ports: + - containerPort: 80 + volumes: + - name: secrets-volume-name + secret: + secretName: managed-secret # <- managed secrets +``` + + + +The definition file of the Kubernetes secret for the CA certificate can be structured like the following: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: custom-ca-certificate +type: Opaque +stringData: + ca.crt: | + -----BEGIN CERTIFICATE----- + MIIEZzCCA0+gAwIBAgIUDk9+HZcMHppiNy0TvoBg8/aMEqIwDQYJKoZIhvcNAQEL + ... + BQAwDTELMAkGA1UEChMCUEgwHhcNMjQxMDI1MTU0MjAzWhcNMjUxMDI1MjE0MjAz + -----END CERTIFICATE----- +``` + +### Auto redeployment + +Deployments using managed secrets don't reload automatically on updates, so they may use outdated secrets unless manually redeployed. +To address this, we added functionality to automatically redeploy your deployment when its managed secret updates. + +#### Enabling auto redeploy + +To enable auto redeployment you simply have to add the following annotation to the deployment that consumes a managed secret + +```yaml +secrets.infisical.com/auto-reload: "true" +``` + + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-deployment + labels: + app: nginx + annotations: + secrets.infisical.com/auto-reload: "true" # <- redeployment annotation +spec: + replicas: 1 + selector: + matchLabels: + app: nginx + template: + metadata: + labels: + app: nginx + spec: + containers: + - name: nginx + image: nginx:1.14.2 + envFrom: + - secretRef: + name: managed-secret + ports: + - containerPort: 80 +``` + + + #### How it works + When a secret change occurs, the operator will check to see which deployments are using the operator-managed Kubernetes secret that received the update. + Then, for each deployment that has this annotation present, a rolling update will be triggered. + \ No newline at end of file diff --git a/docs/integrations/platforms/kubernetes/overview.mdx b/docs/integrations/platforms/kubernetes/overview.mdx new file mode 100644 index 000000000..1b502a6a8 --- /dev/null +++ b/docs/integrations/platforms/kubernetes/overview.mdx @@ -0,0 +1,202 @@ +--- +title: "Kubernetes Operator" +sidebarTitle: "Overview" +description: "How to use Infisical to inject secrets into Kubernetes clusters." +--- + +![title](../../../images/k8-diagram.png) + +The Infisical Secrets Operator is a Kubernetes controller that retrieves secrets from Infisical and stores them in a designated cluster. +It uses an `InfisicalSecret` resource to specify authentication and storage methods. +The operator continuously updates secrets and can also reload dependent deployments automatically. + + + 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/). + + +## Install Operator + +The operator can be install via [Helm](https://helm.sh). Helm is a package manager for Kubernetes that allows you to define, install, and upgrade Kubernetes applications. + + +**Install the latest Infisical Helm repository** +```bash +helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/' + +helm repo update +``` + +**Install the Helm chart** + +To select a specific version, view the application versions [here](https://hub.docker.com/r/infisical/kubernetes-operator/tags) and chart versions [here](https://cloudsmith.io/~infisical/repos/helm-charts/packages/detail/helm/secrets-operator/#versions) + +```bash +helm install --generate-name infisical-helm-charts/secrets-operator +``` + +```bash +# Example installing app version v0.2.0 and chart version 0.1.4 +helm install --generate-name infisical-helm-charts/secrets-operator --version=0.1.4 --set controllerManager.manager.image.tag=v0.2.0 +``` + +**Namespace-scoped Installation** + +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 + +**Note**: For multiple namespace-scoped installations, only the first installation should install CRDs. Subsequent installations should set `installCRDs: false` to avoid conflicts. + +```bash +# First namespace installation (with CRDs) +helm install operator-namespace1 infisical-helm-charts/secrets-operator \ + --namespace first-namespace \ + --set scopedNamespace=first-namespace \ + --set scopedRBAC=true + +# Subsequent namespace installations +helm install operator-namespace2 infisical-helm-charts/secrets-operator \ + --namespace another-namespace \ + --set scopedNamespace=another-namespace \ + --set scopedRBAC=true \ + --set installCRDs=false +``` + +When scoped to a namespace, the operator will: + +- Only watch InfisicalSecrets in the specified namespace +- Only create/update Kubernetes secrets in that namespace +- Only access deployments in that namespace + +The default configuration gives cluster-wide access: + +```yaml +installCRDs: true # Install CRDs (set to false for additional namespace installations) +scopedNamespace: "" # Empty for cluster-wide access +scopedRBAC: false # Cluster-wide permissions +``` + +If you want to install operators in multiple namespaces simultaneously: +- Make sure to set `installCRDs: false` for all but one of the installations to avoid conflicts, as CRDs are cluster-wide resources. +- Use unique release names for each installation (e.g., operator-namespace1, operator-namespace2). + + +## Custom Resource Definitions (CRD's) + +Currently the operator supports the following CRD's. We are constantly expanding the functionality of the operator, and this list will be updated as new CRD's are added. + +1. [InfisicalSecret](/integrations/platforms/kubernetes/infisical-secret-crd): Sync secrets from Infisical to a Kubernetes secret. +2. [InfisicalPushSecret](/integrations/platforms/kubernetes/infisical-push-secret-crd): Push secrets from a Kubernetes secret to Infisical. +3. [InfisicalDynamicSecret](/integrations/platforms/kubernetes/infisical-dynamic-secret-crd): Sync dynamic secrets and create leases automatically in Kubernetes. + +## Connecting to instances with private/self-signed certificate + +To connect to Infisical instances behind a private/self-signed certificate, you can configure the TLS settings in the CRD +to point to a CA certificate stored in a Kubernetes secret resource. + +```yaml +--- +spec: + hostAPI: https://app.infisical.com/api + tls: + caRef: + secretName: custom-ca-certificate + secretNamespace: default + key: ca.crt +--- +``` + + +## Global configuration + +To configure global settings that will apply to all instances of `InfisicalSecret`, you can define these configurations in a Kubernetes ConfigMap. +For example, you can configure all `InfisicalSecret` instances to fetch secrets from a single backend API without specifying the `hostAPI` parameter for each instance. + +### Available global properties + +| Property | Description | Default value | +| -------- | --------------------------------------------------------------------------------- | ----------------------------- | +| hostAPI | If `hostAPI` in `InfisicalSecret` instance is left empty, this value will be used | https://app.infisical.com/api | + +### Applying global configurations + +All global configurations must reside in a Kubernetes ConfigMap named `infisical-config` in the namespace `infisical-operator-system`. +To apply global configuration to the operator, copy the following yaml into `infisical-config.yaml` file. + +```yaml infisical-config.yaml +apiVersion: v1 +kind: Namespace +metadata: + name: infisical-operator-system +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: infisical-config + namespace: infisical-operator-system +data: + hostAPI: https://example.com/api # <-- global hostAPI +``` + +Then apply this change via kubectl by running the following + +```bash +kubectl apply -f infisical-config.yaml +``` + +## Troubleshoot operator + +If the operator is unable to fetch secrets from the API, it will not affect the managed Kubernetes secret. +It will continue attempting to reconnect to the API indefinitely. +The InfisicalSecret resource uses the `status.conditions` field to report its current state and any errors encountered. + +```yaml +$ kubectl get infisicalSecrets +NAME AGE +infisicalsecret-sample 12s + +$ kubectl describe infisicalSecret infisicalsecret-sample +... +Spec: +... +Status: + Conditions: + Last Transition Time: 2022-12-18T04:29:09Z + Message: Infisical controller has located the Infisical token in provided Kubernetes secret + Reason: OK + Status: True + Type: secrets.infisical.com/LoadedInfisicalToken + Last Transition Time: 2022-12-18T04:29:10Z + Message: Failed to update secret because: 400 Bad Request + Reason: Error + Status: False + Type: secrets.infisical.com/ReadyToSyncSecrets +Events: +``` + +## Uninstall Operator + +The managed secret created by the operator will not be deleted when the operator is uninstalled. + + + + Install Infisical Helm repository + ```bash + helm uninstall + ``` + + + ``` + kubectl delete -f https://raw.githubusercontent.com/Infisical/infisical/main/k8-operator/kubectl-install/install-secrets-operator.yaml + ``` + + + +## Useful Articles + +- [Managing secrets in OpenShift with Infisical](https://xphyr.net/post/infisical_ocp/) diff --git a/docs/mint.json b/docs/mint.json index 69ad84f11..79e3168f2 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -348,7 +348,15 @@ { "group": "Container orchestrators", "pages": [ - "integrations/platforms/kubernetes", + { + "group": "Kubernetes", + "pages": [ + "integrations/platforms/kubernetes/overview", + "integrations/platforms/kubernetes/infisical-secret-crd", + "integrations/platforms/kubernetes/infisical-push-secret-crd", + "integrations/platforms/kubernetes/infisical-dynamic-secret-crd" + ] + }, "integrations/platforms/kubernetes-csi", "integrations/platforms/docker-swarm-with-agent", "integrations/platforms/ecs-with-agent"