Add Cloud Dashboard docs (setup + migration from license server) by hank-metalbear · Pull Request #338 · metalbear-co/docs

hank-metalbear · 2026-08-26T20:41:18Z

Summary

Adds documentation for the cloud dashboard, the usage dashboard served from app.metalbear.com for operators that authenticate with a cloud API key (no self-hosted license server). Written to PRO-228.

New customers: sign in, generate a cloud API key (admin-only, identity-sharing choice), install the operator with it, run a first session.
Existing installs on a license key: add cloud.apiKey to the Helm values (license.* stays), upgrade, with the data-timing behavior spelled out (identity forward, usernames backfill per user, service detail doesn't).
Migration from the license server dashboard: remove license.licenseServer (it makes the cloud key a no-op), optional history import, uninstall the license-server chart when it was dashboard-only.
Gotchas: cloud vs license server is one or the other; cloud.anonymizeData: true overrides consent; minimum chart 3.179.0 (identity 3.193.0); air-gapped stays on the license server dashboard.

Changes

New page managing-mirrord/cloud-dashboard.md.
managing-mirrord/admin-dashboard.md: note distinguishing the two dashboards, linking across.
SUMMARY.md: new nav entry under Managing mirrord.

Notes for review

PRO-228 says minimum 3.178.0 for cloud.apiKey, but the 3.178.0 tag's chart doesn't contain the value; it first ships in 3.179.0, so the doc says 3.179.0.
The license-server history import is "contact us" (operator-assisted), per RFC 0010's export/import path.

New page managing-mirrord/cloud-dashboard.md covering the usage dashboard served from app.metalbear.com for operators that authenticate with a cloud API key: how new customers set it up, how to use it, and how to migrate from the self-hosted license server dashboard. Cross-links from the existing Dashboard page and adds a SUMMARY entry. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

greptile-apps · 2026-08-26T20:52:43Z

Greptile Summary

The PR adds setup and license-server migration documentation for the cloud-hosted usage dashboard and distinguishes it from the self-hosted dashboard. The automatically discovered PRO-228 requirements materially inform the intended setup contract.

Adds cloud API-key onboarding, identity-sharing guidance, and dashboard usage instructions.
Documents migration from license-server authentication to cloud authentication.
Adds cross-links and navigation for choosing between cloud and self-hosted dashboards.

Important Files Changed

Filename	Overview
docs/managing-mirrord/cloud-dashboard.md	Adds the complete cloud-dashboard guide, but its setup prerequisites and migration command can leave customers unable to connect or still using license-server authentication.
docs/managing-mirrord/admin-dashboard.md	Correctly distinguishes the self-hosted dashboard and links cloud-authenticated operators to the new guide.
docs/SUMMARY.md	Adds a valid navigation entry for the new cloud-dashboard page.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Existing Operator using license server] --> B[Generate cloud API key]
  B --> C[Remove license.licenseServer from Helm values]
  C --> D[Configure cloud.apiKey]
  D --> E[Upgrade and restart Operator]
  E --> F[Operator authenticates with mirrord cloud]
  F --> G[New sessions appear in Cloud Dashboard]

_{Reviews (1): Last reviewed commit: "Add Cloud Dashboard docs (new-customer s..." | Re-trigger Greptile}

greptile-apps · 2026-08-26T20:52:46Z

+3. **Reinstall the operator with the cloud API key** and remove the license-server configuration. In your Helm values, add `cloud.apiKey` and drop `license.licenseServer`:
+
+   ```bash
+   helm upgrade --set cloud.apiKey.key=<YOUR_API_KEY> mirrord-operator metalbear/mirrord-operator


License-server values remain

When an existing Helm release contains license.licenseServer, this command adds the cloud key but retains the previous license-server value, causing the operator to keep using license-server authentication and send no usage to the cloud dashboard.

Knowledge Base Used: Mirrord platform operations

Source Used: Linear — Docs: how customers enable the cloud dashboard

The documented command is helm upgrade ... -f values.yaml without --reuse-values, so helm does not carry values over from the previous release; the file the customer edits is the whole configuration, and the section explicitly says to remove license.licenseServer from it and why. Also split out in 2f2b4ab: plain license.* (license-key) values stay, only license.licenseServer is the no-op case.

You're right. Because the documented command supplies the complete edited values.yaml with -f and does not use --reuse-values, Helm does not retain the previous license.licenseServer; omitting it from that file removes the setting on upgrade. My comment incorrectly assumed release values were being reused, so it does not apply.

The distinction between the values is also correct: existing license.* license-key settings can remain, while only license.licenseServer conflicts with cloud authentication. No documentation change is needed for this comment.

Tip: You can customize Greptile's behavior for this repo with .greptile/rules.md and .greptile/config.json.

greptile-apps · 2026-08-26T20:52:46Z

+The cloud dashboard needs the operator to reach `analytics.metalbear.com` and `app.metalbear.com` for outbound telemetry. If you run air-gapped or cannot allow that traffic, stay on the [license server dashboard](admin-dashboard.md), which keeps all data inside your cluster.
+{% endhint %}
+
+## New customers: set up the cloud dashboard


Version prerequisites missing

When customers use an Operator older than 3.178.0, cloud.apiKey is unsupported; versions older than 3.193.0 also lack identity reporting. Omitting these minimum versions causes setup to fail or identity details to remain anonymized despite following the guide.

Source Used: Linear — Docs: how customers enable the cloud dashboard

Added in 2f2b4ab as an intro hint. One correction to the source: per the chart history, cloud.apiKey first shipped in chart 3.179.0 (the 3.178.0 tag's values.yaml does not contain it; the commit adding it, #1851, is first contained in 3.179.0), so the doc says 3.179.0. Identity at 3.193.0 confirmed.

greptile-apps · 2026-08-26T20:52:46Z

+   * **Leave it checked** to give your dashboard per-user detail (usernames and targets).
+   * **Uncheck it** to keep telemetry anonymized, in which case the dashboard shows activity without attributing it to named users or targets.


Anonymization overrides consent

When cloud.anonymizeData is true, enabling identity sharing on the API key does not provide usernames or target details because the configuration override keeps telemetry anonymized, contrary to the outcome documented here.

Source Used: Linear — Docs: how customers enable the cloud dashboard

Added in 2f2b4ab: a hint under the key-generation step notes that cloud.anonymizeData: true overrides identity sharing and keeps telemetry anonymized even with consent granted.

greptile-apps · 2026-08-26T20:52:46Z

+
+1. **Sign in.** Go to [app.metalbear.com](https://app.metalbear.com) and sign in (or create your organization).
+
+2. **Generate a cloud API key.** In the onboarding wizard's **Install the Operator** step, click **Generate API Key**. Before generating, decide whether to share identity-level usage data:


Admin permission omitted

When a non-admin platform engineer follows this step, organization-level permissions prevent API-key generation, causing setup or migration to stop without the guide explaining that an organization administrator must perform this action.

Source Used: Linear — Docs: how customers enable the cloud dashboard

Added in 2f2b4ab: the key-generation step now says organization admins only, and points at the API Keys section.

…x two clumsy lines

hank-metalbear · 2026-08-26T21:03:16Z

+If your operator authenticates with a cloud API key rather than a self-hosted license server, you get the usage dashboard at [app.metalbear.com](https://app.metalbear.com) with nothing to deploy in your cluster. It shows the same sessions, users, targets, CI, and adoption views as the [license server dashboard](admin-dashboard.md).
+
+{% hint style="info" %}
+The cloud dashboard is in early access and is being rolled out gradually. If you have connected your operator and still don't see it, [get in touch](https://metalbear.com/mirrord/contact/) and we'll turn it on for your organization.


this isn't the case, it's rolled out 100%

Fixed in 2f2b4ab: the early-access notice is gone (and the beta tag with it); the intro hint now carries the minimum versions instead.

Rollout is complete, so the early-access notice goes. Key generation is admin- only and regenerating replaces the key; anonymizeData overrides consent; minimum chart versions stated. Enabling on a license-key install keeps license.* values and gets its data-timing behavior spelled out; the license-server migration is its own section.

Main restructured the dashboard docs into a shared Dashboard page with License Server Setup and Cloud Setup sub-pages. SUMMARY.md keeps main's sub-pages and the branch's Cloud Dashboard page; admin-dashboard.md takes main's version, since its comparison table already routes cloud API key users to the cloud setup page and the plan hint was retired on main when the cloud dashboard opened to the Team tier. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ByVUL77bCcdDseKzXqb2a7

Main already carries the branch's cloud dashboard content at managing-mirrord/dashboard/cloud.md, so the standalone page would ship as a duplicate. Drop it and its nav entry, and carry over the three lines the setup page lacked: code formatting on mirrord wizard and the mirrord-license-server chart name, and the note that theme, organization, and navigation come from the app shell rather than a standalone app bar. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ByVUL77bCcdDseKzXqb2a7

hank-metalbear and others added 4 commits August 26, 2026 16:41

Tighten the cloud dashboard docs wording

7c9520f

Cut repetition and standardize terminology in the cloud dashboard docs

86517df

Fix the migration upgrade command to go through the values file

99911d9

greptile-apps Bot reviewed Aug 26, 2026

View reviewed changes

hank-metalbear added 2 commits August 26, 2026 16:54

Drop the repeated remove-it instruction and point at the secret setup

20771a8

Cut the mirrored auth sentence and the doubled air-gapped warning, fi…

2237c2a

…x two clumsy lines

hank-metalbear commented Aug 26, 2026

View reviewed changes

hank-metalbear requested a review from liron-sel August 26, 2026 21:15

hank-metalbear and others added 2 commits September 7, 2026 19:54

Navigation Menu

Add Cloud Dashboard docs (setup + migration from license server) - #338

Add Cloud Dashboard docs (setup + migration from license server)#338
hank-metalbear wants to merge 9 commits into
mainfrom
han/cloud-dashboard-docs

hank-metalbear commented Aug 26, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Aug 26, 2026

Greptile Summary

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Aug 26, 2026

Uh oh!

hank-metalbear Aug 26, 2026

Uh oh!

greptile-apps Bot Aug 26, 2026

Uh oh!

greptile-apps Bot Aug 26, 2026

Uh oh!

hank-metalbear Aug 26, 2026

Uh oh!

greptile-apps Bot Aug 26, 2026

Uh oh!

hank-metalbear Aug 26, 2026

Uh oh!

greptile-apps Bot Aug 26, 2026

Uh oh!

hank-metalbear Aug 26, 2026

Uh oh!

hank-metalbear Aug 26, 2026

Uh oh!

hank-metalbear Aug 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		* Leave it checked to give your dashboard per-user detail (usernames and targets).
		* Uncheck it to keep telemetry anonymized, in which case the dashboard shows activity without attributing it to named users or targets.


		1. Sign in. Go to [app.metalbear.com](https://app.metalbear.com) and sign in (or create your organization).

		2. Generate a cloud API key. In the onboarding wizard's Install the Operator step, click Generate API Key. Before generating, decide whether to share identity-level usage data:

Conversation

hank-metalbear commented Aug 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Notes for review

Uh oh!

greptile-apps Bot commented Aug 26, 2026

Greptile Summary

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

hank-metalbear Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

hank-metalbear Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

hank-metalbear Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

hank-metalbear Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

hank-metalbear Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

hank-metalbear Aug 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

hank-metalbear commented Aug 26, 2026 •

edited

Loading