`SecretClass`

A SecretClass is a cluster-global Kubernetes resource that defines a category of secrets that the Secret Operator knows how to provision.

This is intended to provide an abstraction between how the secret is used ("I need a certificate for my cluster’s TLS PKI") and how it is provisioned (automatically and generated by the operator’s internal CA, provisioned by the cluster administrator, or provisioned by an external service such as Hashicorp Vault).

A SecretClass looks like this:

---
apiVersion: secrets.stackable.tech/v1alpha1
kind: SecretClass
metadata:
  name: tls
spec:
  backend: (1)
    autoTls: (2)
      ca:
        secret:
          name: secret-provisioner-tls-ca
          namespace: default
        autoGenerate: true
    # or... (1)
    k8sSearch: (3)
      searchNamespace:
        pod: {}
        # or...
        name: my-namespace

1	Backends are mutually exclusive, only one may be used by each `SecretClass`
2	Configures and selects the `autoTls` backend
3	Configures and selects the `k8sSearch` backend

Backend

Each SecretClass is a associated with a single backend, which dictates the mechanism for issuing that kind of secret.

`autoTls`

Format: TLS

Issues a TLS certificate signed by the Secret Operator. The certificate authority can be provided by the administrator, or managed automatically by the Secret Operator.

A new certificate and keypair will be generated and signed for each Pod, keys or certificates are never reused.

Attributes of the certificate (such as the expiration date, fingerprint, or serial number) will be regenerated for each Pod, and should not be expected to be stable.

Scopes are used to populate the claims (such as subjectAlternateName) of the provisioned certificates.

Reference

spec:
  backend:
    autoTls:
      ca:
        secret:
          name: secret-provisioner-tls-ca
          namespace: default
        autoGenerate: true

autoTls: Declares that the autoTls backend is used.
autoTls.ca: Configures the certificate authority used to issue Pod certificates.
autoTls.ca.secret: Reference (name and namespace) to a K8s Secret object where the CA certificate and key is stored as ca.crt and ca.key respectively. Will be created when the first certificate is issued if it does not already exist.
autoTls.ca.autoGenerate: Whether the certificate authority should be provisioned if it can not be found.

`k8sSearch`

Format: Free-form

A Kubernetes Secret object is selected based on the scopes specified on the Volume. Each field in this Secret is mapped to one file. It is suggested these Secret objects should follow one of the formats defined in this document.

Scopes are translated into additional label filters of the form secrets.stackable.tech/$SCOPE: $SCOPE_VALUE. For example, a Pod named foo mounting a k8sSearch secret with the pod scope would add the label filter secrets.stackable.tech/pod: foo.

Reference

spec:
  backend:
    k8sSearch:
      searchNamespace:
        pod: {}
        # or...
        name: my-namespace

k8sSearch: Declares that the k8sSearch backend is used.
k8sSearch.searchNamespace: Configures the namespace searched for Secret objects.
k8sSearch.searchNamespace.pod: The Secret objects are located in the same namespace as the Pod object. Should be used for secrets that are provisioned by the application administrator.
k8sSearch.searchNamespace.name: The Secret objects are located in a single global namespace. Should be used for secrets that are provisioned by the cluster administrator.

Format

A format describes a set of artifacts (files and their respective contents) produced by a backend.

Each backend should conform to at least one common format. This is intended to allow cluster operators to switch between interoperable backends with minimal impact on secret consumers.

TLS

The secret contains the following files:

ca.crt: The certificate of the Certificate Authority (and associated chain) that has signed the certificate, in the PEM format.
tls.crt: The certificate identifying the Pod, in the PEM format.
tls.key: The private key corresponding to tls.crt, in the PEM format.