`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 in the keys ca.crt and ca.key respectively.
autoTls.ca.autoGenerate: Whether the certificate authority should be provisioned if it can not be found.

`kerberosKeytab`

Format: Kerberos

Creates a Kerberos keytab file for a selected realm. The Kerberos KDC and administrator credentials must be provided by the administrator.

Only MIT Kerberos (krb5) is supported. Heimdal and Active Directory are not supported.

Principals will be created dynamically if they do not already exist.

The administrator keytab must have permission to add principals and get their keys. This corresponds to the flags ae in kadm5.acl.

Reference

spec:
  backend:
    kerberosKeytab:
      realmName: CLUSTER.LOCAL
      kdc: krb5-kdc
      admin:
        mit:
          kadminServer: krb5-kdc
      adminKeytabSecret:
        namespace: default
        name: secret-provisioner-keytab
      adminPrincipal: stackable-secret-operator

kerberosKeytab: Declares that the kerberosKeytab backend is used.
kerberosKeytab.realmName: The name of the Kerberos realm. This should be provided by the Kerberos administrator.
kerberosKeytab.kdc: The hostname of the Kerberos Key Distribution Center (KDC). This should be provided by the Kerberos administrator.
kerberosKeytab.admin.mit.kadminServer: The hostname of the Kerberos Admin Server. This should be provided by the Kerberos administrator.
kerberosKeytab.adminKeytabSecret: Reference (name and namespace) to a K8s Secret object where a keytab with administrative privileges is stored in the key keytab.
kerberosKeytab.adminPrincipal: The name of the Kerberos principal to be used by the Secret Operator. This should be provided by the Kerberos administrator. The credentials for this principal must be stored in the keytab (adminKeytabSecret).

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

Kerberos

The secret contains the following files:

krb5.conf: Kerberos configuration file for authenticating against the Kerberos realm.
keytab: A Kerberos keytab file containing credentials for all requested principals.