Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

README: relocate update API instructions and example #1124

Merged
merged 1 commit into from
Sep 24, 2020
Merged

README: relocate update API instructions and example #1124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 2 additions & 69 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
87 changes: 83 additions & 4 deletions sources/updater/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
```