This section describes package types, resource model, Application constraints, and application installation steps.
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 name | 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 | ap |
Cluster | Package summary: which repos have the package, which versions the release channels point to, how many instances use it |
| Application | — | Namespace | Installed instance. Drives Nelm deployment |
ApplicationPackageVersion content
ApplicationPackageVersion contains package version metadata and information required to configure and deploy an application:
| Content | Field |
|---|---|
Localized package description (en/ru) |
status.packageMetadata.description |
Package maturity stage (Preview, General Availability, and others) |
status.packageMetadata.stage |
DP and Kubernetes version requirements and module dependencies (mandatory, conditional, anyOf, noneOf) |
status.packageMetadata.requirements |
| Application removal confirmation settings. For details, refer to “Deletion confirmation” | status.packageMetadata.disableOptions |
Package version changes from changelog.yaml |
status.packageMetadata.changelog |
OpenAPI v3 schema for validating Application.spec.settings |
status.packageSchemas.settingsSchema |
OpenAPI v3 schema for validating the final set of values passed to hooks and templates |
status.packageSchemas.valuesSchema |
Application installation steps
Installing an application from a package involves several stages, from connecting and scanning the package repository to creating an Application resource, deploying the application, and checking its status.
- Administrator creates a PackageRepository.
- DP creates a PackageRepositoryOperation automatically. The initial scanning is performed when the resource is created, and then repeated based on the
scanIntervalvalue. - The operation scans the repository and creates ApplicationPackageVersion objects for each discovered version.
- User creates an Application in their namespace referencing package repository name (
packageRepositoryName), application package name (packageName), and version (packageVersion). - 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
The following constraints apply:
- No CRD creation: Application templates must not include CustomResourceDefinition objects.
- 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 in the format d8a-<INSTANCE_NAME>-<SUFFIX> (for details, refer to “Templates”), so the instance name is a part of every object name. To keep the object names within the Kubernetes limits, the following naming constraints apply:
- Application instance name (
metadata.name) can’t exceed 24 characters. The validating webhook rejects an Application with a longer name. - Resource name suffix inside the Application can’t exceed 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.
For example, the master StatefulSet of the redis-cache instance (11 characters) is named d8a-redis-cache-master (22 characters).