Declare package roles and metadata

This content is for the v0.1 version. Switch to the latest version for up-to-date documentation.

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

  meta = {
    version = "1.0.0";
    description = "Configuration owned by an application team";
    owner = "platform";
    lifecycle = "stateless";
    scope = "namespace";
  };

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. 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:

  meta = {
    version = "1.0.0";
    description = "Default StorageClass for the composition example";
    owner = "platform";
    roles = [ "storageClasses" ];
  };

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:

      root = {
        resource = self.storageClass;
        out.storageClassName = self.storageClass.out.name;
      };

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:

Run in kix-examples/

❱ kix check how-to-composition
 TOOL         RESULT  DETAILS                                                       
 eval         pass    15 manifests evaluated                                        
 kubeconform  pass    skipped (this validation tool is not yet integrated with Kix) 
 pluto        pass    skipped (this validation tool is not yet integrated with Kix) 
 kyverno      pass    skipped (this validation tool is not yet integrated with Kix) 
 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.