Merge pull request #780 from bottlerocket-os/split-building

Split INSTALL into BUILDING and QUICKSTART

BUILDING.md

@@ -0,0 +1,86 @@
+# Building Bottlerocket
+
+If you'd like to build your own image instead of relying on an Amazon-provided image, follow these steps.
+You can skip to the [setup guide](QUICKSTART.md) to use an existing image in Amazon EC2.
+(We're still working on other use cases!)
+
+## Build an image
+
+### Dependencies
+
+#### Rust
+
+The build system is based on the Rust language.
+We recommend you install the latest stable Rust using [rustup](https://rustup.rs/), either from the official site or your development host's package manager.
+
+To organize build tasks, we use [cargo-make](https://sagiegurari.github.io/cargo-make/).
+We also use [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) during the build process.
+To get these, run:
+
+```
+cargo install cargo-make
+cargo install cargo-deny --version 0.6.2
+```
+
+#### Docker
+
+Bottlerocket uses [Docker](https://docs.docker.com/install/#supported-platforms) to orchestrate package and image builds.
+
+We recommend Docker 19.03 or later.
+Builds rely on Docker's integrated BuildKit support, which has received many fixes and improvements in newer versions.
+
+You'll need to have Docker installed and running, with your user account added to the `docker` group.
+Docker's [post-installation steps for Linux](https://docs.docker.com/install/linux/linux-postinstall/) will walk you through that.
+
+### Build process
+
+To build an image, run:
+
+```
+cargo make
+```
+
+All packages will be built in turn, and then compiled into an `img` file in the `build/` directory.
+
+### Register an AMI
+
+To use the image in Amazon EC2, we need to register the image as an AMI.
+The `bin/amiize.sh` script does this for you.
+
+The script has some assumptions about your setup, in particular that you:
+  * have [aws-cli v1](https://aws.amazon.com/cli/) set up, and that its default profile can create and control EC2 resources
+  * have an SSH key that's registered with EC2 and is available to `ssh` (for example, loaded into `ssh-agent`)
+  * have a few other common tools installed, like `jq`, `du`, and `rsync`
+
+First, decompress the images.
+(Note: these filenames assume an `x86_64` architecture and `aws-k8s` [variant](README.md).)
+
+```
+lz4 -d build/latest/bottlerocket-aws-k8s-x86_64.img.lz4 && \
+lz4 -d build/latest/bottlerocket-aws-k8s-x86_64-data.img.lz4
+```
+
+Next, register an AMI:
+
+```
+bin/amiize.sh --name YOUR-AMI-NAME-HERE \
+              --ssh-keypair YOUR-EC2-SSH-KEYPAIR-NAME-HERE \
+              --root-image build/latest/bottlerocket-aws-k8s-x86_64.img \
+              --data-image build/latest/bottlerocket-aws-k8s-x86_64-data.img \
+              --region us-west-2 \
+              --instance-type m3.xlarge \
+              --arch x86_64 \
+              --worker-ami ami-08d489468314a58df \
+              --user-data 'I2Nsb3VkLWNvbmZpZwpyZXBvX3VwZ3JhZGU6IG5vbmUK'
+```
+
+Your new AMI ID will be printed at the end.
+
+The amiize script starts an EC2 instance, which it uses to write the image to a new EBS volume.
+It then registers this EBS volume as an AMI and terminates the instance.
+In the example command above, the `--worker-ami` is an Amazon Linux AMI, and the `--user-data` disables updates at boot to speed up registration.
+Make sure you use an up-to-date worker AMI.
+
+## Use your image
+
+See the [setup guide](QUICKSTART.md) for information on running Bottlerocket images.

INSTALL.md → QUICKSTART.md

@@ -1,86 +1,3 @@
-# Building Bottlerocket
-
-If you'd like to build your own image instead of relying on an Amazon-provided image, follow these steps.
-You can skip to [Using a Bottlerocket AMI](#using-a-bottlerocket-ami) to use an existing image in Amazon EC2.
-(We're still working on other use cases!)
-
-## Build an image
-
-### Dependencies
-
-#### Rust
-
-The build system is based on the Rust language.
-We recommend you install the latest stable Rust using [rustup](https://rustup.rs/), either from the official site or your development host's package manager.
-
-To organize build tasks, we use [cargo-make](https://sagiegurari.github.io/cargo-make/).
-We also use [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) during the build process.
-To get these, run:
-
-```
-cargo install cargo-make
-cargo install cargo-deny --version 0.6.2
-```
-
-#### Docker
-
-Bottlerocket uses [Docker](https://docs.docker.com/install/#supported-platforms) to orchestrate package and image builds.
-
-We recommend Docker 19.03 or later.
-Builds rely on Docker's integrated BuildKit support, which has received many fixes and improvements in newer versions.
-
-You'll need to have Docker installed and running, with your user account added to the `docker` group.
-Docker's [post-installation steps for Linux](https://docs.docker.com/install/linux/linux-postinstall/) will walk you through that.
-
-### Build process
-
-To build an image, run:
-
-```
-cargo make
-```
-
-All packages will be built in turn, and then compiled into an `img` file in the `build/` directory.
-
-### Register an AMI
-
-To use the image in Amazon EC2, we need to register the image as an AMI.
-The `bin/amiize.sh` script does this for you.
-
-The script has some assumptions about your setup, in particular that you:
-  * have [aws-cli v1](https://aws.amazon.com/cli/) set up, and that its default profile can create and control EC2 resources
-  * have an SSH key that's registered with EC2 and is available to `ssh` (for example, loaded into `ssh-agent`)
-  * have a few other common tools installed, like `jq`, `du`, and `rsync`
-
-First, decompress the images.
-(Note: these filenames assume an `x86_64` architecture and `aws-k8s` [variant](README.md).)
-
-```
-lz4 -d build/latest/bottlerocket-aws-k8s-x86_64.img.lz4 && \
-lz4 -d build/latest/bottlerocket-aws-k8s-x86_64-data.img.lz4
-```
-
-Next, register an AMI:
-
-```
-bin/amiize.sh --name YOUR-AMI-NAME-HERE \
-              --ssh-keypair YOUR-EC2-SSH-KEYPAIR-NAME-HERE \
-              --root-image build/latest/bottlerocket-aws-k8s-x86_64.img \
-              --data-image build/latest/bottlerocket-aws-k8s-x86_64-data.img \
-              --region us-west-2 \
-              --instance-type m3.xlarge \
-              --arch x86_64 \
-              --worker-ami ami-08d489468314a58df \
-              --user-data 'I2Nsb3VkLWNvbmZpZwpyZXBvX3VwZ3JhZGU6IG5vbmUK'
-```
-
-Your new AMI ID will be printed at the end.
-
-The amiize script starts an EC2 instance, which it uses to write the image to a new EBS volume.
-It then registers this EBS volume as an AMI and terminates the instance.
-In the example command above, the `--worker-ami` is an Amazon Linux AMI, and the `--user-data` disables updates at boot to speed up registration.
-Make sure you use an up-to-date worker AMI.
-
 # Using a Bottlerocket AMI
 
 The first release of Bottlerocket focuses on Kubernetes, in particular serving as the host OS for Kubernetes pods.

README.md

@@ -42,10 +42,13 @@ Our first supported variant, `aws-k8s`, supports EKS as described above.
 
 :walking: :running:
 
-To get started, please see [INSTALL](INSTALL.md).
+To build your own Bottlerocket images, please see [BUILDING](BUILDING.md).
 It describes:
 * how to build an image
 * how to register an EC2 AMI from an image
+
+To get started using Bottlerocket, please see [QUICKSTART](QUICKSTART.md).
+It describes:
 * how to set up a Kubernetes cluster, so your Bottlerocket instance can run pods
 * how to launch a Bottlerocket instance in EC2
 
@@ -65,7 +68,7 @@ Bottlerocket has a ["control" container](https://github.com/bottlerocket-os/bott
 This container runs the [AWS SSM agent](https://github.com/aws/amazon-ssm-agent) that lets you run commands, or start shell sessions, on Bottlerocket instances in EC2.
 (You can easily replace this control container with your own just by changing the URI; see [Settings](#settings).
 
-You need to give your instance the SSM role for this to work; see the [setup guide](INSTALL.md#enabling-ssm).
+You need to give your instance the SSM role for this to work; see the [setup guide](QUICKSTART.md#enabling-ssm).
 
 Once the instance is started, you can start a session:
 
@@ -231,8 +234,8 @@ In this format, "settings.kubernetes.cluster-name" refers to the same key as in
 
 The following settings must be specified in order to join a Kubernetes cluster.
 You should [specify them in user data](#using-user-data).
-See the [setup guide](INSTALL.md) for *much* more detail on setting up Bottlerocket and Kubernetes.
-* `settings.kubernetes.cluster-name`: The cluster name you chose during setup; the [setup guide](INSTALL.md) uses "bottlerocket".
+See the [setup guide](QUICKSTART.md) for *much* more detail on setting up Bottlerocket and Kubernetes.
+* `settings.kubernetes.cluster-name`: The cluster name you chose during setup; the [setup guide](QUICKSTART.md) uses "bottlerocket".
 * `settings.kubernetes.cluster-certificate`: This is the base64-encoded certificate authority of the cluster.
 * `settings.kubernetes.api-server`: This is the cluster's Kubernetes API endpoint.
 

START.md

@@ -4,6 +4,7 @@ Welcome to Bottlerocket OS! Bottlerocket is a free and open-source Linux-based o
 
 Here's some important documentation you may want to read:
 - [README.md](README.md) — Read this first!
-- [INSTALL.md](INSTALL.md#using-a-bottlerocket-ami) — Set up a Bottlerocket cluster
+- [BUILDING.md](BUILDING.md) — Build Bottlerocket images
+- [QUICKSTART.md](QUICKSTART.md) — Set up a Bottlerocket cluster
 - [dogswatch README.md](extras/dogswatch/README.md) — Set up and use the Kubernetes operator for Bottlerocket updates
 - [CHANGELOG.md](CHANGELOG.md) — Changes between published versions

tools/gen-docs.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-DOCS=(START.md README.md INSTALL.md CHANGELOG.md extras/dogswatch/README.md)
+DOCS=(START.md README.md BUILDING.md QUICKSTART.md CHANGELOG.md extras/dogswatch/README.md)
 EXTRAS=(extras/dogswatch/{dogswatch,dev/deployment}.yaml)
 
 if ! hash grip; then