docs: Self review of doc pages
This commit is contained in:
@@ -13,8 +13,7 @@ Each server's detail page shows the version it reported at its last sync.
|
||||
|
||||
## Updating from the UI
|
||||
|
||||
**Servers → _a server_ → Update agent** pushes `UpdateAgentCmd` with a target
|
||||
version. The agent then:
|
||||
Open a server and choose **Update agent**. The agent then:
|
||||
|
||||
1. Downloads the binary for its platform from the release.
|
||||
2. Verifies the SHA-256 against `checksums.txt`.
|
||||
@@ -35,8 +34,8 @@ irm https://vantage.example.com/update.ps1 | iex
|
||||
```
|
||||
|
||||
It does the same download, checksum and replace, then restarts the service. Use
|
||||
this when the control plane cannot push for example, when the machine is
|
||||
reachable but its command stream is not.
|
||||
this when Vantage cannot reach the agent to push the update, but you can still
|
||||
reach the machine.
|
||||
|
||||
## Rolling out across a fleet
|
||||
|
||||
@@ -54,9 +53,8 @@ Do one, confirm it returns to `active`, then do the rest.
|
||||
|
||||
## Version compatibility
|
||||
|
||||
The agent API is versioned to tolerate an agent older than the control plane. The
|
||||
reverse an agent newer than the control plane is not a case anyone tests.
|
||||
Upgrade the control plane first.
|
||||
An agent older than your control plane is supported. An agent newer than it is
|
||||
not, so upgrade the control plane first.
|
||||
|
||||
Agents report their version on every poll, so a fleet running mixed
|
||||
versions is visible in the server list rather than something you have to go
|
||||
|
||||
@@ -11,9 +11,8 @@ either one restores to something unusable.
|
||||
|
||||
| Store | Contents | Back up |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| MongoDB | Everything durable servers, keys, assignments, workflows, runs, monitors, incidents, secrets, settings, audit | **Yes** |
|
||||
| MongoDB | Everything durable: servers, keys, assignments, workflows, runs and their logs, monitors, incidents, secrets, settings, audit | **Yes** |
|
||||
| Redis | Sessions only | No. Losing it signs everyone out and nothing else |
|
||||
| `./data` bind mount | Workflow run logs | Optional |
|
||||
| `KEY_ENCRYPTION_KEY` | Not stored anywhere by the app | **Yes, separately** |
|
||||
|
||||
:::danger The database alone is not a backup
|
||||
@@ -50,7 +49,7 @@ nothing writes during the restore.
|
||||
cp /opt/vantage/.env /secure-location/vantage.env
|
||||
```
|
||||
|
||||
Treat it as a credential in its own right it holds the encryption key.
|
||||
Treat it as a credential in its own right, since it holds the encryption key.
|
||||
|
||||
## What a restore gives you
|
||||
|
||||
@@ -62,7 +61,7 @@ What it does **not** do is reconcile the world. After a restore:
|
||||
- Agents reconnect with their existing tokens, since the token hashes are in the
|
||||
database.
|
||||
- If the restore is older than an enrolment, that server's token hash is missing
|
||||
and the agent will fail to authenticate re-enrol it.
|
||||
and the agent will fail to authenticate. Re-enrol it.
|
||||
- The next agent poll rewrites `authorized_keys` to match the restored desired
|
||||
state, which may remove keys added since the backup.
|
||||
|
||||
@@ -74,8 +73,8 @@ What it does **not** do is reconcile the world. After a restore:
|
||||
| Environment file | On change, held in a password manager or secret store |
|
||||
| Restore rehearsal | Occasionally, into a throwaway host |
|
||||
|
||||
The rehearsal is the part that gets skipped and the part that finds the
|
||||
problems.
|
||||
Rehearse a restore now and again. It is the step most often skipped, and the one
|
||||
that finds the problems.
|
||||
|
||||
## Cloud instances
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ sidebar_label: Upgrading
|
||||
---
|
||||
|
||||
Upgrading the control plane is a pull and a recreate. Agents are versioned and
|
||||
upgraded separately see [Agent updates](./agent-updates.md).
|
||||
upgraded separately. See [Agent updates](./agent-updates.md).
|
||||
|
||||
:::info Cloud instances upgrade themselves
|
||||
This page is for self-hosted installs. If your instance is hosted by us, there
|
||||
@@ -26,11 +26,11 @@ renamed or removed.
|
||||
|
||||
## What happens on boot
|
||||
|
||||
1. **Migrations** run, recording markers so each runs once.
|
||||
2. **Indexes** are ensured. Auth and settings index builders are fatal on
|
||||
failure; secret and workflow ones only warn.
|
||||
3. **Default steps** are reseeded from the image, overwriting the `default`
|
||||
library which is why those steps are read-only.
|
||||
1. The database is brought up to date. Each change runs once.
|
||||
2. The built-in workflow steps are reinstalled, which is why those steps cannot
|
||||
be edited.
|
||||
|
||||
If Vantage cannot complete either safely, it stops rather than run half-prepared.
|
||||
|
||||
Watch it:
|
||||
|
||||
@@ -46,6 +46,16 @@ docker compose logs -f server
|
||||
- **Check your `.env`** still supplies everything required. A newly required
|
||||
variable stops the boot rather than defaulting to something unsafe.
|
||||
|
||||
## Single sign-on after an upgrade
|
||||
|
||||
Each identity provider now has its own callback URL. If you configured single
|
||||
sign-on on an older version it was carried over, but its callback URL changed,
|
||||
and sign-in through it fails until you copy the new one from its card in
|
||||
**Settings** and register it with your identity provider. The card shows a
|
||||
reminder until you dismiss it.
|
||||
|
||||
Password sign-in is unaffected, so you can always sign in locally to fix this.
|
||||
|
||||
## Downgrading
|
||||
|
||||
There is no automatic downgrade. Migrations do not roll back, so returning to an
|
||||
@@ -57,7 +67,7 @@ is the reason the backup is not optional.
|
||||
The stack is not designed for it. `docker compose up -d` recreates the server
|
||||
container, which is a short interruption:
|
||||
|
||||
- Agents reconnect on their own they retry, and the poll loop is idempotent.
|
||||
- Agents reconnect on their own.
|
||||
- Workflow runs in progress lose their command stream. Steps already dispatched
|
||||
finish on the agent, but their results have nowhere to go. **Do not upgrade
|
||||
during a run.**
|
||||
@@ -67,5 +77,4 @@ container, which is a short interruption:
|
||||
|
||||
- Confirm every service is `running`.
|
||||
- Confirm servers return to `active` within a couple of poll intervals.
|
||||
- Open a page that touches encryption a secret group to confirm
|
||||
`KEY_ENCRYPTION_KEY` came through.
|
||||
- Open a secret group, to confirm `KEY_ENCRYPTION_KEY` came through.
|
||||
|
||||
Reference in New Issue
Block a user