Example: separate deploy and teardown roles
This example gives anapi 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 atype.permissions/directory: one file per role, such aspermissions/maintenance.toml, each with atype.
type = "custom":
permissions.toml
Template role names
Role names support the same Go template syntax used elsewhere in Nuon config:
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 inpermissions/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
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
provision, reprovision, and deprovision.
Components (components/<name>.toml)
Use the same [[operation_roles]] array on any component config file.
components/my_lambda.toml
deploy and teardown.
Actions (actions/<name>.toml)
Actions use a single top-level role field.
actions/db_migration.toml
Set app-wide rules
Createoperation_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: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:
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
- Operation Roles: what operation roles are and when to use them
- Break Glass: roles your customer switches on when you need them
- Permissions config reference: every field in
permissions.toml