The web view and the API
Several people, each with a role on each hop, signed in by the organisation's identity provider; a REST API over the command line's own functions.
migkit report --serve serves it: every hop's outcomes - what happens to each side, the time and outage predicted with their spread, the guarantees - its progress, the approvals and the changes on the source waiting for an answer, and the evidence, for the people each hop names, each signed in by the organisation's identity provider. The decision record is shown only when asked. The command line is not needed for any of it, and the view does nothing the command line does not: a run started here is the same command, with the same guards.
Signing in
- OpenID Connect: the code flow with PKCE; the ID token checked against the provider's published keys, issuer, audience, expiry and nonce (
MIGKIT_WEB_OIDC_ISSUER). - SAML 2.0: the provider's signed answer to a request this view made, read only out of the element the signature covers (
MIGKIT_WEB_SAML_METADATA). - SCIM 2.0 at
/scim/v2: the provider provisions who may sign in and their groups; a person deactivated there is signed out everywhere at once (MIGKIT_WEB_SCIM_TOKEN). - Without a provider, one local operator, the admin of every hop, set once through an address the view prints when it starts.
- Multi-factor sign-in is the provider's.
Roles
Written in the hops file's access - for every hop, a group of hops by name pattern, or one hop's options.access - by a person's name (shell patterns allowed) or group:NAME. Each role holds the ones before it; nobody has a role the file does not give.
| Role | What it may do |
|---|---|
viewer | reads the hop: what it does to each side, the prediction with its spread, the progress, the evidence, the approvals and offers standing, and the decision record when asked |
operator | also starts runs, holds or lets go a change tail, and answers a change on the source a faster way needs |
approver | also approves a step the hop's approvals hold back - never one they asked for |
admin | also sends the hop's receivers a test message; a global admin also reads the users, groups, sessions and the view's record |
What a person may start
| Run | What it does | Takes |
|---|---|---|
plan | the plan: what the move would do to each side, how long it would take with its spread, the case it is - nothing is written to either side | mode, db, table |
assess | readiness: what would stop a move, before anything moves | - |
check | the read-only comparison of the two sides | db, table, only, deep |
move | the move, as the plan says it | mode, db, table |
sync | the target made equal to the source: dry run, --apply or --go with a restore point | db, kind, mode, on_conflict, tag, apply, go |
cutover | the cutover: the stream torn down and the application moved - the hop's approvals first; a dry run without go | db, go |
drain | the running change tail drained to a position and held there - it cannot be taken back, so it is shown first; a dry run without go | db, to, go |
rollback | a saved state restored on the target - a dry run without apply | db, state, apply |
report | the hop's evidence exported again | - |
The API
Every route is served under /api/v1, answers JSON, and needs an API token made on the account page (Authorization: Bearer ...) or a signed-in page. A hop the caller may not see answers 404; a role too low, 403. The whole description: openapi.json.
| Method | Path | Needs | What it does |
|---|---|---|---|
GET | /api/v1/me | signed-in | who is signed in, and their role on each hop |
GET | /api/v1/hops | signed-in | the hops the caller may see, each with its verdict, runs going on and what waits |
GET | /api/v1/hops/<hop> | viewer | the hop as its file says it, every secret hidden, and what its goal does to each side |
GET | /api/v1/hops/<hop>/validation | viewer | what is wrong with the hop in its file, and what doctor would say of its keys |
GET | /api/v1/hops/<hop>/outcome | viewer | what the hop does to each side and guarantees; each planned database's phases with their p50 and p90, and the outage held to the hop's limits |
GET | /api/v1/hops/<hop>/progress | viewer | where the hop stands: the verdict, each move's progress and tail, and the metrics /metrics serves for it |
POST | /api/v1/hops/<hop>/plan | operator | a dry run of the move: what it would do and how long it would take - a run of its own, nothing written to either side |
GET | /api/v1/hops/<hop>/runs | viewer | the runs started from the view and the API, newest first |
POST | /api/v1/hops/<hop>/runs | operator | start a run: the plan, assess, a check, the move, a sync, the cutover, a rollback or the evidence export - the command line's own command, with the hop's guards and approvals |
GET | /api/v1/hops/<hop>/runs/<run> | viewer | one run: its state, exit, verdict and evidence |
GET | /api/v1/hops/<hop>/runs/<run>/output | viewer | a run's output from offset, secrets hidden |
POST | /api/v1/hops/<hop>/runs/<run>/stop | operator | stop a run as ctrl-c at its terminal would |
GET | /api/v1/hops/<hop>/approvals | viewer | the steps waiting for approval: what each will do, what approving lets happen, who has approved |
POST | /api/v1/hops/<hop>/approvals/<request> | approver | approve a step as the person signed in - never one they asked for |
GET | /api/v1/hops/<hop>/offers | viewer | the changes on the source a faster way needs, offered and not answered: what each buys and what not taking it means |
POST | /api/v1/hops/<hop>/offers/<change> | operator | answer an offered change on the source: yes, no or dba |
GET | /api/v1/hops/<hop>/evidence | viewer | the hop's evidence bundles and its record's chain |
GET | /api/v1/hops/<hop>/evidence/<name> | viewer | one file of the hop's whole-history bundle, as written |
GET | /api/v1/hops/<hop>/evidence/<run>/<name> | viewer | one file of a run's bundle, as written |
GET | /api/v1/hops/<hop>/decisions | viewer | the decision record, on request: each work, the way taken and why, every way passed over and why |
GET | /api/v1/hops/<hop>/notifications | viewer | who is told what: the receivers by kind, the events, the lag |
POST | /api/v1/hops/<hop>/notifications/test | admin | send the hop's receivers a test message |
POST | /api/v1/hops/<hop>/tails/<db>/hold | operator | hold a change tail between batches, its position saved |
POST | /api/v1/hops/<hop>/tails/<db>/drain | operator | drain a running change tail to a position and hold it there - a run of the drain action; a dry run without go |
POST | /api/v1/hops/<hop>/tails/<db>/resume | operator | let a held change tail go on |
POST | /api/v1/hops/<hop>/tails/<db>/stop | operator | end a change tail at its next batch, its position saved |
GET | /api/v1/tokens | signed-in | the caller's API tokens |
POST | /api/v1/tokens | signed-in | a new API token for the caller, shown once |
DELETE | /api/v1/tokens/<token> | signed-in | end one of the caller's API tokens |
GET | /api/v1/admin/people | global admin | the people and groups the identity provider provisioned, and the local account |
GET | /api/v1/admin/sessions | global admin | every session open |
GET | /api/v1/admin/record | global admin | the view's own record: sign-ins, provisioning, tokens, refusals |
GET | /api/v1/openapi.json | anyone | this document |
Setting it up
On this machine alone, nothing needs setting. Anywhere else it takes TLS - its own certificate, or a reverse proxy in front that does TLS, named so only it is answered. Deployment, the proxy's configuration and each provider's settings: docs/web.md.
| Variable | Kind | What it does |
|---|---|---|
MIGKIT_METRICS_TOKEN | secret | the bearer a scraper reads /metrics with; without it only someone signed in reads it, their own hops |
MIGKIT_UI_BIND | text | the address the web view (and the dashboard) listens on; for the web view, anything but this machine's loopback needs TLS |
MIGKIT_UI_HOSTS | list | more host names the web view and the dashboard answer to |
MIGKIT_WEB_IDLE_MINUTES | number | minutes without a request before a sign-in ends |
MIGKIT_WEB_OIDC_CLIENT_ID | text | the client the provider registered for the web view |
MIGKIT_WEB_OIDC_CLIENT_SECRET | secret | its secret, or a reference to where it is kept |
MIGKIT_WEB_OIDC_GROUPS | text | the claim a person's groups are in |
MIGKIT_WEB_OIDC_ISSUER | text | the OpenID Connect provider people sign in through, its issuer's address |
MIGKIT_WEB_OIDC_SCOPES | list | the scopes asked for |
MIGKIT_WEB_PLAIN | flag | serve the web view without TLS beyond this machine's loopback - only where the network to it is the operator's own: a container published on the host's loopback |
MIGKIT_WEB_PROXIES | list | the addresses of the reverse proxies in front of the web view: the only ones answered, and whose forwarded headers are read |
MIGKIT_WEB_RESET | flag | print an address that sets the local operator's password again |
MIGKIT_WEB_SAML_ENCRYPTED | flag | demand an encrypted assertion from the SAML identity provider: a plain one is refused |
MIGKIT_WEB_SAML_GROUPS | text | the attribute a person's groups are in |
MIGKIT_WEB_SAML_METADATA | path | the SAML identity provider's metadata, as it publishes it |
MIGKIT_WEB_SAML_NAME | text | the attribute naming the person, where not the name identifier |
MIGKIT_WEB_SCIM_TOKEN | secret | the bearer token the provider provisions people and groups with; set, only people it provisioned sign in |
MIGKIT_WEB_SESSION_HOURS | number | the longest a sign-in lasts |
MIGKIT_WEB_STATE | path | where the web view keeps its sessions, the people provisioned and its signing key |
MIGKIT_WEB_TLS_CERT | path | the web view's certificate (PEM, its chain after it) |
MIGKIT_WEB_TLS_KEY | path | the certificate's private key |
MIGKIT_WEB_TOKEN_DAYS | number | the longest an API token lasts |
MIGKIT_WEB_URL | text | the address people open the web view at, https:// behind a proxy or with a certificate |