Command line

The flexway binary is both the service and its tools: with no argument it serves; followed by a command it checks, converts or writes, offline, without starting a listener. The same commands ship in every published image, whose entry point is the binary:

docker run --rm -v "$PWD:/etc/flexway:ro" ghcr.io/flexwiz/flexway:<version> validate

Options take one or two dashes (-config or --config). -h prints a command's help and exits 0.

Contents

Command	Role	Exit codes	Since
flexway	Serve	-	0.1.0
flexway validate	Validate a configuration and its contracts	0, 1, 2	0.1.0
flexway import krakend	Take over a KrakenD configuration	0, 1, 2, 3	1.2.0
flexway api-key	Create an API key	0, 1	0.1.0
flexway schema	Write the configuration's published schemas	0, 1, 2	1.7.0
flexway fragment digest	Compute the digest that pins a policy fragment	0, 1, 2	1.7.0
flexway version	Say which version runs	0	1.1.0
flexway-console users	Manage the console's local accounts	0, 1, 2	1.0.0
flexway-console version	Say which console version runs	0	1.1.0

flexway

Serves the configuration the environment names. SIGTERM drains the requests in flight then stops, SIGHUP reads the configuration again at once.

Variable	Default	Role
FLEXWAY_CONFIG	- (required; /etc/flexway/flexway.yaml in the image)	The flexway.yaml to serve
FLEXWAY_ADDR	:8080	Traffic listener
FLEXWAY_ADMIN_ADDR	:9090	Admin listener (admin API)
FLEXWAY_TLS_ADDR	:8443	TLS listener, when server.tls is set

FLEXWAY_CONFIG=/etc/flexway/flexway.yaml flexway

flexway validate

Loads the configuration and every contract it names with the start's loader - same checks, same refusals - with no network and no cluster. A secret reference (${VAR}, file:/...) is checked for its form, not resolved.

flexway validate [--config flexway.yaml] [--contract openapi.yaml] [-v]

Option	Default	Role
--config	$FLEXWAY_CONFIG, else flexway.yaml	The configuration to validate; the paths it holds are read from its directory
--contract	-	Another OpenAPI contract, validated in place of contracts.openapi
-v	no	Lists every resolved operation (method, template, upstream) and the full digest

Code	Meaning
0	Accepted: valid: <n> operation(s) served from <n> contract(s), <n> upstream(s) then config_digest <digest>
1	Refused: the field at fault and the reason
2	Misused command line

docker run --rm -v "$PWD:/w:ro" ghcr.io/flexwiz/flexway:<version> validate --config /w/flexway.yaml --contract /w/next.yaml -v

The config_digest is the one /config publishes on a replica that serves this configuration. Guide: Serving your first API.

flexway import krakend

Converts a krakend.json once, offline: a flexway.yaml, the annotated contract, the same additions as a JSON Patch (contract.patch.json) and a coverage.md report. The result passes the start's loader before it is written.

flexway import krakend --config krakend.json --contract openapi.yaml --out <empty directory>

Option	Default	Role
--config	krakend.json	The KrakenD configuration (rendered, when it is flexible)
--contract	- (required)	The OpenAPI contract the endpoints are matched against
--out	- (required)	An empty or absent directory: the import never overwrites

Code	Meaning
0	Everything taken over
1	Refused, nothing written
2	Misused command line
3	Taken over, with elements without equivalent listed in coverage.md

Guide: Taking over an existing gateway.

flexway api-key

Creates an API key. The command asks for its id, its tenant, the operations it opens (comma-separated operationIds) and its end (90d, 12w or a YYYY-MM-DD date; 90d by default), then prints the key once and the entry to add to the key store - its SHA-256 digest, never the key. No option: the inputs are interactive.

docker run --rm -it ghcr.io/flexwiz/flexway:<version> api-key

Code	Meaning
0	Key created
1	Refused: malformed id (2 to 64 characters, lower-case, digits, ., _, -), no tenant or operation, a date in the past

Guide: API keys.

flexway schema

Writes the configuration's published schemas (JSON Schema 2020-12) from the binary's model, offline: flexway.schema.json, contract-extensions.schema.json and, since 1.7.0, policy-fragment.schema.json (policy fragments) and architecture.schema.json (the flexway.architecture.v1 model of the console's Architecture screen).

flexway schema [--out <directory>]

Option	Default	Role
--out	.	The directory the files are written to; each written path is printed

Code	Meaning
0	Written
1	Write failed
2	Misused command line

docker run --rm -v "$PWD:/out" -u "$(id -u)" ghcr.io/flexwiz/flexway:<version> schema --out /out

Guide: Validating in your editor.

flexway fragment digest

Reads a policy fragment file (kind: PolicyFragment) and prints the digest that pins it in policies.fragments.<import>.digest: sha256: followed by the sha256 of its bytes, what sha256sum prints. A file no gateway would load (unknown key, a host, an import of another fragment, a literal secret) is refused without a digest. Since 1.7.0.

flexway fragment digest <fragment.yaml>

Code	Meaning
0	The digest, alone on its line
1	File unreadable or refused: the reason
2	Misused command line

make fragment-digest FILE=security-baseline.yaml

Guide: Shared policy fragments.

flexway version

Prints flexway <version> (<commit>): the release tag, or dev for a build that is not a release. The same value is in build of /config and at the foot of the console.

docker run --rm ghcr.io/flexwiz/flexway:<version> version

flexway-console users

Manages the console's local accounts, from its container (FLEXWAY_CONSOLE_STORE must name the account store). An invitation link is valid 72 h and printed once.

Subcommand	Role
list	The local accounts: login, name, role, tenant, status, second factor, last sign-in
add [login]	A new account - asks for its name, its role (viewer or admin) and, for a viewer, its tenant; prints its invitation link
reset <login>	Invalidates the password and the sessions; prints a new invitation link
mfa-reset <login>	Turns the second factor off: the account enrols again at its next sign-in
unlock <login>	Ends every lockout of the account
disable <login>	Disables the account (never the last active admin)

Code	Meaning
0	Done
1	Refused (unknown account, last admin...)
2	Unknown or missing subcommand, store not configured

kubectl exec deploy/<release>-flexway-console -- flexway-console users reset admin

Guide: Console accounts.

flexway-console version

Prints flexway-console <version> (<commit>).