API Storage

This page describes how to configure the storage used by the API server, and how to persist cached data across container restarts.

Note

To configure storage for backup data, see the Storage section in the user guide.

Synopsis

values.yaml

api:
  data:
    # Directory where the API server stores cached data
    directory: "/var/lib/kannika"

  # Set the fsGroup to ensure the persistent volume is writable by the container.
  podSecurityContext:
    fsGroup: 1000

  # Persistence settings for the API server's data directory.
  # By default, an emptyDir volume is used, which is deleted when the pod is deleted.
  # If you want to use a PersistentVolumeClaim, set `persistentVolume.enabled` to true.
  # If you want to use a hostPath, set `storage.hostPath` to the path on the host.
  storage:
    # Store data on the host using this absolute path.
    # This is useful for development and testing, but not recommended for production.
    hostPath: "/path/on/host"

    # Store data using a PersistentVolumeClaim.
    persistentVolume:
      # Whether to use a PersistentVolumeClaim to store data.
      # Enabling this will take precedence over the other settings.
      enabled: false
      # The size of the PersistentVolumeClaim.
      size: 5Gi
      # The storage class to use for the PersistentVolumeClaim.
      # If not set, the default storage class will be used.
      storageClass: ""
      labels: {}
      annotations: {}
      accessModes:
        - ReadWriteOnce
      # Used to overwrite the default name of the PersistentVolumeClaim
      nameOverwrite: ""

Data stored by the API

The API stores and caches the following data:

• Event Hub Topics: Topics fetched from EventHubs are stored and cached for performance reasons.
• Backup & Restore Metrics: The API stores metrics from backups and restores. See the corresponding documentation for more information.

This list may change in future versions.

Configuring the data directory

By default, the data directory is located at /var/lib/kannika in the API container.

To configure the data directory, set the api.config.data.directory application property.

values.yaml

api:
  config:
    data:
      directory: /var/lib/kannika

Configuring the data volume

A data volume is mounted onto the Pod to the data directory to store the API data.

By default, this volume is an emptyDir . This means that data is not persisted across container restarts.

Persistent volume

Note

The storage class used here has nothing to do with the storage class used in the operator or in a Volume Storage. The storage class used here is used by Kubernetes to provision a volume, which will be mounted on the pod of the API, so that data is persisted across container restarts.

To use a persistent volume to store the API’s data, set the api.storage.persistentVolume.enabled property to true. This will create a PersistentVolumeClaim .

This is the recommended configuration for production environments, as it ensures that data is persisted across container restarts.

The following properties can be configured:

values.yaml

api:
  storage:
    persistentVolume:
      enabled: true
      storageClass: "default"
      size: 5Gi
      labels: {}
      annotations: {}
      accessModes:
        - ReadWriteOnce
      nameOverwrite: ""

File permissions

When using a persistent volume, the volume may be owned by root by default. If the API container runs as a non-root user, it will not have write access to the data directory.

To fix this, set the api.podSecurityContext.fsGroup property to the group ID of the container’s user. Kubernetes will then change the ownership of the volume to match the specified group.

values.yaml

api:
  podSecurityContext:
    fsGroup: 1000
  storage:
    persistentVolume:
      enabled: true

Tip

If the API pod fails to start with a permission error on the data directory, a missing fsGroup is the most likely cause.

Access modes

The API uses SQLite as its local database engine. SQLite relies on POSIX file locks to coordinate access between readers and writers.

With ReadWriteOnce (RWO), the volume is bound to a single node. This works well with SQLite’s locking model, but can cause brief downtime during rolling updates: the new pod cannot mount the volume until the old pod releases it.

ReadWriteMany (RWX) allows the old and new pod to mount the volume simultaneously, which enables zero-downtime rolling updates. However, most RWX volumes are backed by network filesystems such as NFS or CephFS. These filesystems do not reliably support the file locking that SQLite requires. When both pods access the same SQLite database over a network filesystem, write operations can be silently lost.

Caution

If you use ReadWriteMany, be aware that SQLite data loss can occur when multiple pods write to the database concurrently.

Host path

To store the API data on the host, set the api.storage.hostPath property to an absolute path on the host. This will create a hostPath . volume.

This is useful for development and testing environments, but it is not recommended for production environments.

values.yaml

api:
  storage:
    hostPath: /var/lib/kannika

emptyDir

To store the API data in an emptyDir volume, simply do not configure the api.storage property.

This is useful for local development and testing environments, but it is not recommended for production environments.

values.yaml

api:
  storage: {}