Skip to main content
This guide shows how to define operation roles, assign them to operations, and override them for a single run. For a high-level overview, see Operation Roles.

Example: separate deploy and teardown roles

This example gives an api component one role to deploy and another to tear down, so a deploy can’t delete anything.
1

Define the roles

Add two custom roles to permissions.toml:
permissions.toml
2

Assign them to the component

components/api.toml
3

Ship it

Push to your app branch, then reprovision existing installs so their stacks create the new roles.
4

Check it in the dashboard

The component’s next deploy shows the api-deploy role in the dashboard.

Define your own roles

Your app config must define a provision, maintenance, and deprovision role. Declare them, and any roles of your own, in one of two layouts:
  • permissions.toml: one [[roles]] block per role, each with a type.
  • permissions/ directory: one file per role, such as permissions/maintenance.toml, each with a type.
Use one layout, and declare each standard role once. If two roles share a standard type, Nuon uses the last one without an error. Add your own roles with type = "custom":
permissions.toml
Existing installs get a new role the next time their stack is updated. See Reprovision installs.

Template role names

Role names support the same Go template syntax used elsewhere in Nuon config:
Common template variables: The rendered name must match a role in your permissions or break glass config. If it doesn’t, the run uses the standard role.

Share a policy across roles

Write a policy once and attach it to several roles, such as one database admin policy for your maintenance role and a break glass role. Currently, only AWS CloudFormation supports this. Define each policy in permissions/policies/, then attach it by name. With permissions.toml, declare them as [[named_policies]] blocks in that file instead.
permissions/policies/rds-admin.toml
permissions/maintenance.toml
The name in a role’s [[named_policies]] must match a policy you’ve defined. Named policies are created even when the role that attaches them is disabled. The install stack outputs a named_policy_arns map of policy name to ARN, so components can attach a policy to other roles, such as a Kubernetes workload’s IAM role.

Assign a role to an entity

Sandbox (sandbox.toml)

Use an [[operation_roles]] array to map sandbox operations to roles.
sandbox.toml
Valid operations for sandbox: provision, reprovision, and deprovision.

Components (components/<name>.toml)

Use the same [[operation_roles]] array on any component config file.
components/my_lambda.toml
Valid operations for components: deploy and teardown.

Actions (actions/<name>.toml)

Actions use a single top-level role field.
actions/db_migration.toml

Set app-wide rules

Create operation_roles.toml at the root of your app config. Its rules apply across all installs and match on principal (the entity running the operation) and operation:
operation_roles.toml

Principals

Use * to set one role for every component or every action. Each rule’s operation is provision, reprovision, or deprovision for the sandbox, deploy or teardown for a component, and trigger for an action run.

Ship the config

After adding or changing operation role config, commit it and push to the git branch your app branch tracks:
The push starts a branch run, which uploads your app config to the control plane.

Check which role an entity uses

Open your install’s Components or Actions tab in the dashboard. Each entity shows the currently configured role.

Override the role for one run

You can pick a different role for a single run without changing any config.

CLI

Pass --role-name to nuon actions create-run and nuon installs components deploy-all. Pass --role to sandbox runs, reprovisions, deprovisions, and teardowns:
Use the role’s full name, including the install ID. If the name doesn’t match, the error lists the roles you can use.

Dashboard

On the install page, before triggering a run, use the role selector in the run options panel to choose a role from the install’s stack.

Which role a run uses

When a role is set in more than one place, Nuon uses the first match in this order: If the matching role is switched off in your customer’s stack, a run with a role picked for it fails. Any other run uses the standard role.

Next steps