Mutations

Buoy gates every write through a confirmation modal. The defaults are deliberately strict: by default, you must type the object name before the Confirm button activates, and destructive actions render with a red header. You can dial that down per your taste in Settings.

This page covers the actions that change cluster state. Read-only behavior (logs, YAML viewing, scheduling explanations) is documented in detail-views.md. For plugin-authored actions, see plugins/actions.md.

Contents

• Confirmation Modes
• Single-Object Actions
• Bulk Actions in Tables
• Editing Labels and Annotations
• Editing YAML
• Apply YAML
• Impersonation

Confirmation Modes

Set the mode under Settings, Mutation Confirmations.

When an action is denied for lack of permission, Buoy shows a banner. With the “Impersonate on Auth Failure” toggle enabled, it offers to activate /as with a recent or new identity. The original action is not retried automatically; you re-run it under the new identity.

Single-Object Actions

Every detail view has an Actions menu (kebab, also reachable with m). The available actions depend on the kind. Each opens a confirmation modal; the phrase to type is the object’s name.

Plugins can contribute additional actions to the same menu; they appear under their plugin name.

Bulk Actions in Tables

Any list view supports multi-select. Enter select mode by clicking a row checkbox, pressing x on the cursor row, or pressing a to select every visible row. Shift-click toggles a contiguous range from the last clicked checkbox. The header checkbox toggles every row in the current sort and filter.

While a selection is active, a sticky bar appears above the table with an Actions dropdown and a clear button. Press m to open the menu from the keyboard. The available actions depend on the resolved kind.

The confirm phrase for bulk actions is the verb plus the selection, for example DELETE 3 pods or RESTART 2 deployments. Errors are collected per row and shown inline; partial failures keep the modal open so you can retry or cancel.

Plugins can register bulk actions that obey the same selection model.

Editing Labels and Annotations

The Edit Labels and Edit Annotations dialogs accept kubectl-style syntax in a single text area. Each entry is space- or newline-separated. Blank lines and lines starting with # are ignored.

Worked example:

team=platform
owner=alice
deprecated-
# Annotations follow the same rules.
example.com/last-touched=2026-05-26

Only the keys you list are touched: key=value adds or updates that key, key- removes it, and every other label or annotation is left alone.

Editing YAML

Open a detail view’s YAML tab. Click Edit, or press the Edit button in the tab strip. The editor switches to writable mode and tracks your draft.

When you click Apply, Buoy shows a confirmation modal with a diff between the original and your draft. The phrase to type is the object name. On confirm, your draft is applied to the cluster, taking ownership of the fields you changed even if another controller manages them.

Errors surface inline, labeled with the kind, namespace, and name. The modal stays open so you can fix and retry without losing your draft. Toggling Edit off discards the draft.

Apply YAML

The Apply YAML action takes a multi-document YAML blob and applies each document to the cluster. It’s reachable from the kebab menu on a list view (and from plugins or slash commands that call into it). The result is a table of per-document outcomes: kind, namespace, name, and whether it succeeded.

Audit Log

Every mutation listed on this page writes one row to a local SQLite audit log (audit.db next to prefs.json). The log captures the before/after object JSON, context, impersonation, params, status, and duration — so you can answer “what changed, when, and by whom” without leaving the app. Open it with /audit, or filter to one object via View Audit History in any detail page’s Actions menu. See audit/ for the full reference, including the Secret redaction policy and retention caps.

Impersonation

/as activates Kubernetes impersonation. Once active, every mutation runs as the impersonated user, and the whole app paints a red border so impersonated sessions are visually distinct.

/as alice
/as alice --groups platform,sre
/as alice --groups platform --uid 1234
/as              # clear
/as -            # clear

Sessions auto-expire after 10 minutes of idleness or 60 minutes from activation, whichever comes first. Keystrokes and mouse activity reset the idle timer. See contexts.md for details.

Edit this page on GitLab