Restarter

The Stackable Commons Operator can automatically restart Pod objects based on certain criteria. This can be applied to either the Pod or certain controller objects (such as StatefulSet).

Pod

Pods are evicted when any of their restart criteria (listed below) expire, with the expectation that their owning controller is then responsible for restarting them.

Because they are evicted rather than deleted, this process should respect PodDisruptionBudget constraints, allowing users to ensure that clusters are restarted gracefully.

Expiration date

Annotation: restarter.stackable.tech/expires-at.{tag}

Pods can be configured to expire at a certain point in time. In this case, the Pod should have the annotation restarter.stackable.tech/expires-at.{tag} set to a datetime formatted according to RFC 3339 (such as "2022-04-21T13:24:15.225774724+00:00"). {tag} should be a deterministic but unique ID identifying the reason for the expiry.

Multiple expires-at annotations can be set on the same Pod, in which case the earliest expiration datetime takes precedence.

StatefulSet

StatefulSets are rolling-restarted when any of their restart criteria (listed below) expire.

Stale configuration

Label: restarter.stackable.tech/enabled

The operator can restart StatefulSets when any referenced configuration object (ConfigMap or Secret) changes. To enable this, set the restarter.stackable.tech/enabled label on the StatefulSet to true.

Annotation: restarter.stackable.tech/ignore-configmap.*
Annotation: restarter.stackable.tech/ignore-secret.*

These annotations can be added if the restarter is enabled on a StatefulSet, but some ConfigMaps or Secrets should be excluded from triggering a restart. * can be replaced with any value and is only used to make the annotation key unique.

---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: statefulset-with-enabled-restarter
  labels:
    restarter.stackable.tech/enabled: "true"
  annotations:
    restarter.stackable.tech/ignore-configmap.0: hot-reloaded-configmap
    restarter.stackable.tech/ignore-secret.0: hot-reloaded-secret
spec:
  template:
    spec:
      volumes:
        - name: configuration
          configMap:
            name: hot-reloaded-configmap
        - name: credentials
          secret:
            secretName: hot-reloaded-secret
...

Pod template annotations

To detect changes, the operator adds an annotation for every referenced ConfigMap and Secret to the Pod template of the StatefulSet. Its key is configmap.restarter.stackable.tech/{name} or secret.restarter.stackable.tech/{name}, its value is the UID and resource version of the referenced object (or changes-ignored if it is excluded as described above). Kubernetes rolling-restarts the Pods whenever one of these values changes. These annotations are managed by the operator, there is no need to set them yourself.

Object names can be up to 253 characters long, but Kubernetes limits the part of an annotation key after the / to 63 characters. Longer names are therefore truncated and filled up with the hash of the original name to make sure there are no clashes.

ConfigMap/Secret

Label: restarter.stackable.tech/ignore

If a ConfigMap or Secret is only used for initializing a StatefulSet or contains data which can be hot-reloaded, add the label restarter.stackable.tech/ignore: "true" to avoid unnecessary restarts of the StatefulSet Pods:

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: hot-reloaded-configmap
  labels:
    restarter.stackable.tech/ignore: "true"
...
---
apiVersion: v1
kind: Secret
metadata:
  name: hot-reloaded-secret
  labels:
    restarter.stackable.tech/ignore: "true"
...

Unlike the StatefulSet annotations restarter.stackable.tech/ignore-configmap.* and restarter.stackable.tech/ignore-secret.*, this label affects every StatefulSet that references the labeled ConfigMaps or Secrets.