Skip to main content

​
Operation Roles

The operation_roles.toml file defines an app-level matrix of rules that map entity principals and operations to role names. It is placed at the root of your app config directory and synced via nuon apps sync.
Entity-level role overrides (inline [[operation_roles]] blocks on sandbox.toml and component configs, or the role field on action configs) take precedence over matrix rules. See the Operation Roles Guide for the full precedence chain.

​
Properties

PropertyTypeRequiredDescription
typestring✅ YesMust be "matrix"
rulesarrayNoArray of operation role rules

​
Rule Properties

Each element of the rules array must have the following fields:
PropertyTypeRequiredDescription
principalstring✅ YesIdentifies which entity the rule applies to. See Principal Format below
operationstring✅ YesThe operation the rule applies to. See Valid Operations below
rolestring✅ YesThe role name to use. Must match a role defined in permissions.toml. Supports Go template syntax

​
Principal Format

The principal field identifies the entity that is performing the operation.
EntityPrincipal FormatExample
Specific componentnuon::component:<name>nuon::component:my_lambda
All componentsnuon::component:*nuon::component:*
Sandboxnuon::sandboxnuon::sandbox
Specific actionnuon::action:<name>nuon::action:db_migration
All actionsnuon::action:*nuon::action:*
The nuon::sandbox principal has no name suffix — there is only one sandbox per install.

​
Valid Operations by Entity

EntityValid Operations
componentdeploy, teardown
sandboxprovision, reprovision, deprovision
actiontrigger

​
Role Name Templating

The role field supports Go template syntax. The template is rendered at runtime with the install’s state variables before looking up the role in the stack outputs. Common variables:
VariableDescription
{{.nuon.install.id}}The install ID — ensures per-install role isolation
{{.nuon.install.sandbox.outputs.<key>.name}}Sandbox stack output values
The rendered role name must match a role provisioned in the customer’s stack. Roles that are not the standard provision_role, deprovision_role, or maintenance_role must be declared as custom_roles in permissions.toml.

​
Examples

​
Full operation_roles.toml

operation_roles.toml
type = "matrix"

# Per-component roles
[[rules]]
principal = "nuon::component:my_lambda"
operation = "deploy"
role      = "{{.nuon.install.id}}-lambda-deploy-role"

[[rules]]
principal = "nuon::component:my_lambda"
operation = "teardown"
role      = "{{.nuon.install.id}}-lambda-teardown-role"

# All components share the same deploy role
[[rules]]
principal = "nuon::component:*"
operation = "deploy"
role      = "{{.nuon.install.id}}-shared-deploy-role"

# Sandbox operations
[[rules]]
principal = "nuon::sandbox"
operation = "provision"
role      = "{{.nuon.install.id}}-provision-role"

[[rules]]
principal = "nuon::sandbox"
operation = "reprovision"
role      = "{{.nuon.install.id}}-provision-role"

[[rules]]
principal = "nuon::sandbox"
operation = "deprovision"
role      = "{{.nuon.install.id}}-destroy-role"

# Action roles
[[rules]]
principal = "nuon::action:db_migration"
operation = "trigger"
role      = "{{.nuon.install.id}}-migration-role"

​
Entity-Level Role in sandbox.toml

sandbox.toml
[[operation_roles]]
operation = "provision"
role      = "{{.nuon.install.id}}-provision-role"

[[operation_roles]]
operation = "deprovision"
role      = "{{.nuon.install.id}}-destroy-role"

​
Entity-Level Role in a Component Config

components/my_lambda.toml
[[operation_roles]]
operation = "deploy"
role      = "{{.nuon.install.id}}-deploy-role"

[[operation_roles]]
operation = "teardown"
role      = "{{.nuon.install.id}}-teardown-role"

​
Action Role

actions/db_migration.toml
name             = "db_migration"
timeout          = "10m"
role             = "{{.nuon.install.id}}-migration-role"
break_glass_role = "break-glass-dba-role"

[[triggers]]
type = "manual"