Package types
A Package is an abstract unit that encompasses either an Application or a Module. The distinction is based on scope and purpose:
| Characteristic | Module | Application |
|---|---|---|
| Purpose | Infrastructure extension for the cluster | User workload |
| Scope | Cluster-wide (one per cluster) | Namespaced (unlimited instances) |
| Multiple instances | No (1:1 with the cluster) | Yes (N instances in different namespaces) |
| Enabled by default | Can be enabled via bundle | Only by explicit user action |
| CRD creation | Allowed | Forbidden |
| Cluster-wide objects | Allowed | Forbidden |
Resource model
Deckhouse Platform (DP) Marketplace uses five custom resources:
flowchart TD
PR[PackageRepository] -->|triggers| PRO[PackageRepositoryOperation]
PR -->|populates| APV[ApplicationPackageVersion]
APV -->|aggregated by| AP[ApplicationPackage]
APV -->|referenced by| APP[Application\nnamespace-scoped]
| Resource | Short | Scope | Role |
|---|---|---|---|
PackageRepository |
— | Cluster | Connection to a container registry and scan schedule |
PackageRepositoryOperation |
pro |
Cluster | Scan job that discovers versions |
ApplicationPackageVersion |
apv |
Cluster | One per discovered package version; carries metadata, OpenAPI schemas, and requirements |
ApplicationPackage |
— | Cluster | Informational aggregate: which repos have the package, how many instances use it |
Application |
— | Namespace | Installed instance; drives Nelm deployment |
ApplicationPackageVersion content
Each ApplicationPackageVersion object carries:
status.packageMetadata.description— localized (en/ru) package descriptionstatus.packageMetadata.stage— maturity stage (Preview,General Availability, etc.)status.packageMetadata.requirements— DP and Kubernetes version constraints; module dependencies (mandatory,conditional,anyOf,noneOf)status.packageMetadata.disableOptions— confirmation before the application is deleted (see Deletion confirmation)status.packageMetadata.changelog— changes in the version fromchangelog.yamlstatus.packageSchemas.settingsSchema— OpenAPI v3 schema used to validateApplication.spec.settingsstatus.packageSchemas.valuesSchema— OpenAPI v3 schema for effective values passed to hooks and templates
Scan-to-deploy lifecycle
- Administrator creates PackageRepository.
- DP creates a PackageRepositoryOperation automatically (first scan on creation, then every
scanInterval). - The operation scans the container registry and creates ApplicationPackageVersion objects for each discovered version.
- User creates an Application in their namespace referencing
packageRepositoryName,packageName, andpackageVersion. - DP validates
spec.settingsagainst thesettingsSchemafrom the corresponding ApplicationPackageVersion. - Nelm deploys the Helm templates from the package bundle.
- The
Installedcondition on the Application reflects deployment progress and is the only condition reported until the installation completes. Once it becomesTrue, the other conditions (ConfigurationApplied,Scaled,Ready, and so on) appear.
Application constraints
All constraints exist to enforce namespace isolation and prevent Applications from interfering with cluster-level resources.
Functional constraints
- No CRD creation — Application templates must not include
CustomResourceDefinitionobjects. - No cluster-wide objects — all resources created by an Application must be namespaced.
- No cross-Application dependencies — an Application can declare dependencies only on Modules (via
requirements.modulesinpackage.yaml), not on other Applications. - Hooks are namespace-scoped — hooks must not read or write resources outside their own namespace.
- Manual install only — Applications are never activated by default; installation requires explicit user action.
Naming constraints
The objects of an Application are named d8a-<INSTANCE_NAME>-<SUFFIX> (see Templates), so the instance name is a part of every object name. To keep the object names within the Kubernetes limits:
- Application instance name (
metadata.name): at most 24 characters. The validating webhook rejects an Application with a longer name. - Resource name suffix inside the Application: at most 23 characters for StatefulSets, Jobs, and CronJobs, whose names must fit 52 characters (4 + 24 + 1 + 23 = 52), and at most 34 characters for other objects, whose names must fit 63 characters.
Example: the master StatefulSet of the redis-cache instance (11 characters) is named d8a-redis-cache-master (22 characters).