Credentials operator
The Otterize credentials operator automatically resolves pods to dev-friendly service names, registers them with a SPIRE server or with Otterize Cloud, and provisions credentials as Kubernetes Secrets.
Deploying the credentials operator
To deploy the operator, use the Helm chart.
Acquiring mTLS credentials using the credentials operator
The credentials operator is controlled using annotations placed on pods. To have it provision credentials and place them in Secrets, you must specify credentials-operator.otterize.com/tls-secret-name
.
SPIRE workload registrar
When using SPIRE, the operator registers every pod (even those without annotations). Alongside the credentials operator, you could use SPIRE agents and the SPIRE SDK to work with the same SPIRE server. To learn more, check out the documentation for SPIRE. Note that to use the credentials operator, you do not need to work directly with SPIRE or SPIRE agents, and can do everything completely using annotations and Kubernetes Secrets.
Pod annotations
Annotation | Description | Default |
---|---|---|
credentials-operator.otterize.com/tls-secret-name | If set, the operator will create a secret with this name with mTLS credentials for this pod. | N/A |
credentials-operator.otterize.com/dns-names | If set, overrides the list of subject alternative names in the certificate. Should include the hostname of Kubernetes services that will be used to access this pod. | N/A |
credentials-operator.otterize.com/cert-ttl | Override for the expiration time for the certificate in seconds. | If deployed with the bundled SPIRE server, 1 day (86400). |
credentials-operator.otterize.com/cert-type | Type of the credential bundle - pem or jks . | pem |
credentials-operator.otterize.com/cert-file-name | Certificate key name in the secret. When mounted, this is the filename for the certificate (when using spire it's the SVID file). Only used when cert-type is pem . | svid.pem |
credentials-operator.otterize.com/ca-file-name | Bundle (certificate chain bundle) key name in the secret. When mounted, this is the filename for the certificate chain. Only used when cert-type is pem . | bundle.pem |
credentials-operator.otterize.com/key-file-name | Private key key name in the secret. When mounted, this is the filename for the private key. Only used when cert-type is pem . | key.pem |
credentials-operator.otterize.com/keystore-file-name | Keystore key name in the secret. When mounted, this is the filename for the keystore. Only used when cert-type is jks . | keystore.jks |
credentials-operator.otterize.com/truststore-file-name | Truststore key name in the secret. When mounted, this is the filename for the truststore. Only used when cert-type is jks . | truststore.jks |
credentials-operator.otterize.com/jks-password | Password for the JKS truststore and keystore. Only used when cert-type is jks . | password |
credentials-operator.otterize.com/restart-pod-on-certificate-renewal | A pod with this annotation (no matter the value) will be restarted after certificate renewal, along with any replicas. Should be ideally set through the pod owner's template spec so it will persist between restarts. | N/A |
intents.otterize.com/service-name | Otterize-wide override for this service's name. Used by the operator when registering the service with SPIRE and generating credentials. | See Service identities |
How does the credentials operator work?
SPIRE entry registration
Once the operator resolves the service name for a pod, it labels the pod and registers an entry with the SPIRE server.
If configured to use Otterize Cloud credentials instead of SPIRE (useCloudToGenerateTLSCredentials
in the Helm chart configuration), it registers the Otterize service with Otterize Cloud.
Credential generation
The operator consults the label credentials-operator.otterize.com/tls-secret-name
. If that label exists, the operator creates a secret named after the value of the label with X.509 credentials within, provided by SPIRE or Otterize Cloud, depending on how the credentials operator is configured. This way, the pod can get autogenerated credentials without modifying its code.
When using SPIRE, once the operator has registered the pod with SPIRE, which happens automatically upon startup, the pod can use the SPIRE Workload API to generate credentials for the SVID <servicename>.<namespace>
.
Service name resolution and automatic pod labeling
Service name resolution is performed one of two ways:
- If an
intents.otterize.com/service-name
annotation is present, that name is used. - If not, a recursive look up is performed for the Kubernetes resource owner for a Pod until the root is reached. For example, if you have a
Deployment
namedclient
, which then creates and owns aReplicaSet
, which then creates and owns aPod
, then the service name for that pod isclient
- same as the name of theDeployment
.
The value resulting from this process forms the value of the label credentials-operator.otterize.com/service-name
.