@varde-flyt/vfac 0.1.0-rc.1

package/README.md

@@ -0,0 +1,96 @@
+# vfac
+
+Deploy and manage Varde Flyt Products from a manifest — from a terminal, a
+pipeline or an agent.
+
+```sh
+npm install -g @varde-flyt/vfac
+```
+
+## Getting started
+
+You need three things from your organization's Varde Flyt portal, under
+**Identity → Context Gates**:
+
+```sh
+export VFAC_ENDPOINT=https://your-organization.cloud.vardeflyt.no
+export VFAC_CREDENTIAL_ID=cg_...
+export VFAC_CREDENTIAL_SECRET=...     # shown once, when the Gate Key is created
+```
+
+Then check what you have:
+
+```sh
+vfac doctor
+vfac guide
+vfac whoami
+```
+
+`doctor` checks the endpoint, the API, your credential and what that credential
+reaches, in that order, and reports the first thing that is actually wrong.
+
+`vfac guide` is the documentation. It is served by the platform you are pointed
+at rather than bundled here, so it always describes the deployment in front of
+you — versions, regions, service profiles and configuration are answered by that
+platform's catalogue and are never hardcoded in this tool.
+
+## Choose a Project
+
+The catalogue is read **under a Project**, because that is the scope a Context
+Gate is granted in. Nothing below works until one is selected:
+
+```sh
+vfac project list
+vfac context set --project <projectId>
+```
+
+## The workflow
+
+```sh
+vfac product list
+vfac product show <productId>
+vfac manifest init --product <productId> --name "My resource" > resource.yaml
+```
+
+```sh
+vfac validate -f resource.yaml
+vfac plan     -f resource.yaml
+vfac apply    -f resource.yaml --secret SETTING=env:VARIABLE
+vfac get operation <operationId>
+vfac get product-instance <productInstanceId>
+```
+
+Secrets are supplied per apply and never belong in the manifest — a manifest is a
+file you commit.
+
+## Running it again
+
+**Send no secret.** A pipeline re-applies the same manifest on every push:
+
+```sh
+vfac apply -f resource.yaml
+```
+
+With no secret to write, an apply that finds nothing changed answers `NO_CHANGE`.
+That is the ordinary outcome for a pipeline, not a failure. It is not a health
+check either: `vfac` exits non-zero when a resource matches your manifest and is
+not actually serving.
+
+Sending a secret is itself a change. The platform stores secrets write-only, so
+it has nothing to compare against and treats one it was handed as one to write —
+so this answers `UPDATE` and redeploys, even when the value is the value already
+stored:
+
+```sh
+vfac apply -f resource.yaml --secret SETTING=env:VARIABLE
+```
+
+Send secrets on the apply that creates the resource and on the run that rotates
+one, and on no other run. A pipeline that passes its secrets every run restarts
+your service every time somebody pushes a README.
+
+## Where the Gate Secret goes
+
+Into your secret store, and nowhere else. `vfac` never writes it to disk: it
+exchanges it for a short-lived session, and caches only that, in a `0700`
+directory as a `0600` file.