Platform Database
The platform database is a local PostgreSQL instance provisioned only in air-gapped environments running an offline license key. It stores usage snapshots, which are periodic records of CPU and GPU resource consumption used for license billing. The platform attempts to transmit these snapshots to the vCluster license server every 15 minutes. The local database acts as a staging area. Once a snapshot is successfully transmitted, vCluster's license server holds the authoritative record. Data that has not yet been transmitted exists only in this database.
The platform database does not store core platform state. Tenant cluster definitions, project settings, users, and all other platform objects are stored as Kubernetes custom resources on the control plane cluster. This database exists solely for usage reporting.
This page covers the local PostgreSQL instance used for usage reporting in air-gapped environments. If you need high availability with multiple platform replicas, see Platform External Database. That is a separate feature using a Kine-backed PostgreSQL database as a shared backing store for multi-replica HA deployments, and it requires a fresh installation configured before the platform first starts.
When the platform database is provisioned​
The platform database is only created when all of the following conditions are true at startup:
- The platform is configured with an offline license key (air-gapped mode).
- The platform is not running as a hosted instance (managed and operated by vCluster Labs on your behalf).
- The active license plan does not disable the platform database.
Standard online-licensed installations do not provision this database. If you do not see a platform-db PVC or StatefulSet in your platform namespace, the database is not active in your environment and this page does not apply.
How the platform database surfaces to administrators​
Administrators encounter the platform database in several situations:
Namespace inspection. The platform database runs as a StatefulSet in the platform namespace. A routine kubectl get all or kubectl get pvc will show the platform-db StatefulSet, Service, PVC, and Secret alongside platform resources.
Cluster conditions. The controller sets EmbeddedPostgresDeployed and EmbeddedPostgresAvailable conditions on the Cluster resource. If the database fails to start, kubectl describe cluster.storage.loft.sh <cluster-name> shows a condition message directing you to investigate.
Platform logs. If the database is unreachable, the platform logs error sending usage snapshot every 15 minutes. Administrators tailing logs during an incident will see this repeating.
Platform upgrades. The controller restarts the postgres pods during platform upgrades. Administrators watching pod activity during an upgrade will see platform-db pods cycling, which is expected behavior.
See Troubleshoot Platform Database for steps to resolve conditions and log errors.
What usage snapshots record​
Each snapshot captures a point-in-time count of resource capacity across the platform, not live workload utilization. The data is used to calculate consumption against the committed amounts in your license.
| Metric | Description |
|---|---|
| Tenant cluster count | Total number of tenant clusters across the platform |
| Node count | Total number of nodes across all connected clusters |
| CPU count | Total CPU capacity across all nodes |
| GPU count | Total GPU capacity across all nodes |
| Per-node detail | Machine ID, creation timestamp, and full resource capacity for each node |
| Per-tenant-cluster detail | Name, namespace, UID, creation timestamp, and node associations |
GPU metering in Platform 4.12​
Platform 4.12 calculates the metered gpu total from physical accelerators advertised in node capacity. It also records a breakdown by accelerator vendor. Earlier versions only included nvidia.com/gpu in the total.
The following device plugin resource names count toward the total:
| Vendor | Counted resource names |
|---|---|
| NVIDIA | nvidia.com/gpu |
| AMD | amd.com/gpu |
| Intel GPU | gpu.intel.com/i915, gpu.intel.com/xe |
| Intel Gaudi | habana.ai/gaudi |
| AWS Neuron | aws.amazon.com/neuron |
| Google TPU | google.com/tpu |
Existing environments with non-NVIDIA accelerators can report a higher billable GPU total after upgrading. The previous snapshot remains in effect until the platform writes a new usage snapshot, normally within 15 minutes.
The breakdown groups accelerators by vendor in Platform 4.12. The model value remains empty because the platform doesn't collect the required hardware labels yet. Intel GPUs and Intel Gaudi therefore appear in one intel entry.
The following accelerator configurations aren't fully represented:
- The platform doesn't count NVIDIA sharing resources named
nvidia.com/gpu.sharedor MIG resources namednvidia.com/mig-*. - A time-sliced GPU that remains advertised as
nvidia.com/gpuis counted exactly as advertised. This can exceed the number of physical cards. - The platform doesn't count GPUs allocated through Kubernetes Dynamic Resource Allocation (DRA) ResourceSlices.
- The platform counts
aws.amazon.com/neurondevices and ignoresaws.amazon.com/neuroncoreto avoid counting the same hardware twice.
Use the tenant cluster resource-usage API to inspect the live per-vendor breakdown. Read the gpus field for cross-vendor data. The existing capacity field only includes nvidia.com/gpu for GPU capacity.
Configure​
By default, the platform database uses the default StorageClass. To specify a different StorageClass, navigate to Admin > Config and edit the platformDB.storageClass field.
The value can also be configured in the vCluster Platform Helm values during install or upgrade:
platformDB:
storageClass: <storage-class>