The module lifecycle stage: Experimental

The module has requirements for installation

Before enabling the module, you need to allow the use of experimental modules in the deckhouse ModuleConfig. To do this, set the allowExperimentalModules parameter to true.

Deckhouse Platform installs CRDs but does not remove them when a module is disabled. If you no longer need the created CRDs, delete them.

SystemBucket

Short names: sb

Scope: Namespaced
Version: v1alpha1

SystemBucket asks for a bucket in the platform’s system object storage. The controller creates the bucket in the system backend and writes a ConfigMap in the same namespace (see status.connectionRef) with the S3 connection parameters.

The resource is for Deckhouse components only. It is admitted exclusively in namespaces labelled heritage: deckhouse, and no user-facing RBAC is granted for it.

There is no reclaim policy: deleting a SystemBucket deletes the bucket and every object in it.

No credentials are written anywhere, and none are long-lived. A consumer exchanges its ServiceAccount token at the credentials endpoint (S3_STS_ENDPOINT in the ConfigMap) for a key pair the backend stops honouring at most thirty minutes later. Who may do that, for which bucket, is an ordinary Kubernetes RBAC grant on the virtual systembuckets/read and systembuckets/write subresources — so access is granted and revoked like any other permission, and nothing has to be rotated when it is taken away.

The consumer has to renew its credentials. Ask for a key near the end of its lifetime rather than on every request — every request mints a key, and a bucket is allowed at most 50 unexpired ones at a time.

  • spec
    object
    Desired state of the bucket.
    • spec.bucketName
      string
      Name of the bucket in S3. Defaults to <metadata.namespace>-<metadata.name> when omitted: the backend bucket namespace is flat, while SystemBuckets are namespaced, so the default keeps two components from colliding on a bucket name. Immutable after creation.

      Length: 3..63

      Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$

    • spec.size
      string

      How much the bucket asks for, as a Kubernetes quantity.

      It becomes the bucket’s quota in the backend — a write past it is refused — and it is what the data plane sizes its volumes from: the store provisions the sum of every SystemBucket’s size, so asking for more here is what makes the volumes grow.

      The default is deliberately small: a system bucket is a platform component’s working set, not a data lake.

      It can be raised at any time; the SizeUpToDate condition says when the backend enforces the new quota. Shared PVC capacity is reported separately by Module/system-s3.CapacityReady. It cannot be lowered: the volumes the store provisioned for it cannot shrink (a PersistentVolumeClaim cannot), and a quota below what the bucket holds would only make its writes fail.

      Default: 1Gi

      Pattern: ^[0-9]+(\.[0-9]+)?(E|P|T|G|M|k|Ei|Pi|Ti|Gi|Mi|Ki)?$

  • status
    object
    Observed state of the bucket.
    • status.bucketName
      string
      Effective bucket name created in the backend.
    • status.conditions
      array of objects
      Per-stage conditions: BucketReady, ConnectionReady, and the aggregate Ready. Besides them, SizeUpToDate says whether spec.size has taken effect: Applied or QuotaPending. Shared storage conditions, including PVC growth and Garage migrations, are published on Module/system-s3.
      • status.conditions.lastTransitionTime
        string
        Timestamp of the last status transition for this condition.
      • status.conditions.message
        string
        Human-readable explanation of the current status.

        Maximum length: 32768

      • status.conditions.observedGeneration
        integer
        Value of metadata.generation the condition was last set against.

        Allowed values: 0 <= X

      • status.conditions.reason
        string
        Machine-readable reason for the current status, suitable for log filtering.

        Length: 1..1024

        Pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$

      • status.conditions.status
        string
        Current status of the condition.

        Allowed values: True, False, Unknown

      • status.conditions.type
        string
        Condition type, for example Ready, BucketReady, ConnectionReady, or SizeUpToDate.

        Maximum length: 316

        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.connectionRef
      object

      Reference to the ConfigMap (in this bucket’s namespace) with the S3 connection parameters: S3_ENDPOINT (https), S3_REGION, S3_BUCKET, S3_CA_CERT (the CA that verifies the endpoint), and — for asking for credentials — S3_STS_ENDPOINT, S3_STS_AUDIENCE, S3_STS_CA_CERT.

      A ConfigMap and not a Secret: there is no key pair in it, because the module issues none. Credentials are minted per consumer, for at most thirty minutes, against a ServiceAccount token.

      • status.connectionRef.name
        string

        Required value

    • status.endpoint
      string
      In-cluster S3 endpoint URL of the system object storage.
    • status.objects
      integer
      Number of objects in the bucket, as the backend counts them.
    • status.observedGeneration
      integer
      Most recent metadata.generation reconciled by the controller.
    • status.phase
      string
      Coarse-grained summary derived from Conditions.

      Allowed values: Pending, InProgress, Ready, Error

    • status.quotaBytes
      integer
      Quota the backend enforces on this bucket, derived from spec.size. Reported back rather than echoed from the spec: what stops a write is what the backend holds.
    • status.quotaObjects
      integer
      Number of objects the backend lets this bucket hold: spec.size divided by 64 KiB. Each object costs disk space beyond its bytes (metadata, rounding to the filesystem block), and the store’s volumes allow for that overhead only up to this count. A bucket that reaches it has its writes refused with 403 AccessDenied (“Object quota is reached”) even below quotaBytes; raising spec.size raises both.
    • status.usedBytes
      integer
      Bytes the bucket currently holds, as the backend counts them.