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

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.

RoleWhat it may do
viewerreads 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
operatoralso starts runs, holds or lets go a change tail, and answers a change on the source a faster way needs
approveralso approves a step the hop's approvals hold back - never one they asked for
adminalso 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

RunWhat it doesTakes
planthe 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 sidemode, db, table
assessreadiness: what would stop a move, before anything moves-
checkthe read-only comparison of the two sidesdb, table, only, deep
movethe move, as the plan says itmode, db, table
syncthe target made equal to the source: dry run, --apply or --go with a restore pointdb, kind, mode, on_conflict, tag, apply, go
cutoverthe cutover: the stream torn down and the application moved - the hop's approvals first; a dry run without godb, go
drainthe running change tail drained to a position and held there - it cannot be taken back, so it is shown first; a dry run without godb, to, go
rollbacka saved state restored on the target - a dry run without applydb, state, apply
reportthe 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.

MethodPathNeedsWhat it does
GET/api/v1/mesigned-inwho is signed in, and their role on each hop
GET/api/v1/hopssigned-inthe hops the caller may see, each with its verdict, runs going on and what waits
GET/api/v1/hops/<hop>viewerthe hop as its file says it, every secret hidden, and what its goal does to each side
GET/api/v1/hops/<hop>/validationviewerwhat is wrong with the hop in its file, and what doctor would say of its keys
GET/api/v1/hops/<hop>/outcomeviewerwhat 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>/progressviewerwhere the hop stands: the verdict, each move's progress and tail, and the metrics /metrics serves for it
POST/api/v1/hops/<hop>/planoperatora 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>/runsviewerthe runs started from the view and the API, newest first
POST/api/v1/hops/<hop>/runsoperatorstart 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>viewerone run: its state, exit, verdict and evidence
GET/api/v1/hops/<hop>/runs/<run>/outputviewera run's output from offset, secrets hidden
POST/api/v1/hops/<hop>/runs/<run>/stopoperatorstop a run as ctrl-c at its terminal would
GET/api/v1/hops/<hop>/approvalsviewerthe steps waiting for approval: what each will do, what approving lets happen, who has approved
POST/api/v1/hops/<hop>/approvals/<request>approverapprove a step as the person signed in - never one they asked for
GET/api/v1/hops/<hop>/offersviewerthe 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>operatoranswer an offered change on the source: yes, no or dba
GET/api/v1/hops/<hop>/evidenceviewerthe hop's evidence bundles and its record's chain
GET/api/v1/hops/<hop>/evidence/<name>viewerone file of the hop's whole-history bundle, as written
GET/api/v1/hops/<hop>/evidence/<run>/<name>viewerone file of a run's bundle, as written
GET/api/v1/hops/<hop>/decisionsviewerthe decision record, on request: each work, the way taken and why, every way passed over and why
GET/api/v1/hops/<hop>/notificationsviewerwho is told what: the receivers by kind, the events, the lag
POST/api/v1/hops/<hop>/notifications/testadminsend the hop's receivers a test message
POST/api/v1/hops/<hop>/tails/<db>/holdoperatorhold a change tail between batches, its position saved
POST/api/v1/hops/<hop>/tails/<db>/drainoperatordrain 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>/resumeoperatorlet a held change tail go on
POST/api/v1/hops/<hop>/tails/<db>/stopoperatorend a change tail at its next batch, its position saved
GET/api/v1/tokenssigned-inthe caller's API tokens
POST/api/v1/tokenssigned-ina new API token for the caller, shown once
DELETE/api/v1/tokens/<token>signed-inend one of the caller's API tokens
GET/api/v1/admin/peopleglobal adminthe people and groups the identity provider provisioned, and the local account
GET/api/v1/admin/sessionsglobal adminevery session open
GET/api/v1/admin/recordglobal adminthe view's own record: sign-ins, provisioning, tokens, refusals
GET/api/v1/openapi.jsonanyonethis 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.

VariableKindWhat it does
MIGKIT_METRICS_TOKENsecretthe bearer a scraper reads /metrics with; without it only someone signed in reads it, their own hops
MIGKIT_UI_BINDtextthe address the web view (and the dashboard) listens on; for the web view, anything but this machine's loopback needs TLS
MIGKIT_UI_HOSTSlistmore host names the web view and the dashboard answer to
MIGKIT_WEB_IDLE_MINUTESnumberminutes without a request before a sign-in ends
MIGKIT_WEB_OIDC_CLIENT_IDtextthe client the provider registered for the web view
MIGKIT_WEB_OIDC_CLIENT_SECRETsecretits secret, or a reference to where it is kept
MIGKIT_WEB_OIDC_GROUPStextthe claim a person's groups are in
MIGKIT_WEB_OIDC_ISSUERtextthe OpenID Connect provider people sign in through, its issuer's address
MIGKIT_WEB_OIDC_SCOPESlistthe scopes asked for
MIGKIT_WEB_PLAINflagserve 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_PROXIESlistthe addresses of the reverse proxies in front of the web view: the only ones answered, and whose forwarded headers are read
MIGKIT_WEB_RESETflagprint an address that sets the local operator's password again
MIGKIT_WEB_SAML_ENCRYPTEDflagdemand an encrypted assertion from the SAML identity provider: a plain one is refused
MIGKIT_WEB_SAML_GROUPStextthe attribute a person's groups are in
MIGKIT_WEB_SAML_METADATApaththe SAML identity provider's metadata, as it publishes it
MIGKIT_WEB_SAML_NAMEtextthe attribute naming the person, where not the name identifier
MIGKIT_WEB_SCIM_TOKENsecretthe bearer token the provider provisions people and groups with; set, only people it provisioned sign in
MIGKIT_WEB_SESSION_HOURSnumberthe longest a sign-in lasts
MIGKIT_WEB_STATEpathwhere the web view keeps its sessions, the people provisioned and its signing key
MIGKIT_WEB_TLS_CERTpaththe web view's certificate (PEM, its chain after it)
MIGKIT_WEB_TLS_KEYpaththe certificate's private key
MIGKIT_WEB_TOKEN_DAYSnumberthe longest an API token lasts
MIGKIT_WEB_URLtextthe address people open the web view at, https:// behind a proxy or with a certificate