Install a package
Installing a package touches the same layers as registering a service or a scope yourself, and only the nullplatform layer changes: instead of registering a copy of the specification, you install the package. This page covers both kinds, with the tofu-modules that do the work.
Before you start
You need an agent that will run the package's worker, with public.ecr.aws/nullplatform/* among its worker.allowedRegistries, and a cloud provider configured at the NRN where you install or above it. Each package's repository README lists what else it needs, such as a state bucket or an environment variable on the agent.
The three layers
| Layer | What you create | Where it comes from |
|---|---|---|
| Infrastructure | The cloud permissions the worker uses, usually an IAM role | The package's repository, as a requirements module |
| nullplatform | The installation and the agent channel; for a scope, also the scope type and its settings | tofu-modules' service_package_installation or scope_package_installation |
| Bindings | The role under the selector the package expects, in your IAM provider | Your providers |
The repository README of each package tells you the inputs of its requirements module and the selector its worker looks for.
The installation itself is one API call: the modules send a POST request to /package_installations with the NRN, the package and the revision of the version you pin.
Pick one release
Pick one release of the package's repository and use its version everywhere a version goes: the requirements module, the installation and, for a scope, the templates. The cloud permissions are the ones the worker of that same release expects, so mixing releases surfaces at runtime, as a failed action. The latest release is on the repository's releases page, and the package's versions are visible in Platform settings. Through the API, a GET request to /packages with visible_to and slug finds the package, and its revisions list every version.
Install a service
# ── infrastructure layer ─────────────────────────────────────────────
module "my_service_requirements" {
source = "git::https://github.com/nullplatform/<repository>.git//<service>/specs/requirements/aws?ref=vX.Y.Z"
# the inputs its README lists
}
# The agent role must be allowed to assume it: add it to the assume_role_arns
# of tofu-modules' infrastructure/aws/iam/agent.
# assume_role_arns = [..., module.my_service_requirements.permissions_role_arn]
# ── nullplatform layer ───────────────────────────────────────────────
# For a service the installation is the whole nullplatform side, channel included.
module "my_service" {
source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/service_package_installation?ref=v9.16.0"
nrn = "organization=1:account=2"
package_slug = "np-<slug>"
package_version = "X.Y.Z" # the same release, without the v
agent_tags_selectors = { cluster = "runtime" } # must match the agent's TAGS
}
# ── bindings layer ───────────────────────────────────────────────────
# One aws-iam-configuration per NRN and dimensions: add the entry to the list
# your IAM provider already has.
# { selector = "<selector>", arn = module.my_service_requirements.permissions_role_arn }
If you keep agent channels in a separate bindings layer, use package_installation in the nullplatform layer and service_definition_agent_association in bindings, with package_slug set to the package's slug.
Install a scope
A scope package brings the specification and its actions. The scope type, the NRN settings and the scope configuration schema are yours, and scope_package_installation creates them from the templates of the same release.
# ── nullplatform layer ───────────────────────────────────────────────
module "my_scope" {
source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/scope_package_installation?ref=v9.16.0"
nrn = "organization=1:account=2"
np_api_key = var.np_api_key # for the NRN settings
package_slug = "np-<slug>"
package_version = "X.Y.Z"
service_spec_name = "<the scope type developers pick>"
service_spec_description = "<description>"
service_path = "<scope>"
repository_scope_template = "https://raw.githubusercontent.com/nullplatform/<repository>/refs/tags"
repository_scope_template_branch = "vX.Y.Z" # the same release
create_scope_configuration = true
create_agent_channel = false # the channel lives in your bindings layer
}
# ── bindings layer ───────────────────────────────────────────────────
module "my_scope_channel" {
source = "git::https://github.com/nullplatform/tofu-modules.git//nullplatform/scope_definition_agent_association?ref=v9.16.0"
nrn = "organization=1:account=2"
tags_selectors = { cluster = "runtime" }
scope_specification_id = module.my_scope.service_specification_id
scope_specification_slug = module.my_scope.service_specification_slug
service_path = "<scope>"
# The channel template, from the same release
repository_notification_channel = "https://raw.githubusercontent.com/nullplatform/<repository>/refs/tags"
repository_notification_channel_branch = "vX.Y.Z"
worker_orchestrator = true
package_slug = "np-<slug>"
}
The scope's settings go in a provider of the configuration schema the installation created; the repository README says which settings the scope reads.
From a catalog of definitions
If your layers keep a catalog of service_definition or scope_definition entries, an installation is an entry of the same catalog that carries package_slug and package_version instead of a repository: a second module block, with the same for_each over those entries, points at service_package_installation or scope_package_installation. Their outputs have the names service_definition and scope_definition use, so the map your bindings layer reads keeps its shape.
Already registered a copy?
If you registered the same service or scope yourself, you have a specification with the plain slug, such as aws-s3-bucket, and an agent channel filtered to it. The global package uses another slug, such as np-aws-s3-bucket, so both can live in one organization:
- Add the installation next to your
service_definitionorscope_definition. Its channel routes only the global slug, and your existing channel keeps serving your copy. - Keep your IAM role: both specifications assume the role under the same selector, with the same permissions.
- Existing services and scopes stay on your copy: an instance can't move to another specification. Create new ones from the installed specification, and remove your copy and its channel once nothing uses them.
Upgrade
Move the release in every layer where you pinned it: ref of the requirements module, package_version of the installation and, for a scope, the templates ref. On the nullplatform side, the module sends a PATCH request that moves the installation's default_revision_id.
Instances created from the previous version keep running it. To move them, roll out the version in waves.
Global package or your own fork
| Global package | Your own fork | |
|---|---|---|
| Specs and code | Maintained by nullplatform in the repository | Maintained by you, in your fork |
| What you install | The package, read-only | A package you publish in your organization, or a registered copy |
| Updates | A new release: move the version | Only when you merge upstream into your fork |
| When | Always, unless you need changes to the specification, the links, the actions or the workflows | Substantial changes: new actions or links, another specification, workflows that behave differently |
Use the global package. It's the only way to keep receiving fixes, features and security patches: each one arrives as a release, and you take it by moving the installed version. If something is missing or wrong, open an issue or a pull request in the repository, so every organization gets it.
Fork only to change what the service or scope is. A fork means you become the publisher of a different package: you build its worker image, publish it in your organization under your own slug, and maintain its specs, code and installation. Each repository README has the steps for its own fork.
The shortcut, and why it's risky
The worker image nullplatform publishes is a global artifact, so a package of your own may pin it and change only the specs. It saves you the build, and it's the main trade-off to understand before taking it: the code in that image reads the specification it was released with, the attributes the form collects, the actions and their parameters, the links and what they export. Every change to your specs is a divergence the image doesn't know about, and the next release assumes specs you no longer have. A service or scope behaves as one thing because its specs and its code are released together. Take the shortcut only for changes the image can't see, such as descriptions, defaults within the same shape, or visibility.
What a fork costs
Updates stop arriving unless you merge them yourself. There's no way back for existing instances, since they can't move to another specification. And you own the operations: images, releases and the compatibility of your specs with the agent.
Next steps
- Packages: what a package is and how versions work
- Roll out a version: move the services and scopes you already have to the version you upgraded to
- Sample services: the services nullplatform publishes as global packages
- tofu-modules: the modules used on this page, with their inputs and outputs
- Package installation API: install a package, move its version and list what's installed