A Catalog is a namespace’s shared catalog: one Corrosion cluster that every Library in the namespace writes into. Declare one Catalog in a namespace. It stands the catalog pod, the one standing member of that cluster, which holds the namespace’s catalog on a durable claim and reports what it holds over the bus. It sizes that claim, the claim every Library’s Jobs take, and the claim every screen’s agent runs on, and it owns the pod, its claim, and the namespace’s catalog Service and EndpointSlice.

Each catalog agent holds the whole namespace’s catalog, because the cluster gossips every row to every peer. So one size covers the whole namespace, on the Catalog, in place of a size on each Library.

apiVersion: library.liken.sh/v1alpha1
kind: Catalog
metadata:
  name: catalog
  namespace: media
spec:
  storage:
    size: 1Gi

A namespace has exactly one Catalog. A Library in a namespace with no Catalog waits until one exists, and more than one Catalog marks every Catalog in the namespace Blocked and stands no cluster. An empty storageClassName binds each catalog volume to the cluster’s default StorageClass. A claimName names an existing claim for the catalog pod to mount in place of the one the operator provisions. A SQLite file on a claim served over NFS can corrupt when its node is lost, so prefer a StorageClass that binds node-local storage. A spec.screens.storageClassName classes the screens’ claims apart from the durable one, and omitted, the cluster’s default binds them too.

The namespace’s shared catalog. Declare one Catalog in a namespace, and every Library in it writes into that catalog.

spec

Where the catalog is stored and how large each agent’s copy is.

Field Type Required Description
storage object yes The volume every catalog agent in the namespace takes.
screens object no The settings every screen pod in the namespace takes.

spec.storage

The volume every catalog agent in the namespace takes.

Field Type Required Description
size string no The size of each agent’s catalog volume. Small by default. Default: 1Gi.
storageClassName string no The StorageClass each agent’s catalog volume binds to. Omitted, the cluster’s default binds it.
claimName string no An existing PersistentVolumeClaim in this namespace for the catalog pod to mount, in place of the one the operator provisions; the operator creates none when it is set.

spec.screens

The settings every screen pod in the namespace takes.

Field Type Required Description
storageClassName string no The StorageClass each screen’s catalog volume binds to. Omitted, the cluster’s default binds it, and a node-local class such as local-path is the right one, because a screen pod is already pinned to the machine that holds its display. The size is spec.storage.size, because a screen holds the same rows the durable catalog holds.

status

The cluster the Catalog stands, written only by the library operator.

Field Type Required Description
members []string no The pods that are members of the namespace’s catalog cluster: the catalog pod, the pods of the Jobs that are running, and the screen pods.
storageSize string no The storage size the agents were given.
screens []object no One entry per screen pod in the namespace, in Player order: the Player it draws for, the claim its catalog agent runs on, the node it runs on, and its phase. A screen whose namespace has no single Catalog runs on an emptyDir and names no claim.
conditions []object no The typed observations the operator keeps on this Catalog, in the standard Kubernetes form; Ready is True when the catalog pod runs with every container ready, and False with the reason PodPending, PodFailed, or ManyCatalogs.

status.screens[]

One entry per screen pod in the namespace, in Player order: the Player it draws for, the claim its catalog agent runs on, the node it runs on, and its phase. A screen whose namespace has no single Catalog runs on an emptyDir and names no claim.

Field Type Required Description
player string no The Player the screen draws for.
claim string no The claim the screen’s catalog agent runs on, or empty for a screen on an emptyDir.
node string no The node the screen pod runs on, which is the node its claim is bound to.
phase string no The screen pod’s phase, as the kubelet reports it.

status.conditions[]

The typed observations the operator keeps on this Catalog, in the standard Kubernetes form; Ready is True when the catalog pod runs with every container ready, and False with the reason PodPending, PodFailed, or ManyCatalogs.

Field Type Required Description
type string yes The check this entry reports, in CamelCase. It is the key of this list. Pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$.
status string yes The verdict. True is the good verdict, and Unknown means the operator cannot tell yet. One of: True, False, Unknown.
observedGeneration integer no The metadata.generation this condition judged.
reason string no One CamelCase word for why the condition holds this verdict, meant for a program to match on. Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$.
message string no The same answer in a sentence a person reads.
lastTransitionTime string yes When the verdict last changed. It moves only when the status flips.