Connect to Kubernetes Secrets
This article describes how to connect Kubernetes Secrets as a secret store to your Humanitec Operator setup.
Before you begin
Before you begin, make sure you have the following resources and permissions:
- A Kubernetes namespace, where your K8s secrets are stored, is in the same Kubernetes cluster with the Humanitec Operator.
- Access to the cluster via
kubectl
.
Prepare your environment
- Define an ID for your secret store. This ID will later match the secret store registrations in the Humnanitec Operator and in the Platform Orchestrator.
export SECRET_STORE_ID=my-k8s-store
- Define the namespace where you’ll store your K8s Secrets.
export SECRETS_NAMESPACE=my-secrets
- The Humanitec Operator runs using a service account which already has all required permissions to access Secrets in the cluster.
Register the secret store with the Operator
You have the option to make the secret store accessible cluster-wide, i.e. for all deployments onto the same Kubernetes cluster, or Environment-local, i.e. for the namespace of a particular Application Environment only.
A cluster-wide secret store is defined in the Operator namespace and can be referenced from all Deployments onto the cluster. An Environment-local store is defined in an Environment namespace and can only be referenced from Deployments into that namespace. The environment-local store therefore offers greater isolation of your secret store access.
When resolving a secret reference, the Operator will first try to use an Environment-local secret store of the store ID defined in the reference, and fall back to using a cluster-wide secret store of the same ID if not found.
The default
secret store must be a cluster-wide store. Any Environment-local store labelled default
will not be used as such.
- Create the secret store registration using the following command. Modify it according to your setup:
- If this is not your default secret store, omit the label
app.humanitec.io/default-store
- If this is an Environment-local secret store, modify the
metadata.namespace
attribute to match the Environment namespace
kubectl apply -f - << EOF
apiVersion: humanitec.io/v1alpha1
kind: SecretStore
metadata:
name: ${SECRET_STORE_ID}
namespace: humanitec-operator-system
labels:
app.humanitec.io/default-store: "true"
spec:
kubernetes:
namespace: ${SECRETS_NAMESPACE}
EOF
- Confirm the secret store registration.
To confirm the secret store registration, and anytime you wish to check for registered secret stores, use the following command:
# Cluster-wide secret store
kubectl get secretstores -n humanitec-operator-system
# Environment-local secret store
kubectl get secretstores -n my-environment-namespace
Register the secret store with the Platform Orchestrator
Create secrets
Use regular Kubernetes mechanisms to create and maintain secrets. A Kubernetes secret may contain one or more secret values. E.g. to create a secret containing two secret values, use this command:
kubectl create secret generic mysql-secrets \
--from-literal=mysql-username='super secret username' \
--from-literal=mysql-password='super secret password' \
--namespace=secrets-namespace
Deregister the secret store
Deregistering a secret store removes access to the store. It does not delete any secrets contained therein.
- Deregister the secret store from the Operator
Use this command to deregister a secret store from the Operator. Note that only future deployments trying to reference the store are affected. Running deployments with existing secret mappings continue to work using the present secret values because the Operator has mapped them into Kubernetes secrets in the deployment’s target namespace.
# Cluster-wide secret store
kubectl delete secretstore ${SECRET_STORE_ID} -n humanitec-operator-system
# Environment-local secret store
kubectl delete secretstore ${SECRET_STORE_ID} -n my-environment-namespace
Make sure that exactly one cluster-wide secret store is the default secret store at all times on your cluster.
default
secret store may cause disruptions for future deployments if Resource cookies have been stored there previously. Validate the existence of cookies, and when switching to a another default
store, consider migrating them over to the new default
store.Resource Cookies
Resource cookies are stored in Kubernetes Secrets having names according to this pattern:
<resource-gures-id>.cookies.<driver-org>.<driver-id>
and a secret key named value
inside it.
Limitations
The Kubernetes secret store has the following limitations:
- It does not support secret versioning. Only one version of a secret value can be maintained at any time, and any
version
named in a secret reference will be ignored. To maintain and restore previous values, you will have to create the appropriate processes yourself.
Next steps
- Test the Humanitec Operator and secret store setup using these test cases.
- Perform the Update Resource Definitions for related Applications tutorial to verify your setup.
- Ensure the sample Applications are being deployed to your Orchestrator-enabled cluster by adjusting the matching criteria for the cluster Resource.
- Observe how custom resources of type
workload
andresource
are being created on the cluster, and check theirstatus
sections. - Observe how the Operator writes operational state (“resource cookies”) into your default secret store.