From ccd00a06d5e259b62cc45594d08cdd6ecd73e690 Mon Sep 17 00:00:00 2001 From: Tom Kirchner Date: Wed, 5 Feb 2020 15:02:11 -0800 Subject: [PATCH] docs: update to describe transactions --- README.md | 17 +++++++++++++---- workspaces/api/README.md | 8 ++++---- workspaces/api/apiclient/README.md | 11 +++++++++-- workspaces/api/apiclient/README.tpl | 11 +++++++++-- workspaces/api/apiserver/README.md | 14 +++++++++----- workspaces/api/apiserver/src/lib.rs | 14 +++++++++----- 6 files changed, 53 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 6915a08a3cf..3f200a0ecf0 100644 --- a/README.md +++ b/README.md @@ -197,17 +197,26 @@ This can include any number of settings changes. apiclient -m PATCH -u /settings -d '{"timezone": "America/Thunder_Bay"}' ``` -This will *stage* the setting in a "pending" area. -You can see all the pending settings like this: +This will *stage* the setting in a "pending" area - a transaction. +You can see all your pending settings like this: ``` -apiclient -u /settings/pending +apiclient -u /tx ``` To *commit* the settings, and let the system apply them to any relevant configuration files or services, do this: ``` -apiclient -m POST -u /settings/commit_and_apply +apiclient -m POST -u /tx/commit_and_apply ``` +Behind the scenes, these commands are working with the "default" transaction. +This keeps the interface simple. +System services use their own transactions, so you don't have to worry about conflicts. +For example, there's a "thar-boot" transaction used to coordinate changes at startup. + +If you want to group sets of changes yourself, pick a transaction name and append a `tx` parameter to the URLs above. +For example, if you want the name "FOO", you can `PATCH` to `/settings?tx=FOO` and `POST` to `/tx/commit_and_apply?tx=FOO`. +(Transactions are created automatically when used, and are cleaned up on reboot.) + For more details on using the client, see the [apiclient documentation](workspaces/api/apiclient/). #### Using user data diff --git a/workspaces/api/README.md b/workspaces/api/README.md index dafdfece3fd..02922071423 100644 --- a/workspaces/api/README.md +++ b/workspaces/api/README.md @@ -53,10 +53,10 @@ storewolf ensures the default values (defined in [defaults.toml](../models/defau First, it has to create the data store directories and symlinks if they don’t exist. Then, it goes key-by-key through the defaults, and if a key isn’t already set, sets it with the default value. -The settings are written to the *pending* section of the data store, meaning they’re not available until committed later by [settings-committer](#settings-committer). +The settings are written to the *pending* section of the data store, in a "thar-boot" transaction, which is used for startup coordination. +This means they’re not available until committed later by [settings-committer](#settings-committer). -If there are any pending settings in the data store, they’re discarded. -We’re unable to guarantee users that any pending settings they haven’t committed will survive a reboot, because we have to be able to commit changes ourselves during the boot process (see later services), and we don’t yet have a way of separating transactions. +If there are any pending transactions in the data store when storewolf starts, they’re discarded. ### apiserver @@ -101,7 +101,7 @@ Pluto generates settings needed for Kubernetes configuration, for example cluste [Further docs](settings-committer/) -This binary sends a commit request to the API, which moves all the pending settings from the above services into the live part of the data store. +This binary sends a commit request to the API (by default for the "thar-boot" transaction) which moves all the pending settings from the above services into the live part of the data store. It's called as a prerequisite of other services, like [sundog](#sundog) and [settings-applier](#settings-applier), that rely on settings being committed. ### settings-applier diff --git a/workspaces/api/apiclient/README.md b/workspaces/api/apiclient/README.md index 757a84c7c19..36d1c3bc93d 100644 --- a/workspaces/api/apiclient/README.md +++ b/workspaces/api/apiclient/README.md @@ -25,16 +25,23 @@ Getting settings: ``` apiclient -m GET -u /settings -apiclient -m GET -u /settings/pending ``` Changing settings: ``` apiclient -X PATCH -u /settings -d '{"timezone": "OldLosAngeles"}' -apiclient -m POST -u /settings/commit_and_apply +apiclient -m POST -u /tx/commit_and_apply ``` +You can also check what you've changed but not commited by looking at the pending transaction: + +``` +apiclient -m GET -u /tx +``` + +(You can group changes into transactions by adding a parameter like `?tx=FOO` to the calls above.) + ## apiclient library The apiclient library provides simple, synchronous methods to query an HTTP API over a diff --git a/workspaces/api/apiclient/README.tpl b/workspaces/api/apiclient/README.tpl index 128a611e7b6..f666ad911f0 100644 --- a/workspaces/api/apiclient/README.tpl +++ b/workspaces/api/apiclient/README.tpl @@ -25,16 +25,23 @@ Getting settings: ``` apiclient -m GET -u /settings -apiclient -m GET -u /settings/pending ``` Changing settings: ``` apiclient -X PATCH -u /settings -d '{"timezone": "OldLosAngeles"}' -apiclient -m POST -u /settings/commit_and_apply +apiclient -m POST -u /tx/commit_and_apply ``` +You can also check what you've changed but not commited by looking at the pending transaction: + +``` +apiclient -m GET -u /tx +``` + +(You can group changes into transactions by adding a parameter like `?tx=FOO` to the calls above.) + ## apiclient library {{readme}} diff --git a/workspaces/api/apiserver/README.md b/workspaces/api/apiserver/README.md index 4d4f1fc3503..33e23c84396 100644 --- a/workspaces/api/apiserver/README.md +++ b/workspaces/api/apiserver/README.md @@ -21,12 +21,16 @@ The interface is documented in [OpenAPI format](https://swagger.io/docs/specific The Settings APIs are particularly important. You can GET settings from the `/settings` endpoint. You can also PATCH changes to the `/settings` endpoint. -Settings are stored as pending until a commit API is called. -Pending settings can be retrieved from `/settings/pending` to see what will change. +Settings are stored as a pending transaction until a commit API is called. +Pending settings can be retrieved from `/tx` to see what will change. -Upon making a `commit` API call, pending settings are made live. -Upon making an `apply` API call, an external settings applier tool is called to apply the changes to the system and restart services as necessary. -There's also a `commit_and_apply` API to do both, which is the most common case. +Upon making a `/tx/commit` POST call, the pending transaction is made live. +Upon making an `/tx/apply` POST call, an external settings applier tool is called to apply the changes to the system and restart services as necessary. +There's also `/tx/commit_and_apply` to do both, which is the most common case. + +If you don't specify a transaction, the "default" transaction is used, so you usually don't have to think about it. +If you want to group changes into transactions yourself, you can add a `tx` parameter to the APIs mentioned above. +For example, if you want the name "FOO", you can `PATCH` to `/settings?tx=FOO` and `POST` to `/tx/commit_and_apply?tx=FOO`. Requests are directed by `server::router`. `server::controller` maps requests into our data model. diff --git a/workspaces/api/apiserver/src/lib.rs b/workspaces/api/apiserver/src/lib.rs index f81668dfe08..079444d08f3 100644 --- a/workspaces/api/apiserver/src/lib.rs +++ b/workspaces/api/apiserver/src/lib.rs @@ -18,12 +18,16 @@ The interface is documented in [OpenAPI format](https://swagger.io/docs/specific The Settings APIs are particularly important. You can GET settings from the `/settings` endpoint. You can also PATCH changes to the `/settings` endpoint. -Settings are stored as pending until a commit API is called. -Pending settings can be retrieved from `/settings/pending` to see what will change. +Settings are stored as a pending transaction until a commit API is called. +Pending settings can be retrieved from `/tx` to see what will change. -Upon making a `commit` API call, pending settings are made live. -Upon making an `apply` API call, an external settings applier tool is called to apply the changes to the system and restart services as necessary. -There's also a `commit_and_apply` API to do both, which is the most common case. +Upon making a `/tx/commit` POST call, the pending transaction is made live. +Upon making an `/tx/apply` POST call, an external settings applier tool is called to apply the changes to the system and restart services as necessary. +There's also `/tx/commit_and_apply` to do both, which is the most common case. + +If you don't specify a transaction, the "default" transaction is used, so you usually don't have to think about it. +If you want to group changes into transactions yourself, you can add a `tx` parameter to the APIs mentioned above. +For example, if you want the name "FOO", you can `PATCH` to `/settings?tx=FOO` and `POST` to `/tx/commit_and_apply?tx=FOO`. Requests are directed by `server::router`. `server::controller` maps requests into our data model.