Merge pull request #1802 from tjkirch/api-exec

Add 'apiclient exec' for running commands in host containers

README.md

@@ -132,6 +132,11 @@ 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](#api) to configure and manage your Bottlerocket host.
 To do even more, read the next section about the [admin container](#admin-container).
+If you've enabled the admin container, you can access it from the control container like this:
+
+```
+apiclient exec admin bash
+```
 
 ### Admin container
 
@@ -159,6 +164,12 @@ If you're using a custom control container, or want to make the API calls direct
 apiclient set host-containers.admin.enabled=true
 ```
 
+Once you've enabled the admin container, you can either access it through SSH or from the control container like this:
+
+```
+apiclient exec admin bash
+```
+
 Once you're in the admin container, you can run `sheltie` to get a full root shell in the Bottlerocket host.
 Be careful; while you can inspect and change even more as root, Bottlerocket's filesystem and dm-verity setup will prevent most changes from persisting over a restart - see [Security](#security).
 
@@ -556,6 +567,12 @@ superpowered = false
 If the `enabled` flag is `true`, it will be started automatically.
 
 All host containers will have the `apiclient` binary available at `/usr/local/bin/apiclient` so they're able to [interact with the API](#using-the-api-client).
+You can also use `apiclient` to run programs in other host containers.
+For example, to access the admin container:
+
+```
+apiclient exec admin bash
+```
 
 In addition, all host containers come with persistent storage that survives reboots and container start/stop cycles.
 It's available at `/.bottlerocket/host-containers/$HOST_CONTAINER_NAME` and (since Bottlerocket v1.0.8) `/.bottlerocket/host-containers/current`.
@@ -634,7 +651,7 @@ AWS-specific settings are automatically set based on calls to the Instance MetaD
 ### Logs
 
 You can use `logdog` through the [admin container](#admin-container) to obtain an archive of log files from your Bottlerocket host.
-SSH to the Bottlerocket host, then run:
+SSH to the Bottlerocket host or `apiclient exec admin bash` to access the admin container, then run:
 
 ```bash
 sudo sheltie
@@ -651,6 +668,8 @@ ssh -i YOUR_KEY_FILE \
     "cat /.bottlerocket/rootfs/var/log/support/bottlerocket-logs.tar.gz" > bottlerocket-logs.tar.gz
 ```
 
+(If your instance isn't accessible through SSH, you can use [SSH over SSM](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started-enable-ssh-connections.html).)
+
 For a list of what is collected, see the logdog [command list](sources/logdog/src/log_request.rs).
 
 ### Kdump Support
@@ -732,6 +751,8 @@ This way, you can configure your Bottlerocket instance without having to make AP
 
 See [Settings](#settings) above for examples and to understand what you can configure.
 
+You can also access host containers through the API using [apiclient exec](sources/api/apiclient/README.md#exec-mode).
+
 The server and client are the user-facing components of the API system, but there are a number of other components that work together to make sure your settings are applied, and that they survive upgrades of Bottlerocket.
 
 For more details, see the [API system documentation](sources/api/).

sources/api/README.md

@@ -169,3 +169,32 @@ Now you can inspect settings in the API or do any other testing you like.
 
 You won't have dynamic settings generated by [sundog](#sundog) during a normal Bottlerocket launch, but you're probably not locally running the software that needs those, like Kubernetes.
 If you are, you can set them manually; see the top-level README for descriptions of those settings.
+
+#### Testing apiclient exec
+
+When you use `apiclient exec`, the server needs to know the containerd socket it can use to run the requested command, and it needs root access to talk to containerd.
+Here's how you can test the feature locally.
+
+Follow the [setup steps above](#Setup) if you haven't already, then stop the apiserver, because we'll need to run it a different way.
+
+First, run a task in containerd locally.  Here's an example:
+```
+sudo ctr i pull public.ecr.aws/amazonlinux/amazonlinux:latest
+sudo ctr run --rm -t public.ecr.aws/amazonlinux/amazonlinux:latest al bash
+```
+
+If you use a containerd socket other than the default `/run/containerd/containerd.sock` then pass it to ctr with `-a PATH` on each of those commands.
+
+Next, run apiserver as root so it can talk to containerd.
+From the `sources` directory:
+```
+sudo target/debug/apiserver --datastore-path /tmp/data-store/current --socket-path /tmp/bottlerocket-api.sock
+```
+
+If you use a containerd socket other than the default `/run/containerd/containerd.sock` then pass it to apiserver with `--exec-socket-path PATH` on that command.
+
+Finally, use apiclient to start another program in your container task.
+From the `sources/api/apiclient` directory:
+```
+cargo run -- --socket-path /tmp/bottlerocket-api.sock exec al bash
+```

sources/api/api-exec.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2021-11-01T16:42:43.754Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/15.4.0 Chrome/91.0.4472.164 Electron/13.5.0 Safari/537.36" etag="7qaOFmb267Qq1O5nCDpU" version="15.4.0" type="device"><diagram id="WwR_IrcpEeUXiprJ6851" name="Page-1">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</diagram></mxfile>