feat: Phases 9/11/12/13 — diff / lessons / inconsistencies / digest (#3)
This commit was merged in pull request #3.
This commit is contained in:
@@ -0,0 +1,236 @@
|
||||
# HPE Morpheus VM Essentials — Lessons
|
||||
|
||||
Notes and gotchas about running, integrating with, and upgrading
|
||||
**HPE Morpheus VM Essentials (HVM)** that aren't obvious from the
|
||||
official docs alone. The official docs (User Manual, Release Notes,
|
||||
Deployment Guide) describe the product as designed; this file is
|
||||
what experienced operators actually learn.
|
||||
|
||||
> Treat this as living context. Update it when you (or the LLM
|
||||
> driving this MCP) discover something non-obvious that the docs
|
||||
> don't say or don't make findable. Each section is an H2 so the
|
||||
> `hvm_api_lessons(topic=...)` tool can return just the relevant
|
||||
> piece.
|
||||
|
||||
## TL;DR
|
||||
|
||||
- **HVM is KVM under the hood.** The "VM Essentials manager" is a
|
||||
control-plane VM that orchestrates KVM hosts ("HVM Hosts"). The
|
||||
manager runs the same web UI you'd see in HPE Morpheus Enterprise,
|
||||
but scoped to the HVM hypervisor capability set. Elevating
|
||||
unlocks the full Morpheus Enterprise feature set.
|
||||
- **Versioning is independent per upgrade hop.** The manager,
|
||||
HVM Host agents, and the Plugin API are versioned separately. After
|
||||
every manager upgrade, re-check HVM Host agent versions — they
|
||||
don't auto-upgrade with the manager.
|
||||
- **Compatibility matrix lives in the Release Notes.** Each version's
|
||||
Release Notes lists the compatible Plugin API + Worker versions
|
||||
for that build. Use `weekly_digest` or `get_page` on the Release
|
||||
Notes when planning an upgrade.
|
||||
- **Two consumer surfaces:** the web UI on the manager (port 443),
|
||||
and the REST API (same host, `/api/` path). For automation use
|
||||
the REST API; for ad-hoc admin use the UI.
|
||||
|
||||
## Manager sizing — pick based on cluster count
|
||||
|
||||
The Deployment Guide page `VME Manager sizing` is the authoritative
|
||||
table. Quick mental model:
|
||||
|
||||
| Size | vCPU | RAM | Max HVM clusters (prod-realistic) |
|
||||
|--------|------|-------|------------------------------------|
|
||||
| Small | 2 | 12GB | 1 (test/PoC only) |
|
||||
| Medium | 4 | 16GB | 3 |
|
||||
| Large | 4 | 32GB | up to 10 |
|
||||
|
||||
**Pick Medium by default for production.** Small is genuinely
|
||||
underpowered for anything beyond a lab — UI latency degrades fast
|
||||
when concurrent provisioning runs.
|
||||
|
||||
You CAN'T resize the manager in place by editing the VM. Backup, deploy
|
||||
a new manager at the new size, restore. See `Backing Up and Restoring
|
||||
the HPE Morpheus VM Essentials Manager` in the User Manual.
|
||||
|
||||
## Upgrade ordering — manager first, then host agents
|
||||
|
||||
HVM doesn't auto-upgrade host agents along with the manager. Every
|
||||
manager upgrade hop is two steps:
|
||||
|
||||
1. **Upgrade the manager** (e.g., 8.1.0 → 8.1.1). Standard upgrade
|
||||
process per the Deployment Guide.
|
||||
2. **Upgrade each HVM Host's agent.** Manager → HVM Host detail →
|
||||
ACTIONS menu → "Upgrade Agent". Alternative: download the agent
|
||||
upgrade script and run it on each host. Scripts are UNIQUE PER
|
||||
HOST — don't reuse one script across multiple hosts.
|
||||
|
||||
Some upgrade hops won't actually require a host-agent update (the
|
||||
manager release didn't change the agent). Check the Release Notes for
|
||||
the target version to see whether a host agent upgrade is included.
|
||||
|
||||
> Skipping the agent upgrade step is the #1 cause of cluster issues
|
||||
> right after a manager upgrade. Symptoms: hosts appear "out of
|
||||
> sync" or "agent disconnected" in the manager UI, even though the
|
||||
> hosts themselves are healthy.
|
||||
|
||||
## Plugin API + Worker version compatibility
|
||||
|
||||
Each HVM version pins a specific compatible Plugin API version and
|
||||
minimum HVM Host Worker version. The Release Notes for that version
|
||||
state both. Examples (verify against the live Release Notes):
|
||||
|
||||
- HVM 8.1.2 → Plugin API 1.3.4, HVM Host Worker ≥ 5.4.8
|
||||
- (Earlier versions: check the corresponding `hvm_release_notes_*`
|
||||
bundle.)
|
||||
|
||||
When writing a plugin or integration:
|
||||
|
||||
- Pin the Plugin API version explicitly in your integration's deps.
|
||||
- Test against the matrix combinations of the HVM versions you're
|
||||
promising support for.
|
||||
- Be aware that minor versions can change the Plugin API surface;
|
||||
don't assume drop-in compat across 8.1.x.
|
||||
|
||||
## Backups — the "global settings first" trap
|
||||
|
||||
`Initial Backups Setup` says to configure Global Backup Settings,
|
||||
Storage Providers, and Execution Schedules **before** creating any
|
||||
backup jobs. This is real — if you skip global settings and just
|
||||
create a backup, the job runs with defaults that may not match what
|
||||
you want (retention, schedule alignment, synthetic-full cadence).
|
||||
|
||||
Order of operations:
|
||||
|
||||
1. **Global Backup Settings** (Administration → Settings → Backups)
|
||||
— enable scheduled backups globally, set defaults.
|
||||
2. **Storage Providers** (Infrastructure → Storage) — configure
|
||||
where backups land.
|
||||
3. **Execution Schedules** (Library → Automation → Execute
|
||||
Scheduling) — define when jobs run.
|
||||
4. **Then** create backup jobs (Backups → Backups → ADD).
|
||||
|
||||
### Synthetic Full backups
|
||||
|
||||
Only meaningful for HVM Instance backups (not VMware/etc.). When
|
||||
enabled, the manager periodically synthesizes a "new full" from a
|
||||
chain of incrementals so restore time stays bounded as the chain
|
||||
grows. Recommended on for production HVM Instance backups.
|
||||
|
||||
### VMware-specific quirk
|
||||
|
||||
For VMware Cloud-type backups, the manager merges + consolidates
|
||||
snapshots BEFORE the OVF export. That means a long-held snapshot
|
||||
chain gets squashed into the backup — fine, but the source VM's
|
||||
snapshot list changes as a side effect of the backup run. Coordinate
|
||||
with anyone who relied on those snapshots existing.
|
||||
|
||||
## Console access — hypervisor vs guest, and keyboard layouts
|
||||
|
||||
HVM VMs expose **two** console paths:
|
||||
|
||||
- **Guest console** — what's inside the VM (the OS desktop /
|
||||
console). Subject to whatever the guest OS provides.
|
||||
- **Hypervisor console** — the KVM-level console (pre-OS, BIOS,
|
||||
bootloader). Useful for OS install, kernel-panic recovery,
|
||||
GRUB editing.
|
||||
|
||||
Per-VM keyboard layout is set on the VM, then applied to each
|
||||
session. Choose based on the keyboard the operator who'll actually
|
||||
use the console has. Mismatches show up as characters being typed
|
||||
"wrong" in the console even though the keyboard is fine — usually
|
||||
operator picks the layout setting once during VM provisioning and
|
||||
forgets to revisit.
|
||||
|
||||
### 8.1.2 added Japanese 101/102 keyboard layout
|
||||
|
||||
Only in 8.1.2 and later: Japanese 101/102 hardware keyboards are
|
||||
supported. The 106/109 layout (the more common JP keyboard form
|
||||
factor) was announced as a planned future enhancement at 8.1.2.
|
||||
|
||||
The 8.1.2 console UI also gained a "keyboard tips" pop-over (the
|
||||
"?" button) using the HPE Morpheus key extension. Works for VMware,
|
||||
vCD, and HVM/KVM consoles.
|
||||
|
||||
## Elevating to HPE Morpheus Enterprise
|
||||
|
||||
HVM ships as the VM-only subset of HPE Morpheus's platform. Elevating
|
||||
upgrades the manager into the full Morpheus Enterprise SKU, which
|
||||
unlocks multi-cloud, container, automation, and policy features.
|
||||
|
||||
Elevation is an in-place upgrade — you don't redeploy the manager.
|
||||
Per the User Manual page `Elevating to HPE Morpheus Enterprise`:
|
||||
|
||||
- Acquire/install a Morpheus Enterprise license.
|
||||
- Run the elevation procedure (UI-driven from the manager).
|
||||
- HVM clusters keep working unchanged after elevation.
|
||||
|
||||
> When elevated, the docs you want to read shift to the Morpheus
|
||||
> Enterprise documentation set (sd0000{7510,7621,7732}en_us). A
|
||||
> separate `morpheus-docs` MCP exists for that surface; treat HVM
|
||||
> docs as a strict subset.
|
||||
|
||||
## REST API surface
|
||||
|
||||
**TODO — fill in as we learn it.** The Deployment Guide includes an
|
||||
"API reference" entry; the actual API is the Morpheus REST API
|
||||
(scoped to the HVM-relevant subset on a non-elevated manager). Until
|
||||
this section gets real content, the practical advice is:
|
||||
|
||||
- Hit `https://<manager>/api/` — same shape as Morpheus Enterprise's
|
||||
API. Use bearer-token auth (issue tokens from the user profile /
|
||||
api-tokens UI).
|
||||
- The Morpheus public OpenAPI / API docs document the full surface;
|
||||
HVM-only managers reject Enterprise-only endpoints with 404.
|
||||
- Plugin API and REST API are SEPARATE surfaces. Plugins extend the
|
||||
manager; the REST API is for external automation.
|
||||
|
||||
If you've integrated against HVM REST in anger and have specific
|
||||
notes (auth quirks, undocumented endpoints, schema gotchas,
|
||||
pagination behavior, etc.), drop them here.
|
||||
|
||||
## Networking & deployment scenarios
|
||||
|
||||
The Deployment Guide outlines two recommended network topologies:
|
||||
|
||||
- **Scenario 1: Converged networking** (one bonded interface group
|
||||
carries management + storage + VM traffic, segmented by VLAN).
|
||||
Simpler to deploy; recommended for most environments.
|
||||
- **Scenario 2: Decoupled networking** (separate physical NICs for
|
||||
management vs storage vs VM traffic). More throughput for
|
||||
high-density VM hosts but more cabling.
|
||||
|
||||
`Network Bonding` covers the bond configuration. Active-Backup is the
|
||||
safe default; LACP requires switch coordination.
|
||||
|
||||
The **Required ports** page is the authoritative list — check it
|
||||
before firewalling anything between the manager and HVM Hosts. The
|
||||
list changes as features evolve; don't memorize.
|
||||
|
||||
## Common operational gotchas
|
||||
|
||||
- **Storage Buckets vs Backup Targets.** Same concept, different
|
||||
context. A "Storage Bucket" is a configured storage provider in
|
||||
Morpheus terms; a "Backup Target" is what the backup wizard calls
|
||||
the same thing during the create-backup flow. They're the same
|
||||
underlying object.
|
||||
- **Disabling 2FA.** Per-user, set from the user's profile page.
|
||||
There's no global "disable 2FA for everyone" toggle — for
|
||||
environments that need to back out a 2FA rollout, disable
|
||||
per-user.
|
||||
- **VM Essentials Network Pool.** Defined in Infrastructure →
|
||||
Network → Pools. The HVM provisioning flow allocates IPs from
|
||||
this pool — if pool is exhausted, provisioning fails with a
|
||||
confusing error message in the activity log; check pool free
|
||||
count first when troubleshooting.
|
||||
|
||||
## Adding to this doc
|
||||
|
||||
Two ways:
|
||||
|
||||
1. Manually edit `docs_mcp/api_lessons.md` in this repo and commit.
|
||||
The next image build picks it up.
|
||||
2. Use `submit_doc_bug` for upstream issues, and append the
|
||||
takeaway here once the docs team responds.
|
||||
|
||||
The point of this doc is to surface the kind of context an
|
||||
experienced operator would mention in a hallway conversation but
|
||||
that doesn't quite fit anywhere in the formal product docs. Keep
|
||||
sections tight — one H2 = one topic the LLM can return on demand.
|
||||
Reference in New Issue
Block a user