Merge pull request #962 from etungsten/updates-documentation

Updates documentation update

README.md

@@ -96,7 +96,7 @@ Then you'd be able to start a session using only your instance ID, like this:
 aws ssm start-session --target INSTANCE_ID
 ```
 
-With the [default control container](https://github.com/bottlerocket-os/bottlerocket-control-container), you can make API calls to change settings in your Bottlerocket host.
+With the [default control container](https://github.com/bottlerocket-os/bottlerocket-control-container), you can make [API calls](#api) to configure and manage your Bottlerocket host.
 To do even more, read the next section about the [admin container](#admin-container).
 
 ### Admin container
@@ -133,7 +133,88 @@ Be careful; while you can inspect and change even more as root, Bottlerocket's f
 Rather than a package manager that updates individual pieces of software, Bottlerocket downloads a full filesystem image and reboots into it.
 It can automatically roll back if boot failures occur, and workload failures can trigger manual rollbacks.
 
-Currently, you can update using a CLI tool, updog.
+The update process uses images secured by [TUF](https://theupdateframework.github.io/).
+For more details, see the [update system documentation](sources/updater/).
+
+### Update methods
+
+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 the 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
+```
+
+#### Updog
+
+You can also update using a CLI tool, `updog`, if you [connect through a host container](#exploration).
+
 Here's how you can see whether there's an update:
 
 ```
@@ -149,6 +230,12 @@ reboot
 
 (If you know what you're doing and want to update *now*, you can run `updog update --reboot --now`)
 
+#### Bottlerocket Update Operator
+
+If you are running the Kubernetes variant of Bottlerocket, you can use the [Bottlerocket update operator](https://github.com/bottlerocket-os/bottlerocket-update-operator) to automate Bottlerocket updates.
+
+### Update rollback
+
 The system will automatically roll back if it's unable to boot.
 If the update is not functional for a given container workload, you can do a manual rollback:
 
@@ -157,11 +244,6 @@ signpost rollback-to-inactive
 reboot
 ```
 
-We're working on more automated update methods.
-
-The update process uses images secured by [TUF](https://theupdateframework.github.io/).
-For more details, see the [update system documentation](sources/updater/).
-
 ## Settings
 
 Here we'll describe the settings you can configure on your Bottlerocket instance, and how to do it.

sources/api/update_api.drawio

@@ -0,0 +1 @@
+<mxfile host="drawio.corp.amazon.com" modified="2020-07-01T16:51:45.936Z" agent="Mozilla/5.0 (X11; Linux x86_64; rv:77.0) Gecko/20100101 Firefox/77.0" etag="0gBlpDYsLrGuW78c89-E" version="12.4.8" type="device"><diagram id="giZAHtWMypYogrpCSbqG" name="Page-1">7Zldb5swFIZ/TS4j8RFCcpmmaSdtUytlU7eryoET8OpgZEyT7NfPLuabEFLlU9pV4LWx8XNe8OGkZ05Xm0eGQv87dYH0DM3d9Mz7nmHohjUSP1LZKsXWxoniMewqLRfm+C8oUVNqjF2ISh05pYTjsCw6NAjA4SUNMUbX5W5LSsqzhsiDmjB3EKmrL9jlfqKOLC3XvwD2/HRmXVMtK5R2VkLkI5euC5I565lTRilPjlabKRBJL+WSXPewozW7MQYB73LB+Pf2z4YtguDb6z3fvNjWr/hn30xGeUckVgsWA8Shi7iAbjxEHPE4UvfPtykURuPABTmu3jPv1j7mMA+RI1vXwgdC8/mKqOYlDbiKq26JczUjMA6bnUvRM0DCWkBXwNlWdFEXmCn+1FVDKzlf5yHS0z5+ITyphpQrvGzoHJw4UOwO4Dho4ogcjmkgOTJYMoj8fka2AlR4I5SHIaMORNF+qAvkvHkfYXiKOcEBnBC2Voad+rnA2jgr62E765CBXJxifVOorQ6+Pi9ru521PHoXlG8RdtXXpn5pY4/2vUQWcrO4JcZX5+dxA+IKTwjciUwcxJlDUBRhp8t+Bm4tj6hAEpPQmDmwfxfhiHnA970B69ALVNugMiBIPLbl220irWZ4plgsZFdMB0YlVskq1UXFfKQyjl59/uzKQAmG2kAfcc9W/XkrpI/7lXph2NEL9jV5wTyWF0Zn9oJ+1V6wO3ph9N8LR/CCcdVeGHX0wuCavHCze0SHfEGmUuEh6ZMqVaBFOkJWS+iaVtlGGUvGu/j9qzeENxOPnljpTV8K5yDVErdW95+bT1NyX+GTl1W0E5VVWkK302z9hu+i8XnZ1atUj7MfLfhOVZU6CF/6yqrTsxvoVXfL48Grl6aen+Z1epf9jPwMWfvSZK0a2a8g7m1SYytWzsvwIs7oG0wpoUwoAZX07paYkIqECPYCmWUIUiD0O8kRO4hMVMMKu66cpjFa5RfK6QNTiMSgIRLVLKBDJGTZI6uQJ7t6/keDOfsH</diagram></mxfile>

sources/updater/README.md

@@ -4,7 +4,7 @@ This document describes the Bottlerocket update system and its components, namel
 - 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
-- dogswatch: an optional component that coordinates node updates with the rest of the cluster
+- Bottlerocket update operator (brupop): an optional component that coordinates node updates with the rest of the cluster
 
 ![Update overview](update-system.png)
 ## TUF and tough

sources/updater/update-system.drawio

@@ -1 +1 @@
-<mxfile modified="2019-10-16T17:26:00.146Z" host="drawio.corp.amazon.com" agent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:69.0) Gecko/20100101 Firefox/69.0" etag="Rv5cDU7fOmM64uIt0t11" pages="1" version="10.9.7" type="device"><diagram id="3ayFpOOYjWGc_ZlwSSnA" name="Page-1">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</diagram></mxfile>
+<mxfile modified="2020-06-30T19:27:17.147Z" host="drawio.corp.amazon.com" agent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:77.0) Gecko/20100101 Firefox/77.0" etag="JZPBOeuuHfH1MHTPThNB" version="12.4.8" type="device"><diagram id="3ayFpOOYjWGc_ZlwSSnA" name="Page-1">7V3bdps6EP2aPMYLiasfc2uT9qTNaZqVpC9dspFtnWKgIMdxv/6IADZIsg22wKRJX2qEkPGePaOt0UCO9LPp88cIhZPrwMXeEdTc5yP9/AhCoNmQ/Ze0LNIWxwJpwzgibtZp1XBL/uD8yqx1RlwclzrSIPAoCcuNw8D38ZCW2lAUBfNyt1Hglb81RGMsNNwOkSe23hOXTrJWYPVXJy4xGU+yr3agnZ6Yorxz9kviCXKDeaFJvzjSz6IgoOmn6fMZ9hLwclzS6z6sObu8sQj7tMoFF+f04bt26//7/KcfnZ9+/nL37fLYyG7uCXmz7Bdnd0sXOQRRMPNdnIwCjvTT+YRQfBuiYXJ2zozO2iZ06mWnl78yORBvMbvrJxxR/Fxoym75Iw6mmEYL1iU7a9rZHWb8gVp2PF9Zw+xnbZOCIQw9a0QZA8bLsVcgsQ8ZTnLMfkXoeP7P3fDLFbm/HBtXX+8fH46BUQczbTtmCmByIAdTX4QJQAlMwGgKJl0xSi6KJ0sWKoDMNsuQWYYuQAYdKWT2/pBJvVHvILNAvwzTkkVFZslg0lUwSwoTNDsI044oWaAplEQuDaJZGITpZEmjwPNwpNAlVUd+g4PUskwRUlsCab8pRIHVPd5ZZoXAb0hQahAmu3sw9XPydAgmR4DpLnSD8X5YqfZCyyrzy9AkXigTFlZjuPXXBzYmxtkv7W5M49E0JWq2XTTzLyugeU3GEaIk8FnzLQ0iLADKYAmTj0MUue0LN8cog6gDEUSpbtMaAxEIIJ4MKXliyGk3KKIkRZNDkf1cyjkvm5V/4bPACyLW4gc+63k6Ip7HNSGPjP0EfwYim8P10wQ8whatJ9mJKXHd5Gukpim7Q8k6IyYMbrM7lCww6/OdE4/QEE0ljbqNWQpK5ibLS+zgkif2cZx8vPKRxHxpN/a1hZ5v0ahAA2bHrCpq3SnyyQjHtPdfLHG9WikNBZBxEQtYBw/7opRNMlHH4dpodWDITNmCql3IRL026DZkzsEhE6XahEWm7kJmSSJZu5Dpoh6jZMoCGZqG3YhlkEs1goPTTBflV+yjMJ4EHQn/PGTw4PFfF3UQRdEY07ibiOmHd0wxn53MmN2Ai19XypZELcMly9EWhLaWy13W+nuW7IGdZsJ3ebzS2Ol1iY4twZx3TE4cxy9bhyesA7DD5/WjDPKG73cfWOdvOAxiwla5i4LAH/AXsbb027mxIknH7q8OVMyb3ApApNuSgu3QTdSz15giF1HUUSOoXpVBLgRIEpytrsl0MQv8PZ1h3ohBnI7ZQ9TidQMrhJUCq5phTwNKPRwFw1+YbgnDlSJ2JzmngGb8NjbQJVO/bJvMVsC0H9b882/j49Pjj9mfy6dP17NjZtkKG//Yd0+S4pwERg/FMRmWbcHgiBYPCUg9Mz98LJ47f84QTI8W+dEzoQ95P/b5cTUEO1pdlBzk16R2z4t79MoJ6ziYRUO8weOypFSqqzf0yzc0sFsqRRItXix5kRg0b4uwh16yl8W7lVk5+4abgLw4aq4lucBl8Ttg6Q/PrlpxRRjI1rmB+IKAFBlhIMYMtCh0C5MO8fobtrm1gg1KhVDsQzriitFLTHcneYVKjW0kL+80CSzMubzi72ORvlIu7+o3u5M8J+92ljudYjlXXODw1WJVSc6pLtupxnFVNKxQCVOgYTaDCZNeTjuoIPTWoWvM0KGij7w0fyBefpPFSfgI6i7CzmgozNjsjDV08GD0cmtudv2e7HYqsjvPDryzWyW7gZjYU0ZvUCR3getr6L0DB3OHKGkRuE2MVPKI9vmtdYrfBqdRhCrWhgleV6Is6zzyKhq+VntLfwg29+dr5WAbEkhSwFRNA5VIXm9O2s9pTey4hsxpHTjQLYtztI2u9er0Dsd0sKuqb8ljAO/h/c0ewPc3sgR0ox4gKZ6SVJNM83qqn6AHfo6CYF2yWLiy1+vt0rd2Wrrt7QpuYQhlO4iy5JiK9LHckPDQoczeFsvk+jpPdMjVBBf/Rs4QD6WiZeCYhqnViX9FabHRN15doDysdK4dJ3llYbYw80MFKb7KrrHBL6yl09zgiLBfleRjNyQC7c3im3MXDJhgsGXu0rdsHVntKO/cj97dYxf3cMBG99jaX7fbkBG7JhOVzT59YG+bfmRexs8W9eebtQ702qYNXtMIz3V1zDGMNfe7doXJ9TesNuaZBtOb++V/KlC7Yo5m+wRgvRN9D6Lz92u2IpAqPCn49xP3PUJzTFPDrQqPV/793OrWnvmhubVvULTsNoLirvnizdzNV3o9TXNKq71M1K7fLGcHwrpx1/RMJ9eO+ZPYHfGS17Z2NDZK3q39Tc1R6lTSt6woWTpWdLX6e6BrOd4RRtrcawEsx+yZu5HSAVuHUicMpFSot1hSS4XtO2uvjQo2MFRRQTJUw1RQsjO7GxX2Sfp0lQoGVEYFcaiGqSCWfYO07PqCGXvgkXhC/HEiJqJZLL46Y/8yaQ+PkhFUPcy+ljt13pXGRWo7W60Xtx9lr5RTUZsvf6OcuI8MUyN9Y+MT/JSaaBa6iCYvJZg292hL981lS95AA/O2dswllqXpqbnOg7nvBchN7UWmaIybeNzlFRhJF1+m17JPwS7OgdrLv8oG6OiEaJm2MpksDtXwhAjEzWst9d4rn1CSRtg81L5B17UM59Cuu+XZ4bSK6QZHMYnpywu/KtZIJW+zSt73+7of32305T4Ol1xp890+l5/+nXwbO+Cnf/71Prpyb+5vfhzvWwK+yyNh9RMd4pSw1hZb03t6t4K/qqydUNPMV6Cqi/tSItXTA5W2TVqh1h5Egm+CSDr/JGvDRNq1+E2BsNxnW6EjLBCSK1ZfWXJFHKphKojZdyOVkidh6C3Kq/Y3KCVt2XuOFElJdrj62wmpPVd/gUK/+B8=</diagram></mxfile>