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

refactors readme and EKS quickstart for bottlerocket.dev #3285

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

refactors readme and EKS quickstart for bottlerocket.dev #3285

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7503f9b
refactors readme and EKS quickstart for bottlerocket.dev
stockholmux Jul 24, 2023
287887f
Merge branch 'develop' into quickstart-readme-update
stockholmux Aug 10, 2023
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
53 changes: 6 additions & 47 deletions QUICKSTART-EKS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,8 @@
# Using a Bottlerocket AMI with Amazon EKS

The first release of Bottlerocket focuses on Kubernetes, in particular serving as the host OS for Kubernetes pods.
An updated automated quickstart for Bottlerocket on EKS has moved to [bottlerocket.dev's Amazon EKS Quickstart documentation](https://bottlerocket.dev/en/os/latest/#/install/quickstart/aws/k8s/). This document still has valuable information on [optional configuration cluster configuration](#optional-cluster-configuration) as well as [manual setup instructions](#manual-setup).

One easy way to get started is to use Amazon EKS, a service that manages a Kubernetes control plane for you.
This document will focus on EKS to make it easy to follow a single path.
There's nothing that limits Bottlerocket to EKS or AWS, though.

Most of this is one-time setup, and yes, we plan to automate more of it!
Once you have a cluster, you can skip to the last step, [Launch!](#launch)
While this document is named `QUICKSTART-EKS.md`, this is filename is preserved to retain existing links.

## Dependencies

Expand All @@ -22,43 +17,18 @@ Finally, you'll need [aws-cli](https://aws.amazon.com/cli/) set up to interact w

## Automated setup

If you have a recent `eksctl`, as mentioned above, most of Bottlerocket setup for EKS is automated.

### Cluster setup

#### Cluster setup configuration file

eksctl can use a configuration file to simplify setup.
We have sample configuration files in the repo:
* [`sample-eksctl.yaml`](sample-eksctl.yaml) - recommended for most setups.
* [`sample-eksctl-ssh.yaml`](sample-eksctl-ssh.yaml) - for test clusters where you know you'll want SSH access. Make sure to change the `publicKeyName` setting to the name of the SSH key pair you have registered with EC2.

Pick the file most appropriate for you and make a copy, for example `my-eksctl.yaml`.
In this file you can change your desired numbered of nodes and even set Bottlerocket settings in advance if you like. The 'settings' section under 'bottlerocket' can include any [Bottlerocket settings](https://github.com/bottlerocket-os/bottlerocket#description-of-settings).

Note that the configuration file includes the AWS region, so change it from `us-west-2` if you operate in another region.

To learn more about eksctl configuration files, you can look at the [full schema](https://eksctl.io/usage/schema/) or [official examples](https://github.com/weaveworks/eksctl/tree/master/examples).

#### Cluster creation
For an automated Bottlerocket on EKS quick start, visit [bottlerocket.dev's Amazon EKS Quickstart documentation](https://bottlerocket.dev/en/os/latest/#/install/quickstart/aws/k8s/).

You can set up a new cluster like this, pointing to the file you created in the last step:

```shell
eksctl create cluster --config-file ./my-eksctl.yaml
```

This will take a few minutes to create the EKS cluster and spin up your Bottlerocket worker nodes.
## Optional cluster configuration

#### Optional cluster configuration

##### CSI plugin
### CSI plugin

If you want to create a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) on a Bottlerocket host, you will need to use the [EBS CSI Plugin](https://github.com/kubernetes-sigs/aws-ebs-csi-driver).
This is because the default EBS driver relies on file system tools that are not included with Bottlerocket.
A walk-through of creating a storage class using the driver is available [here](https://docs.aws.amazon.com/eks/latest/userguide/ebs-csi.html).

##### conntrack configuration
### conntrack configuration

By default `kube-proxy` will set the `nf_conntrack_max` kernel parameter to a default value that may differ from what Bottlerocket originally sets at boot.
If you prefer to keep Bottlerocket's [default setting](packages/release/release-sysctl.conf), edit the kube-proxy configuration details with:
Expand All @@ -80,17 +50,6 @@ Add `--conntrack-max-per-core` and `--conntrack-min` to the kube-proxy arguments

```

### Done!

Bottlerocket instances are launched in an autoscaling group, up to the number specified in your eksctl configuration file.
(You can change this number after creation by [configuring the ASG](https://console.aws.amazon.com/ec2/autoscaling/home#AutoScalingGroups:view=details), the same way you might change other ASGs.)

The Bottlerocket instances will automatically register into the EKS cluster created by eksctl.
You can now use normal Kubernetes tools like `kubectl` to manage your cluster and the Bottlerocket nodes.

For example, to run a simple busybox pod:
`kubectl run -i -t busybox --image=busybox --restart=Never`

## Manual setup

If you'd like even more control over your setup, something that eksctl can't (yet) provide, or you just want to see what's involved, you can follow these steps.
Expand Down
9 changes: 5 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Bottlerocket is a free and open-source Linux-based operating system meant for ho

To learn more about Bottlerocket, visit the [official Bottlerocket website and documentation](https://bottlerocket.dev/).
Otherwise, if you’re ready to jump right in, read one of our setup guides for running Bottlerocket in [Amazon EKS](QUICKSTART-EKS.md), [Amazon ECS](QUICKSTART-ECS.md), or [VMware](QUICKSTART-VMWARE.md).

If you're interested in running Bottlerocket on bare metal servers, please refer to the [provisioning guide](PROVISIONING-METAL.md) to get started.

Bottlerocket focuses on security and maintainability, providing a reliable, consistent, and safe platform for container-based workloads.
Expand Down Expand Up @@ -108,7 +109,7 @@ Our supported architectures include `x86_64` and `aarch64` (written as `arm64` i
:walking: :running:

Bottlerocket is best used with a container orchestrator.
To get started with Kubernetes in Amazon EKS, please see [QUICKSTART-EKS](QUICKSTART-EKS.md).
To get started with Kubernetes in Amazon EKS, please see [the current Amazon EKS Quickstart guide on bottlerocket.dev](https://bottlerocket.dev/en/os/latest/#/install/quickstart/aws/k8s/).
To get started with Kubernetes in VMware, please see [QUICKSTART-VMWARE](QUICKSTART-VMWARE.md).
To get started with Amazon ECS, please see [QUICKSTART-ECS](QUICKSTART-ECS.md).
These guides describe:
Expand Down Expand Up @@ -150,7 +151,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).)

In AWS, you need to give your instance the SSM role for this to work; see the [setup guide](QUICKSTART-EKS.md#enabling-ssm).
In AWS, you need to give your instance the SSM role for this to work; see the [EKS setup guide](QUICKSTART-EKS.md#enabling-ssm).
Outside of AWS, you can use [AWS Systems Manager for hybrid environments](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-managedinstances.html).
There's more detail about hybrid environments in the [control container documentation](https://github.com/bottlerocket-os/bottlerocket-control-container/#connecting-to-aws-systems-manager-ssm).

Expand Down Expand Up @@ -364,7 +365,7 @@ You should [specify them in user data](#using-user-data).

For Kubernetes variants in AWS, you must also specify:

* `settings.kubernetes.cluster-name`: The cluster name you chose during setup; the [setup guide](QUICKSTART-EKS.md) uses "bottlerocket".
* `settings.kubernetes.cluster-name`: The cluster name you chose during setup; the [EKS setup guide](QUICKSTART-EKS.md) uses "bottlerocket".

For Kubernetes variants in VMware, you must specify:

Expand Down Expand Up @@ -1433,7 +1434,7 @@ Currently, the following NVIDIA driver versions are supported in Bottlerocket:
The official AMIs for these variants can be used with EC2 GPU-equipped instance types such as: `p2`, `p3`, `p4`, `g3`, `g4dn`, `g5` and `g5g`.
Note that older instance types, such as `p2`, are not supported by NVIDIA driver `515.X` and above.
You need to make sure you select the appropriate AMI depending on the instance type you are planning to use.
Please see [QUICKSTART-EKS](QUICKSTART-EKS.md#aws-k8s--nvidia-variants) for further details about Kubernetes variants, and [QUICKSTART-ECS](QUICKSTART-ECS.md#aws-ecs--nvidia-variants) for ECS variants.
Please see [the EKS setup guide](QUICKSTART-EKS.md#aws-k8s--nvidia-variants) for further details about Kubernetes variants, and [QUICKSTART-ECS](QUICKSTART-ECS.md#aws-ecs--nvidia-variants) for ECS variants.

## Details

Expand Down