How-to guide Author packages and clusters

Declare package roles and metadata

Describe package ownership and lifecycle, and claim a registered infrastructure role when the package provides one.

Add meta beside a package’s options and build attributes:

16
  meta = {
17
    version = "1.0.0";
18
    description = "Configuration owned by an application team";
19
    owner = "platform";
20
    lifecycle = "stateless";
21
    scope = "namespace";
22
  };

View source on GitHub ↗

Use these fields to describe the package:

version identifies the package version shown by inspection commands and in PackageInstance records.
description gives the package a short human-readable purpose.
owner identifies the team responsible for it and supports governance scorecard rules.
lifecycle classifies its state as stateless, stateful, durable, or ephemeral. Kix records it in the kix.run/lifecycle annotation. Replacing a package marked stateful triggers the deployment migration gate.
scope constrains dependencies. With scope = "namespace", instances in other namespaces cannot depend on the package: automatic resolution skips it for consumers in other namespaces, and an explicit deps.<x> = ref.<ns>.<instance> to it fails. The default is cluster.

version, description, and owner describe the package. lifecycle and scope affect evaluation and deployment behavior, so choose them carefully.

Claim an infrastructure role

Add meta.roles only when the package provides one of Kix’s registered cluster infrastructure roles. This minimal provider claims the storageClasses role:

13
  meta = {
14
    version = "1.0.0";
15
    description = "Default StorageClass for the composition example";
16
    owner = "platform";
17
    roles = [ "storageClasses" ];
18
  };

View source on GitHub ↗

Registered roles are also dependency-resolution aliases. Kix validates role names, prevents conflicting providers, and checks any required out attributes when a consumer resolves the role.

The storageClasses role requires an exported storageClassName, so the package root supplies it:

35
      root = {
36
        resource = self.storageClass;
37
        out.storageClassName = self.storageClass.out.name;
38
      };

View source on GitHub ↗

Do not use roles as general package tags. Ordinary application dependencies are resolved through instance names, aliases, or explicit deps wiring.

Check the declarations

Run the normal checks after adding or changing metadata:

kix-examples/

❱ kix check how-to-composition
 TOOL       RESULT  DETAILS                      
 eval       pass    16 manifests evaluated       
 scorecard  pass    0 errors, 0 warnings, 0 info

Evaluation fails if a role name is unknown, two managed packages claim the same role, or a resolved provider does not satisfy the role’s output contract.