README: relocate update API instructions and example

Relocates update API instructions, diagrams and example from the main Bottlerocket README to the update system documentation.
bottlerocket-os · Sep 22, 2020 · b6f2222 · b6f2222
1 parent 0ee62e6
commit b6f2222
Show file tree

Hide file tree

Showing 2 changed files with 85 additions and 73 deletions.
diff --git a/README.md b/README.md
@@ -148,78 +148,11 @@ There are several ways of updating your Bottlerocket hosts:
 
 #### Update API
 
-The [Bottlerocket API](#api) allows you to update and reboot your host with simple API calls.  You can change [settings](#updates-settings) to control which updates are selected.
-
-In general, the process of using the update API looks like this.  You refresh the list of known updates, then apply one to the system.  Calls to `/updates/status` will tell you the current state and give more details on any errors.
-
-![Update API overview](sources/api/update_api.png)
-
-First, refresh the list of available updates:
-```
-apiclient -u /actions/refresh-updates -m POST
-```
-
-Now you can see the list of available updates, along with the chosen update, according to your `version-lock` [setting](#updates-settings):
-```
-apiclient -u /updates/status
-```
-
-This will return the current update status in JSON format. The status should look something like the following (pretty-printed):
-```
-{
-  "update_state": "Available",
-  "available_updates": [
-    "0.4.0",
-    "0.3.4",
-    ...
-  ],
-  "chosen_update": {
-    "arch": "x86_64",
-    "version": "0.4.0",
-    "variant": "aws-k8s-1.15"
-  },
-  "active_partition": {
-    "image": {
-      "arch": "x86_64",
-      "version": "0.3.2",
-      "variant": "aws-k8s-1.15"
-    },
-    "next_to_boot": true
-  },
-  "staging_partition": null,
-  "most_recent_command": {
-    "cmd_type": "refresh",
-    "cmd_status": "Success",
-    ...
-  }
-}
-```
-
-You can see that we're running `v0.3.2` in the active partition, and that `v0.4.0` is available.
-If you're happy with that selection, you can request that the update be downloaded and applied to disk.  (The update will remain inactive until you make the `activate-update` call below.)
-```
-apiclient -u /actions/prepare-update -m POST
-```
-
-After you request that the update be prepared, you can check the update status again until it reflects the new version in the staging partition.
-```
-apiclient -u /updates/status
-```
-
-If the staging partition shows the new version, you can proceed to "activate" the update.
-This means that as soon as the host is rebooted it will try to run the new version.  (If the new version can't boot, we automatically flip back to the old version.)
-```
-apiclient -u /actions/activate-update -m POST
-```
-
-You can reboot the host with:
-```
-apiclient -u /actions/reboot -m POST
-```
+The [Bottlerocket API](#api) includes methods for checking and starting system updates.  You can read more about the update APIs in our [update system documentation](sources/updater/README.md#update-api).
 
 #### Updog
 
-You can also update using a CLI tool, `updog`, if you [connect through a host container](#exploration).
+You can update Bottlerocket using a CLI tool, `updog`, if you [connect through the admin container](#admin-container).
 
 Here's how you can see whether there's an update:
 

diff --git a/sources/updater/README.md b/sources/updater/README.md
@@ -1,10 +1,11 @@
 # Bottlerocket update infrastructure
 This document describes the Bottlerocket update system and its components, namely;
 
-- tough: implementation of "The Update Framework" (TUF)
-- updog: update client that interfaces with a TUF repository to find and apply updates
-- signpost: helper tool to update partition priority flags
-- Bottlerocket update operator (brupop): an optional component that coordinates node updates with the rest of the cluster
+- [tough](#tuf-and-tough): implementation of "The Update Framework" (TUF)
+- [updog](#updog): update client that interfaces with a TUF repository to find and apply updates
+- [signpost](#signpost): helper tool to update partition priority flags
+- [Bottlerocket update operator (brupop)](https://github.com/bottlerocket-os/bottlerocket-update-operator): an optional component that coordinates node updates with the rest of the cluster
+- [Bottlerocket update API](#update-api): a set of API calls for checking and starting system updates
 
 ![Update overview](update-system.png)
 ## TUF and tough
@@ -53,3 +54,81 @@ For more information about update waves see [Waves](waves/).
 Once an update has been successfully written to the inactive partition, Updog calls the Signpost utility.
 This updates the priority bits in the GUID partition table of each partition and swaps the "active" and "inactive" partitions.
 For more information see [Signpost](signpost/)
+
+## Update API
+The [Bottlerocket API](../../README.md#api) allows you to update and reboot your host.  You can change [settings](../../README.md#updates-settings) to control which updates will be selected.
+
+[thar-be-updates](../api/thar-be-updates) is the component driving the update actions in the background.
+
+In general, the process of using the update API looks like this:
+![Update API overview](../api/update_api.png)
+
+You refresh the list of known updates, then apply one to the system.
+Calls to `/updates/status` will tell you the current state and give more details on any errors.
+
+### Walkthrough
+
+First, refresh the list of available updates:
+```
+apiclient -u /actions/refresh-updates -m POST
+```
+
+Now you can see the list of available updates, along with the chosen update, according to your `version-lock` [setting](../../README.md#updates-settings):
+```
+apiclient -u /updates/status
+```
+
+This will return the current update status in JSON format. The status should look something like the following (pretty-printed):
+```
+{
+  "update_state": "Available",
+  "available_updates": [
+    "0.4.0",
+    "0.3.4",
+    ...
+  ],
+  "chosen_update": {
+    "arch": "x86_64",
+    "version": "0.4.0",
+    "variant": "aws-k8s-1.15"
+  },
+  "active_partition": {
+    "image": {
+      "arch": "x86_64",
+      "version": "0.3.2",
+      "variant": "aws-k8s-1.15"
+    },
+    "next_to_boot": true
+  },
+  "staging_partition": null,
+  "most_recent_command": {
+    "cmd_type": "refresh",
+    "cmd_status": "Success",
+    ...
+  }
+}
+```
+
+You can see that we're running `v0.3.2` in the active partition, and that `v0.4.0` is available.
+If you're happy with that selection, you can request that the update be downloaded and applied to disk.
+(The update will remain inactive until you make the `activate-update` call below.)
+```
+apiclient -u /actions/prepare-update -m POST
+```
+
+After you request that the update be prepared, you can check the update status again until it reflects the new version in the staging partition.
+```
+apiclient -u /updates/status
+```
+
+If the staging partition shows the new version, you can proceed to "activate" the update.
+This means that as soon as the host is rebooted it will try to run the new version.
+(If the new version can't boot, we automatically flip back to the old version.)
+```
+apiclient -u /actions/activate-update -m POST
+```
+
+You can reboot the host with:
+```
+apiclient -u /actions/reboot -m POST
+```