How-to guide Author packages and clusters
Add typed package options
Declare validated package settings with defaults, descriptions, and useful evaluation errors.
Package options define the values cluster authors may place under an
instance’s config. Kix validates those values while evaluating the cluster,
before it renders Kubernetes manifests.
This guide extends the local package from Create a local package.
Declare the options
Section titled “Declare the options”Add an options attribute beside meta and build:
options = { message = lib.mkOption { type = lib.types.str; default = "Hello from Kix"; description = "Text served from the application root."; };
environment = lib.mkOption { type = lib.types.enum [ "preview" "production" ]; default = "preview"; description = "Environment name exposed to the container."; };
replicas = lib.mkOption { type = lib.types.ints.positive; default = 1; description = "Number of application replicas."; };
healthCheck = kix.options.healthCheck; };Each lib.mkOption declaration can provide:
type, which rejects values outside the package contract.default, which supplies a value when the instance omits the option.description, which explains the setting in generated reference material.example, when a useful value is not obvious from the default.
The example also composes kix.options.healthCheck, a shared option set. You
can combine shared option sets with package-specific fields using //, as the
post-deploy health-check guide demonstrates.
Read options from the build function
Section titled “Read options from the build function”Add config to the build function arguments. Read evaluated values from that
attribute set:
build = { self, config, scope, kix, ...}: { deployment = scope.mkDeployment { name = scope.instanceName; spec.replicas = config.replicas; };};config includes defaults as well as values set by the instance. Package code
therefore does not need a separate fallback for replicas or environment.
Default one option from another
Section titled “Default one option from another”When one option’s default depends on another option, return config beside
options. It is a module, written as an attribute set or as a
{ config, lib, ... }: function:
options = { replicas = lib.mkOption { type = lib.types.int; default = 1; }; minAvailable = lib.mkOption { type = lib.types.int; default = 0; };};config = { config, ... }: { minAvailable = lib.mkDefault (config.replicas - 1);};Write package defaults with lib.mkDefault. Kix evaluates every
lib.mkDefault in a package’s config at a lower priority than the
instance’s, so a value the instance sets wins, even when the instance also
uses lib.mkDefault. A plain value in the package’s config is a fixed
setting instead, and conflicts with a different plain value on the instance.
Evaluation errors from this module name it package config of <namespace>/<instance>.
Packages use this for images released together, where each component’s tag
follows the main image’s tag. See
kix.options.image.
Configure an instance
Section titled “Configure an instance”Set option values under config:
instances.apps.web = { package = webPackage; config = { message = "Hello from production"; environment = "production"; replicas = 2; };};Fields not declared by the package are rejected. Values must also satisfy the declared type.
Check a validation error
Section titled “Check a validation error”For example, the package allows preview and production as environment
names. Setting environment = "staging" produces this error:
❱ kix check how-to-application
TOOL RESULT DETAILS
eval fail could not read the built resources and their dependencies: nix build failed: warning: not writing modified lock file of flake 'path:kix-examples':
• Updated input 'kixpkgs':
'git+https://github.com/kix-run/kixpkgs?ref=refs/heads/main&rev=9dcf5b3e33b728ef3fc76a693e4feda2921b1913' (2026-09-10)
→ 'path:/nix/store/y987fl3ssw1130fh2gai5n82h1167dc7-source/docs/..?lastModified=0&narHash=sha256-SBH07wTy4boKkMii0JnCl6fpORWVXKtJDZ3StdHJ%2BMY%3D' (1970-01-01)
error:
… while calling the 'derivationStrict' builtin
at <nix/derivation-internal.nix>:37:12:
36|
37| strict = derivationStrict drvAttrs;
| ^
38|
… while evaluating the derivation attribute 'name'
at /nix/store/4rg99msfmkk9gppakagpgkzcixwg7yxq-source/pkgs/stdenv/generic/make-derivation.nix:624:11:
623| derivationArg = removeAttrs attrs removedOrReplacedAttrNames // {
624| ${if (attrs ? name || (attrs ? pname && attrs ? version)) then "name" else null} =
| ^
625| let
… while evaluating the option `instances.how-to-app.preview.config.environment':
(stack trace truncated; use '--show-trace' to show the full, detailed trace)
error: A definition for option `instances.how-to-app.preview.config.environment' is not of type `one of "preview", "production"'. Definition values:
- In `<unknown-file>, via option instances.how-to-app.preview.config': "staging"
(exit code: 1)The error names the option and the rejected definition. It also names the instance and the file that set the value. Restore an allowed value and check the cluster again:
❱ kix check how-to-application
TOOL RESULT DETAILS
eval pass 17 manifests evaluated
scorecard pass 0 errors, 11 warnings, 2 info