> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuon.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Break Glass

> Customers can grant you elevated access when you need it.

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

**1. You define the emergency level of access**

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

**2. Your customer controls when and how the role is created**

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

**3. Your customer switches it on**

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

**4. You run an action**

Run an [action](https://docs.nuon.co/concepts/actions.md) or [runbook](https://docs.nuon.co/concepts/runbooks.md) with the role.

**5. Your customer switches it off**

Your customer switches the role off or removes it.

**6. 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](https://docs.nuon.co/concepts/operation-roles.md) 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.

```toml break_glass.toml theme={null}
[[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](https://docs.nuon.co/config-ref/break-glass.md) for Break Glass roles.

## Use a break glass role

Set an action's `role` to the break glass role:

```toml actions/eks-upgrade.toml theme={null}
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.

```toml theme={null}
[[triggers]]
type = "role-enabled"
```

It fires for any role, so check `ROLE_NAME` first. See [Role change triggers](https://docs.nuon.co/concepts/actions.md#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](https://docs.nuon.co/guides/slack.md#role-change-notifications) and a [webhook](https://docs.nuon.co/guides/webhooks.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.