flexway
FRENTalk to an expert

Proposing a change from the console

GuideOperationsSince version 1.2.0

Markdown

Operations guide: configure, deploy and observe the gateway. What the capability does, product side: product guide; calling it: developer guide.

Goal: change an upstream's delay, a tenant's budget or a policy's configuration from the console, without ever writing to the gateway: the change becomes a pull request in the GitOps repository, reviewed and merged under its rules; GitOps then reconciles it.

Configuration - once, by the operator:

Step What to do
1. Create the GitHub application Contents and Pull requests read and write, Checks, Commit statuses and Metadata read; neither Administration nor Workflows; no webhook. Install it on the one GitOps repository; do not add it to the actors allowed to bypass the rules
2. Set the key by reference The private key in the secret manager, synced into a Secret (ESO), mounted as a file: repo.existingSecret (key private-key by default) - never a chart value
3. Protect the target branch A ruleset requiring a pull request and at least one approval, readable by the application; classic protection (unreadable without Administration) is declared: repo.protection: declared, shown "not verified"
4. Fill in the repository repo.url, repo.branch, repo.path (the directory of flexway.yaml), repo.appId, repo.installationId 
repo:
  url: https://github.com/acme-platform/gateway-config
  branch: main
  path: deploy/flexway
  appId: "123456"
  installationId: "7890123"
  existingSecret: console-github-app

Outside Kubernetes (Docker, VM): FLEXWAY_CONSOLE_REPO_URL, _REPO_BRANCH, _REPO_PATH, _REPO_APP_ID, _REPO_INSTALLATION_ID, _REPO_APP_KEY=file:/run/secrets/github-app/private-key and FLEXWAY_CONSOLE_PROPOSALS_STORE=file:/var/lib/flexway-console/proposals on a volume, one replica. The roles: flexway-proposer and flexway-reviewer at the provider (with or without a tenant), or chosen in Users for a local account.

The path of a proposal:

  1. A proposer (or a reviewer, an admin) opens a policy's step, an upstream's detail or a tenant's usage and clicks "Propose this change": new value, title, reason.
  2. The console reads flexway.yaml in the repository, replaces the node keeping comments and order, shows the diff, has the gateway's own loader load it and simulates the described requests. Nothing is written to the repository.
  3. The author submits it for review: the diff is frozen (fingerprint).
  4. A reviewer opens the pull request (or rejects it, with a reason): a flexway/p-NNNN-... branch, one commit carrying exactly the reviewed diff, a generated body.
  5. Review and merge happen in the repository, under its rules; the console reads reviews, checks and the merge every 30 s.
  6. After the merge, the console computes the expected config_digest on the merge commit; the proposal is applied when every replica serves it (flexway_config_info).
Status Meaning
Draft Its author's; refused by the loader, it cannot be submitted
In review Diff frozen; a reviewer opens the pull request or rejects it
PR open In the repository; "modified in the repository" when the branch no longer carries the reviewed diff alone
Merged Waiting for the reload; "merged with a gap" when the merged content differs from the reviewed one
Applied Every replica serves the expected digest
Stale flexway.yaml changed on the target branch: Regenerate replays the edit on the new head
Rejected, withdrawn Finished; kept 400 days, with its journal

Check: flexway validate on the repository after the merge prints the same config_digest the console expects; each replica's /config publishes it.

docker run --rm -v "$PWD/deploy/flexway:/cfg" ghcr.io/flexwiz/flexway:<version> validate --config /cfg/flexway.yaml
# valid: 12 operation(s) served from 1 contract(s), 2 upstream(s)
# config_digest 9e41b7c0d2aa

Troubleshooting

Symptom Cause and fix
503 repo_unprotected, "branch not protected" banner No readable rule requires a pull request and an approval: add a ruleset, or declare the protection (repo.protection: declared)
502 repo_refused The key is revoked, the installation does not cover the repository, or a permission is missing: check the application, then wait for the key to be read again (no restart)
"Modified in the repository" Someone pushed to the flexway/* branch: review the pull request in the repository; the console keeps both fingerprints in the journal
"Merged with a gap" The merge carries other contents than the reviewed ones: the journal says so; the expected digest is the merge commit's
"Reload expected" past 15 min GitOps has not synchronised, or the gateway refused the reload (last_reload of /config)

Available since 1.2.0; automatic rules and the operations AI are planned for 1.10.0. Proven against a GitHub double; a run against a demonstration repository remains to be done before promising GitHub Enterprise Server compatibility and signed commits.

Next steps