Break Glass - Nuon documentation

When a critical part of your app goes down, you need unusually high access, customer security teams will want auditability and scoped permissions. Nuon records when access was granted, what ran, and when it access was removed, so you can show them afterward.

How it works

You define the emergency level of access

Define the role and permissions you’ll need when something goes wrong.

Your customer controls when and how the role is created

Your customer’s security team can review the role before it’s ever created.

Your customer switches it on

When you have an incident, they switch the role on.

You run an action

Run an action or runbook with the role.

Your customer switches it off

Your customer switches the role off or removes it.

Share the Nuon-generated audit report

Share the post-incident report of everything done in their environment.

When to use break glass

Debugging an incident
Recovering an install a normal deploy can’t fix
Restoring a database
Upgrading a Kubernetes cluster

Break glass and operation roles

If your customer switches the same role on every week, ask them to approve it as a standing operation role instead.

	Break glass role	Operation role
Access	Granted when you need it, with a record of every use.	Standing. Your customer approves it once.
Default	Off. Created only when your customer switches it on.	On.
Declared in	`break_glass.toml`	`permissions.toml` or `permissions/`

Define a break glass role

Declare roles in break_glass.toml at the root of your app config. Your customer sees each role’s display_name and description when deciding whether to switch it on.

break_glass.toml

[[role]]
name         = "{{.nuon.install.id}}-eks-upgrade"
display_name = "EKS cluster upgrade"
description  = "Lets the vendor upgrade the EKS cluster."

[[role.policies]]
name     = "eks-upgrade"
contents = """
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "eks:DescribeCluster",
        "eks:DescribeUpdate",
        "eks:UpdateClusterVersion",
        "eks:DescribeNodegroup",
        "eks:UpdateNodegroupVersion"
      ],
      "Resource": "*"
    }
  ]
}
"""

On GCP, use gcp_permissions or gcp_predefined_role in place of contents.
Azure, use azure_actions or azure_built_in_roles.

See the config reference for Break Glass roles.

Use a break glass role

Set an action’s role to the break glass role:

actions/eks-upgrade.toml

name    = "eks-upgrade"
timeout = "30m"
role    = "{{.nuon.install.id}}-eks-upgrade"

[[triggers]]
type = "manual"

[[steps]]
name    = "upgrade cluster"
command = "aws eks update-cluster-version --name $CLUSTER_NAME --kubernetes-version 1.31"

[steps.env_vars]
CLUSTER_NAME = "{{.nuon.sandbox.outputs.cluster.name}}"

To use the role for a single run, pick it in the dashboard’s role selector or pass --role-name to nuon actions create-run.

Run actions when access is granted

A role-enabled trigger runs an action as soon as your customer switches a role on.

[[triggers]]
type = "role-enabled"

It fires for any role, so check ROLE_NAME first. See Role change triggers.

How your customer switches it on

CloudFormation: update the stack with the current template and set the role’s Enable… parameter.
Azure: redeploy the stack with the role’s enable parameter set.
Terraform (stack module, AWS or GCP): add the role to the module’s roles map, such as roles = { "eks-upgrade" = true }, and apply.
Terraform (generated files, AWS or GCP): set enabled = true on the role in break_glass_roles and apply.

Audit

Every break glass session leaves a record:

Access granted and removed: each time a role is switched on or off, Nuon can send a Slack notification and a webhook event, if you’ve set them up.
Work done: each run shows the role it used in the dashboard.
Actions in the account: your customer’s cloud audit logs, such as AWS CloudTrail, record each time the runner assumes the role.

​How it works

​When to use break glass

​Break glass and operation roles

​Define a break glass role

​Use a break glass role

​Run actions when access is granted

​How your customer switches it on

​Audit