Getting started Platform engineers Developers MVP Program

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

  1. 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
  1. Define the namespace where you’ll store your K8s Secrets.
export SECRETS_NAMESPACE=my-secrets
  1. 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.

  1. 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
  1. 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.

  1. 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.

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 and resource are being created on the cluster, and check their status sections.
    • Observe how the Operator writes operational state (“resource cookies”) into your default secret store.
Top