From 36af975594ad57a0ac993d59084d07a777525835 Mon Sep 17 00:00:00 2001 From: Daniel Hougaard Date: Sun, 8 Dec 2024 22:42:29 +0400 Subject: [PATCH] docs(k8-operator): k8's dynamic secret docs --- docs/integrations/platforms/kubernetes.mdx | 484 +++++++++++++++++++-- 1 file changed, 448 insertions(+), 36 deletions(-) diff --git a/docs/integrations/platforms/kubernetes.mdx b/docs/integrations/platforms/kubernetes.mdx index 0a61f4682..2c699c197 100644 --- a/docs/integrations/platforms/kubernetes.mdx +++ b/docs/integrations/platforms/kubernetes.mdx @@ -58,6 +58,16 @@ Once you apply the manifest, the operator will be installed in `infisical-operat + +## 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). @@ -946,25 +956,6 @@ spec: -### 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 `InfisicalSecret` CRD -to point to a CA certificate stored in a Kubernetes secret resource. - -```yaml ---- -spec: - hostAPI: https://app.infisical.com/api - resyncInterval: 10 - tls: - caRef: - secretName: custom-ca-certificate - secretNamespace: default - key: ca.crt - authentication: ---- -``` - The definition file of the Kubernetes secret for the CA certificate can be structured like the following: ```yaml @@ -1042,18 +1033,6 @@ After filling out the fields in the InfisicalPushSecret CRD, you can apply it di 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. -```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. - ```yaml infisical-push-secret.yaml apiVersion: secrets.infisical.com/v1alpha1 kind: InfisicalPushSecret @@ -1114,6 +1093,19 @@ After applying the InfisicalPushSecret CRD, you should notice that the secrets y 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 @@ -1424,22 +1416,442 @@ After applying, you should notice that the secrets have been pushed to Infisical kubectl apply -f example-infisical-push-secret-crd.yaml # The InfisicalPushSecret CRD itself ``` -### Connecting to instances with private/self-signed certificate +## Sync Dynamic Secrets to your cluster -To connect to Infisical instances behind a private/self-signed certificate, you can configure the TLS settings in the `InfisicalPushSecret` CRD +### 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 - resyncInterval: 30s tls: caRef: secretName: custom-ca-certificate secretNamespace: default key: ca.crt - authentication: - # ... +--- ```