From 30dfb4d4f7e9b55eedc737d0bde51efb51a5bd6b Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 2 Sep 2024 10:06:10 +0000 Subject: [PATCH 1/3] Bump micromatch from 4.0.5 to 4.0.8 Bumps [micromatch](https://github.com/micromatch/micromatch) from 4.0.5 to 4.0.8. - [Release notes](https://github.com/micromatch/micromatch/releases) - [Changelog](https://github.com/micromatch/micromatch/blob/master/CHANGELOG.md) - [Commits](https://github.com/micromatch/micromatch/compare/4.0.5...4.0.8) --- updated-dependencies: - dependency-name: micromatch dependency-type: indirect ... Signed-off-by: dependabot[bot] <support@github.com> --- package-lock.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/package-lock.json b/package-lock.json index 40257dc5..ce7b5da1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -309,11 +309,11 @@ "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==" }, "micromatch": { - "version": "4.0.5", - "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.5.tgz", - "integrity": "sha512-DMy+ERcEW2q8Z2Po+WNXuw3c5YaUSFjAO5GsJqfEl7UjvtIuFKO6ZrKvcItdy98dwFI2N1tg3zNIdKaQT+aNdA==", + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz", + "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==", "requires": { - "braces": "^3.0.2", + "braces": "^3.0.3", "picomatch": "^2.3.1" } }, From af7705e2ec5c5361ddfcc0849298b0f1325c0975 Mon Sep 17 00:00:00 2001 From: Piyush Jena <piyushjena1996@gmail.com> Date: Wed, 18 Sep 2024 21:20:42 -0700 Subject: [PATCH 2/3] Docs for 1.22.0 --- content/en/os/1.21.x/_index.markdown | 2 +- content/en/os/1.22.x/_index.markdown | 4 + content/en/os/1.22.x/api/_index.markdown | 6 + .../en/os/1.22.x/api/endpoints/index.markdown | 11 + .../os/1.22.x/api/reporting/_index.markdown | 50 ++ .../api/reporting/cis-k8s/index.markdown | 33 + .../1.22.x/api/reporting/cis/index.markdown | 37 + .../1.22.x/api/settings-index/_index.markdown | 7 + .../en/os/1.22.x/api/settings/_index.markdown | 5 + .../api/settings/autoscaling/_index.markdown | 10 + .../1.22.x/api/settings/aws/_index.markdown | 11 + .../1.22.x/api/settings/boot/_index.markdown | 13 + .../bootstrap-containers/_index.markdown | 8 + .../settings/cloudformation/_index.markdown | 14 + .../container-registry/_index.markdown | 9 + .../container-runtime/_index.markdown | 8 + .../1.22.x/api/settings/dns/_index.markdown | 12 + .../1.22.x/api/settings/ecs/_index.markdown | 9 + .../settings/host-containers/_index.markdown | 11 + .../api/settings/kernel/_index.markdown | 9 + .../api/settings/kubernetes/_index.markdown | 12 + .../api/settings/metrics/_index.markdown | 9 + .../1.22.x/api/settings/motd/_index.markdown | 9 + .../api/settings/network/_index.markdown | 8 + .../1.22.x/api/settings/ntp/_index.markdown | 8 + .../api/settings/oci-defaults/_index.markdown | 13 + .../api/settings/oci-hooks/_index.markdown | 10 + .../1.22.x/api/settings/pki/_index.markdown | 15 + .../api/settings/updates/_index.markdown | 8 + content/en/os/1.22.x/concepts/_index.markdown | 6 + .../1.22.x/concepts/api-driven/index.markdown | 95 +++ .../bootstrap-containers/_index.markdown | 91 ++ .../concepts/chain-of-trust/index.markdown | 56 ++ .../1.22.x/concepts/components/index.markdown | 156 ++++ .../concepts/host-containers/_index.markdown | 89 ++ .../restricted-filesystem/index.markdown | 58 ++ .../concepts/shell-less-host/index.markdown | 41 + .../updating-bottlerocket/index.markdown | 43 + .../1.22.x/concepts/variants/index.markdown | 173 ++++ content/en/os/1.22.x/install/_index.markdown | 12 + .../1.22.x/install/quickstart/_index.markdown | 5 + .../install/quickstart/aws/_index.markdown | 5 + .../install/quickstart/aws/ecs/index.markdown | 175 ++++ .../aws/host-containers/index.markdown | 107 +++ .../install/quickstart/aws/k8s/index.markdown | 126 +++ content/en/os/1.22.x/login/_index.markdown | 6 + .../login/regaining-access/index.markdown | 246 ++++++ content/en/os/1.22.x/update/_index.markdown | 6 + .../1.22.x/update/guidelines/index.markdown | 64 ++ .../index.markdown | 75 ++ .../os/1.22.x/update/methods/_index.markdown | 5 + .../update/methods/in-place/index.markdown | 165 ++++ .../methods/node-replacement/index.markdown | 24 + .../version-information/_index.markdown | 6 + .../gpu-drivers/1.22.0/index.markdown | 7 + .../gpu-drivers/_index.markdown | 5 + .../packages-by-variant/index.markdown | 10 + .../packages/1.22.0/index.markdown | 488 +++++++++++ .../packages/_index.markdown | 5 + .../variants/index.markdown | 10 + data/homepagediagrams/variants.toml | 6 +- data/nvidia/1.22.0/kmod-5.10-nvidia.toml | 32 + data/nvidia/1.22.0/kmod-5.15-nvidia.toml | 42 + data/nvidia/1.22.0/kmod-6.1-nvidia.toml | 42 + data/settings/1.22.x/autoscaling.toml | 15 + data/settings/1.22.x/aws.toml | 31 + data/settings/1.22.x/boot.toml | 87 ++ .../settings/1.22.x/bootstrap-containers.toml | 61 ++ data/settings/1.22.x/cloudformation.toml | 25 + data/settings/1.22.x/container-registry.toml | 64 ++ data/settings/1.22.x/container-runtime.toml | 40 + data/settings/1.22.x/dns.toml | 19 + data/settings/1.22.x/ecs.toml | 204 +++++ data/settings/1.22.x/host-containers.toml | 63 ++ data/settings/1.22.x/kernel.toml | 91 ++ data/settings/1.22.x/kubernetes.toml | 627 ++++++++++++++ data/settings/1.22.x/metrics.toml | 29 + data/settings/1.22.x/motd.toml | 5 + data/settings/1.22.x/network.toml | 92 ++ data/settings/1.22.x/ntp.toml | 7 + data/settings/1.22.x/oci-defaults.toml | 792 ++++++++++++++++++ data/settings/1.22.x/oci-hooks.toml | 17 + data/settings/1.22.x/pki.toml | 37 + data/settings/1.22.x/updates.toml | 66 ++ data/variants/1.22.x/aws-dev.toml | 51 ++ data/variants/1.22.x/aws-ecs-1-nvidia.toml | 43 + data/variants/1.22.x/aws-ecs-1.toml | 36 + data/variants/1.22.x/aws-ecs-2-nvidia.toml | 49 ++ data/variants/1.22.x/aws-ecs-2.toml | 43 + data/variants/1.22.x/aws-k8s-1.23-nvidia.toml | 46 + data/variants/1.22.x/aws-k8s-1.23.toml | 40 + data/variants/1.22.x/aws-k8s-1.24-nvidia.toml | 46 + data/variants/1.22.x/aws-k8s-1.24.toml | 40 + data/variants/1.22.x/aws-k8s-1.25-nvidia.toml | 46 + data/variants/1.22.x/aws-k8s-1.25.toml | 40 + data/variants/1.22.x/aws-k8s-1.26-nvidia.toml | 45 + data/variants/1.22.x/aws-k8s-1.26.toml | 39 + data/variants/1.22.x/aws-k8s-1.27-nvidia.toml | 45 + data/variants/1.22.x/aws-k8s-1.27.toml | 39 + data/variants/1.22.x/aws-k8s-1.28-nvidia.toml | 51 ++ data/variants/1.22.x/aws-k8s-1.28.toml | 44 + data/variants/1.22.x/aws-k8s-1.29-nvidia.toml | 51 ++ data/variants/1.22.x/aws-k8s-1.29.toml | 44 + data/variants/1.22.x/aws-k8s-1.30-nvidia.toml | 51 ++ data/variants/1.22.x/aws-k8s-1.30.toml | 44 + data/variants/1.22.x/aws-k8s-1.31-nvidia.toml | 51 ++ data/variants/1.22.x/aws-k8s-1.31.toml | 44 + data/variants/1.22.x/metal-dev.toml | 48 ++ data/variants/1.22.x/metal-k8s-1.28.toml | 47 ++ data/variants/1.22.x/metal-k8s-1.29.toml | 47 ++ data/variants/1.22.x/vmware-dev.toml | 53 ++ data/variants/1.22.x/vmware-k8s-1.28.toml | 51 ++ data/variants/1.22.x/vmware-k8s-1.29.toml | 51 ++ data/variants/1.22.x/vmware-k8s-1.30.toml | 51 ++ data/variants/1.22.x/vmware-k8s-1.31.toml | 51 ++ data/versions/current.toml | 8 +- 116 files changed, 6642 insertions(+), 8 deletions(-) create mode 100644 content/en/os/1.22.x/_index.markdown create mode 100644 content/en/os/1.22.x/api/_index.markdown create mode 100644 content/en/os/1.22.x/api/endpoints/index.markdown create mode 100644 content/en/os/1.22.x/api/reporting/_index.markdown create mode 100644 content/en/os/1.22.x/api/reporting/cis-k8s/index.markdown create mode 100644 content/en/os/1.22.x/api/reporting/cis/index.markdown create mode 100644 content/en/os/1.22.x/api/settings-index/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/autoscaling/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/aws/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/boot/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/bootstrap-containers/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/cloudformation/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/container-registry/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/container-runtime/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/dns/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/ecs/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/host-containers/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/kernel/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/kubernetes/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/metrics/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/motd/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/network/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/ntp/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/oci-defaults/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/oci-hooks/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/pki/_index.markdown create mode 100644 content/en/os/1.22.x/api/settings/updates/_index.markdown create mode 100644 content/en/os/1.22.x/concepts/_index.markdown create mode 100644 content/en/os/1.22.x/concepts/api-driven/index.markdown create mode 100644 content/en/os/1.22.x/concepts/bootstrap-containers/_index.markdown create mode 100644 content/en/os/1.22.x/concepts/chain-of-trust/index.markdown create mode 100644 content/en/os/1.22.x/concepts/components/index.markdown create mode 100644 content/en/os/1.22.x/concepts/host-containers/_index.markdown create mode 100644 content/en/os/1.22.x/concepts/restricted-filesystem/index.markdown create mode 100644 content/en/os/1.22.x/concepts/shell-less-host/index.markdown create mode 100644 content/en/os/1.22.x/concepts/updating-bottlerocket/index.markdown create mode 100644 content/en/os/1.22.x/concepts/variants/index.markdown create mode 100644 content/en/os/1.22.x/install/_index.markdown create mode 100644 content/en/os/1.22.x/install/quickstart/_index.markdown create mode 100644 content/en/os/1.22.x/install/quickstart/aws/_index.markdown create mode 100644 content/en/os/1.22.x/install/quickstart/aws/ecs/index.markdown create mode 100644 content/en/os/1.22.x/install/quickstart/aws/host-containers/index.markdown create mode 100644 content/en/os/1.22.x/install/quickstart/aws/k8s/index.markdown create mode 100644 content/en/os/1.22.x/login/_index.markdown create mode 100644 content/en/os/1.22.x/login/regaining-access/index.markdown create mode 100644 content/en/os/1.22.x/update/_index.markdown create mode 100644 content/en/os/1.22.x/update/guidelines/index.markdown create mode 100644 content/en/os/1.22.x/update/locking-to-a-specific-release/index.markdown create mode 100644 content/en/os/1.22.x/update/methods/_index.markdown create mode 100644 content/en/os/1.22.x/update/methods/in-place/index.markdown create mode 100644 content/en/os/1.22.x/update/methods/node-replacement/index.markdown create mode 100644 content/en/os/1.22.x/version-information/_index.markdown create mode 100644 content/en/os/1.22.x/version-information/gpu-drivers/1.22.0/index.markdown create mode 100644 content/en/os/1.22.x/version-information/gpu-drivers/_index.markdown create mode 100644 content/en/os/1.22.x/version-information/packages-by-variant/index.markdown create mode 100644 content/en/os/1.22.x/version-information/packages/1.22.0/index.markdown create mode 100644 content/en/os/1.22.x/version-information/packages/_index.markdown create mode 100644 content/en/os/1.22.x/version-information/variants/index.markdown create mode 100644 data/nvidia/1.22.0/kmod-5.10-nvidia.toml create mode 100644 data/nvidia/1.22.0/kmod-5.15-nvidia.toml create mode 100644 data/nvidia/1.22.0/kmod-6.1-nvidia.toml create mode 100644 data/settings/1.22.x/autoscaling.toml create mode 100644 data/settings/1.22.x/aws.toml create mode 100644 data/settings/1.22.x/boot.toml create mode 100644 data/settings/1.22.x/bootstrap-containers.toml create mode 100644 data/settings/1.22.x/cloudformation.toml create mode 100644 data/settings/1.22.x/container-registry.toml create mode 100644 data/settings/1.22.x/container-runtime.toml create mode 100644 data/settings/1.22.x/dns.toml create mode 100644 data/settings/1.22.x/ecs.toml create mode 100644 data/settings/1.22.x/host-containers.toml create mode 100644 data/settings/1.22.x/kernel.toml create mode 100644 data/settings/1.22.x/kubernetes.toml create mode 100644 data/settings/1.22.x/metrics.toml create mode 100644 data/settings/1.22.x/motd.toml create mode 100644 data/settings/1.22.x/network.toml create mode 100644 data/settings/1.22.x/ntp.toml create mode 100644 data/settings/1.22.x/oci-defaults.toml create mode 100644 data/settings/1.22.x/oci-hooks.toml create mode 100644 data/settings/1.22.x/pki.toml create mode 100644 data/settings/1.22.x/updates.toml create mode 100644 data/variants/1.22.x/aws-dev.toml create mode 100644 data/variants/1.22.x/aws-ecs-1-nvidia.toml create mode 100644 data/variants/1.22.x/aws-ecs-1.toml create mode 100644 data/variants/1.22.x/aws-ecs-2-nvidia.toml create mode 100644 data/variants/1.22.x/aws-ecs-2.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.23-nvidia.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.23.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.24-nvidia.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.24.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.25-nvidia.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.25.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.26-nvidia.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.26.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.27-nvidia.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.27.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.28-nvidia.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.28.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.29-nvidia.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.29.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.30-nvidia.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.30.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.31-nvidia.toml create mode 100644 data/variants/1.22.x/aws-k8s-1.31.toml create mode 100644 data/variants/1.22.x/metal-dev.toml create mode 100644 data/variants/1.22.x/metal-k8s-1.28.toml create mode 100644 data/variants/1.22.x/metal-k8s-1.29.toml create mode 100644 data/variants/1.22.x/vmware-dev.toml create mode 100644 data/variants/1.22.x/vmware-k8s-1.28.toml create mode 100644 data/variants/1.22.x/vmware-k8s-1.29.toml create mode 100644 data/variants/1.22.x/vmware-k8s-1.30.toml create mode 100644 data/variants/1.22.x/vmware-k8s-1.31.toml diff --git a/content/en/os/1.21.x/_index.markdown b/content/en/os/1.21.x/_index.markdown index d0b5043f..436854ca 100644 --- a/content/en/os/1.21.x/_index.markdown +++ b/content/en/os/1.21.x/_index.markdown @@ -1,4 +1,4 @@ +++ -title="1.21.x (Current)" +title="1.21.x" type="docs" +++ diff --git a/content/en/os/1.22.x/_index.markdown b/content/en/os/1.22.x/_index.markdown new file mode 100644 index 00000000..41a6edc5 --- /dev/null +++ b/content/en/os/1.22.x/_index.markdown @@ -0,0 +1,4 @@ ++++ +title="1.22.x (Current)" +type="docs" ++++ diff --git a/content/en/os/1.22.x/api/_index.markdown b/content/en/os/1.22.x/api/_index.markdown new file mode 100644 index 00000000..c6e3f727 --- /dev/null +++ b/content/en/os/1.22.x/api/_index.markdown @@ -0,0 +1,6 @@ ++++ +title = "API" +type = "docs" +description = "Bottlerocket's primary administrative interface" +weight = 999 ++++ \ No newline at end of file diff --git a/content/en/os/1.22.x/api/endpoints/index.markdown b/content/en/os/1.22.x/api/endpoints/index.markdown new file mode 100644 index 00000000..51580880 --- /dev/null +++ b/content/en/os/1.22.x/api/endpoints/index.markdown @@ -0,0 +1,11 @@ ++++ +title = "API Endpoint Reference" +type = "swagger" +description = "Paths and methods for the API" ++++ + +The following output is generated from [Bottlerocket's OpenAPI Spec](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/openapi.yaml). + +--- + +{{< swaggerui src="../../../../external/openapi/1.15.x/openapi.yaml" >}} diff --git a/content/en/os/1.22.x/api/reporting/_index.markdown b/content/en/os/1.22.x/api/reporting/_index.markdown new file mode 100644 index 00000000..7e0dc21c --- /dev/null +++ b/content/en/os/1.22.x/api/reporting/_index.markdown @@ -0,0 +1,50 @@ ++++ +title = "Reporting" +type = "docs" +description = "Using the Report API to automate operating system-level reporting." ++++ + +Operating systems are complicated; inspecting and reporting data about the OS is a common but tedious task that needs repeating as configurations change. +Manually gathering this data for Bottlerocket has additional complications due to API abstracted settings and indirect access to the host. + +The Bottlerocket report API provides a mechanism to automate operating system-level reporting. +You can run reports that self-evaluate the OS based on the current state of the system compared to known standards. + +## Center for Internet Security (CIS) Benchmark + +You can currently generate reports on your Bottlerocket nodes against two different CIS benchmarks: + +- [Bottlerocket CIS Benchmark](./cis/) +- [Kubernetes CIS Benchmark](./cis-k8s) + +## Running a report + +You will need to be running the [control container](../../concepts/shell-less-host/#control-container) or, alternately, mount the `apiclient` binary and the Bottlerocket API unix socket into a container as well as have the appropriate SELinux permissions. + +First, create an interactive shell session on the control container or container with `apiclient`. +From the shell run: + +```shell +apiclient report <report identifier> +``` + +This will evaluate the current node to a particular report and return the results in a human-readable format. + +If you intend to process the report with some other piece of software, add the flag `-f` with the value of `json` for a JSON representation of the report: + +```shell +# Returns evaluation of the report in JSON format +apiclient report <report identifier> -f json +``` + +## Evaluation Results + +Evaluation of each item on the report will result in one of three outcomes: + +* `PASS`: Evaluated item is in compliance with the benchmark. +* `FAIL`: Evaluated item is not in compliance with the benchmark. +* `SKIP`: The item could not be automatically evaluated. + +## All Available Reports + +{{< on-github >}} diff --git a/content/en/os/1.22.x/api/reporting/cis-k8s/index.markdown b/content/en/os/1.22.x/api/reporting/cis-k8s/index.markdown new file mode 100644 index 00000000..09dfe7b4 --- /dev/null +++ b/content/en/os/1.22.x/api/reporting/cis-k8s/index.markdown @@ -0,0 +1,33 @@ ++++ +title = "K8s CIS Benchmark" +type = "docs" +description = "Generating a Kubernetes CIS Benchmark report" +toc_hide=true ++++ + +The [Kubernetes CIS Benchmark](https://www.cisecurity.org/benchmark/kubernetes) contains a number of security best practices to harden Kubernetes worker nodes. + +{{% alert title="Note" color="success" %}} +The Kubernetes CIS Benchmark contains two levels, however, currently, level 2 only adds one additional check (4.2.8) for worker nodes. The Bottlerocket reporting API cannot automatically evaluate this additional check and therefore the two levels are functionally identical for automatic evaluation purposes. +{{% /alert %}} + +## Examples + +Expanding upon the general instructions to [run a report](../#running-a-report), for the Bottlerocket CIS benchmark use the identifier `cis-k8s`: + +```shell +apiclient report cis-k8s +``` + +Adding the flag `-l` with the value of `2` will evaluate to the Level 2 benchmark. For example: + +```shell +# Returns evaluation of CIS Benchmark Level 2 +apiclient report cis-k8s -l 2 +``` + +## Audit and Remediation + +Refer to the [Kubernetes CIS Benchmark](https://www.cisecurity.org/benchmark/kubernetes) for detailed audit and remediation steps. + +{{< on-github >}} diff --git a/content/en/os/1.22.x/api/reporting/cis/index.markdown b/content/en/os/1.22.x/api/reporting/cis/index.markdown new file mode 100644 index 00000000..89e2a36f --- /dev/null +++ b/content/en/os/1.22.x/api/reporting/cis/index.markdown @@ -0,0 +1,37 @@ ++++ +title = "Bottlerocket CIS Benchmark" +type = "docs" +description = "Generating a Bottlerocket CIS Benchmark report" +toc_hide=true ++++ + +The [Bottlerocket CIS Benchmark](https://www.cisecurity.org/benchmark/bottlerocket) contains a number of security best practices to harden Bottlerocket worker nodes. +The benchmark contains two levels: + +* **Level 1:** basic guidelines with clear security benefits that do not inhibit the node. +Bottlerocket’s default settings are compliant with level 1. +* **Level 2:** detailed, specific guidance that provide more defence to the node. +This level introduces some trade-offs between functionality and security. + +The report API has built-in tests that allow you to evaluate the state of the node to both Level 1 and Level 2. + +## Examples + +Expanding upon the general instructions to [run a report](../#running-a-report), for the Bottlerocket CIS benchmark use the identifier `cis`: + +```shell +apiclient report cis +``` + +Adding the flag `-l` with the value of `2` will evaluate to the Level 2 benchmark. For example: + +```shell +# Returns evaluation of CIS Benchmark Level 2 +apiclient report cis -l 2 +``` + +## Audit and Remediation + +Refer to the [Bottlerocket CIS Benchmark](https://www.cisecurity.org/benchmark/bottlerocket) for detailed audit and remediation steps. + +{{< on-github >}} diff --git a/content/en/os/1.22.x/api/settings-index/_index.markdown b/content/en/os/1.22.x/api/settings-index/_index.markdown new file mode 100644 index 00000000..c75c2c46 --- /dev/null +++ b/content/en/os/1.22.x/api/settings-index/_index.markdown @@ -0,0 +1,7 @@ ++++ +title="Settings Index" +type="docs" +description="Comprehesive list of all documented settings" ++++ + +{{< all-settings new_badge=true >}} diff --git a/content/en/os/1.22.x/api/settings/_index.markdown b/content/en/os/1.22.x/api/settings/_index.markdown new file mode 100644 index 00000000..4f0b9f1b --- /dev/null +++ b/content/en/os/1.22.x/api/settings/_index.markdown @@ -0,0 +1,5 @@ ++++ +title="Settings Reference" +type="docs" +description="Individual settings avaliable for the `/settings` endpoint" ++++ \ No newline at end of file diff --git a/content/en/os/1.22.x/api/settings/autoscaling/_index.markdown b/content/en/os/1.22.x/api/settings/autoscaling/_index.markdown new file mode 100644 index 00000000..dd96f615 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/autoscaling/_index.markdown @@ -0,0 +1,10 @@ ++++ +title="autoscaling" +type="docs" +toc_hide=true +description="Settings related to auto scaling groups (`settings.autoscaling.*`)" ++++ + +[Amazon EC2 Auto Scaling](https://docs.aws.amazon.com/autoscaling/ec2/userguide/auto-scaling-groups.html) settings for `aws-*` variants. + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/aws/_index.markdown b/content/en/os/1.22.x/api/settings/aws/_index.markdown new file mode 100644 index 00000000..34f09cad --- /dev/null +++ b/content/en/os/1.22.x/api/settings/aws/_index.markdown @@ -0,0 +1,11 @@ ++++ +title="aws" +type="docs" +toc_hide=true +description="Settings specific to the AWS platform (`settings.aws.*`)" ++++ + +Only pertinent on `aws-*` variants or on other variants in conjunction with [IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html), these settings are automatically gathered using instance metadata. +Typically, you do not need to explicitly populate these settings, however you can manually override these settings using the API for testing or other purposes. + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/boot/_index.markdown b/content/en/os/1.22.x/api/settings/boot/_index.markdown new file mode 100644 index 00000000..cdd15111 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/boot/_index.markdown @@ -0,0 +1,13 @@ ++++ +title="boot" +type="docs" +toc_hide=true +description="Settings related to kernel boot config (`settings.boot.*`)" ++++ + +{{% alert title="Warning" color="warning" %}} +Bottlerocket only allows boot configuration for `kernel` and `init`. +If you specify any other boot config key the settings generation will fail. +{{% /alert %}} + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/bootstrap-containers/_index.markdown b/content/en/os/1.22.x/api/settings/bootstrap-containers/_index.markdown new file mode 100644 index 00000000..b06a9418 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/bootstrap-containers/_index.markdown @@ -0,0 +1,8 @@ ++++ +title="bootstrap-containers" +type="docs" +toc_hide=true +description="Settings related to bootstrap containers (`settings.bootstrap-containers.*`)" ++++ + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/cloudformation/_index.markdown b/content/en/os/1.22.x/api/settings/cloudformation/_index.markdown new file mode 100644 index 00000000..006a9d43 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/cloudformation/_index.markdown @@ -0,0 +1,14 @@ ++++ +title="cloudformation" +type="docs" +toc_hide=true +description="Settings related to CloudFormation signaling (`settings.cloudformation.*`)" ++++ + +You can setup Bottlerocket to send successful host creation or update signals to AWS CloudFormation. See [CreationPolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-creationpolicy.html) and [UpdatePolicy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-attribute-updatepolicy.html) for more information about signaling in CloudFormation. + +{{% alert title="Note" color="success" %}} +These setting only function on `aws-*` variants. +{{% /alert %}} + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/container-registry/_index.markdown b/content/en/os/1.22.x/api/settings/container-registry/_index.markdown new file mode 100644 index 00000000..d617d2ce --- /dev/null +++ b/content/en/os/1.22.x/api/settings/container-registry/_index.markdown @@ -0,0 +1,9 @@ ++++ +title="container-registry" +type="docs" +toc_hide=true +description="Settings related to container image registries (`settings.container-registry.*`)" + ++++ + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/container-runtime/_index.markdown b/content/en/os/1.22.x/api/settings/container-runtime/_index.markdown new file mode 100644 index 00000000..195fef1e --- /dev/null +++ b/content/en/os/1.22.x/api/settings/container-runtime/_index.markdown @@ -0,0 +1,8 @@ ++++ +title="container-runtime" +type="docs" +toc_hide=true +description="Settings related to container runtime behaviour (`settings.container-runtime.*`)" ++++ + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/dns/_index.markdown b/content/en/os/1.22.x/api/settings/dns/_index.markdown new file mode 100644 index 00000000..457b54f2 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/dns/_index.markdown @@ -0,0 +1,12 @@ ++++ +title="dns" +type="docs" +toc_hide=true +description="Settings related to custom DNS settings (`settings.dns.*`)" ++++ + +Bottlerocket generates the host `resolv.conf`[^1] from `settings.dns.*` values. + +{{< settings >}} + +[^1]: `/etc/resolv.conf` for variants using [wicked](https://github.com/openSUSE/wicked) and `/run/systemd/resolve/resolv.conf` for variants using systemd-networkd (`*-k8s-1.28-*` and `*-ecs-2-*` and newer). diff --git a/content/en/os/1.22.x/api/settings/ecs/_index.markdown b/content/en/os/1.22.x/api/settings/ecs/_index.markdown new file mode 100644 index 00000000..6937b314 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/ecs/_index.markdown @@ -0,0 +1,9 @@ ++++ +title="ecs" +type="docs" +toc_hide=true +description="Settings related to Amazon ECS (`settings.ecs.*`)" + ++++ + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/host-containers/_index.markdown b/content/en/os/1.22.x/api/settings/host-containers/_index.markdown new file mode 100644 index 00000000..f3707ae9 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/host-containers/_index.markdown @@ -0,0 +1,11 @@ ++++ +title="host-containers" +type="docs" +toc_hide=true +description="Settings related to host containers (`settings.host-containers.*`)" + ++++ + +You can use the `host-containers` settings to alter the settings for the control and admin containers, or you can define your own host containers with these settings. + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/kernel/_index.markdown b/content/en/os/1.22.x/api/settings/kernel/_index.markdown new file mode 100644 index 00000000..ae80b6b3 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/kernel/_index.markdown @@ -0,0 +1,9 @@ ++++ +title="kernel" +type="docs" +toc_hide=true +description="Settings related to the Linux kernel (`settings.kernel.*`)" + ++++ + +{{< settings >}} \ No newline at end of file diff --git a/content/en/os/1.22.x/api/settings/kubernetes/_index.markdown b/content/en/os/1.22.x/api/settings/kubernetes/_index.markdown new file mode 100644 index 00000000..ed89526f --- /dev/null +++ b/content/en/os/1.22.x/api/settings/kubernetes/_index.markdown @@ -0,0 +1,12 @@ ++++ +title="kubernetes" +type="docs" +toc_hide=true +description="Settings related to Kubernetes (`settings.kubernetes.*`)" ++++ + +{{< settings >}} + +--- + +Some setting descriptions come from the [Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/) or [Kubelet Options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options) documentation. diff --git a/content/en/os/1.22.x/api/settings/metrics/_index.markdown b/content/en/os/1.22.x/api/settings/metrics/_index.markdown new file mode 100644 index 00000000..845f164b --- /dev/null +++ b/content/en/os/1.22.x/api/settings/metrics/_index.markdown @@ -0,0 +1,9 @@ ++++ +title="metrics" +type="docs" +toc_hide=true +description="Settings related to metrics (`settings.metrics.*`)" ++++ + + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/motd/_index.markdown b/content/en/os/1.22.x/api/settings/motd/_index.markdown new file mode 100644 index 00000000..b0204745 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/motd/_index.markdown @@ -0,0 +1,9 @@ ++++ +title="motd" +type="docs" +toc_hide=true +description="Settings related to the message of the day (`settings.motd`)" + ++++ + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/network/_index.markdown b/content/en/os/1.22.x/api/settings/network/_index.markdown new file mode 100644 index 00000000..b6cf14ef --- /dev/null +++ b/content/en/os/1.22.x/api/settings/network/_index.markdown @@ -0,0 +1,8 @@ ++++ +title="network" +type="docs" +toc_hide=true +description="Settings related to networking configuration (`settings.network.*`)" ++++ + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/ntp/_index.markdown b/content/en/os/1.22.x/api/settings/ntp/_index.markdown new file mode 100644 index 00000000..2b4427b9 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/ntp/_index.markdown @@ -0,0 +1,8 @@ ++++ +title="ntp" +type="docs" +toc_hide=true +description="Settings related to time servers/system time (`settings.ntp.*`)" ++++ + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/oci-defaults/_index.markdown b/content/en/os/1.22.x/api/settings/oci-defaults/_index.markdown new file mode 100644 index 00000000..2c32112d --- /dev/null +++ b/content/en/os/1.22.x/api/settings/oci-defaults/_index.markdown @@ -0,0 +1,13 @@ ++++ +title="oci-defaults" +type="docs" +toc_hide=true +description="Settings related to orchestrated containers for overriding the [OCI runtime spec](https://github.com/opencontainers/runtime-spec/blob/main/config.md) defaults (`settings.oci-defaults.*`)." + ++++ + +{{% alert title="Note" color="secondary" %}} +These settings apply only to [orchestrated containers](../../../concepts/components/#container-and-orchestrator-support), not to [host containers](../../../concepts/components/#operational-and-administrative-workloads). +{{% /alert %}} + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/oci-hooks/_index.markdown b/content/en/os/1.22.x/api/settings/oci-hooks/_index.markdown new file mode 100644 index 00000000..ceef294c --- /dev/null +++ b/content/en/os/1.22.x/api/settings/oci-hooks/_index.markdown @@ -0,0 +1,10 @@ ++++ +title="oci-hooks" +type="docs" +toc_hide=true +description="Settings related host-provided OCI Hooks (`settings.oci-hooks.*`)." ++++ + +Enable/disable OCI hooks provided by the host. + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/pki/_index.markdown b/content/en/os/1.22.x/api/settings/pki/_index.markdown new file mode 100644 index 00000000..45cbe45c --- /dev/null +++ b/content/en/os/1.22.x/api/settings/pki/_index.markdown @@ -0,0 +1,15 @@ ++++ +title="pki" +type="docs" +toc_hide=true +description="Settings related to Custom CA Certificates (`settings.pki.*`)" + ++++ + +By default, Bottlerocket ships with the [Mozilla CA certificate store](https://wiki.mozilla.org/CA/Included_Certificates), but you can add self-signed certificates with `settings.pki.<bundle name>`. + +{{% alert title="Tip" color="success" %}} +If your user data is over the size limit for the platform, you can use `apiclient` with this setting from within a [bootstrap container](https://github.com/bottlerocket-os/bottlerocket#bootstrap-containers-settings) to add certificates. +{{% /alert %}} + +{{< settings >}} diff --git a/content/en/os/1.22.x/api/settings/updates/_index.markdown b/content/en/os/1.22.x/api/settings/updates/_index.markdown new file mode 100644 index 00000000..b0c86342 --- /dev/null +++ b/content/en/os/1.22.x/api/settings/updates/_index.markdown @@ -0,0 +1,8 @@ ++++ +title="updates" +type="docs" +toc_hide=true +description="Settings related to updates (`settings.updates.*`)" ++++ + +{{< settings >}} diff --git a/content/en/os/1.22.x/concepts/_index.markdown b/content/en/os/1.22.x/concepts/_index.markdown new file mode 100644 index 00000000..1f3f48c0 --- /dev/null +++ b/content/en/os/1.22.x/concepts/_index.markdown @@ -0,0 +1,6 @@ ++++ +title="Concepts" +type="docs" +description="High-level concepts in Bottlerocket" +weight = "50" ++++ \ No newline at end of file diff --git a/content/en/os/1.22.x/concepts/api-driven/index.markdown b/content/en/os/1.22.x/concepts/api-driven/index.markdown new file mode 100644 index 00000000..ea77b6bc --- /dev/null +++ b/content/en/os/1.22.x/concepts/api-driven/index.markdown @@ -0,0 +1,95 @@ ++++ +title = "API Driven" +type = "docs" +description = "Administration and setting manipulation with the Bottlerocket API" ++++ + +Bottlerocket is an API-driven operating system. +This is a departure from general purpose Linux distributions where you install packages, configure services through individual configuration files, and use commands from the shell to perform administrative tasks. + +With the concept of variants, all installed software for any given image is a known quantity and an included API enables you to configure everything from a single interface. +Additionally, administrative tasks like checking for updates and rebooting as well as executing commands on the host are all accomplished with API calls. + +## Accessing the API + +Bottlerocket API requests are made with HTTP requests over a Unix domain socket. +The API is only accessible by containers running on the same host with specific SELinux labels. +The API Unix domain socket is accessible by mounting; containers running on the host can access the API as long as they have both the correct SELinux labels and mount the socket. +Both the Admin and Control containers have the requisite SELinux labels and socket pre-mounted. +Because access to the API socket is through explicit mounts and SELinux labels there is no authentication required. +Consequently, any remote access to the API necessitates an authenticated transport mechanism. + +## API Client + +Bottlerocket ships with a tool called `apiclient` which provides a command line interface for interacting with the API. +The client is a minimal abstraction over the API: it accepts command-line arguments, translates the arguments into an API call, and returns the response as standard output. +Access to the `apiclient` binary is typically provided as a read-only mount from the host to containers that need access. + +## Settings + +You can view and alter Bottlerocket settings through the API. +The API is able to `set` or `get` one or many *settings*. +A setting is accessible by a path and contains a value. + +Take this `set` example that alters a single setting: + +```goat + +-- Path Value + | | ++---------+---------+ +-+-+ +| | | | +host-containers.admin.enabled=false + | | + +--+--+ + | + Setting +``` + +If you `get` a path without the setting, it returns all the settings and values in the path: + +```goat + +-- Path + | ++---------+---------+ +| | +host-containers.admin --> Values of: + enabled + source + superpowered +``` + +If you `get` a path and a setting, it returns only the value of that specific setting: + +```goat + +-- Path + | ++---------+---------+ +| | +host-containers.admin.enabled --> Value of: + | | enabled + +--+--+ + | + Setting +``` + +Internally, these settings are either marshalled into various config formats for each related process or they are directly accessed by Bottlerocket’s own tools. + +From the API client, you can either pass in settings in a key/value (format with the key being the path) or as JSON containing both the path and value(s). + +As an example: + +```shell +host-containers.admin.enabled=false +``` + +The above key/value format is equivalent to: + +```json +{ "host-containers" : { "admin" : { "enabled": false } } } +``` + +### User Data + +User Data is a collection of settings contained in a TOML-formatted file that is processed by the API at boot: anything you can manipulate using `apiclient` you can also manipulate with User Data. + +{{< on-github >}} diff --git a/content/en/os/1.22.x/concepts/bootstrap-containers/_index.markdown b/content/en/os/1.22.x/concepts/bootstrap-containers/_index.markdown new file mode 100644 index 00000000..1d5b589e --- /dev/null +++ b/content/en/os/1.22.x/concepts/bootstrap-containers/_index.markdown @@ -0,0 +1,91 @@ ++++ +title = "Bootstrap Containers" +type = "docs" +description = "Setting up the host with containers that start during boot." ++++ + +Bootstrap containers are a form of {{< ver-ref project="os" page="/concepts/host-containers" >}}host container{{< /ver-ref >}} that you can use to run critical software before the node connects to an orchestrator. +They give you substantial power to configure and modify the system in ways that would otherwise be [difficult or impossible](#use-cases). + +## Lifecycle + +When you define a bootstrap container using user-data or the Bottlerocket API, the following sequence occurs on next boot: + +- [`systemd`](https://systemd.io/) starts all of the bootstrap containers concurrently, +- `systemd` will not move to the next [target](https://www.freedesktop.org/software/systemd/man/systemd.target.html) until all of the bootstrap containers start, run, and exit, +- any bootstrap container configured with `{{< ver-ref project="os" page="/api/settings/bootstrap-containers#name_mode">}}mode=once{{< /ver-ref >}}` will change to `{{< ver-ref project="os" page="/api/settings/bootstrap-containers#name_mode">}}mode=off{{< /ver-ref >}}` once complete, +- any bootstrap container set to `{{< ver-ref project="os" page="/api/settings/bootstrap-containers#name_essential">}}essential=true{{< /ver-ref >}}` that exits with an non-zero exit code halts the boot process, +- unless stopped in the previous step, the boot process continues by loading the orchestrator agent ({{% ver-ref project="os" page="/concepts/components#container-and-orchestrator-support"%}} `kubelet` on `*-k8s-*` {{% /ver-ref %}} variants or the {{% ver-ref project="os" page="/concepts/components#ecs-variants" %}}ECS agent on `*-ecs-*`{{% /ver-ref %}} variants). + +### Examples + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner colsplit="7" >}} + {{< bootstrap_containers_diagram example=1 >}} + {{</ twocol_inner >}} + {{% twocol_inner %}} +This example shows four bootstrap containers (`B1`,`B2`,`B3`, and `B4`) starting. +The start order of these containers is not sequential and could be in any order. +Container `B2` runs the longest and the next stage of the boot does not proceed until it completes. + {{%/ twocol_inner %}} +{{</ twocol >}} + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner colsplit="7" >}} + {{< bootstrap_containers_diagram example=2 >}} + {{</ twocol_inner >}} + {{% twocol_inner %}} +This example is the same as the previous one except container `B2` is configured with {{< ver-ref project="os" page="/api/settings/bootstrap-containers#name_essential">}}`essential=true`{{< /ver-ref >}}. +Container `B2` exits with a non-zero exit code and consequently the boot halts. + {{%/ twocol_inner %}} +{{</ twocol >}} + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner colsplit="7" >}} + {{< bootstrap_containers_diagram example=3 >}} + {{</ twocol_inner >}} + {{% twocol_inner %}} +This example is the same as the first except container `B4` is configured with {{< ver-ref project="os" page="/api/settings/bootstrap-containers#name_mode">}}`mode=once`{{< /ver-ref >}}. +After all the bootstrap containers finish, Bottlerocket (via a `systemd` unit) updates container `B4`'s `mode` to `off`. + {{%/ twocol_inner %}} +{{</ twocol >}} + +### Considerations + +As a consequence of this lifecycle, you should keep a few things in mind when using bootstrap containers: + +1. Bootstrap containers should be short-running and cleanly exit when complete otherwise the node will hang. +2. Since `systemd` starts all the bootstrap containers concurrently, you cannot rely on a deterministic starting order. +3. Bootstrap containers do not have access to the container orchestrator nor the rest of the cluster. +4. Bootstrap containers should not modify critical configuration files (e.g. `/etc/`). + +## Capabilities and permissions + +Bootstrap containers sit somewhat between default host containers and `superpowered` host container permissions. +They have access to the underlying host filesystem at `/.bottlerocket/` which contains the root filesystem (`/.bottlerocket/rootfs`). +Additionally, bootstrap containers run with the {{< ver-ref project="os" page="/api/settings/oci-defaults#capabilities_sys-admin" >}}CAP_SYS_ADMIN capability{{< /ver-ref >}}, allowing for the creation of files, directories, and mounts accessible to the host (however the root filesystem remains {{< ver-ref project="os" page="/concepts/restricted-filesystem#immutable-filesystem" >}}immutable{{</ ver-ref>}}). +You cannot elevate the permissions of bootstrap containers. + +## Use cases + +Bootstrap containers have a variety of uses. + +1. Configure large setting values. +On many platforms there are [limits to the size of user-data](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-add-user-data.html) but you can use a bootstrap container to pass large values into `apiclient`. +2. Conditionally halt boot. +You can perform checks or evaluation of the system in a {{< ver-ref project="os" page="/api/settings/bootstrap-containers#name_essential" >}}bootstrap container with `essential` set to `true`{{< /ver-ref >}}. +3. Apply settings you do not want to store in plaintext. +In cases where you need to pass values that you would not want to store in plain-text on external systems (such as credentials), you can instead use a bootstrap container that sets the values via `apiclient`. +4. Configure ephemeral disks. Since [bootstrap containers have access to `/.bottlerocket/rootfs/mnt`](#capabilities-and-permissions) and all bootstrap or `superpowered` host containers share this bind mount, you can configure ephemeral disks attached to your host in a bootstrap container and use it elsewhere. + +## Also see + +- {{< ver-ref project="os" page="/api/settings/bootstrap-containers">}} bootstrap-containers in the API Setting Reference{{< /ver-ref >}} + +{{< on-github >}} diff --git a/content/en/os/1.22.x/concepts/chain-of-trust/index.markdown b/content/en/os/1.22.x/concepts/chain-of-trust/index.markdown new file mode 100644 index 00000000..93ba9808 --- /dev/null +++ b/content/en/os/1.22.x/concepts/chain-of-trust/index.markdown @@ -0,0 +1,56 @@ ++++ +title = "Chain of Trust" +type = "docs" +description = "Bottlerocket's cryptographic validation mechansims" ++++ + +Container hosts are particularly sensitive, with nearly unfettered access to your workloads, secrets, storage, and network. +Consequently, ensuring that only your desired code runs on the host is paramount. Bottlerocket’s chain of trust provides cryptographic verification of all parts of the boot sequence through to your containers starting. +Effectively, this means that every step verifies the next step in the sequence and any verification failure will immediately prevent any further progress. + +Starting from Bottlerocket 1.15.0 with Kubernetes 1.28 or ECS 2 variants (or newer), Secure Boot is enabled by default, where supported by firmware. + +## Boot Sequence + +{{% readfile "/includes/os/1.15.x/secure-boot.svg" %}} + +The chain of trust starts prior to booting Bottlerocket. +Modern, server-class machines initialize by loading firmware that conforms to the [UEFI specification](https://en.wikipedia.org/wiki/UEFI). +In the most basic configuration, the firmware hands off control of the machine to the OS or bootloader. +However, UEFI optionally implements Secure Boot, which is a mechanism that prevents hand off to unsigned software. Bottlerocket uses Secure Boot by default. + +To start, the firmware retrieves the Bottlerocket certificate stored in the system’s NVRAM and uses it to verify that the first-stage bootloader, [shim](https://github.com/rhboot/shim), is correctly signed. + +{{% alert title="Note" color="success" %}} +Many operating systems use a version of shim signed by the Microsoft 3rd Party UEFI CA certificate. Bottlerocket does not use this certificate. +Instead, Bottlerocket uses a self-signed certificate intended to allow you to focus your machine’s trust only to your specified OS (in this case, Bottlerocket). +From Microsoft’s article [“Secure the Windows boot process”](https://learn.microsoft.com/en-us/windows/security/operating-system-security/system-security/secure-the-windows-10-boot-process): + +*“Since the Microsoft 3rd Party UEFI CA certificate signs the bootloaders for all Linux distributions, trusting the Microsoft 3rd Party UEFI CA signature in the UEFI database increases the attack surface of systems. A customer who intended to only trust and boot a single Linux distribution will trust all distributions - much more than their desired configuration.”* +{{% /alert %}} + +Shim has access to certs stored in NVRAM. These certs are needed to verify the signed binary for GNU GRUB, the next step in the boot process. +GRUB verifies the signature of its configuration file, `grub.cfg`, then grub calls into shim to verify the kernel. +The GRUB configuration also contains the dm-verity root hash for the immutable root filesystem. GRUB hands off to the now-verified Linux kernel which can mount the root filesystem using the dm-verity root hash. + +If any verification fails during the above process, the boot sequence will cease. +After the boot process, dm-verity will detect any changes to the block device underlying the root filesystem and trigger a reboot of the machine. + +## Requirements + +This chain of trust relies on Secure Boot enabled firmware. Secure Boot has some prerequisites which are primarily relevant on `metal` variants: + +1. UEFI firmware +2. Firmware Secure Boot feature enabled; Compatibility Support Module and/or legacy bios emulation disabled +3. The machine’s NVRAM must contain Bottlerocket’s "db" certificate, which is used to sign shim. The Bottlerocket EFI partition includes this certificate in both PEM and DER formats. + +Verifying these requirements varies by hardware vendor and may involve making edits on your hardware’s firmware setup menu. + +On `aws-*` variants , any instance based with a Xen-based hypervisor (generation 4 and below) use a legacy BIOS mode and consequently cannot use Secure Boot. + +## Related + +- [FAQ: How do I disable Secure Boot?](/en/faq/#4_3) +- [Concept: Restricted filesystem](../restricted-filesystem/) + +{{< on-github >}} diff --git a/content/en/os/1.22.x/concepts/components/index.markdown b/content/en/os/1.22.x/concepts/components/index.markdown new file mode 100644 index 00000000..30e0a7ce --- /dev/null +++ b/content/en/os/1.22.x/concepts/components/index.markdown @@ -0,0 +1,156 @@ ++++ +title = "Components" +type = "docs" +description = "The pieces that constitute Bottlerocket" ++++ + +The components of Bottlerocket differ substantially from most Linux distributions. By providing ready-to-run images, some software typically considered as workloads of an operating system are integral to Bottlerocket. + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner >}}{{< components_diagram >}}{{</ twocol_inner >}} + {{% twocol_inner colsplit="7" %}} This diagram represents the components of the `aws-k8s-*` variant. Subsequent sections will dissect and explain this variant. {{%/ twocol_inner %}} +{{</ twocol >}} + +### Foundation + +{{< twocol containerclass="td-max-width-on-larger-screens docs-figure" rowclass="docs-figure">}} + {{< twocol_inner >}} + {{< components_diagram + disable_kubelet=true + disable_containerd_left=true + disable_containerd_right=true + disable_pods=true + disable_host_containers=true + disable_systemd=true + >}} + {{</ twocol_inner >}} + {{% twocol_inner colsplit="7" %}} +The Linux kernel provides the foundation of Bottlerocket. The kernel (major+minor) version may vary between variants, but does not change on update. + {{%/ twocol_inner %}} +{{</ twocol >}} + +### System Services + +{{< twocol containerclass="td-max-width-on-larger-screens docs-figure" rowclass="docs-figure">}} + {{< twocol_inner >}} + {{< components_diagram + disable_kubelet=true + disable_containerd_left=true + disable_containerd_right=true + disable_pods=true + disable_host_containers=true + disable_kernel=true + >}} + {{</ twocol_inner >}} + {{% twocol_inner colsplit="7" %}} +systemd serves as the initialization and service management layer. systemd unifies a broad, modern, widely-used set of APIs that Bottlerocket can build atop in a variety of contexts. + {{%/ twocol_inner %}} +{{</ twocol >}} + +### Container and Orchestrator Support + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner >}} + {{< components_diagram + disable_pods=true + disable_host_containers=true + disable_kernel=true + disable_systemd=true + >}} + {{</ twocol_inner >}} + {{% twocol_inner colsplit="7" %}} +Bottlerocket runs two instances of the container runtime, containerd. Containers used for operational and administrative purposes have a devoted containerd instance, whilst orchestrator-managed workloads have a separate containerd instance. + +On Kubernetes variants, Bottlerocket runs Kubelet to communicate with the Kubernetes control plane and orchestrate container lifecycles. + {{%/ twocol_inner %}} +{{</ twocol >}} + +### Application Workloads + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner >}} + {{< components_diagram + disable_host_containers=true + disable_kernel=true + disable_systemd=true + disable_containerd_left=true + disable_containerd_right=true + disable_kubelet=true + >}} + {{</ twocol_inner >}} + {{% twocol_inner colsplit="7"%}} +Bottlerocket defers workload management to the orchestrator. While Bottlerocket is a distinctive operating system, the differences are mostly transparent to your application workloads. If your workload requires specific host-level interactions, accommodations go through the Bottlerocket Settings API in addition to typical patterns of mounted directories and container privileges. + {{%/ twocol_inner %}} +{{</ twocol >}} + +### Operational and Administrative Workloads + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner >}} + {{< components_diagram + disable_kernel=true + disable_systemd=true + disable_containerd_left=true + disable_containerd_right=true + disable_kubelet=true + disable_pods=true + >}} + {{</ twocol_inner >}} + {{% twocol_inner colsplit="7"%}} +“Host Containers” are containers specifically used to maintain, operate, or administer the node. Host containers provide a secondary method to manipulate and administer the operating system even if the orchestrator agent is non-responsive or exhausted of resources. + +There are two host containers that are published for use with Bottlerocket: the control container and the admin container. +The control container is on by default. +It is pre-configured to be able to use the Bottlerocket API and can be accessed by SSM. +The admin container is off by default and has elevated privileges for system exploration and debugging. +Furthermore, any container can be [run as a host container](https://github.com/bottlerocket-os/bottlerocket#custom-host-containers), and any number of host containers can run. + {{%/ twocol_inner %}} +{{</ twocol >}} + +## Differences between variants + +### ECS Variants + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner >}} + {{< components_diagram + show_ecs="true" + kubelet_label="docker" + pods_label="Tasks" + >}} + {{</ twocol_inner >}} + {{% twocol_inner colsplit="7"%}} + +Bottlerocket ECS variants function in roughly the same way but differ subtly in components. Instead of Kubelet, ECS variants use the ecs-agent and Docker daemon. The ecs-agent communicates with the ECS control plane but Docker interposes between the agent and the container runtime. + + {{%/ twocol_inner %}} +{{</ twocol >}} + +### On-premise Variants (Baremetal & VMware) + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner >}} + {{< components_diagram + disable_control_container="true" + >}} + {{</ twocol_inner >}} + {{% twocol_inner colsplit="7"%}} + +Variants designed to run on-premises have different access constraints. The control container with SSM is available, but disabled by default. As with the other variants, Bottlerocket does not start with an enabled admin container, however some solutions may enable it for an easier first-boot access path. + + {{%/ twocol_inner %}} +{{</ twocol >}} + +{{< on-github >}} diff --git a/content/en/os/1.22.x/concepts/host-containers/_index.markdown b/content/en/os/1.22.x/concepts/host-containers/_index.markdown new file mode 100644 index 00000000..75d1db21 --- /dev/null +++ b/content/en/os/1.22.x/concepts/host-containers/_index.markdown @@ -0,0 +1,89 @@ ++++ +title = "Host Containers" +type = "docs" +description = "Special purpose, non-orchestrated containers for node management and administration" ++++ + +Host containers are a special type of container you can use to manage and administer your Bottlerocket node. +These containers are non-orchestrated, which means Kubernetes or ECS are unaware of these containers and cannot directly manage their lifecycle. +Instead you manage the lifecycle of these containers by manipulating specific {{< ver-ref project="os" page="/api/settings/" >}}Bottlerocket settings{{< /ver-ref >}} with the {{< ver-ref project="os" page="/concepts/api-driven" >}}API{{< /ver-ref >}}. + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner >}}{{< components_diagram hide_admin_and_control=true >}}{{</ twocol_inner >}} + {{% twocol_inner colsplit="7" %}} This diagram represents the components of the `aws-k8s-*` variant. + Note the "Host Containers" in the upper left. + {{%/ twocol_inner %}} +{{</ twocol >}} + +## Built-in host containers + +Depending on the variant, Bottlerocket has two standard host containers: the {{< ver-ref project="os" page="/install/quickstart/aws/host-containers#interacting-with-a-bottlerocket-node-through-host-containers" >}}control container{{< /ver-ref >}} and the {{< ver-ref project="os" page="/install/quickstart/aws/host-containers#exploring-the-admin-container" >}}admin container{{< /ver-ref >}}. +The control container provides a pathway to connect ([via SSM](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html)) to and interact with the host as well as conveniently access the Bottlerocket API. +The control container also provides an entry point to the admin container. +The admin container allows you to more deeply interact with the host as it mounts the root filesystem and has elevated privileges. + +The control and admin containers are not actually special: both are just host containers with specific privileges. +Case in point, you can disable (and {{< ver-ref project="os" page="/login/regaining-access" >}}re-enable{{</ ver-ref >}}) these containers as-needed and you can even fully replace the functionality of both the host and admins containers with your own host containers. + +## Properties of host containers + +Host containers have a number of different properties from orchestrated containers. + +### Runtime + +Bottlerocket has two parallel instances of `containerd`: one for your orchestrated workloads and one for host containers. + +### API Access + +All host containers automatically mount the API socket (`/run/api.sock`) and the API Client (`/usr/local/bin/apiclient`). +This allows you to run API commands and manipulate Bottlerocket settings from within the host containers without explicitly mounting these resources. +As a consequence, any user that can access a host container can change configurations which could effect the efficiency or stability of the node. + +### Lifecycle & restarts + +Host containers start and stop based on the value of their {{< setting-reference setting="settings.host-containers.<container>.enabled" >}}enabled{{</ setting-reference >}} setting. +If a host container exits, Bottlerocket automatically restarts the container after 45 seconds. + +### Superpower + +Host containers can have high levels of privilege. +See {{< setting-reference setting="settings.host-containers.<container>.superpowered" >}}{{</ setting-reference >}} for more details. + +### Updates + +Host containers do not update automatically. +Updates only occur when you update the {{< setting-reference setting="settings.host-containers.<container>.source" >}}{{</ setting-reference >}} or when an {{< ver-ref project="os" page="/update/methods/in-place" >}}in-place update{{</ ver-ref >}} occurs. + +### User data + +Distinct, but inspired by instance user data, host containers pass arbitrary[^1] base64-encoded data from the API into a file[^2]. + +### Persistent storage + +All host containers have persistent storage that survive node reboots as well as container stop/start cycles[^2]. + +## Use Cases + +When considering if you should use a host container, evaluate the specific properties of host containers and if you need to manage the lifecycle with your orchestrator. +Generally, you should try to solve your problem with an orchestrated container and only turn to a host container for low-level use-cases. + +Examples: + +- The control container is a host container because it needs to be available early to give you access to the OS. +- The admin container is a host container because it needs high levels of privilege and you may need it to debug when orchestration isn't working + +## Also See + +- `{{< ver-ref project="os" page="/api/settings/host-containers/" >}}host-containers{{</ ver-ref >}}` settings reference +- `{{< ver-ref project="os" page="/api/settings/bootstrap-containers/" >}}boostrap-containers{{</ ver-ref >}}` setting reference +- {{< ver-ref project="os" page="/concepts/bootstrap-containers/" >}}Bootstrap Containers{{</ ver-ref >}} + +[^1]: The admin container has a special uses for user data. See the warning on {{< setting-reference setting="settings.host-containers.<container>.user-data" >}}{{</ setting-reference >}} +[^2]: Paths for persistent storage and user data (`<HOST_CONTAINER_NAME>` being the name of the host container): + + - `/.bottlerocket/host-containers/<HOST_CONTAINER_NAME>` and `/.bottlerocket/host-containers/<HOST_CONTAINER_NAME>/user-data` + - `/.bottlerocket/host-containers/current` and `/.bottlerocket/host-containers/current/user-data` + +{{< on-github >}} diff --git a/content/en/os/1.22.x/concepts/restricted-filesystem/index.markdown b/content/en/os/1.22.x/concepts/restricted-filesystem/index.markdown new file mode 100644 index 00000000..7b653b02 --- /dev/null +++ b/content/en/os/1.22.x/concepts/restricted-filesystem/index.markdown @@ -0,0 +1,58 @@ ++++ +title = "Restricted Filesystem" +type = "docs" +description = "Protections to the host filesystem" ++++ + +Bottlerocket is a container host operating system. +Most containerized workloads need little, if any access to the underlying host filesystem. +This, paired with image-based updates, means that much of the filesystem can be immutable. +Still, there are some resources like logs, container images, and configuration files that do need to be mutable for a practically operable system. +Bottlerocket splits the difference by having some storage that is immutable and some that is mutable, using different protection mechanisms for each filesystem. +Additionally, some mutable storage in Bottlerocket only exists ephemerally and any changes will not survive a reboot. + +## Immutable Filesystem + +Bottlerocket’s root filesystem is a dm-verity device: all dm-verity devices are read-only. +In context of Bottlerocket, it means that modification of the root filesystem is not possible by userspace processes. + +### Block-level protection + +dm-verity also protects the root filesystem from unintended changes at the block level: it uses a hash tree to provide transparent integrity checking. +At a high level, dm-verity works like this: + +* A hash function calculates a cryptographic digest for each physical block, +* The same hash function calculates the combination of all the digests from the previous step, +* This repeats until a single digest remains (the “root block”). + +dm-verity saves the root block digest and compares it after every write with the new root block digest. + +{{% readfile "/includes/os/1.13.x/dm-verity-without-change.markdown" %}} + +If a physical block changes, this causes each subsequent layer to produce a different digest resulting in a different root block digest. + +{{% readfile "/includes/os/1.13.x/dm-verity-with-change.markdown" %}} + +The kernel will trigger a reboot if the root block digest changes. + +## Mutable Filesystem + +An immutable filesystem is not practical for many resources in Bottlerocket. +Files in the non-root filesystem have a variety of different accessibility requirements. +Bottlerocket uses SELinux policies to protect files in the non-root filesystem. +Unlike the immutable filesystem, SELinux allows for granular labels applied at a per-file basis, so protections vary based on the requirements of each resource. + +For example, Kubelet can write logs to `/var/log/containers` and the Bottlerocket API server can change `/etc/motd` because of specific SELinux labels. + +SELinux policies in Bottlerocket are set to enforcing, meaning they both log attempts and prevent changes to particular resources. +Also unlike the immutable filesystem, a sufficiently privileged user can alter the SELinux labels of a file or resource. + +## Ephemeral Storage + +Part of the mutable filesystem, `/etc` , does not persist through a reboot. +The use of ephemeral storage in this area provides two advantages: + +* it creates more reliable pathways for configuration changes (through the API and/or with special containers specifications like [CNI](https://github.com/containernetworking/cni) or [CSI](https://github.com/container-storage-interface/spec)), +* it makes it more difficult for attackers to make changes that persist. + +{{< on-github >}} diff --git a/content/en/os/1.22.x/concepts/shell-less-host/index.markdown b/content/en/os/1.22.x/concepts/shell-less-host/index.markdown new file mode 100644 index 00000000..01eddc41 --- /dev/null +++ b/content/en/os/1.22.x/concepts/shell-less-host/index.markdown @@ -0,0 +1,41 @@ ++++ +title = "Shell-less Host" +type = "docs" +description = "Using Linux without a shell" ++++ + +Bottlerocket images do not have an SSH server nor even a shell. +As it turns out, you don’t need one in the host operating system itself. +Bottlerocket does, however, give you out-of-band access that allows you to launch a shell from a container to explore, debug, manually update, and change settings on the host. + +## Host container out-of-band access + +Since the software doesn’t exist on the host to facilitate interactive shell sessions, it is provided through a container. +These containers are granted access to resources on the underlying host, have the required software for remote connections, and are run in the host containerd instance. + +### Control container + +The control container’s purpose is to provide a first-tier host access where you can make API calls and gain access to some host-level resources. +For `aws-k8s-*` and `aws-ecs-*` variants, the control container is on by default and remote connections are made through AWS SSM. + +The control container is also the path to enable or enter the admin container. + +### Admin container + +The admin container is designed to provide out-of-band access with elevated privileges. +On `aws-k8s-*` and `aws-ecs-*` variants, the admin container is not enabled by default but can be turned on or entered through the control container. +The best security practice is to disable the admin container and only enable it as-needed. + +The admin container has a mount to the host file system[^1], an unrestricted SELinux label as well as all of the capabilities of the control container. +Using the admin container should be rare: only used as-needed and by those required. + +## With `kubectl` on Kubernetes + +For variants designed to be used with Kubernetes, you can gain out-of-band access to a node by using `kubectl exec` and a pod spec with specific volume mounts and security contexts. +You can read more about this method in [Regaining Access to a Bottlerocket Node](../../login/regaining-access/). +This method is very similar to running the control container, but it runs in the orchestrated containerd instance instead of the host containerd instance. + +[^1]: The admin container mount for the host file system is located at `/.bottlerocket/rootfs/`. + Despite the use of `rootfs` in the path, this mount has both {{< ver-ref project="os" page="/concepts/restricted-filesystem#immutable-filesystem" >}}immutable{{< /ver-ref >}} and {{< ver-ref project="os" page="/concepts/restricted-filesystem#mutable-filesystem" >}}mutable{{< /ver-ref >}} directories. + +{{< on-github >}} diff --git a/content/en/os/1.22.x/concepts/updating-bottlerocket/index.markdown b/content/en/os/1.22.x/concepts/updating-bottlerocket/index.markdown new file mode 100644 index 00000000..1c1b36f1 --- /dev/null +++ b/content/en/os/1.22.x/concepts/updating-bottlerocket/index.markdown @@ -0,0 +1,43 @@ ++++ +title = "Updates" +type = "docs" +description = "Overview of different methods to update Bottlerocket" ++++ + +Bottlerocket is designed to be updated in an [image-based fashion](https://github.com/bottlerocket-os/bottlerocket#updates). +This means that updates are applied by downloading an image of the entire operating system to a different partition on disk, then switching to using that partition when the system is rebooted. +This is done instead of a series of individual package updates on the current operating system partition. +This is a departure from the traditional package-based Linux update model such as `apt` or `yum`, which are what you would find in Ubuntu or Amazon Linux. + +## Ways To Update + +The update method you choose depends on the [Bottlerocket variant](https://github.com/bottlerocket-os/bottlerocket#variants) you are using and your environment. + +The ways to update Bottlerocket can be classified into two main categories: _in-place updates_ and _node replacement_. +_In-place updates_ are updates that are applied to the same node (no infrastructure reprovisioning), while _node replacement_ is when you replace an existing node with a new node that is running the updated version of Bottlerocket. + +At its core, an _in-place update_ is a call to the Bottlerocket API server using `apiclient`. +The `apiclient` command can be run from the [control container](https://github.com/bottlerocket-os/bottlerocket#control-container). +There are also orchestrated systems that perform the `apiclient` calls for you: the [ECS updater](../../update/methods/in-place/#ecs) for ECS, [Brupop](../../update/methods/in-place/#brupop) for Kubernetes, and [SSM Command Documents](../../update/methods/in-place/#ssm) for both. + +The following table shows whether a given update method is an _in-place update_ or a _node replacement_. + +In-Place Updates | Node Replacement +--- | --- +[`apiclient` commands](../../update/methods/in-place/#apiclient-commands) | [EKS Console](../../update/methods/node-replacement/#eks-console) +[ECS updater](../../update/methods/in-place/#ecs) | [`eksctl`](../../update/methods/node-replacement/#eksctl) +[Brupop](../../update/methods/in-place/#brupop) | +[SSM command documents](../../update/methods/in-place/#ssm) | + +## Conclusion + +There are many ways to update Bottlerocket, including: + +- Running [`apiclient` commands](../../update/methods/in-place/#apiclient-commands) directly in the [control container](https://github.com/bottlerocket-os/bottlerocket#control-container) +- The [ECS updater](../../update/methods/in-place/#ecs) +- [Brupop](../../update/methods/in-place/#brupop), the [EKS Console](../../update/methods/node-replacement/#eks-console), and [`eksctl`](../../update/methods/node-replacement/#eksctl) on Kubernetes +- [Applying SSM Command Documents](../../update/methods/in-place/#ssm) to your nodes + +It is also possible to [lock your nodes to a specific release](../../update/locking-to-a-specific-release). + +{{< on-github >}} diff --git a/content/en/os/1.22.x/concepts/variants/index.markdown b/content/en/os/1.22.x/concepts/variants/index.markdown new file mode 100644 index 00000000..65f42768 --- /dev/null +++ b/content/en/os/1.22.x/concepts/variants/index.markdown @@ -0,0 +1,173 @@ ++++ +title="Variants" +type="docs" +description="Variants are the basis for environment-specific, ready-to-run images." ++++ + +General purpose distributions of Linux have "packages" that are delivered by a package manager. +This allows the distribution to ship a limited set of drivers, tools, and applications with the kernel; the user then adds additional packages that suits the workload after the operating system is installed. + +Bottlerocket is not a general purpose Linux distribution and intentionally doesn’t have a package manager. Instead Bottlerocket has *variants*. +Variants are pre-defined sets of drivers, tools, and applications that are tailored to a specific architecture, platform, and orchestrator (as well as a “flavor,” more on that later). +For example, there is a variant that consists of everything needed to run as a Kubernetes (orchestrator) node on an aarch64 (architecture) processor in AWS EC2 (platform). +Bottlerocket delivers the variant as a complete, ready-to-run image. + +Variants may be specific to particular versions of the orchestrator. +For example, the variant for Kubernetes 1.25 is distinct from the variant for Kubernetes 1.24. + +## Variants and images + +Variants are a construct to identify the constituent components that are used to build an image. +As a consequence, you do not directly install a variant on a machine or instance, you install an image that is a build of the components contained in the variant at a specific Bottlerocket version. + +## Variants and versions + +The version of Bottlerocket is independent of the variant: a variant will be available across many different Bottlerocket versions. +Keep in mind that Kubernetes variants are only compatible with specific versions of Kubernetes: the Kubernetes version number is distinct from the version of Bottlerocket. + +## Artifact file names + +The file name for any Bottlerocket image artifact begins with `bottlerocket` and is followed by a [kebab case](https://www.alexhyett.com/snake-case-vs-camel-case-vs-pascal-case-vs-kebab-case/#kebab-case-kebab-case) delimited list of components. +The components in the file name follow a specific order: + +```text +[platform]-[orchestrator]-[orchestrator version](optional:-[ flavour])-[Architecture]-[version]-[commit] +``` + +Example: `bottlerocket-aws-k8s-1.25-nvidia-aarch64-1.13.0...` + +|Platform|Orchestrator|Orchestrator Version|Flavor|Architecture|Bottlerocket version| +|---|---|---|---|---|---| +|`aws`|`k8s`|`1.25`|`nvidia`|`aarch64`|`1.13.0`| + +Example: `bottlerocket-vmware-k8s-1.24-x86_64-1.12...` + +|Platform|Orchestrator|Orchestrator Version|Flavor|Architecture|Bottlerocket version| +|---|---|---|---|---|---| +|`vmware`|`k8s`|`1.24`|*none*|`x86_64`|`1.12.0`| + +When referencing variants in writing, `bottlerocket-` and the commit are typically omitted for brevity. + +## Flavors + +Variants may also package in drivers for specific hardware called a “flavor.” Currently, the only flavor is 'nvidia', which adds support for Nvidia GPUs. + +## Variants, updating, & migrating + +You can update to a newer Bottlerocket version of the same variant (an ‘in-place update’). +However, you cannot update to a different variant: that is a migration (which involves replacing a node in the orchestrated cluster). + +A few examples: + +|Original|New|In-Place Update|Node Replacement / Migration|Explaination| +|---|---|---|---|---| +|aws-k8s-1.24-x86_64-**1.12.0**|aws-k8s-1.24-x86_64-**1.13.0**|✓|✓|This is moving between versions of the same variant, so this can be accomplished by an update| +|aws-k8s-**1.24**-x86_64-1.12.0|aws-k8s-**1.25**-x86_64-1.12.0|✗|✓|The orchestrator version is part of the variant, so this is a migration.| +|aws-k8s-**1.24**-x86_64-**1.12.0**|aws-k8s-**1.25**-x86_64-**1.13.0**|✗|✓|Both the Bottlerocket version and the variant are changing so this must be accomplished by a migration.| +|aws-k8s-1.24-x86_64-1.13.0|aws-k8s-1.24-**nvidia**-x86_64-1.13.0|✗|✓|The flavor is part of the variant, so this change must be accomplished by a migration| +|aws-**ecs-2**-x86_64-1.15.0|aws-**k8s-1.28**-x86_64-1.15.0|✗|✗|The orchestrator has changed. The cluster must be rebuilt.| + +If you are using a node replacement strategy, the distinction between migrating and updating is less important as any change is effectively a migration. + +## Software inventory and security advisories + +Since Bottlerocket doesn’t use a package manager, keeping track of the software delivered as part of a variant is a little different. +Additionally, the concept of a ‘package’ is only relevant as a part of the build process. +In the course of running Bottlerocket, you probably want to keep track of what specific software and versions you are using as well as understand how this software relates to known vulnerabilities. + +{{% alert title="Note" color="success" %}} +The best patching strategy for Bottlerocket is to always update to the most recent release. +Since packages are only used at build-time and the packages cannot mutate, the inventory will never change for a given version and variant. +Updating to the most recent version will patch all packages. +{{% /alert %}} + +Bottlerocket provides information to both understand the software included in a variant and how it connects to published security advisories. + +### Software Inventory + +The Bottlerocket build process generates an `applications.json` file at `/var/lib/bottlerocket/inventory/` on the host file system. This JSON file contains objects that represent a build-time package. The `applications.json` file structure is as follows: + +```json +{ + "Content": [ + { + "Name": <name string>, + "Publisher": "Bottlerocket", + "Version": <version as string>, + "Release": <build ID as string>, + "InstalledTime": <ISO 8601 date as string>, + "ApplicationType": "Unspecified", + "Architecture": <architecture as string>, + "Url": <url as string>, + "Summary": <description as string + }, + ... + ] +} +``` + +`Publisher` and `ApplicationType` are “Bottlerocket” and “Unspecified” (respectively) for all packages across all variants. +`Version`, `Release`, `InstalledTime`, and `Architecture` are a consistent value for each object in the `Content` array in a given release as they represent data about the build and variant of Bottlerocket, not individual packages. + +### Security Advisories + +Bottlerocket publishes security advisories on [the repo’s GitHub’s Security tab](https://github.com/bottlerocket-os/bottlerocket/security/advisories) and a gzipped `updateinfo.xml` file at advisories.bottlerocket.aws (make sure you follow redirects: e.g. use `curl -LO https://advisories.bottlerocket.aws/updateinfo.xml.gz`). + +Both places contain approximately the same information but in different formats. +The security advisories match with the package information provided in the `applications.json` file. +For example, take the following snippet from `applications.json`: + +```json +{ + "Content": [ + ... + { + "Name": "kernel-6.1", + "Publisher": "Bottlerocket", + "Version": "1.16.1", + "Release": "763f6d4c", + "InstalledTime": "2023-11-09T08:15:34Z", + "ApplicationType": "Unspecified", + "Architecture": "x86_64", + "Url": "https://www.kernel.org/", + "Summary": "The Linux kernel" + } + ... + ] +} + +``` + +And a snippet from the `updateinfo.xml` file (which relates to [GHSA-868r-x68r-5c5p on GitHub](https://github.com/bottlerocket-os/bottlerocket/security/advisories/GHSA-868r-x68r-5c5p), note the representation of the similar information). + +```xml +<updates> + ... + <update author="etungsten" from="etungsten" status="final" type="security" version="1.4"> + <id>GHSA-868r-x68r-5c5p</id> + <title>kernel CVE-2023-5345</title> + <issued date="2023-11-13T22:21:51Z"/> + <updated date="2023-11-13T22:21:51Z"/> + <severity>medium</severity> + <description>A flaw was found in the SMB client component in the Linux kernel. In case of an error in smb3_fs_context_parse_param, ctx->password was freed, but the field was not set to NULL, potentially leading to a use-after-free vulnerability. This flaw allows a local user to crash or potentially escalate their privileges on the system.</description> + <references> + <reference href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-5345" id="CVE-2023-5345" type="cve"/> + <reference href="https://github.com/bottlerocket-os/bottlerocket/security/advisories/GHSA-868r-x68r-5c5p" id="GHSA-868r-x68r-5c5p" type="ghsa"/> + </references> + <pkglist> + <collection short="bottlerocket"> + <name>Bottlerocket</name> + <package arch="x86_64" name="kernel-6.1" version="1.16.1" release="0" epoch="0"/> + <package arch="aarch64" name="kernel-6.1" version="1.16.1" release="0" epoch="0"/> + </collection> + </pkglist> + </update> + ... +</updates> +``` + +If you are building a script to determine if your Bottlerocket nodes need patching, evaluate the `.Content.Name`, `.Content.Version`, and `.Content.Architecture` from the object in `applications.json` and compare these values with the `./updates/update/pkglist/collection/package[@name]`, `./updates/update/pkglist/collection/package[@version]`, and `./updates/update/pkglist/collection/package[@arch]` in `updateinfo.xml`. + +Human beings should use the GitHub security advisories compared to the {{< ver-ref project="os" page="/version-information/packages-by-variant" >}} Packages by Variant list{{</ ver-ref >}} (or use other tools). + +{{< on-github >}} diff --git a/content/en/os/1.22.x/install/_index.markdown b/content/en/os/1.22.x/install/_index.markdown new file mode 100644 index 00000000..f8a5e838 --- /dev/null +++ b/content/en/os/1.22.x/install/_index.markdown @@ -0,0 +1,12 @@ ++++ +title="Install" +type="docs" +description="How to install Bottlerocket" +weight=50 +body_class="suppress-additional-index" ++++ +{{< hide-and-re-highlight-menu link_url="/en/os/%s/install/quickstart/" >}} + +### AWS Quickstart Install Guides + +{{< redirect-list actual="/os/%s/install/quickstart/aws/" >}} diff --git a/content/en/os/1.22.x/install/quickstart/_index.markdown b/content/en/os/1.22.x/install/quickstart/_index.markdown new file mode 100644 index 00000000..9761fe49 --- /dev/null +++ b/content/en/os/1.22.x/install/quickstart/_index.markdown @@ -0,0 +1,5 @@ ++++ +title="Quickstarts" +type="docs" +description="Getting started quickly with Bottlerocket" ++++ diff --git a/content/en/os/1.22.x/install/quickstart/aws/_index.markdown b/content/en/os/1.22.x/install/quickstart/aws/_index.markdown new file mode 100644 index 00000000..a9c568ab --- /dev/null +++ b/content/en/os/1.22.x/install/quickstart/aws/_index.markdown @@ -0,0 +1,5 @@ ++++ +title="AWS" +type="docs" +description="Quickstarts for AWS" ++++ diff --git a/content/en/os/1.22.x/install/quickstart/aws/ecs/index.markdown b/content/en/os/1.22.x/install/quickstart/aws/ecs/index.markdown new file mode 100644 index 00000000..c39447fd --- /dev/null +++ b/content/en/os/1.22.x/install/quickstart/aws/ecs/index.markdown @@ -0,0 +1,175 @@ ++++ +title="Amazon ECS" +type="docs" +description="How to get started with Bottlerocket on Amazon ECS" ++++ + +{{< hide-and-re-highlight-menu link_url="/en/os/%s/install/quickstart/" depad="true" >}} +{{< hide-and-re-highlight-menu link_url="/en/os/%s/install/quickstart/aws/" depad="true" >}} +{{< breadcrumb-remove link_url="/en/os/%s/install/quickstart/">}} +{{< breadcrumb-remove link_url="/en/os/%s/install/quickstart/aws/">}} + +When registering EC2 instances as capacity for an ECS cluster, you can use Bottlerocket as the operating system for these instances. +If you want to understand the AWS console workflow, start with the [video _Amazon ECS: Using Bottlerocket_.](#aws-console-quickstart) +Otherwise, read the [AWS CLI Quickstart](#aws-cli-quickstart) or the pattern [Amazon ECS cluster on Bottlerocket](https://containersonaws.com/pattern/ecs-ec2-bottlerocket-cluster) which outlines how to start Bottlerocket with [SAM CLI](https://docs.aws.amazon.com/serverless-application-model/). + +## AWS CLI Quickstart + +This quickstart uses a number of techniques/tools like `jq` and environment variables to make the quickstart experience as simple and straightforward as possible. +These tools are not absolutely necessary to use Bottlerocket on ECS. + +### Prerequisites + +There are some preliminary tasks to complete in order to use ECS. +You need to both set up your AWS account for use with ECS and have an IAM role for ECS configured: + +- Complete the steps in [Setting up with Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/get-set-up-for-amazon-ecs.html). +- Ensure that the AWS user you use for this quickstart has the has the [AmazonECS_FullAccess](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonECS_FullAccess) policy attached (scope down as needed for your production requirements). +- Ensure that you have an [IAM role created](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html#instance-iam-role-create) named `ecsInstanceRole` and configured according to the AWS ECS Developer Guide. + - Be sure to follow _both_ the [AWS Console steps](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html#instance-iam-role-create) as well as the AWS CLI steps (section labeled "To create the ecsInstanceRole role (AWS CLI)" - the AWS CLI steps cover an important aspect: adding an Instance Profile to the role) + +In this quickstart, the following software is used to interact with AWS and parse the responses received: + +- [`aws-cli`](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions): Used to interact with AWS services. +- [`jq`](https://stedolan.github.io/jq/download/): Used for parsing response data from `aws-cli`. + +### Create a Cluster + +First, set some environment variables to use throughout this quickstart: + +```bash +export AWS_REGION=us-west-2 +export ECS_CLUSTER_NAME=bottlerocket-quickstart-ecs +export ECS_INSTANCE_ROLE_NAME=ecsInstanceRole +``` + +Then, create an ECS cluster with the AWS CLI as follows: + +```bash +aws ecs --region $AWS_REGION create-cluster --cluster-name $ECS_CLUSTER_NAME +``` + +You should see output confirming your new cluster similar to the following: + +```json +{ + "cluster": { + "clusterArn": "arn:aws:ecs:us-west-2:xxxxxxxxxxxx:cluster/bottlerocket-quickstart-ecs", + "clusterName": "bottlerocket-quickstart-ecs", + "status": "ACTIVE", + "registeredContainerInstancesCount": 0, + "runningTasksCount": 0, + "pendingTasksCount": 0, + "activeServicesCount": 0, + "statistics": [], + "tags": [], + "settings": [ + { + "name": "containerInsights", + "value": "disabled" + } + ], + "capacityProviders": [], + "defaultCapacityProviderStrategy": [] + } +} +``` + +### Launching Instances Into Your Cluster + +After your ECS cluster is created, you can add instances to it. + +#### Enabling SSM + +Enable SSM on the `ecsInstanceRole` IAM role by attaching the `AmazonSSMManagedInstanceCore` managed policy to the role: + +```bash +aws iam attach-role-policy \ + --role-name $ECS_INSTANCE_ROLE_NAME \ + --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore +``` + +#### Connecting To Your Cluster + +In order to communicate with ECS, configure each node with the name of the cluster. +The following command will create a file named `quickstart-ecs-user-data.toml` with the appropriate contents: + +```bash +cat << EOF > quickstart-ecs-user-data.toml +[settings.ecs] +cluster = "$ECS_CLUSTER_NAME" +EOF +``` + +#### Launch + +Now you can add Bottlerocket instances to your ECS cluster! +There are some values that you need to set in your environment first such as the Subnet ID, Bottlerocket AMI ID, and ECS Instance Profile Name. +You can get the information you need using the AWS CLI: + +```bash +export ECS_VPC_ID=$(aws ec2 describe-vpcs \ + --region $AWS_REGION \ + --filters=Name=isDefault,Values=true \ + | jq --raw-output '.Vpcs[].VpcId') +export ECS_SUBNET_ID=$(aws ec2 describe-subnets \ + --region $AWS_REGION \ + --filter=Name=vpc-id,Values=$ECS_VPC_ID \ + | jq --raw-output '.Subnets[0] | {id: .SubnetId, public: .MapPublicIpOnLaunch, az: .AvailabilityZone} | .id') +export BOTTLEROCKET_AMI_ID="resolve:ssm:/aws/service/bottlerocket/aws-ecs-2/x86_64/latest/image_id" +export ECS_INSTANCE_PROFILE_NAME=$(aws iam list-instance-profiles-for-role \ + --role-name $ECS_INSTANCE_ROLE_NAME \ + --query "InstanceProfiles[*].InstanceProfileName" \ + --output text) +``` + +Then launch an instance into your cluster: + +```bash +aws ec2 run-instances \ + --subnet-id $ECS_SUBNET_ID \ + --image-id $BOTTLEROCKET_AMI_ID \ + --instance-type m5.large \ + --region $AWS_REGION \ + --tag-specifications "ResourceType=instance,Tags=[{Key=ecs-cluster,Value=$ECS_CLUSTER_NAME}]" \ + --user-data file://quickstart-ecs-user-data.toml \ + --iam-instance-profile Name=$ECS_INSTANCE_PROFILE_NAME +``` + +Once the instance launches, you should be able to run tasks on your Bottlerocket instance using either the ECS API or web console. + +### Confirming Your Instances Are Running + +To confirm that nodes are running in your cluster, you can run the following command to list your ECS cluster nodes: + +```bash +aws ec2 describe-instances \ + --no-cli-pager \ + --filters "Name=tag:ecs-cluster,Values=$ECS_CLUSTER_NAME" \ + --query "Reservations[*].Instances[*].{PrivateDNS:PrivateDnsName,InstanceID:InstanceId,Cluster:Tags[?Key=='ecs-cluster']|[0].Value,State:State.Name}" \ + --output=table +``` + +You should see output that contains a column similar to the following: + +```bash + +----------------------+ +... | InstanceID | ... + +----------------------+ + | i-04c2b2087... | + +----------------------+ +``` + +### Interacting With Your Cluster + +To confirm in depth that an instance is running Bottlerocket, save the instance ID and follow the steps in the [Host Containers Quickstart](../host-containers). + +Congratulations! +You now have a Bottlerocket cluster running on ECS. + +{{< on-github >}} + +## AWS Console Quickstart + +If you want to start an ECS cluster using EC2 nodes running Bottlerocket, the follow video provides a high level walk through. +{{< youtube c4hhZZwSrP0 >}} diff --git a/content/en/os/1.22.x/install/quickstart/aws/host-containers/index.markdown b/content/en/os/1.22.x/install/quickstart/aws/host-containers/index.markdown new file mode 100644 index 00000000..c7d44cab --- /dev/null +++ b/content/en/os/1.22.x/install/quickstart/aws/host-containers/index.markdown @@ -0,0 +1,107 @@ ++++ +title="Host Containers" +type="docs" +description="How to interact with a Bottlerocket node through Host Containers" ++++ + +{{< hide-and-re-highlight-menu link_url="/en/os/%s/install/quickstart/" depad="true" >}} +{{< hide-and-re-highlight-menu link_url="/en/os/%s/install/quickstart/aws/" depad="true" >}} +{{< breadcrumb-remove link_url="/en/os/%s/install/quickstart/">}} +{{< breadcrumb-remove link_url="/en/os/%s/install/quickstart/aws/">}} + +## Prerequisites + +- An AWS EC2 Instance ID (begins with `i-`) of a Bottlerocket instance +- [`aws-cli`](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions): Used to interact with AWS services. +- [SSM Session Manager Plugin for AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html): Used to enter SSM sessions on Bottlerocket nodes through the AWS CLI. + +## Interacting With a Bottlerocket Node Through Host Containers + +Run the following command to enter an SSM session on the node: + +```bash +aws ssm start-session --target INSTANCE_ID +``` + +Replace `INSTANCE_ID` with the instance ID you picked earlier. + +Entering the SSM session will place you in the control container. + +You should see output similar to the following: + +```bash + Welcome to Bottlerocket's control container! + ╱╲ + ╱┄┄╲ This container gives you access to the Bottlerocket API, + │▗▖│ which in turn lets you inspect and configure the system. + ╱│ │╲ You'll probably want to use the `apiclient` tool for that; + │╰╮╭╯│ for example, to inspect the system: + ╹╹ + apiclient -u /settings + +You can run `apiclient --help` for usage details, and check the main +Bottlerocket documentation for descriptions of all settings and examples of +changing them. + +If you need to debug the system further, you can use the admin container. The +admin container has more debugging tools installed and allows you to get root +access to the host. The easiest way to get started is like this, which enables +and enters the admin container using apiclient: + + enter-admin-container + +You can also access the admin container through SSH if you have network access. +Just enable the container like this, then SSH to the host: + + enable-admin-container + +You can disable the admin container like this: + + disable-admin-container + +[ssm-user@control]$ +``` + +Use `apiclient` to get the Bottlerocket host Message Of The Day (MOTD): + +```bash +apiclient get settings.motd +``` + +You should see output similar to the following: + +```bash +{ + "settings": { + "motd": "Hello from eksctl!" + } +} +``` + +### Exploring the Admin Container + +From the control container, you can enter the admin container: + +```bash +enter-admin-container +``` + +Then, check the `/etc/os-release` file contents from the _Bottlerocket host filesystem_, mounted at `/.bottlerocket/rootfs/`. +You should see something similar to the following: + +{{< tabpane text=true right=true >}} + {{< tab header="Orchestrator:" disabled=true />}} + {{< tab header="EKS" >}} +[root@admin]# cat /.bottlerocket/rootfs/etc/os-release +{{< os-release-example orchestrator="k8s" build_id="6ef1139f" >}} + {{< /tab >}} + {{< tab header="ECS" >}} +[root@admin]# cat /.bottlerocket/rootfs/etc/os-release +{{< os-release-example orchestrator="ecs" build_id="32e9bb46" >}} + {{< /tab >}} +{{< /tabpane >}} + +Congratulations! +You have successfully navigated a Bottlerocket system through the control and admin containers. + +{{< on-github >}} diff --git a/content/en/os/1.22.x/install/quickstart/aws/k8s/index.markdown b/content/en/os/1.22.x/install/quickstart/aws/k8s/index.markdown new file mode 100644 index 00000000..4b7b3cd5 --- /dev/null +++ b/content/en/os/1.22.x/install/quickstart/aws/k8s/index.markdown @@ -0,0 +1,126 @@ ++++ +title="Amazon EKS" +type="docs" +description="How to get started with Bottlerocket on Amazon EKS" ++++ + +{{< hide-and-re-highlight-menu link_url="/en/os/%s/install/quickstart/" depad="true" >}} +{{< hide-and-re-highlight-menu link_url="/en/os/%s/install/quickstart/aws/" depad="true" >}} +{{< breadcrumb-remove link_url="/en/os/%s/install/quickstart/">}} +{{< breadcrumb-remove link_url="/en/os/%s/install/quickstart/aws/">}} + +## Prerequisites + +In order to set up a Bottlerocket cluster on EKS, you will need the latest versions of the following tools installed: + +- [`eksctl`](https://eksctl.io/): Used to create EKS clusters. +- [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl): Used to interact with resources within a Kubernetes cluster. +- [`aws-cli`](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions): Used to interact with AWS services. +- [SSM Session Manager Plugin for AWS CLI](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html): Used to enter SSM sessions on Bottlerocket nodes through the AWS CLI. + +## Cluster Setup + +There are two main steps to setting up an EKS cluster: creating the configuration file and applying the configuration file using `eksctl`. + +### Cluster Configuration File + +`eksctl` can use a YAML configuration file to create an EKS cluster. +First, set some environment variables: + +- `AWS_REGION`: AWS region to create the cluster in. +- `K8S_VERSION`: Kubernetes version to use for the cluster. +- `EKS_CLUSTER_NAME`: Name of the EKS cluster to create. + +```bash +export AWS_REGION="us-west-2" +export K8S_VERSION="1.25" +export EKS_CLUSTER_NAME="bottlerocket-quickstart-eks" +``` + +The following command (on Linux and macOS) will create an example configuration file named `bottlerocket-quickstart-eks.yaml` that specifies a cluster with 3 Bottlerocket nodes: + +```bash +cat << EOF > bottlerocket-quickstart-eks.yaml +--- +apiVersion: eksctl.io/v1alpha5 +kind: ClusterConfig + +metadata: + name: $EKS_CLUSTER_NAME + region: $AWS_REGION + version: "$K8S_VERSION" + +nodeGroups: + - name: ng-bottlerocket-quickstart + instanceType: m5.large + desiredCapacity: 3 + amiFamily: Bottlerocket + iam: + attachPolicyARNs: + - arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy + - arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy + - arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly + - arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore + bottlerocket: + settings: + motd: "Hello from eksctl!" +EOF +``` + +On Windows, you will need to create this file in a text editor and replace `$EKS_CLUSTER_NAME`, `$AWS_REGION`, and `$K8S_VERSION` with your desired values. +The contents to copy are _between_ the `cat << EOF > bottlerocket-quickstart-eks.yaml` and `EOF` lines. + +### Cluster Creation + +Start the cluster creation process using the configuration file you created in the last step (`bottlerocket-quickstart-eks.yaml` in this example): + +```bash +eksctl create cluster --config-file ./bottlerocket-quickstart-eks.yaml +``` + +Get a cup of coffee ☕️, it will take a while to provision your control plane and cluster nodes. + +## Confirm Your Cluster is Running + +To confirm that Bottlerocket nodes are running in your cluster, you can run the following command to list your cluster nodes and what operating system they are running: + +```bash +kubectl get nodes -o=wide +``` + +You should see output that contains a column similar to the following: + +```bash +... OS-IMAGE ... + Bottlerocket OS 1.12.0 (aws-k8s-1.25) + Bottlerocket OS 1.12.0 (aws-k8s-1.25) + Bottlerocket OS 1.12.0 (aws-k8s-1.25) +``` + +Next, get an instance ID from any one of the nodes in the cluster (remember that `$EKS_CLUSTER_NAME` is set to the name of your EKS cluster): + +```bash +aws ec2 describe-instances --no-cli-pager --filters "Name=tag:aws:eks:cluster-name,Values=$EKS_CLUSTER_NAME" --query "Reservations[*].Instances[*].{PrivateDNS:PrivateDnsName,InstanceID:InstanceId,Cluster:Tags[?Key=='aws:eks:cluster-name']|[0].Value,State:State.Name}" --output=table +``` + +You should see output that contains a column similar to the following: + +```bash + +----------------------+ +... | InstanceID | ... + +----------------------+ + | i-04c2b2087... | + | i-0e61e2b0a... | + | i-022aca952... | + +----------------------+ +``` + +## Interacting With Your Cluster + +To confirm in depth that an instance is running Bottlerocket, pick an instance ID and follow the steps in the [Host Containers Quickstart](../host-containers). +Any of the instance IDs listed for the `bottlerocket-quickstart-eks` cluster should work. + +Congratulations! +You now have a Bottlerocket cluster running on EKS. + +{{< on-github >}} diff --git a/content/en/os/1.22.x/login/_index.markdown b/content/en/os/1.22.x/login/_index.markdown new file mode 100644 index 00000000..06f50145 --- /dev/null +++ b/content/en/os/1.22.x/login/_index.markdown @@ -0,0 +1,6 @@ ++++ +title="Login" +type="docs" +description="Accessing Bottlerocket" +weight="50" ++++ diff --git a/content/en/os/1.22.x/login/regaining-access/index.markdown b/content/en/os/1.22.x/login/regaining-access/index.markdown new file mode 100644 index 00000000..4aa16d7e --- /dev/null +++ b/content/en/os/1.22.x/login/regaining-access/index.markdown @@ -0,0 +1,246 @@ ++++ +title = "Regaining Access to a Bottlerocket Node" +description = "How to Regain Access to a Bottlerocket Node After Disabling the Control and Admin Containers" +type = "docs" ++++ + +## Introduction + +The standard way to access a shell on a Bottlerocket node is to use either the admin container or the control container. +In some cases where both the admin and control containers are disabled, it is still possible to regain access to a Bottlerocket node. + +## Solution Description + +In general, the solution is to mount the [API client](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/apiclient/README.md) and API socket into a container on the Bottlerocket node and use the API client to re-enable the admin container, control container, or both. + +{{% alert title="Warning" color="warning" %}} +The solutions on this page provide a minimal overview. +It involves mounting critical resources into containers with elevated privileges. +Use carefully, only run as long as necessary, and clean up afterwards. +{{% /alert %}} + +## Steps to Regain Access on Kubernetes + +1. Create a pod that mounts the API client and API socket with the correct SELinux labels. + + Some notes on the Pod spec below: + + - The API socket has a specific SELinux label applied to it (`system_u:object_r:api_socket_t:s0`) that restricts access to the `api_socket_t` type and `s0` sensitivity level. + To learn more about the SELinux labels in Bottlerocket, see the [Security Guidance documentation](https://github.com/bottlerocket-os/bottlerocket/blob/develop/SECURITY_GUIDANCE.md#limit-use-of-privileged-selinux-labels). + - In order to access the API socket, the Pod must have compatible SELinux options applied to it. + - Use the `control_t` type (has access to `api_socket_t`) and `s0` sensitivity level to allow the container to access the API socket. + - The entrypoint for the container is `sleep infinity` so that the container stays running for you to `exec` into. + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: regain-access +spec: + containers: + - name: regain-access + image: fedora + command: ["sleep", "infinity"] + volumeMounts: + - mountPath: /usr/bin/apiclient + name: apiclient + readOnly: true + - mountPath: /run/api.sock + name: apiserver-socket + securityContext: + seLinuxOptions: + level: s0 + role: system_r + type: control_t + user: system_u + volumes: + - name: apiclient + hostPath: + path: /usr/bin/apiclient + type: File + - name: apiserver-socket + hostPath: + path: /run/api.sock + type: Socket +``` + +2. `exec` into the container. + +```bash +kubectl exec -it regain-access -- bash +``` + +3. Use `apiclient` to enable the [admin container](https://github.com/bottlerocket-os/bottlerocket-admin-container#authenticating-with-the-admin-container), [control container](https://github.com/bottlerocket-os/bottlerocket-control-container#connecting-to-aws-systems-manager-ssm), or both. + +Admin container: + +```bash +apiclient set host-containers.admin.enabled=true +``` + +Control container: + +```bash +apiclient set host-containers.control.enabled=true +``` + +4. Exit the shell and delete the `regain-access` pod. +The Bottlerocket node should be accessible again. + +## Steps to Regain Access on ECS + +You can regain access to a Bottlerocket node using ECS Exec starting in v1.14.0. + +This solution requires the use of [ECS Exec](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html) and [associated IAM permissions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html#ecs-exec-enabling-and-using). +The instructions for proper IAM permissions to enable ECS Exec can be found in the AWS blog post [Using Amazon ECS Exec to access your containers on AWS Fargate and Amazon EC2](https://aws.amazon.com/blogs/containers/new-using-amazon-ecs-exec-access-your-containers-fargate-ec2/). + +1. First, you will need to setup a few environment variables. `CONTAINER_NAME` and `SERVICE_NAME` are not specifically relevant, but they need to be consistent across multiple files and commands. + +```shell +export CONTAINER_NAME="regain-access" +export CLUSTER=<your cluster name> +export SERVICE_NAME="regain-access" +export TASK_ROLE_ARN=<the ARN for your IAM task role> +``` + +2. Now you will create a task definition that will mount the Bottlerocket `apiclient` and the related socket path as well as giving it the proper SELinux labels. +Piping `cat` to a file to generate the task definition[^1] JSON will allow for interpolating the variables into the final file. + +```shell +cat << EOF > task-def.json +{ + "family": "regain-access", + "containerDefinitions": [ + { + "name": "${CONTAINER_NAME}", + "image": "fedora", + "cpu": 0, + "memoryReservation": 300, + "portMappings": [], + "essential": true, + "command": ["sleep", "infinity"], + "environment": [], + "mountPoints": [ + { + "sourceVolume": "apiclient", + "containerPath": "/usr/bin/apiclient", + "readOnly": true + }, + { + "sourceVolume": "apisocket", + "containerPath": "/run/api.sock" + } + ], + "volumesFrom": [], + "dockerSecurityOptions": [ + "label:user:system_u", + "label:role:system_r", + "label:type:control_t", + "label:level:s0" + ] + } + ], + "taskRoleArn": "${TASK_ROLE_ARN}", + "volumes": [ + { + "name": "apiclient", + "host": { + "sourcePath": "/usr/bin/apiclient" + } + }, + { + "name": "apisocket", + "host": { + "sourcePath": "/run/api.sock" + } + } + ], + "requiresCompatibilities": [ + "EC2" + ], + "cpu": "1024", + "memory": "1024" +} +EOF +``` + +3. The following will take the file from the previous step and use the AWS CLI to register the task definition. +Running the AWS CLI command without any options, will produce a large amount of JSON that is hard to sift through. Instead, use the `query` parameter to get only what you need, format the output text and skip the pager. +Then take the results and put it into another environment variable. Any errors will be visible as a response in standard output. + +```shell +export REGAIN_ACCESS_ARN=$(aws ecs register-task-definition \ + --cli-input-json file://task-def.json \ + --query "taskDefinition.taskDefinitionArn" \ + --output text --no-cli-pager) +``` + +4. As a confidence check, `echo` the environment variable to make sure it matches what you’d expect from an ARN. + +```shell +echo $REGAIN_ACCESS_ARN +``` + +5. With the task definition ARN stored in the environment variable, you can create the service. You may want to limit the deployment of this service to specific instance(s). + +```shell +aws ecs create-service --cluster "${CLUSTER}" \ + --task-definition "${REGAIN_ACCESS_ARN}" \ + --service-name "${SERVICE_NAME}" \ + --desired-count 1 \ + --launch-type EC2 \ + --enable-execute-command \ + --no-cli-pager +``` + +6. The subsequent step will need the task ARN which is not included in the response from the `create-service` call; the command below will grab all the task ARNs from the service name and cluster you specified earlier (which should only be one), filter the response with the `query` parameter, and use an environment variable to store only what you need. +Wait a few seconds after the previous step and run the following command: + +```shell +export TASK_ARN=$(aws ecs list-tasks --cluster ${CLUSTER} \ + --service-name ${SERVICE_NAME} \ + --no-cli-pager \ + --output text \ + --query "taskArns[0]") +``` + +7. Again, do a confidence check to ensure the environment variable looks as you’d expect. + +```shell +echo $TASK_ARN +``` + +8. Finally, you can use `execute-command` to open an interactive shell with the container. + +```shell +aws ecs execute-command --cluster "${CLUSTER}" \ + --task "${TASK_ARN}" \ + --container "${CONTAINER_NAME}" \ + --interactive \ + --command /bin/bash" +``` + +9. You should see a message like this followed by an interactive shell + +```shell +Starting session with SessionId: ecs-execute-command-<some hex values> +``` + +10. In the shell use `apiclient` to enable the [admin container](https://github.com/bottlerocket-os/bottlerocket-admin-container#authenticating-with-the-admin-container), [control container](https://github.com/bottlerocket-os/bottlerocket-control-container#connecting-to-aws-systems-manager-ssm), or both. + + +```bash +# Admin container +apiclient set host-containers.admin.enabled=true +``` + +```bash +# Control container: +apiclient set host-containers.control.enabled=true +``` + +11. Now you should be able to access your admin or control container using SSM. You no longer need anything created in this how-to, feel free to delete the service and IAM policies. + +[^1]: This task definition uses `fedora` as an image, but almost any base image with a shell will also work. + +{{< on-github >}} diff --git a/content/en/os/1.22.x/update/_index.markdown b/content/en/os/1.22.x/update/_index.markdown new file mode 100644 index 00000000..c5adc61e --- /dev/null +++ b/content/en/os/1.22.x/update/_index.markdown @@ -0,0 +1,6 @@ ++++ +title="Updating" +type="docs" +description="Details on moving to newer versions of Bottlerocket" +weight="50" ++++ diff --git a/content/en/os/1.22.x/update/guidelines/index.markdown b/content/en/os/1.22.x/update/guidelines/index.markdown new file mode 100644 index 00000000..94fec08b --- /dev/null +++ b/content/en/os/1.22.x/update/guidelines/index.markdown @@ -0,0 +1,64 @@ ++++ +title="Guidelines for Updating In-Place" +type="docs" +description="Moving to newer versions without replacing nodes" ++++ + +## Introduction + +There are some guidelines and considerations to keep in mind when updating your Bottlerocket nodes _in-place_. +Some movements between versions are updates, some are not updates, and there are some caveats you may need to consider based on the history of the project. + +## Update Paths + +Certain movements between releases of Bottlerocket are accessible through an _in-place_ update path. + +### Between Minor or Patch Versions of the Same Variant + +With the exception of moving between major versions and a [caveat discussed below](#too-many-releases-between-versions), it is possible to update _in-place_ from one released version of a variant to another released version of the same variant. +In particular, the following update paths work: + +- Minor version to minor version (e.g. `1.10.0` to `1.11.0`) +- Patch version to patch version (e.g. `1.9.1` to `1.9.2`) +- Minor version to patch version (e.g. `1.10.0` to `1.10.1`) +- Patch version to minor version (e.g. `1.10.1` to `1.11.0`) + +Furthermore, skipping minor or patch versions of the same variant is allowed. +Bottlerocket runs all update [settings migrations](https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/api/migration#data-store-migration) between the initial and target versions in sequence if a version is skipped. +So, for the `1.10.1` to `1.12.0` example, the [settings migrations](https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/api/migration#data-store-migration) from `1.11.0` and `1.11.1` are run as part of the update to `1.12.0`. + +## Caveats and Limits + +You may need to consider the following caveats when updating your Bottlerocket nodes. + +### Too Many Releases Between Versions + +There is a [known issue](https://github.com/bottlerocket-os/bottlerocket/issues/2589) where Bottlerocket boots into a "no space left on device" error when updating between versions that are "too far apart" (too many intermediate releases -- minor or patch -- between the initial and target). +For example, updating between versions `1.7.2` and `1.11.0` fails in this way. + +The workaround is to update Bottlerocket only a couple releases at a time from your starting point, using version locking, until you reach the desired state. + +This caveat is discussed in detail in [issue 2589](https://github.com/bottlerocket-os/bottlerocket/issues/2589). + +Specifically, there is [an important note regarding updating to the latest versions of Bottlerocket](https://github.com/bottlerocket-os/bottlerocket/issues/2589#issuecomment-1344941291). + +### Updates vs. Other Movements + +There are some movements between releases of Bottlerocket that are not accessible through an update path. +Such movements are described below. + +#### Between Major Versions + +It is not possible to update _in-place_ from one major version to another. +Major versions are considered breaking changes. + +In order to move between major versions, node replacement with the desired release is necessary. + +#### Across Different Variants + +It is not possible to update _in-place_ from one variant to another. +For example, moving from an `aws-k8s-1.22` variant to an `aws-k8s-1.23` variant is not an update path. + +In order to move between Kubernetes versions (or any variant), you must replace the nodes in your cluster with new nodes running the desired variant. + +{{< on-github >}} diff --git a/content/en/os/1.22.x/update/locking-to-a-specific-release/index.markdown b/content/en/os/1.22.x/update/locking-to-a-specific-release/index.markdown new file mode 100644 index 00000000..5c5c0b60 --- /dev/null +++ b/content/en/os/1.22.x/update/locking-to-a-specific-release/index.markdown @@ -0,0 +1,75 @@ ++++ +title = "Locking to a Specific Release" +type = "docs" +description = "How to lock a Bottlerocket node to a specific release version" ++++ + +Locking your Bottlerocket nodes to a specific release is possible using the Bottlerocket Settings API. + +_A quick explanation of the `apiclient` command used below:_ + +Two settings are set: `updates.version-lock` and `updates.ignore-waves`. + +- `updates.version-lock`: which version of Bottlerocket to lock to when `apiclient` checks for updates. +- `updates.ignore-waves`: ignore the [update waves behavior](https://github.com/bottlerocket-os/bottlerocket/tree/develop/sources/updater/waves) and update the Bottlerocket node immediately. + +To create an SSM Command Document, follow the steps in the [AWS Systems Manager User Guide: "Create an SSM document (console)"](https://docs.aws.amazon.com/systems-manager/latest/userguide/create-ssm-console.html). +Remember to select "YAML" in the "Content" box, since the [SSM Command Document below](#ssm-command-document-lock-to-a-specific-release) is formatted in YAML. + +## SSM Command Document: Lock to a Specific Release + +The following SSM Command Document is referred to in this documentation as `version-lock-bottlerocket-node`: + +```yaml +--- +schemaVersion: "2.2" +description: "Lock a Bottlerocket host to a specific version via the Bottlerocket Settings API" +parameters: + TargetVersion: + type: "String" + description: "The target version of Bottlerocket to lock to (e.g. 1.12.0)" +mainSteps: + - name: "setTargetVersion" + action: "aws:runShellScript" + inputs: + timeoutSeconds: '20' + runCommand: + - "apiclient set updates.version-lock=\"{{ TargetVersion }}\" updates.ignore-waves=true" +``` + +You should now have the above SSM Command Document available in the SSM "Owned by me" tab in the "Documents" section of the SSM Console. + +## Applying a Version Lock + +In order to apply a version lock using SSM, follow these steps: + +1. First, tell your Bottlerocket nodes that you want them to lock to a specific version. + - Apply the [`version-lock-bottlerocket-node` SSM Command Document previously described](#ssm-command-document-lock-to-a-specific-release). + - In the "Command parameters" section of the Run Command page, remember to specify the full version of Bottlerocket that you want to lock to (e.g. `1.12.0`, not `1.12`). + - If you are using EKS, select all nodes in a given EKS cluster by specifying an instance tag in the "Target selection" section of the page. + Specify `eks:cluster-name` as the tag key, with the tag value set to your cluster name. +2. Next, tell your Bottlerocket nodes to prepare to boot into that specific version. + - Apply the [`update-bottlerocket-node` SSM Command Document](../methods/in-place/#ssm-command-document-check-for-and-apply-updates-to-a-bottlerocket-node), described in the [in-place update documentation](../methods/in-place/). +3. Finally, reboot your Bottlerocket nodes into the version you locked to. + - Apply the [`reboot-bottlerocket-node` SSM Command Document](../methods/in-place/#ssm-command-document-reboot-a-bottlerocket-node), described in the [in-place update documentation](../methods/in-place/). + +## Removing a Version Lock + +In order to remove a version lock using SSM, [create](https://docs.aws.amazon.com/systems-manager/latest/userguide/create-ssm-console.html) and [apply](https://docs.aws.amazon.com/systems-manager/latest/userguide/running-commands-console.html) the following SSM Command Document to the Bottlerocket nodes you want to remove a Version Lock from (the SSM Command Document can be named `version-unlock-bottlerocket-node` for example): + +### SSM Command Document: Remove a Version Lock + +```yaml +--- +schemaVersion: "2.2" +description: "Remove a Version Lock from a Bottlerocket host via the Bottlerocket Settings API" +mainSteps: + - name: "unsetTargetVersion" + action: "aws:runShellScript" + inputs: + timeoutSeconds: '20' + runCommand: + - "apiclient set updates.version-lock=\"latest\" updates.ignore-waves=false" +``` + +{{< on-github >}} diff --git a/content/en/os/1.22.x/update/methods/_index.markdown b/content/en/os/1.22.x/update/methods/_index.markdown new file mode 100644 index 00000000..d8648712 --- /dev/null +++ b/content/en/os/1.22.x/update/methods/_index.markdown @@ -0,0 +1,5 @@ ++++ +title="Update Methods" +type="docs" +description="Methods to update Bottlerocket clusters" ++++ diff --git a/content/en/os/1.22.x/update/methods/in-place/index.markdown b/content/en/os/1.22.x/update/methods/in-place/index.markdown new file mode 100644 index 00000000..4ac6c434 --- /dev/null +++ b/content/en/os/1.22.x/update/methods/in-place/index.markdown @@ -0,0 +1,165 @@ ++++ +title = "In-Place Updates" +type = "docs" +description = "How to update a Bottlerocket node in-place" ++++ + +Bottlerocket clusters can be updated in-place, meaning that the existing Bottlerocket nodes will download updated software to use, without re-provisioning the nodes. +There are different ways to update in-place depending on your environment. + +## `apiclient` Commands + +At its core, updating Bottlerocket consists of three steps: checking for an update, applying an update, and rebooting into the new Bottlerocket version. + +These steps have specific `apiclient` commands associated with them: + +### Check for Update + +In order to check for an update using `apiclient`, issue the following command in the control container: + +```bash +apiclient update check +``` + +### Apply Update + +If an update is found while checking for an update, apply the update using the following command: + +```bash +apiclient update apply +``` + +That command downloads the updated Bottlerocket image, apply it to a separate partition on disk, and prepare the system to use the new version of Bottlerocket. +In particular, [the partition that was just updated with the new Bottlerocket image is marked as the "active" next boot partition](https://github.com/bottlerocket-os/bottlerocket#updates-1). + +It is also possible to combine the Check and Apply steps into a single command: + +```bash +apiclient update apply --check +``` + +That command first checks for an update, and then applies the update if one is found. + +### Reboot Into the New Version + +After applying the update, reboot the system in order to begin using the new version of Bottlerocket. +That can be done with the following command: + +```bash +apiclient reboot +``` + +## ECS + +For the `aws-ecs-*` variants of Bottlerocket, use the [ECS updater](https://github.com/bottlerocket-os/bottlerocket-ecs-updater#how-it-works). +See the [ECS updater installation documentation](https://github.com/bottlerocket-os/bottlerocket-ecs-updater#installation) for more information on how to install and use the ECS updater. + +By default, the ECS updater checks for updates every 12 hours. + +In order to install the ECS updater, you need a few different pieces of information: the subnet information for your cluster, the name of the CloudWatch Logs log group where you want logs stored, and the name of the ECS cluster you want the ECS updater to keep updated. +Further information on how to get that information can be found in the [Getting Started section of the ECS updater documentation](https://github.com/bottlerocket-os/bottlerocket-ecs-updater#getting-started). +After you've gathered those three values, you are ready to install the ECS updater. + +Detailed installation steps, including commands to run, are provided in the [Install section of the ECS updater documentation](https://github.com/bottlerocket-os/bottlerocket-ecs-updater#install). + +## Kubernetes + +For the `aws-k8s-*` variants of Bottlerocket, there are a handful of possible ways to update Bottlerocket: Brupop, the EKS Console, `eksctl`, and SSM Command Documents. +The following sections discuss each of these methods. + +### Brupop + +The recommended method to update your Bottlerocket nodes on Kubernetes is with Brupop. + +#### Brupop: Install via Released YAML + +Brupop installation via the released YAML file is covered in the [Brupop documentation](https://github.com/bottlerocket-os/bottlerocket-update-operator#installation). + +## SSM + +If your Bottlerocket nodes are registered with AWS Systems Manager (SSM), it may be convenient for you to use SSM Command Documents to update your Bottlerocket nodes. + +**Important:** when using the SSM instructions below to update Bottlerocket nodes, workloads will _not_ be drained from the node before rebooting the node, causing interruptions to the workloads (unlike when using Brupop, for example). + +### SSM Command Document Method + +This method performs the same action as the [`apiclient` commands](#apiclient-commands) method above, but uses SSM Command Documents rather than interactively running the `apiclient` commands from the [control container](https://github.com/bottlerocket-os/bottlerocket#control-container). +SSM Command Documents allow you to specify shell commands to run on target nodes. +Use the `aws:runShellScript` SSM Action inside SSM Command Documents to run the `apiclient update` command on your Bottlerocket nodes. +See the [`apiclient` documentation](https://github.com/bottlerocket-os/bottlerocket/blob/develop/sources/api/apiclient/README.md#update-mode) to learn more about `apiclient update`. + +The following three subsections cover how to create two SSM Command Documents and apply them to your Bottlerocket nodes: one Command Document updates and prepares a Bottlerocket node to use the latest available version of the Bottlerocket image, and the other Command Document reboots a Bottlerocket node in order to use that latest acquired Bottlerocket image. + +Both the update and reboot steps can be combined into a single SSM Command Document, however keeping the two steps separate allows you to apply updates and reboot your Bottlerocket nodes in separate patterns, if needed. +For example, you may want to apply updates to your Bottlerocket nodes all at once, but reboot them in groups. + +#### 1. Create the SSM Command Document for Updating Nodes + +To create an SSM Command Document, follow the steps in the [AWS Systems Manager User Guide: "Create an SSM document (console)"](https://docs.aws.amazon.com/systems-manager/latest/userguide/create-ssm-console.html). +Remember to select "YAML" in the "Content" box, since the [SSM Command Document below](#ssm-command-document-check-for-and-apply-updates-to-a-bottlerocket-node) is formatted in YAML. + +A quick overview of what `apiclient update apply --check` does: + +1. First, the `--check` flag executes: `apiclient` checks for the available Bottlerocket OS images and selects the latest one. +2. Next, the `apply` subcommand executes: `apiclient` downloads the latest Bottlerocket OS image and prepares the Bottlerocket node to use it. + +##### SSM Command Document: Check For and Apply Updates to a Bottlerocket Node + +The following SSM Command Document is referred to in this documentation as `update-bottlerocket-node`: + +```yaml +--- +schemaVersion: "2.2" +description: "Update a Bottlerocket host via the Bottlerocket Update API" +mainSteps: + - name: "updateBottlerocket" + action: "aws:runShellScript" + inputs: + timeoutSeconds: '120' + runCommand: + - "apiclient update apply --check" +``` + +Congratulations! +You now have an SSM Command Document that updates a Bottlerocket node to the latest version of Bottlerocket. + +#### 2. Create the SSM Command Document for Rebooting Nodes + +To create an SSM Command Document, follow the steps in the [AWS Systems Manager User Guide: "Create an SSM document (console)"](https://docs.aws.amazon.com/systems-manager/latest/userguide/create-ssm-console.html). +Remember to select "YAML" in the "Content" box, since the [SSM Command Document below](#ssm-command-document-reboot-a-bottlerocket-node) is formatted in YAML. + +##### SSM Command Document: Reboot a Bottlerocket Node + +The following SSM Command Document is referred to in this documentation as `reboot-bottlerocket-node`: + +```yaml +--- +schemaVersion: "2.2" +description: "Reboot a Bottlerocket host via the Bottlerocket API" +mainSteps: + - name: "updateBottlerocket" + action: "aws:runShellScript" + inputs: + timeoutSeconds: '120' + runCommand: + - "apiclient reboot" +``` + +Congratulations! +You now have an SSM Command Document that reboots a Bottlerocket node. + +#### 3. Apply the SSM Command Documents to Your Bottlerocket Nodes + +After creating the two SSM Command Documents above ([`update-bottlerocket-node`](#ssm-command-document-check-for-and-apply-updates-to-a-bottlerocket-node) and [`reboot-bottlerocket-node`](#ssm-command-document-reboot-a-bottlerocket-node)), apply them to your Bottlerocket nodes. + +To apply SSM Command Documents to your Bottlerocket nodes, follow the steps in the [AWS Systems Manager User Guide: "To send a command using Run Command"](https://docs.aws.amazon.com/systems-manager/latest/userguide/running-commands-console.html). + +If you are using EKS, select all nodes in a given EKS cluster by specifying an instance tag in the "Target selection" section of the page. +Specify `eks:cluster-name` as the tag key, with the tag value set to your cluster name. + +After running the SSM Command Document, you are taken to the SSM Command status page. +If you would like to see the output of the SSM Command Document that you just ran, click on an Instance ID in the "Targets and outputs" section of the page and see any output or errors. + +Once the [first SSM Command Document (`update-bottlerocket-node`)](#ssm-command-document-check-for-and-apply-updates-to-a-bottlerocket-node) has finished running, apply the [second SSM Command Document (`reboot-bottlerocket-node`)](#ssm-command-document-reboot-a-bottlerocket-node) to your Bottlerocket nodes using the same process as above. + +{{< on-github >}} diff --git a/content/en/os/1.22.x/update/methods/node-replacement/index.markdown b/content/en/os/1.22.x/update/methods/node-replacement/index.markdown new file mode 100644 index 00000000..47211817 --- /dev/null +++ b/content/en/os/1.22.x/update/methods/node-replacement/index.markdown @@ -0,0 +1,24 @@ ++++ +title = "Node Replacement" +type = "docs" +description = "How to update a Bottlerocket cluster by replacing nodes" ++++ + +Bottlerocket clusters can be updated via node replacement, meaning that the existing Bottlerocket nodes will be replaced by new Bottlerocket nodes that run updated software. +This requires nodes to be reprovisioned. + +## EKS + +When running the `aws-k8s-*` variants of Bottlerocket on EKS, use either the EKS Console or [`eksctl`](https://eksctl.io/) to update your Bottlerocket nodes using the _node replacement_ method. +This means that you are replacing your existing Bottlerocket nodes with new Bottlerocket nodes, rather than updating your existing Bottlerocket nodes in-place. + +### EKS Console + +In order to update your Bottlerocket nodes in an EKS cluster using the EKS Console, follow the [steps found under the "AWS Management Console" tab, in the EKS User Guide](https://docs.aws.amazon.com/eks/latest/userguide/update-managed-node-group.html#mng-update). + +### `eksctl` + +Using [`eksctl`](https://eksctl.io/) is another option to update your Bottlerocket nodes. +Specific commands can be found in the [EKS User Guide: "Update a node group version", on the `eksctl` tab](https://docs.aws.amazon.com/eks/latest/userguide/update-managed-node-group.html#mng-update). + +{{< on-github >}} diff --git a/content/en/os/1.22.x/version-information/_index.markdown b/content/en/os/1.22.x/version-information/_index.markdown new file mode 100644 index 00000000..66ad9de4 --- /dev/null +++ b/content/en/os/1.22.x/version-information/_index.markdown @@ -0,0 +1,6 @@ ++++ +title = "Version Information" +description = "Information specific to this version of Bottlerocket" +type = "docs" +weight="50" ++++ \ No newline at end of file diff --git a/content/en/os/1.22.x/version-information/gpu-drivers/1.22.0/index.markdown b/content/en/os/1.22.x/version-information/gpu-drivers/1.22.0/index.markdown new file mode 100644 index 00000000..ae259f89 --- /dev/null +++ b/content/en/os/1.22.x/version-information/gpu-drivers/1.22.0/index.markdown @@ -0,0 +1,7 @@ ++++ +title = "1.22.0" +description = "Drivers included in each GPU-enabled variant" +type = "docs" ++++ + +{{< nvidia-versions >}} diff --git a/content/en/os/1.22.x/version-information/gpu-drivers/_index.markdown b/content/en/os/1.22.x/version-information/gpu-drivers/_index.markdown new file mode 100644 index 00000000..9a3a5bce --- /dev/null +++ b/content/en/os/1.22.x/version-information/gpu-drivers/_index.markdown @@ -0,0 +1,5 @@ ++++ +title = "GPU Driver Versions" +description = "Versions of GPU drivers included in each patch release of Bottlerocket" +type = "docs" ++++ \ No newline at end of file diff --git a/content/en/os/1.22.x/version-information/packages-by-variant/index.markdown b/content/en/os/1.22.x/version-information/packages-by-variant/index.markdown new file mode 100644 index 00000000..f883e4f1 --- /dev/null +++ b/content/en/os/1.22.x/version-information/packages-by-variant/index.markdown @@ -0,0 +1,10 @@ ++++ +title = "Packages by Variant" +description = "Packages contained in each variant" +type = "docs" ++++ +Legend: + +⬤ Has package, ◯ Does __not__ have package + +{{< packages-by-variant >}} diff --git a/content/en/os/1.22.x/version-information/packages/1.22.0/index.markdown b/content/en/os/1.22.x/version-information/packages/1.22.0/index.markdown new file mode 100644 index 00000000..11990bb1 --- /dev/null +++ b/content/en/os/1.22.x/version-information/packages/1.22.0/index.markdown @@ -0,0 +1,488 @@ +--- +title: "1.22.0" +type: "docs" +description: "Package Versions in Bottlerocket Release 1.22.0" +packages: + - package: acpid + version: 2.0.34 + patches: + - "0001-Remove-shell-dependency-by-only-shutting-down.patch" + - package: amazon-ssm-agent + version: 3.3.808.0 + patches: + - "0001-agent-Add-config-to-make-shell-optional.patch" + - package: aws-iam-authenticator + version: 0.6.21 + - package: aws-signing-helper + version: 1.1.1 + - package: bash + version: 5.2.32 + patches: + - "bash-5.0-patch-1.patch" + - "bash-4.4-no-loadable-builtins.patch" + - "bash-5.0-patch-2.patch" + - package: binutils + version: 2.38 + - package: chrony + version: 4.5 + - package: cni + version: 1.2.3 + - package: cni-plugins + version: 1.5.1 + - package: conntrack-tools + version: 1.4.8 + patches: + - "0001-disable-RPC-helper.patch" + - package: containerd + version: 1.7.20 + - package: coreutils + version: 9.5 + - package: dbus-broker + version: 36 + patches: + - "0001-c-utf8-disable-strict-aliasing-optimizations.patch" + - package: docker-cli + version: 25.0.5 + patches: + - "0001-non-tcp-host-header.patch" + - package: docker-engine + version: 25.0.6 + patches: + - "0002-oci-inject-kmod-in-all-containers.patch" + - "0001-Change-default-capabilities-using-daemon-config.patch" + - package: docker-init + version: 19.03.15 + - package: e2fsprogs + version: 1.47.1 + - package: early-boot-config + version: 0.1 + - package: ecr-credential-provider + version: 1.25.15 + - package: ecr-credential-provider-1.27 + version: 1.27.8 + - package: ecr-credential-provider-1.29 + version: 1.29.6 + - package: ecr-credential-provider-1.30 + version: 1.30.3 + - package: ecr-credential-provider-1.31 + version: 1.31.0 + - package: ecs-agent + version: 1.82.3 + patches: + - "0005-bottlerocket-change-execcmd-directories-for-Bottlero.patch" + - "1001-bottlerocket-default-filesystem-locations.patch" + - "0006-containermetadata-don-t-use-dataDirOnHost-for-metada.patch" + - "0001-bottlerocket-default-filesystem-locations.patch" + - "0002-bottlerocket-remove-unsupported-capabilities.patch" + - "0004-bottlerocket-fix-procfs-path-on-host.patch" + - "0003-bottlerocket-bind-introspection-to-localhost.patch" + - package: ecs-gpu-init + version: 0.0 + - package: ethtool + version: 6.10 + - package: filesystem + version: 1.0 + - package: findutils + version: 4.10.0 + - package: glibc + version: 2.38 + patches: + - "0047-sparc-Fix-broken-memset-for-sparc32-BZ-31068.patch" + - "0059-AArch64-Cleanup-emag-memset.patch" + - "0016-elf-Remove-unused-l_text_end-field-from-struct-link_.patch" + - "0011-sysdeps-tst-bz21269-fix-Wreturn-type.patch" + - "0018-NEWS-Add-the-2.38.1-bug-list.patch" + - "0027-tunables-Terminate-if-end-of-input-is-reached-CVE-20.patch" + - "0008-malloc-Remove-bin-scanning-from-memalign-bug-30723.patch" + - "0066-iconv-ISO-2022-CN-EXT-fix-out-of-bound-writes-when-w.patch" + - "0057-AArch64-Add-support-for-MOPS-memcpy-memmove-memset.patch" + - "0068-login-Check-default-sizes-of-structs-utmp-utmpx-last.patch" + - "0007-malloc-Enable-merging-of-remainders-in-memalign-bug-.patch" + - "0042-syslog-Fix-heap-buffer-overflow-in-__vsyslog_interna.patch" + - "0024-Fix-leak-in-getaddrinfo-introduced-by-the-fix-for-CV.patch" + - "9001-move-ldconfig-cache-to-ephemeral-storage.patch" + - "0055-LoongArch-Correct-__ieee754-_-_scalb-__ieee754-_-_sc.patch" + - "0017-elf-Move-l_init_called_next-to-old-place-of-l_text_e.patch" + - "0021-iconv-restore-verbosity-with-unrecognized-encoding-n.patch" + - "0032-elf-Fix-wrong-break-removal-from-8ee878592c.patch" + - "0058-AArch64-Cleanup-ifuncs.patch" + - "0043-syslog-Fix-heap-buffer-overflow-in-__vsyslog_interna.patch" + - "0023-manual-jobs.texi-Add-missing-item-EPERM-for-getpgid.patch" + - "0020-getaddrinfo-Fix-use-after-free-in-getcanonname-CVE-2.patch" + - "0030-Revert-elf-Move-l_init_called_next-to-old-place-of-l.patch" + - "0060-AArch64-Add-memset_zva64.patch" + - "0046-S390-Fix-building-with-disable-mutli-arch-BZ-31196.patch" + - "0005-x86_64-Fix-build-with-disable-multiarch-BZ-30721.patch" + - "0013-libio-Fix-oversized-__io_vtables.patch" + - "0038-NEWS-Mention-bug-fixes-for-29039-30694-30709-30721.patch" + - "HACK-only-build-and-install-localedef.patch" + - "0054-linux-Use-rseq-area-unconditionally-in-sched_getcpu-.patch" + - "0036-x86-64-Fix-the-dtv-field-load-for-x32-BZ-31184.patch" + - "0052-malloc-Use-__get_nprocs-on-arena_get2-BZ-30945.patch" + - "0015-elf-Always-call-destructors-in-reverse-constructor-o.patch" + - "0028-Revert-elf-Remove-unused-l_text_end-field-from-struc.patch" + - "0025-Document-CVE-2023-4806-and-CVE-2023-5156-in-NEWS.patch" + - "0063-aarch64-fix-check-for-SVE-support-in-assembler.patch" + - "0064-AArch64-Check-kernel-version-for-SVE-ifuncs.patch" + - "0029-Revert-elf-Always-call-destructors-in-reverse-constr.patch" + - "0065-powerpc-Fix-ld.so-address-determination-for-PCREL-mo.patch" + - "0009-sysdeps-tst-bz21269-fix-test-parameter.patch" + - "0051-arm-Remove-wrong-ldr-from-_dl_start_user-BZ-31339.patch" + - "glibc-cs-path.patch" + - "0034-elf-Fix-TLS-modid-reuse-generation-assignment-BZ-290.patch" + - "0039-NEWS-Mention-bug-fixes-for-30745-30843.patch" + - "0067-sparc-Remove-64-bit-check-on-sparc32-wordsize-BZ-275.patch" + - "0045-x86_64-Optimize-ffsll-function-code-size.patch" + - "0031-sysdeps-sem_open-Clear-O_CREAT-when-semaphore-file-i.patch" + - "0004-x86-Fix-incorrect-scope-of-setting-shared_per_thread.patch" + - "0053-S390-Do-not-clobber-r7-in-clone-BZ-31402.patch" + - "0041-libio-Check-remaining-buffer-size-in-_IO_wdo_write-b.patch" + - "0019-CVE-2023-4527-Stack-read-overflow-with-large-TCP-res.patch" + - "0014-elf-Do-not-run-constructors-for-proxy-objects.patch" + - "0048-sparc64-Remove-unwind-information-from-signal-return.patch" + - "0070-nptl-Fix-tst-cancel30-on-kernels-without-ppoll_time6.patch" + - "0033-LoongArch-Delete-excessively-allocated-memory.patch" + - "0050-sparc-Remove-unwind-information-from-signal-return-s.patch" + - "0049-sparc-Fix-sparc64-memmove-length-comparison-BZ-31266.patch" + - "0044-syslog-Fix-integer-overflow-in-__vsyslog_internal-CV.patch" + - "0061-AArch64-Remove-Falkor-memcpy.patch" + - "0035-elf-Add-TLS-modid-reuse-test-for-bug-29039.patch" + - "0062-aarch64-correct-CFI-in-rawmemchr-bug-31113.patch" + - "0012-io-Fix-record-locking-contants-for-powerpc64-with-__.patch" + - "0003-nscd-Do-not-rebuild-getaddrinfo-bug-30709.patch" + - "0010-sysdeps-tst-bz21269-handle-ENOSYS-skip-appropriately.patch" + - "0069-login-structs-utmp-utmpx-lastlog-_TIME_BITS-independ.patch" + - "0022-string-Fix-tester-build-with-fortify-enable-with-gcc.patch" + - "0037-x86-64-Fix-the-tcb-field-load-for-x32-BZ-31185.patch" + - "0040-getaddrinfo-translate-ENOMEM-to-EAI_MEMORY-bug-31163.patch" + - "0056-Add-HWCAP2_MOPS-from-Linux-6.5-to-AArch64-bits-hwcap.patch" + - "0002-x86-Fix-for-cache-computation-on-AMD-legacy-cpus.patch" + - "0026-Propagate-GLIBC_TUNABLES-in-setxid-binaries.patch" + - "0001-stdlib-Improve-tst-realpath-compatibility-with-sourc.patch" + - "0006-i686-Fix-build-with-disable-multiarch.patch" + - package: grep + version: 3.11 + - package: grub + version: 2.06 + patches: + - "0024-gptprio_test-check-GPT-is-repaired-when-appropriate.patch" + - "0027-gpt-add-helper-for-picking-a-valid-header.patch" + - "0008-gpt-add-a-new-generic-GUID-type.patch" + - "0037-gpt-read-entries-table-at-the-same-time-as-the-heade.patch" + - "0001-setup-Add-root-device-argument-to-grub-setup.patch" + - "0023-gptrepair_test-fix-typo-in-cleanup-trap.patch" + - "0010-gpt-split-out-checksum-recomputation.patch" + - "0048-add-flag-to-only-search-root-dev.patch" + - "0005-gpt-consolidate-crc32-computation-code.patch" + - "0035-gpt-always-revalidate-when-recomputing-checksums.patch" + - "0012-gpt-switch-partition-names-to-a-16-bit-type.patch" + - "0004-gpt-record-size-of-of-the-entries-table.patch" + - "0014-gpt-add-search-by-partition-label-and-uuid-commands.patch" + - "0017-gpt-add-search-by-disk-uuid-command.patch" + - "0007-gpt-add-write-function-and-gptrepair-command.patch" + - "0009-gpt-new-gptprio.next-command-for-selecting-priority-.patch" + - "0021-gpt-refuse-to-write-to-sector-0.patch" + - "0013-tests-add-some-partitions-to-the-gpt-unit-test-data.patch" + - "0016-gpt-minor-cleanup.patch" + - "0011-gpt-move-gpt-guid-printing-function-to-common-librar.patch" + - "0046-Revert-sb-Add-fallback-to-EFI-LoadImage-if-shim_lock.patch" + - "0015-gpt-clean-up-little-endian-crc32-computation.patch" + - "0036-gpt-include-backup-in-sync-check-in-revalidation.patch" + - "0040-gpt-write-backup-GPT-first-skip-if-inaccessible.patch" + - "0019-gpt-add-verbose-debug-logging.patch" + - "0018-gpt-do-not-use-disk-sizes-GRUB-will-reject-as-invali.patch" + - "0041-gptprio-Use-Bottlerocket-boot-partition-type-GUID.patch" + - "0022-gpt-properly-detect-and-repair-invalid-tables.patch" + - "0032-gpt-check-header-and-entries-status-bits-together.patch" + - "0006-gpt-add-new-repair-function-to-sync-up-primary-and-b.patch" + - "0039-gpt-rename-and-update-documentation-for-grub_gpt_upd.patch" + - "0044-efi-return-virtual-size-of-section-found-by-grub_efi.patch" + - "0020-gpt-improve-validation-of-GPT-headers.patch" + - "0026-gpt-prefer-disk-size-from-header-over-firmware.patch" + - "0043-util-mkimage-avoid-adding-section-table-entry-outsid.patch" + - "0047-Revert-UBUNTU-Move-verifiers-after-decompressors.patch" + - "0045-mkimage-pgp-move-single-public-key-into-its-own-sect.patch" + - "0031-gpt-do-not-use-an-enum-for-status-bit-values.patch" + - "0033-gpt-be-more-careful-about-relocating-backup-header.patch" + - "0028-gptrepair-fix-status-checking.patch" + - "0042-util-mkimage-Bump-EFI-PE-header-size-to-accommodate-.patch" + - "0029-gpt-use-inline-functions-for-checking-status-bits.patch" + - "0025-gpt-fix-partition-table-indexing-and-validation.patch" + - "0003-gpt-rename-misnamed-header-location-fields.patch" + - "0002-gpt-start-new-GPT-module.patch" + - "0038-gpt-report-all-revalidation-errors.patch" + - "0030-gpt-allow-repair-function-to-noop.patch" + - "0034-gpt-selectively-update-fields-during-repair.patch" + - package: host-ctr + version: 0.0 + - package: iproute + version: 6.4.0 + patches: + - "0001-skip-libelf-check.patch" + - package: iptables + version: 1.8.9 + patches: + - "1001-extensions-NAT-Fix-for-Werror-format-security.patch" + - "1002-ip6tables-Fix-checking-existence-of-rule.patch" + - package: iputils + version: 20240117 + - package: kernel-5.10 + version: 5.10.224 + patches: + - "1001-Makefile-add-prepare-target-for-external-modules.patch" + - "5001-Revert-netfilter-nf_tables-drop-map-element-referenc.patch" + - "1003-af_unix-increase-default-max_dgram_qlen-to-512.patch" + - "2000-kbuild-move-module-strip-compression-code-into-scrip.patch" + - "1002-initramfs-unlink-INITRAMFS_FORCE-from-CMDLINE_-EXTEN.patch" + - "2001-kbuild-add-support-for-zstd-compressed-modules.patch" + - package: kernel-5.15 + version: 5.15.165 + patches: + - "1001-Makefile-add-prepare-target-for-external-modules.patch" + - "1002-Revert-kbuild-hide-tools-build-targets-from-external.patch" + - "1004-af_unix-increase-default-max_dgram_qlen-to-512.patch" + - "1003-initramfs-unlink-INITRAMFS_FORCE-from-CMDLINE_-EXTEN.patch" + - package: kernel-6.1 + version: 6.1.106 + patches: + - "1001-Makefile-add-prepare-target-for-external-modules.patch" + - "1002-Revert-kbuild-hide-tools-build-targets-from-external.patch" + - "1004-af_unix-increase-default-max_dgram_qlen-to-512.patch" + - "1003-initramfs-unlink-INITRAMFS_FORCE-from-CMDLINE_-EXTEN.patch" + - "1005-Revert-Revert-drm-fb_helper-improve-CONFIG_FB-depend.patch" + - package: kexec-tools + version: 2.0.28 + - package: keyutils + version: 1.6.1 + - package: kmod + version: 31 + - package: kmod-5.10-nvidia + version: 1.0.0 + - package: kmod-5.15-nvidia + version: 1.0.0 + - package: kmod-6.1-neuron + version: 2.16.7.0 + patches: + - "0001-kbuild-do-not-outline-atomics-for-arm64.patch" + - package: kmod-6.1-nvidia + version: 1.0.0 + - package: kubernetes-1.23 + version: 1.23.17 + - package: kubernetes-1.24 + version: 1.24.17 + - package: kubernetes-1.25 + version: 1.25.16 + - package: kubernetes-1.26 + version: 1.26.15 + - package: kubernetes-1.27 + version: 1.27.14 + - package: kubernetes-1.28 + version: 1.28.10 + - package: kubernetes-1.29 + version: 1.29.5 + - package: kubernetes-1.30 + version: 1.30.1 + - package: kubernetes-1.31 + version: 1.31.0 + - package: libacl + version: 2.3.2 + - package: libattr + version: 2.5.2 + - package: libaudit + version: 3.1.4 + - package: libbpf + version: 1.4.3 + - package: libcap + version: 2.70 + patches: + - "9001-dont-test-during-install.patch" + - package: libdbus + version: 1.15.6 + - package: libelf + version: 0.191 + - package: libexpat + version: 2.6.3 + - package: libffi + version: 3.4.6 + - package: libgcc + version: 0.0 + - package: libglib + version: 2.78.4 + - package: libinih + version: 58 + - package: libiw + version: 29 + patches: + - "wireless-tools-29-makefile.patch" + - package: libkcapi + version: 1.5.0 + - package: libmnl + version: 1.0.5 + - package: libncurses + version: 6.5 + patches: + - "ncurses-config.patch" + - "ncurses-libs.patch" + - "ncurses-urxvt.patch" + - package: libnetfilter_conntrack + version: 1.0.9 + - package: libnetfilter_cthelper + version: 1.0.1 + - package: libnetfilter_cttimeout + version: 1.0.1 + - package: libnetfilter_queue + version: 1.0.5 + - package: libnfnetlink + version: 1.0.2 + - package: libnftnl + version: 1.2.6 + - package: libnl + version: 3.10.0 + - package: libnvidia-container + version: 1.16.1 + patches: + - "0004-Use-NVIDIA_PATH-to-look-up-binaries.patch" + - "0002-use-prefix-from-environment.patch" + - "0001-use-shared-libtirpc.patch" + - "0003-keep-debug-symbols.patch" + - "0005-makefile-avoid-ldconfig-when-cross-compiling.patch" + - package: libnvme + version: 1.9 + patches: + - "0001-linux-Fix-uninitialized-variables.patch" + - package: libpcre + version: 10.43 + - package: libseccomp + version: 2.5.5 + - package: libselinux + version: 3.6 + - package: libsemanage + version: 3.6 + patches: + - "0001-remove-bzip2-dependency.patch" + - package: libsepol + version: 3.6 + patches: + - "0001-libsepol-cil-Check-common-perms-when-verifiying-all.patch" + - package: libstd-rust + version: 0.0 + - package: libtirpc + version: 1.3.4 + - package: liburcu + version: 0.14.0 + - package: libxcrypt + version: 4.4.36 + - package: libz + version: 1.3.1 + - package: libzstd + version: 1.5.6 + - package: linux-firmware + version: 20230625 + patches: + - "0005-linux-firmware-usb-remove-firmware-for-USB-Serial-PC.patch" + - "0001-linux-firmware-snd-remove-firmware-for-snd-audio-dev.patch" + - "0007-linux-firmware-Remove-firmware-for-Accelarator-devic.patch" + - "0002-linux-firmware-video-Remove-firmware-for-video-broad.patch" + - "0006-linux-firmware-ethernet-Remove-firmware-for-ethernet.patch" + - "0004-linux-firmware-scsi-Remove-firmware-for-SCSI-devices.patch" + - "0010-linux-firmware-amd-ucode-Remove-amd-microcode.patch" + - "0009-linux-firmware-various-Remove-firmware-for-various-d.patch" + - "0008-linux-firmware-gpu-Remove-firmware-for-GPU-devices.patch" + - "0003-linux-firmware-bt-wifi-Remove-firmware-for-Bluetooth.patch" + - package: login + version: 0.0.1 + - package: makedumpfile + version: 1.7.5 + patches: + - "0000-fix-strip-invocation-for-TARGET-env-variable.patch" + - "0001-do-not-overlink-with-bzip2.patch" + - package: mdadm + version: 4.3 + patches: + - "0001-report-monitor-output-to-syslog.patch" + - package: microcode + version: 0.0 + - package: netdog + version: 0.1.1 + - package: nvidia-container-toolkit + version: 1.16.1 + - package: nvidia-k8s-device-plugin + version: 0.16.2 + - package: nvme-cli + version: 2.9.1 + - package: oci-add-hooks + version: 1.0.0 + - package: open-vm-tools + version: 12.3.5 + patches: + - "0002-dont-force-cppflags.patch" + - "0003-Update-shutdown-code-to-work-for-Bottlerocket.patch" + - "0001-no_cflags_werror.patch" + - package: os + version: 0.0 + - package: pigz + version: 2.8 + - package: policycoreutils + version: 3.6 + - package: procps + version: 4.0.4 + - package: readline + version: 8.2 + patches: + - "readline-8.2-shlib.patch" + - package: release + version: 0.0 + - package: runc + version: 1.1.14 + - package: selinux-policy + version: 0.0 + - package: shim + version: 15.8 + - package: socat + version: 1.8.0.0 + patches: + - "0001-xioopts-conditionally-compile-applyopts_termios_valu.patch" + - package: soci-snapshotter + version: 0.7.0 + - package: static-pods + version: 0.1 + - package: strace + version: 6.9 + - package: systemd + version: 252.22 + patches: + - "9013-sd-dhcp-lease-parse-multiple-domains-in-option-15.patch" + - "9010-units-keep-modprobe-service-units-running.patch" + - "9004-units-mount-tmp-with-noexec.patch" + - "9007-pkg-config-stop-hardcoding-prefix-to-usr.patch" + - "9014-meson-make-gpt-auto-generator-selectable-at-build-ti.patch" + - "1001-sd-netlink-make-calc_elapse-return-USEC_INFINITY-whe.patch" + - "9012-core-mount-increase-mount-rate-limit-burst-to-25.patch" + - "9009-sysusers-set-root-shell-to-sbin-nologin.patch" + - "9002-core-add-separate-timeout-for-system-shutdown.patch" + - "9006-mount-setup-mount-etc-with-specific-label.patch" + - "9011-systemd-networkd-Conditionalize-hostnamed-timezoned-.patch" + - "9008-sysctl-do-not-set-rp_filter-via-wildcard.patch" + - "9001-use-absolute-path-for-var-run-symlink.patch" + - "9005-mount-setup-apply-noexec-to-more-mounts.patch" + - "9003-machine-id-setup-generate-stable-ID-under-Xen-and-VM.patch" + - "1002-sd-netlink-make-the-default-timeout-configurable-by-.patch" + - package: util-linux + version: 2.40.2 + - package: wicked + version: 0.6.68 + patches: + - "1003-ship-mkconst-and-schema-sources-for-runtime-use.patch" + - "0001-dhcp6-refresh-ipv6-flags-on-staring-in-auto-mode.patch" + - "1005-client-validate-ethernet-namespace-node.patch" + - "1004-adjust-safeguard-for-dhcp6-defer-timeout.patch" + - "1007-dhpc6-don-t-cancel-transmission-if-random-delay-happ.patch" + - "1001-avoid-gcrypt-dependency.patch" + - "1006-server-discover-hardware-address-of-unconfigured-int.patch" + - "1002-exclude-unused-components.patch" + - "1008-dhcp6-reduce-maximum-initial-solicitation-delay-to-1.patch" + - package: xfsprogs + version: 6.8.0 +--- + +{{< packages-table >}} diff --git a/content/en/os/1.22.x/version-information/packages/_index.markdown b/content/en/os/1.22.x/version-information/packages/_index.markdown new file mode 100644 index 00000000..d45e7bea --- /dev/null +++ b/content/en/os/1.22.x/version-information/packages/_index.markdown @@ -0,0 +1,5 @@ ++++ +title="Package Versions" +type="docs" +description="Versions of packages included in this release of Bottlerocket" ++++ diff --git a/content/en/os/1.22.x/version-information/variants/index.markdown b/content/en/os/1.22.x/version-information/variants/index.markdown new file mode 100644 index 00000000..6570701f --- /dev/null +++ b/content/en/os/1.22.x/version-information/variants/index.markdown @@ -0,0 +1,10 @@ ++++ +title = "Variants & Kernels" +description = "Kernel versions and parameters specific for each Bottlerocket variant" +type = "docs" ++++ +{{< page-ver >}} + +See [_Update Policy_ in the Security Features document on GitHub](https://github.com/bottlerocket-os/bottlerocket/blob/develop/SECURITY_FEATURES.md#update-policy) for information on when and how Bottlerocket applies security patches to variants. + +{{< kernel-variant-info >}} diff --git a/data/homepagediagrams/variants.toml b/data/homepagediagrams/variants.toml index 833d2bcd..bb7bc92f 100644 --- a/data/homepagediagrams/variants.toml +++ b/data/homepagediagrams/variants.toml @@ -1,11 +1,11 @@ # This drives the variants diagram on the homepage [bottlerocket_versions] major= 1 -minor= 21 +minor= 22 [k8s_versions] -newer= 1.30 -older= 1.29 +newer= 1.31 +older= 1.30 [ecs_versions] newer= 2 diff --git a/data/nvidia/1.22.0/kmod-5.10-nvidia.toml b/data/nvidia/1.22.0/kmod-5.10-nvidia.toml new file mode 100644 index 00000000..c0634bac --- /dev/null +++ b/data/nvidia/1.22.0/kmod-5.10-nvidia.toml @@ -0,0 +1,32 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/tree/develop/packages/kmod-5.10-nvidia/Cargo.toml +[package] +name = "kmod-5_10-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" + +[lib] +path = "../packages.rs" + +[package.metadata.build-package] +package-name = "kmod-5.10-nvidia" +releases-url = "https://docs.nvidia.com/datacenter/tesla/" + +[[package.metadata.build-package.external-files]] +url = "https://s3.amazonaws.com/EULA/NVidiaEULAforAWS.pdf" +sha512 = "e1926fe99afc3ab5b2f2744fcd53b4046465aefb2793e2e06c4a19455a3fde895e00af1415ff1a5804c32e6a2ed0657e475de63da6c23a0e9c59feeef52f3f58" + +[[package.metadata.build-package.external-files]] +url = "https://us.download.nvidia.com/tesla/470.256.02/NVIDIA-Linux-x86_64-470.256.02.run" +sha512 = "a837946dd24d7945c1962a695f1f31965f3ceb6927f52cd08fd51b8db138b7a888bbeab69243f5c8468a7bd7ccd47f5dbdb48a1ca81264866c1ebb7d88628f88" +force-upstream = true + +[[package.metadata.build-package.external-files]] +url = "https://us.download.nvidia.com/tesla/470.256.02/NVIDIA-Linux-aarch64-470.256.02.run" +sha512 = "38eee5933355c34ca816a2ac0fbc4f55c19c20e1322891bfc98cb6b37d99a31218eea9314877ab0e3cf3ac6eb61f9d9d4d09d0af304b689f18b4efa721b65d5c" +force-upstream = true + +[build-dependencies] +glibc = { path = "../glibc" } +kernel-5_10 = { path = "../kernel-5.10" } diff --git a/data/nvidia/1.22.0/kmod-5.15-nvidia.toml b/data/nvidia/1.22.0/kmod-5.15-nvidia.toml new file mode 100644 index 00000000..ca2028ec --- /dev/null +++ b/data/nvidia/1.22.0/kmod-5.15-nvidia.toml @@ -0,0 +1,42 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/tree/develop/packages/kmod-5.15-nvidia/Cargo.toml +[package] +name = "kmod-5_15-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" + +[lib] +path = "../packages.rs" + +[package.metadata.build-package] +package-name = "kmod-5.15-nvidia" +releases-url = "https://docs.nvidia.com/datacenter/tesla/" + +[[package.metadata.build-package.external-files]] +url = "https://s3.amazonaws.com/EULA/NVidiaEULAforAWS.pdf" +sha512 = "e1926fe99afc3ab5b2f2744fcd53b4046465aefb2793e2e06c4a19455a3fde895e00af1415ff1a5804c32e6a2ed0657e475de63da6c23a0e9c59feeef52f3f58" + +[[package.metadata.build-package.external-files]] +url = "https://us.download.nvidia.com/tesla/535.183.01/NVIDIA-Linux-x86_64-535.183.01.run" +sha512 = "02b6b679f4fc1d5305f32fca8ce0875eef04cb99f5611d0bb85ac7607ecdd5b2aa4d60b51bf47546477464531a07fffa5bf3db3859868648bd5e86565d85afbb" +force-upstream = true + +[[package.metadata.build-package.external-files]] +url = "https://us.download.nvidia.com/tesla/535.183.01/NVIDIA-Linux-aarch64-535.183.01.run" +sha512 = "d2ac1be8c19b359023c31941374911f3adfe1be34aa2821ef582df4c854ac4eefbbcb10aa22583ac8c9d5caf9326bda12ed1ce6343d67479ed37a4887bd17b5e" +force-upstream = true + +[[package.metadata.build-package.external-files]] +url = "https://developer.download.nvidia.com/compute/cuda/repos/rhel9/x86_64/nvidia-fabric-manager-535.183.01-1.x86_64.rpm" +sha512 = "d52879d1e552b949a529ede9c4ce3e7b66af0df96e8f43906f211673b99815561c83a7c382be17950b1308457ca496ce49adca41766f808cc5a340471353494b" +force-upstream = true + +[[package.metadata.build-package.external-files]] +url = "https://developer.download.nvidia.com/compute/cuda/repos/rhel9/sbsa/nvidia-fabric-manager-535.183.01-1.aarch64.rpm" +sha512 = "75e1d306b9aa6cc8737bce50f39dc641f64de6a944c50f2c9706345c656f203c4706414dcb51def7671f0fd02fd18605aa3d62958b690d2705cb7011c54ff48e" +force-upstream = true + +[build-dependencies] +glibc = { path = "../glibc" } +kernel-5_15 = { path = "../kernel-5.15" } diff --git a/data/nvidia/1.22.0/kmod-6.1-nvidia.toml b/data/nvidia/1.22.0/kmod-6.1-nvidia.toml new file mode 100644 index 00000000..bd5f034e --- /dev/null +++ b/data/nvidia/1.22.0/kmod-6.1-nvidia.toml @@ -0,0 +1,42 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/tree/develop/packages/kmod-6.1-nvidia/Cargo.toml +[package] +name = "kmod-6_1-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" + +[lib] +path = "../packages.rs" + +[package.metadata.build-package] +package-name = "kmod-6.1-nvidia" +releases-url = "https://docs.nvidia.com/datacenter/tesla/" + +[[package.metadata.build-package.external-files]] +url = "https://s3.amazonaws.com/EULA/NVidiaEULAforAWS.pdf" +sha512 = "e1926fe99afc3ab5b2f2744fcd53b4046465aefb2793e2e06c4a19455a3fde895e00af1415ff1a5804c32e6a2ed0657e475de63da6c23a0e9c59feeef52f3f58" + +[[package.metadata.build-package.external-files]] +url = "https://us.download.nvidia.com/tesla/535.183.01/NVIDIA-Linux-x86_64-535.183.01.run" +sha512 = "02b6b679f4fc1d5305f32fca8ce0875eef04cb99f5611d0bb85ac7607ecdd5b2aa4d60b51bf47546477464531a07fffa5bf3db3859868648bd5e86565d85afbb" +force-upstream = true + +[[package.metadata.build-package.external-files]] +url = "https://us.download.nvidia.com/tesla/535.183.01/NVIDIA-Linux-aarch64-535.183.01.run" +sha512 = "d2ac1be8c19b359023c31941374911f3adfe1be34aa2821ef582df4c854ac4eefbbcb10aa22583ac8c9d5caf9326bda12ed1ce6343d67479ed37a4887bd17b5e" +force-upstream = true + +[[package.metadata.build-package.external-files]] +url = "https://developer.download.nvidia.com/compute/cuda/repos/rhel9/x86_64/nvidia-fabric-manager-535.183.01-1.x86_64.rpm" +sha512 = "d52879d1e552b949a529ede9c4ce3e7b66af0df96e8f43906f211673b99815561c83a7c382be17950b1308457ca496ce49adca41766f808cc5a340471353494b" +force-upstream = true + +[[package.metadata.build-package.external-files]] +url = "https://developer.download.nvidia.com/compute/cuda/repos/rhel9/sbsa/nvidia-fabric-manager-535.183.01-1.aarch64.rpm" +sha512 = "75e1d306b9aa6cc8737bce50f39dc641f64de6a944c50f2c9706345c656f203c4706414dcb51def7671f0fd02fd18605aa3d62958b690d2705cb7011c54ff48e" +force-upstream = true + +[build-dependencies] +glibc = { path = "../glibc" } +kernel-6_1 = { path = "../kernel-6.1" } diff --git a/data/settings/1.22.x/autoscaling.toml b/data/settings/1.22.x/autoscaling.toml new file mode 100644 index 00000000..a2f2ac44 --- /dev/null +++ b/data/settings/1.22.x/autoscaling.toml @@ -0,0 +1,15 @@ +[[docs.ref.should-wait]] +description = """ +If set to `true`, the node waits until the instance reaches the [`InService` state](https://docs.aws.amazon.com/autoscaling/ec2/userguide/ec2-auto-scaling-lifecycle.html#as-lifecycle-inservice) to join the cluster. +""" +accepted_values = [ + "`true`", + "`false`" +] +note = """ +Only set this value to `true` if the instance is currently (or will be) in an auto scaling group. +""" +default = "`false`" + +[[docs.ref.should-wait.example]] +value = "true" diff --git a/data/settings/1.22.x/aws.toml b/data/settings/1.22.x/aws.toml new file mode 100644 index 00000000..f72f9b80 --- /dev/null +++ b/data/settings/1.22.x/aws.toml @@ -0,0 +1,31 @@ +[[docs.ref.config]] +description = """ +The base64-encoded representation of data used to populate `~/.aws/config` +""" +warning = """ +Avoid adding a `[profile default]` section. +Recent versions of `aws-iam-authenticator` (and perhaps other components) pick up the default credential settings when `settings.aws.profile` is set to `default`. +""" +see = [ + ["`ecr-credential-provider` under [`settings.kubernetes.credential-providers`](../kubernetes/#credential-providers)"] +] + +[[docs.ref.credentials]] +description = """ +The base64-encoded representation of data used to populate `~/.aws/credentials` +""" + +[[docs.ref.profile]] +description = """ +The profile name to use for [`settings.aws.config`](#config) and [`settings.aws.credentials`](#credentials). +""" +default = "`default`" +[[docs.ref.profile.example]] +value = "myprofile" + +[[docs.ref.region]] +description = """ +The AWS region (e.g. `us-west-2`) +""" +note = "You do not need to explicitly set `setting.aws.region` unless you have a reason to override this default value." +default = "The region is automatically inferred based on calls to the [Instance MetaData Service (IMDS)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html)." diff --git a/data/settings/1.22.x/boot.toml b/data/settings/1.22.x/boot.toml new file mode 100644 index 00000000..f5a03b8e --- /dev/null +++ b/data/settings/1.22.x/boot.toml @@ -0,0 +1,87 @@ +[[docs.ref.init-parameters]] +description = """ +Init parameters expressed as key/value pairs. +If boot data exists at `/proc/bootconfig`, Bottlerocket generates the settings from this data on first boot. +During the boot process, the init parameters pass via the kernel command line. +""" +see = [ + ["[Boot Configuration on kernel.org](https://www.kernel.org/doc/html/latest/admin-guide/bootconfig.html)"] +] +[[docs.ref.init-parameters.example]] +direct_toml = """ +[settings.boot.init-parameters] +"log_level" = ["debug"] +"splash" = [] +""" +direct_shell = """ +apiclient apply <<EOF +[settings.boot.init-parameters] +"log_level" = ["debug"] +"splash" = [] +EOF +""" + + + +[[docs.ref.kernel-parameters]] +description = """ +Kernel parameters expressed as key/value pairs. +If boot data exists at `/proc/bootconfig`, Bottlerocket generates the settings from this data on first boot. +During the boot process, the parameters pass via the kernel command line. +""" +see = [ + ["[Boot Configuration on kernel.org](https://www.kernel.org/doc/html/latest/admin-guide/bootconfig.html)"] +] +[[docs.ref.kernel-parameters.example]] +direct_toml = """ +[settings.boot.kernel-parameters] +"console" = [ + "tty0", + "ttyS1,115200n8", +] +"crashkernel" = [ + "2G-:256M" +] +"slub_debug" = [ + "options,slabs" +] +"usbcore.quirks" = [ + "0781:5580:bk", + "0a5c:5834:gij" +] +""" +direct_shell = """ +apiclient apply <<EOF +[settings.boot.kernel-parameters] +"console" = [ + "tty0", + "ttyS1,115200n8", +] +"crashkernel" = [ + "2G-:256M" +] +"slub_debug" = [ + "options,slabs" +] +"usbcore.quirks" = [ + "0781:5580:bk", + "0a5c:5834:gij", +] +EOF +""" + +[[docs.ref.reboot-to-reconcile]] +description = """ +When `true`, changes observed to `settings.boot.kernel-parameters` or `settings.boot.init-parameters` during the boot proccess trigger a reboot. +""" +note = """ +The reboot occurs only if the actual settings value changes. +If `settings.boot.kernel-parameters` or `settings.boot.init-parameters` are set to an existing value, no reboot will occur even if `settings.boot.reboot-to-reconcile` is set to `true`. +This allows you to place `settings.boot.kernel-parameters` and `settings.boot.init-parameters` in user data or a [bootstrap container](../../../concepts/bootstrap-containers/) without causing a reboot loop. +""" +accepted_values = [ + "`true`", + "`false`" +] +[[docs.ref.reboot-to-reconcile.example]] +value = "true" diff --git a/data/settings/1.22.x/bootstrap-containers.toml b/data/settings/1.22.x/bootstrap-containers.toml new file mode 100644 index 00000000..342ca59d --- /dev/null +++ b/data/settings/1.22.x/bootstrap-containers.toml @@ -0,0 +1,61 @@ +[[docs.ref.name_essential]] +name_override = "<name>.essential" +description = "If `essential` is set to `true` the bootstrap container will halt the boot process when it exits with a non-zero exit code." +default = "`false`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["[`settings.bootstrap-containers.<name>.source`](#name_source) for a full example with `settings.bootstrap-containers.<name>.essential`."], + ["The {{< ver-ref project=\"os\" page=\"/concepts/bootstrap-containers#lifecycle\" >}}bootstrap container lifecycle{{< /ver-ref >}} conceptual documentationion"] +] + + +[[docs.ref.name_mode]] +name_override = "<name>.mode" +description = """ +Specifies how (or if) a container starts at boot. +If you set the value to: + +* `"always"`, the container will start on every boot, +* `"off"`, the container will not start at boot, +* `"once"`, the container will start on the first boot but after exit, the `mode` changes to `off`. +""" +accepted_values = [ + "`\"always\"`", + "`\"off\"`", + "`\"once\"`" +] +see = [ + ["[`settings.bootstrap-containers.<name>.source`](#name_source) for a full example with `settings.bootstrap-containers.<name>.mode`."], + ["The {{< ver-ref project=\"os\" page=\"/concepts/bootstrap-containers#lifecycle\" >}}bootstrap container lifecycle{{< /ver-ref >}} conceptual documentation"] + +] + +[[docs.ref.name_source]] +name_override = "<name>.source" +description = "Defines the URI for a container to run as a bootstrap container." +[[docs.ref.name_user-data]] +name_override = "<name>.user-data" +description = """ +An optional field that allows you to pass arbitrary base64-encoded data to the bootstrap container. +The data is avaliable to the bootstrap container at `/.bottlerocket/bootstrap-containers/<container>/user-data` or `/.bottlerocket/bootstrap-containers/current/user-data`. +""" +[[docs.ref.name_source.example]] +direct_toml = """ +# Creates a bootstrap container called `mybootstrap` +# It runs only one time and if exits with a non-zero code, will halt the boot process +[settings.bootstrap-containers.mybootstrap] +source = \"uri.to.container.in.oci-compatible-registry.example.com/foo:1.0.0" +mode = "once" +essential = true +""" +direct_shell = """ +# Creates a bootstrap container called `mybootstrap` +# It runs only one time and if exits with a non-zero code, will halt the boot process +apiclient set \\ + bootstrap-containers.mybootstrap.source=\"uri.to.container.in.oci-compatible-registry.example.com/foo:1.0.0" \\ + bootstrap-containers.mybootstrap.mode=\"once\" \\ + bootstrap-containers.mybootstrap.mode=true +""" diff --git a/data/settings/1.22.x/cloudformation.toml b/data/settings/1.22.x/cloudformation.toml new file mode 100644 index 00000000..d9e9590b --- /dev/null +++ b/data/settings/1.22.x/cloudformation.toml @@ -0,0 +1,25 @@ +[[docs.ref.logical-resource-id]] +description = """ +The logical ID of the AutoScalingGroup resource that you want to signal. +""" +see = [ + ["[Logical IDs in the AWS CloudFormation documentation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html#resources-section-structure-logicalid)"] +] + +[[docs.ref.should-signal]] +description = """ +Controls if signals should be sent to CloudFormation. +""" +note = """ +If `settings.cloudformation.should-signal` is `true`, both `settings.cloudformation.stack-name` and `settings.cloudformation.logical-resource-id` are required. +""" +default = "`false`" +accepted_values = [ + "`true`", + "`false`" +] + +[[docs.ref.stack-name]] +description = """ +Name of the CloudFormation Stack to signal. +""" diff --git a/data/settings/1.22.x/container-registry.toml b/data/settings/1.22.x/container-registry.toml new file mode 100644 index 00000000..ecd25ff5 --- /dev/null +++ b/data/settings/1.22.x/container-registry.toml @@ -0,0 +1,64 @@ +[[docs.ref.mirrors]] +description = """ +An [array of tables](https://toml.io/en/v1.0.0#array-of-tables) that represent container image registry mirrors. +Each table must contain the `registry` (a string) and `endpoints` (an array of strings). +When pulling an image from a registry, the container runtime will try the endpoints one-by-one and use the first working registry. +The runtime will still try the default registry URL if the mirrors fail. + +The Docker container runtime can [only provide pull-through caches for images from Docker Hub (docker.io)](https://docs.docker.com/registry/recipes/mirror/#gotcha) and ignores mirrors for other registries. +Consequently, Bottlerocket variants that use the Docker container runtime (e.g. `aws-ecs-1` or `aws-ecs-2`) have the same limitation. +""" + +note = """ +Bottlerocket cannot configure registry mirrors for private Amazon Elastic Container Registry (Amazon ECR) repositories. +For example, the Bottlerocket default host or bootstrap container images from ECR cannot be mirrored. +""" + +[[docs.ref.mirrors.example]] +direct_toml = """ +[[settings.container-registry.mirrors]] +registry = "*" +endpoint = ["https://<example-mirror>","https://<example-mirror-2>"] + +[[settings.container-registry.mirrors]] +registry = "docker.io" +endpoint = [ "https://<my-docker-hub-mirror-host>", "https://<my-docker-hub-mirror-host-2>"] +""" + +[[docs.ref.credentials]] +description = """ +An [array of tables](https://toml.io/en/v1.0.0#array-of-tables) that represent image registry credentials. +The fields (all strings) in the table specify the `registry` and credential information such as `username`, `password`, `auth`, `identitytoken`. +The credential fields map to [containerd's registry credential fields](https://github.com/containerd/containerd/blob/v1.6.0/docs/cri/registry.md#configure-registry-credentials), which in turn map to fields in `.docker/config.json`. +""" + +warning = "Avoid storing plain text credentials in external systems. As an alternative, programmatically apply these settings via `apiclient` using a bootstrap or host container." + +[[docs.ref.credentials.example]] +direct_toml = """ +[[settings.container-registry.credentials]] +registry = "docker.io" +username = "foo" +password = "bar" + +[[settings.container-registry.credentials]] +registry = "gcr.io" +auth = "example_base64_encoded_auth_string" +""" +direct_shell = """ +apiclient set --json '{ + "container-registry": { + "credentials": [ + { + "registry": "docker.io", + "username": "foo", + "password": "bar" + }, + { + "registry": "gcr.io", + "auth": "example_base64_encoded_auth_string" + } + ] + } +}' +""" diff --git a/data/settings/1.22.x/container-runtime.toml b/data/settings/1.22.x/container-runtime.toml new file mode 100644 index 00000000..1291b072 --- /dev/null +++ b/data/settings/1.22.x/container-runtime.toml @@ -0,0 +1,40 @@ +[[docs.ref.enable-unprivileged-icmp]] +description = "If `true` unprivileged containers can open [ICMP](https://en.wikipedia.org/wiki/Internet_Control_Message_Protocol) echo sockets." +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["[CRI Plugin Config Guide - Full configuration](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#full-configuration)"] +] + + +[[docs.ref.enable-unprivileged-ports]] +description = "If `true` unprivileged containers can bind to ports less than 1024." +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["[CRI Plugin Config Guide - Full configuration](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#full-configuration)"] +] + +[[docs.ref.max-concurrent-downloads]] +description = "The number of allowed concurrent layer downloads for each image." +accepted_values = [ + "a positive number" +] +see = [ + ["[CRI Plugin Config Guide - Full configuration](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#full-configuration)"] +] + + +[[docs.ref.max-container-log-line-size]] +description = "A value that dictates the maximum log line size, any larger log lines will split into multiple lines. Values are expressed in bytes." +accepted_values = [ + "`-1` for no limit", + "a positive numbers" +] +see = [ + ["[CRI Plugin Config Guide - Full configuration](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#full-configuration)"] +] diff --git a/data/settings/1.22.x/dns.toml b/data/settings/1.22.x/dns.toml new file mode 100644 index 00000000..0d3c259f --- /dev/null +++ b/data/settings/1.22.x/dns.toml @@ -0,0 +1,19 @@ +[[docs.ref.name-servers]] +description = "A list of IP address strings that represent the desired name server(s)." +accepted_values = [ "IP addresses" ] +see = [ + ["[`resolve.conf` manual page](https://man7.org/linux/man-pages/man5/resolv.conf.5.html)"] +] +note = "If you do not provide this setting, Bottlerocket gathers the name servers from the DHCP lease." +[[docs.ref.name-servers.example]] +value = "[\"1.2.3.4\", \"5.6.7.8\"]" + + +[[docs.ref.search-list]] +description = "An list of domain strings that represent the desired domain search path(s)." +see = [ + ["[`resolve.conf` manual page](https://man7.org/linux/man-pages/man5/resolv.conf.5.html)"] +] +note = "If you do not provide this setting, Bottlerocket gathers the DNS search list from the DHCP lease." +[[docs.ref.search-list.example]] +value = "[\"foo.bar\", \"baz.foo\"]" diff --git a/data/settings/1.22.x/ecs.toml b/data/settings/1.22.x/ecs.toml new file mode 100644 index 00000000..373296f6 --- /dev/null +++ b/data/settings/1.22.x/ecs.toml @@ -0,0 +1,204 @@ +# tags + +[[docs.tag.startup-only]] +heading = "Startup Only Settings" +description = """ +These settings affect how the instances join the ECS cluster. +Since joining a cluster happens at startup, they need to be set in user data. +""" + +[[docs.tag.cleanup]] +heading = "Image & Task Cleanup Settings" +description = "Settings related to [cleaning up images](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/automated_image_cleanup.html)." + +[[docs.tag.logging]] +heading = "Log Settings" +description = "Settings related to logs from the ECS Agent" + + +# reference +[[docs.ref.backend-host]] +description = "Sets the endpoint to make calls against (e.g `ecs.us-east-1.amazonaws.com`)." +default = "The endpoint for your current region." + +[[docs.ref.awsvpc-block-imds]] +description = "Blocks access to [Instance Metadata](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) for Tasks started with `awsvpc` network mode if `true`" +default = "`false`" +see = [ + ["`ECS_AWSVPC_BLOCK_IMDS` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] + +[[docs.ref.cluster]] +description = """ +The name or [ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) of your Amazon ECS cluster. +If left unspecified, the Bottlerocket host will join your default cluster. +""" +tags = [ + "startup-only" +] + +[[docs.ref.instance-attributes]] +description = "[Attributes](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-placement-constraints.html#attributes) in the form of key, value pairs added when registering the container instance in the cluster." +tags = [ + "startup-only" +] +see = [ + ["`ECS_INSTANCE_ATTRIBUTES` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] +[[docs.ref.instance-attributes.example]] +comment = "Example user data for setting up attributes" +[[docs.ref.instance-attributes.example.multiline]] +attribute1 = "foo" +attribute2 = "bar" + +[[docs.ref.allow-privileged-containers]] +description = """Allow the launch of privileged containers on the container instance. +If this value is set to `false`, privileged containers are not permitted. +""" +see = [ + ["`ECS_DISABLE_PRIVILEGED` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] + +default = "`false`" + +[[docs.ref.container-stop-timeout]] +description = """ +Time to wait for the task's containers to stop on their own before they are forcefully stopped. +Valid time units include `s`, `m`, and `h` (e.g. `1h`, `1m1s`). +""" +default = "`30s`" +see = [ + ["`ECS_CONTAINER_STOP_TIMEOUT` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] + +[[docs.ref.enable-spot-instance-draining]] +description = """ +If the instance receives a spot termination notice, the agent will set the instance's state to `DRAINING`, +so the workload can be moved gracefully before the instance is removed. +""" +default = "`false`" +see = [ + ["`ECS_ENABLE_SPOT_INSTANCE_DRAINING` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] + + +[[docs.ref.image-pull-behavior]] +description = "The behavior used to customize the [pull image process](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html#ecs-agent-availparam) for your container instances." +accepted_values = [ + "`default`", + "`always`", + "`once`", + "`prefer-cached`" +] +default = "`default`" +see = [ + ["`ECS_IMAGE_PULL_BEHAVIOR` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] + +[[docs.ref.logging-drivers]] +description = """ +The list of logging drivers available on the container instance. +The ECS agent running on a container instance must register available logging drivers before tasks that use those drivers are eligible to be placed on the instance. +Bottlerocket enables the `json-file`, `awslogs`, and `none` drivers by default. +""" +tags = [ + "logging" +] +see = [ + ["`ECS_AVAILABLE_LOGGING_DRIVERS` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] + + +[[docs.ref.loglevel]] +description = "The level of verbosity for the ECS agent's logs." +accepted_values = [ + "`debug`", + "`info`", + "`warn`", + "`error`", + "`crit`" +] +tags = [ + "logging" +] +default = "`info`" +see = [ + ["`ECS_LOGLEVEL` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] + + +[[docs.ref.metadata-service-rps]] +description = """ +The steady state rate limit of the throttling configurations set for the task metadata service. +""" +note = "This directly maps to the values set by the ECS_TASK_METADATA_RPS_LIMIT environment variable." +see = [ + ["`ECS_TASK_METADATA_RPS_LIMIT` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] + +[[docs.ref.metadata-service-burst]] +description = "The burst rate limit of the throttling configurations set for the task metadata service." +note = "This directly maps to the values set by the ECS_TASK_METADATA_RPS_LIMIT environment variable." +see = [ + ["`ECS_TASK_METADATA_RPS_LIMIT` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] + + +[[docs.ref.reserved-memory]] +description = "The amount of memory, in MiB, reserved for critical system processes." + +[[docs.ref.task-cleanup-wait]] +description = """ +Time to wait before the task's containers are removed after they are stopped. +Valid time units include `s`, `m`, and `h` (e.g. `1h`, `1m1s`). +""" +tags = [ + "cleanup" +] + +[[docs.ref.image-cleanup-delete-per-cycle]] +description = "Number of images to delete in a single image cleanup cycle." +see = [ + ["`ECS_NUM_IMAGES_DELETE_PER_CYCLE` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] +tags = [ + "cleanup" +] + +[[docs.ref.image-cleanup-enabled]] +description = "Enable automatic images clean up after the tasks have been removed." +default = "`true`" +see = [ + ["`ECS_DISABLE_IMAGE_CLEANUP` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] +tags = [ + "cleanup" +] + +[[docs.ref.image-cleanup-age]] +description = """ +Time since the image was pulled to be considered for clean up. +Valid time units include `s`, `m`, and `h` (e.g. `1h`, `1m1s`). +""" +tags = [ + "cleanup" +] + +[[docs.ref.image-cleanup-wait]] +description = """ +Time to wait between image cleanup cycles +Valid time units include `s`, `m`, and `h` (e.g. `1h`, `1m1s`). +""" +tags = [ + "cleanup" +] + +[[docs.ref.enable-container-metadata]] +description = """ +When `true`, the agent will create a file describing the container's metadata at +the path stored in the environment variable `ECS_CONTAINER_METADATA_FILE` +""" +default = "`false`" +see = [ + ["`ECS_ENABLE_CONTAINER_METADATA` in the [ECS Agent Environment Variables](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables)"] +] diff --git a/data/settings/1.22.x/host-containers.toml b/data/settings/1.22.x/host-containers.toml new file mode 100644 index 00000000..fa9688ca --- /dev/null +++ b/data/settings/1.22.x/host-containers.toml @@ -0,0 +1,63 @@ + + +[[docs.ref.container_enabled]] +name_override = "<container>.enabled" +description = "If `true` the container starts automatically at boot. Bottlerocket requires this key alongside [`source`](#container_source) and [`superpowered`](#container_superpowered) to start a host container." +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["[`host-containers.<container>.source` for custom host container example](#container_source)"], + ["[Shell-less host](../../../concepts/shell-less-host/)"] +] + +[[docs.ref.container_source]] +name_override = "<container>.source" +description = "The URI for the container to run as a host container. Bottlerocket requires this key alongside [`enabled`](#container_enabled) and [`superpowered`](#container_superpowered) to start a host container." +[[docs.ref.container_source.example]] +direct_toml = """ +[settings.host-containers.mycontainer] +enabled = true +source = "uri.to.container.in.oci-compatible-registry.example.com/foo:1.0.0" +superpowered = false +""" +direct_shell = """ +apiclient set \\ + settings.host-containers.mycontainer.enabled=true \\ + settings.host-containers.mycontainer.source="uri.to.container.in.oci-compatible-registry.example.com/foo:1.0.0" \\ + settings.host-containers.mycontainer.superpowered=false +""" +see = [ + ["[Shell-less host](../../../concepts/shell-less-host/)"] +] + +[[docs.ref.container_superpowered]] +name_override = "<container>.superpowered" +description = "If `true`, effectively grants the container root access to the host. Bottlerocket requires this key alongside [`enabled`](#container_enabled) and [`source`](#container_source) to start a host container." +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["[`host-containers.<container>.source` for custom host container example](#container_source)"], + ["[Shell-less host](../../../concepts/shell-less-host/)"] + +] + +[[docs.ref.container_user-data]] +name_override = "<container>.user-data" +description = """ +An optional field that stores arbitrary base64-encoded data. +The data in this field is accessible by the host container at `/.bottlerocket/host-containers/<container>/user-data` and `/.bottlerocket/host-containers/current/user-data`. +""" +note = """ +Despite the common name, host container `user-data` and instance `user-data` function differently. +Host container `user-data` may consist of anything and it is up to the container to interepret the data. +""" +warning = """ +The [Bottlerocket admin container](../../../concepts/components/#operational-and-administrative-workloads) decodes JSON for SSH keys from user data. +If you provide user data to the admin container, no SSH keys will be automatically passed into the admin container by Bottlerocket. +If using custom user data with the admin container, you must also provide your own authentication information in this user data. +See [Authenticating with the Admin Container](https://github.com/bottlerocket-os/bottlerocket-admin-container#authenticating-with-the-admin-container) for more information. +""" diff --git a/data/settings/1.22.x/kernel.toml b/data/settings/1.22.x/kernel.toml new file mode 100644 index 00000000..b44dc4e4 --- /dev/null +++ b/data/settings/1.22.x/kernel.toml @@ -0,0 +1,91 @@ +[[docs.ref.lockdown]] +description = """ +Sets the mode for the lockdown Linux security module. +""" +warning = "Changing this setting from `confidentiality` to `integrity` or `integrity` to `none` requires a reboot to take effect." +accepted_values = [ + """ +`confidentiality` : blocks most methods of reading kernel memory from userspace. +Tools that rely on reading kernel memory may not work in this mode. +""", + """ +`integrity` : blocks most methods for overwriting kernel memory or modifying kernel code. +This mode prevents unsigned kernel modules from loading. +""", + "`none` : disables protection by the Lockdown security module.", +] +default = "`integrity` except for `nvidia` and `dev` variant flavours which use `none`" +see = [ + ["[`kernel_lockdown` Linux Manual Page](https://man7.org/linux/man-pages/man7/kernel_lockdown.7.html)"], + ["Bottlerocket [Security Gudiance on GitHub](https://github.com/bottlerocket-os/bottlerocket/blob/develop/SECURITY_GUIDANCE.md#enable-kernel-lockdown)"], + ["[Linux kernel lockdown, integrity, and confidentiality](https://mjg59.dreamwidth.org/55105.html)"] +] + +[[docs.ref.modules_allowed]] +name_override = "modules.<name>.allowed" +warning = "This setting only affects *loading* of kernel modules at boot time. Changing the setting of already loaded (running) kernel modules to `false` has no affect until reboot." +description = """ +Allows (`true`) or disallows (`false`) the loading of kernel module `<name>`. +""" +see = [ + [ "settings", "boot", "kernel-parameters" ] +] +note = """ +Use [`settings.boot.kernel-parameters`](../boot/#kernel-parameters) to set module parameters through the kernel command line. +""" +accepted_values = [ + "`true`", + "`false`" +] +[[docs.ref.modules_allowed.example]] +direct_toml = """ +[settings.kernel.modules.sctp] +allowed = false + +[settings.kernel.modules.udf] +allowed = true +""" +direct_shell = """ +apiclient set settings.kernel.modules.sctp.allowed=false + +apiclient set settings.kernel.modules.udf.allowed=true +""" + +[[docs.ref.sysctl]] +description = "Sets kernel parameters." +note = "Add quotes (`\"`) around keys as they often contain dots (`.`) as well as around values." +see = [ + ["[`sysctl` Linux Manual Page](https://man7.org/linux/man-pages/man8/sysctl.8.html)"] +] +[[docs.ref.sysctl.example]] +direct_toml = """ +[settings.kernel.sysctl] +"user.max_user_namespaces" = "16384" +"vm.max_map_count" = "262144" +""" + +[[docs.ref.modules_autoload]] +name_override = "modules.<name>.autoload" +description = "If `true`, the kernel `<name>` module loads automatically on boot." +see = [ + [ "settings", "boot", "kernel-parameters" ] +] +note = """ +You must use this setting in conjuction with [`settings.kernel.modules.<name>.allowed`](#modules_allowed) on the same module. +This ensures that the OS doesn't auto-load a blocked module. + +Use [`settings.boot.kernel-parameters`](../boot/#kernel-parameters) to set module parameters through the kernel command line. +""" +accepted_values = [ + "`true`", + "`false`" +] +[[docs.ref.modules_autoload.example]] +direct_toml = """ +[settings.kernel.modules.ip_vs_lc] +allowed = true +autoload = true +""" +direct_shell = """ +apiclient set settings.kernel.modules.ip_vs_lc.allowed=true settings.kernel.modules.ip_vs_lc.autoload=true +""" diff --git a/data/settings/1.22.x/kubernetes.toml b/data/settings/1.22.x/kubernetes.toml new file mode 100644 index 00000000..26a00c97 --- /dev/null +++ b/data/settings/1.22.x/kubernetes.toml @@ -0,0 +1,627 @@ +[[docs.tag.labels-and-taints]] +heading = "Node labels & taints" +description = "You can use these optional settings to customize the node labels and taints." + + +[[docs.tag.required-vmware]] +heading = "Settings needed for `vmware-k8s-*` variants" +description = """ +Required settings for Kubernetes VMware variants. +These settings are typically specified in [user data](https://github.com/bottlerocket-os/bottlerocket#using-user-data). + +See the [VMware setup guide](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-VMWARE.md) for more information. +""" + +[[docs.tag.required-eks]] +heading = "Settings needed for `aws-k8s-*` variants" +description = """ +Required settings for Kubernetes variants in AWS. +These settings are typically specified in [user data](https://github.com/bottlerocket-os/bottlerocket#using-user-data). + +See the [EKS Quickstart](https://bottlerocket.dev/en/os/latest/#/install/quickstart/aws/k8s/) and the [EKS setup guide](https://github.com/bottlerocket-os/bottlerocket/blob/develop/QUICKSTART-EKS.md) for more details on setting up Bottlerocket and Kubernetes on Amazon EKS. +""" +# [[docs.tag.required-eks.example]] +# tab = "TOML Example" +# type = "toml" +# source = """ +# [foo] +# bar = "baz" +# """ + +[[docs.tag.required-metal]] +heading = "Settings needed for `metal-k8s-*` variants" +description = """ +Required settings for Kubernetes bare metal variants. +These settings are typically specified in [user data](https://github.com/bottlerocket-os/bottlerocket#using-user-data). + +See [metal provisioning guide](https://github.com/bottlerocket-os/bottlerocket/blob/develop/PROVISIONING-METAL.md) for more information. +""" + +[[docs.tag.static-pods]] +heading = "Static Pods & standalone mode" +description = """ +You can also optionally specify [static pods](https://kubernetes.io/docs/tasks/configure-pod-container/static-pod/) for your node. +Static pods can be particularly useful when running in standalone mode. +""" + +[[docs.ref.api-server]] +description = "The cluster's Kubernetes API endpoint. This is typically specified in [user data](https://github.com/bottlerocket-os/bottlerocket#using-user-data)." +tags = [ + "required-eks", + "required-vmware", + "required-metal" +] +[[docs.ref.cluster-certificate]] +description = "The base64-encoded certificate authority of the cluster." +tags = [ + "required-eks", + "required-vmware", + "required-metal" +] +[[docs.ref.cluster-name]] +description = "The cluster name you chose during setup." +tags= [ + "required-eks" +] +[[docs.ref.bootstrap-token]] +description = """ +The token to use for [TLS bootstrapping](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/). +Only used when `settings.kubernetes.authentication-mode` is set to `tls` (ignored otherwise). +""" +tags = ["required-vmware", "required-metal"] +see = [ + [ "settings", "kubernetes", "authentication-mode" ], + [ "[TLS bootstrapping](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet-tls-bootstrapping/) "] +] + + +[[docs.ref.node-labels]] +description = "[Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) in the form of key, value pairs added when registering the node in the cluster." +tags = [ + "labels-and-taints" +] +note = "Remember to quote keys (since they often contain `.`) and to quote all values." + +see = [ + ["[Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)"] +] + +[[docs.ref.node-labels.example]] +[[docs.ref.node-labels.example.multiline]] +"label1" = "foo" +"label2" = "bar" + + +[[docs.ref.node-taints]] +description = "[Taints](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) in the form of key, values and effects entries added when registering the node in the cluster." +tags = [ + "labels-and-taints" +] +note = "Remember to quote keys (since they often contain `.`) and to quote all values." +see = [ + ["[Taints and Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)"] +] + +[[docs.ref.node-taints.example]] +[[docs.ref.node-taints.example.multiline]] +"dedicated" = '["experimental:PreferNoSchedule", "experimental:NoExecute"]' +"special" = '["true:NoSchedule"]' + +[[docs.ref.cluster-dns-ip]] +description = """ +The IP of the DNS service running in the cluster. +On AWS variants, this is derived from the EKS Service IP CIDR or the CIDR block of the primary network interface. +This value can be set as a string containing a single IP address, or as a list containing multiple IP addresses. +""" +see = [ + ["[`clusterDNS` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + ["[`--cluster-dns` in Kubelet Options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options)"] +] + +[[docs.ref.cluster-dns-ip.example]] +comment = "Valid, single IP" +value = "\"10.0.0.1\"" +[[docs.ref.cluster-dns-ip.example]] +comment = "Also valid, multiple nameserver IPs" +value = "[\"10.0.0.1\", \"10.0.0.2\"]" + +[[docs.ref.allowed-unsafe-sysctls]] +description= "Enables specified list of unsafe sysctls." +see = [ + [ "[Using sysctls in a Kubernetes Cluster](https://kubernetes.io/docs/tasks/administer-cluster/sysctl-cluster/)" ], + [ "[`allowedUnsafeSysctls` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"] +] + +[[docs.ref.allowed-unsafe-sysctls.example]] +value = "[\"net.core.somaxconn\", \"net.ipv4.ip_local_port_range\"]" +[[docs.ref.authentication-mode]] +description = "The authentication method kubelet should use to connect to the API server, and for incoming requests." +default = "`aws` for AWS variants, `tls` for other variants" +see = [ + ["settings", "kubernetes", "bootstrap-token" ] +] + +[[docs.ref.cloud-provider]] +description= "The cloud provider for the cluster." +default= "`aws` for AWS variants, `external` for other variants" +see = [ + [ "[kubernetes/cloud-provider](https://github.com/kubernetes/cloud-provider)"], + [ "[`--cloud-provider` in Kubelet Options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options)"] +] + +[[docs.ref.cluster-domain]] +description= "The DNS domain for the cluster, allowing all Kubernetes-run containers to search this domain before the host's search domains" +default= "`cluster.local`" +see = [ + ["[`clusterDomain` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + ["[`--cluster-domain` in Kubelet Options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options)"] +] + + +[[docs.ref.container-log-max-files]] +description= "The maximum number of container log files that can be present for a container." +see = [ + [ "[`containerLogMaxFiles` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + [ "[Logging Architecture](https://kubernetes.io/docs/concepts/cluster-administration/logging/#log-rotation)"] +] + +[[docs.ref.container-log-max-size]] +description= "The maximum size of container log file before it is rotated." +see = [ + [ "[`containerLogMaxSize` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + [ "[Logging Architecture](https://kubernetes.io/docs/concepts/cluster-administration/logging/#log-rotation)"] +] + +[[docs.ref.cpu-cfs-quota-enforced]] +description= "Whether CPU CFS quotas are enforced" +default= "`true`" +see = [ + [ "[`cpuCFSQuota` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"] +] +[[docs.ref.cpu-manager-policy]] +description= """ +Specifies the CPU manager policy. +If you want to allow pods with certain resource characteristics to be granted increased CPU affinity and exclusivity on the node, you can set this setting to `static`. +You should reboot if you change this setting after startup - try `apiclient reboot` +""" +accepted_values = [ + "`static`", + "`none`" +] +default = "`none`" +see = [ + ["[`cpuManagerPolicy` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + [ "settings", "kubernetes","cpu-manager-policy-options" ] +] + +[[docs.ref.cpu-manager-policy-options]] +description = """ +Policy options to apply when `settings.kubernetes.cpu-manager-policy` is set to `static`. +There currently there is only one allowed option, so the default is implict if not the setting is not defined. +""" +see = [ + ["[Static policy options](https://kubernetes.io/docs/tasks/administer-cluster/cpu-management-policies/#static-policy-options)"], + ["[`cpuManagerPolicyOptions` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + ["settings", "kubernetes", "cpu-manager-policy-options"], +] +accepted_values = [ + "`full-pcpus-only`" +] + +[[docs.ref.cpu-manager-policy-options.example]] +comment = "When `settings.kubernetes.cpu-manager-policy` is set to `static`" +value = "[\"full-pcpus-only\"]" + +[[docs.ref.cpu-manager-reconcile-period]] +description = """ +Specifies the CPU manager reconcile period, which controls how often updated CPU assignments are written to cgroupfs. +The value is a duration like `30s` for 30 seconds or `1h5m` for 1 hour and 5 minutes. +""" +see = [ + ["[`cpuManagerReconcilePeriod` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"] +] + +[[docs.ref.credential-providers]] +description = """ +Contains a collection of Kubelet image credential provider settings. +Each key under this setting is the name of the plugin to configure. See Example 1 below. +The `ecr-credential-provider` plugin can also be used for AWS IAM Roles Anywhere support. +IAM Roles Anywhere is configured using the [`settings.aws.config`](../aws#config) setting. +The content of that setting needs to configure the `credential_process` using the `aws_signing_helper` using your IAM Roles Anywhere settings, see Example 2 below. +""" +note = "`ecr-credential-provider` is currently the only supported provider. To manage its AWS credentials, see the `settings.aws.config` and `settings.aws.credentials` settings." + +see = [ + ["[Roles Anywhere documentation on `aws_signing_helper` arguments](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/credential-helper.html)"] +] + +[[docs.ref.credential-providers.example]] +direct_toml = """ +# Example 1: user data for configuring the `ecr-credential-provider` credential provider plug-in +[settings.kubernetes.credential-providers.ecr-credential-provider] +enabled = true +# (optional - defaults to "12h") +cache-duration = "30m" +image-patterns = [ + # One or more URL paths to match an image prefix. Supports globbing of subdomains. + "*.dkr.ecr.us-east-2.amazonaws.com", + "*.dkr.ecr.us-west-2.amazonaws.com" +] + +[settings.kubernetes.credential-providers.ecr-credential-provider.environment] +# The following are not used with ecr-credential-provider, but are provided for illustration +"KEY" = "abc123xyz" +"GOMAXPROCS" = "2" +""" + +[[docs.ref.credential-providers.example]] +direct_toml = """ +# Example 2: `credential_process` using the `aws_signing_helper` +[default] +region = us-west-2 +credential_process = aws_signing_helper credential-process \ + --certificate /var/lib/kubelet/pki/kubelet-client-current.pem \ + --private-key /var/lib/kubelet/pki/kubelet-client-current.pem \ + --profile-arn [profile ARN] + --role-arn [role ARN] + --trust-anchor-arn [trust anchor ARN] +""" + + + + +[[docs.ref.event-burst]] +description = "The maximum size of a burst of event creations." +see = [ + [ "[`eventBurst` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.event-qps]] +description = "The maximum event creations per second." +see = [ + [ "[`eventRecordQPS` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + + +[[docs.ref.image-gc-high-threshold-percent]] +description = """ +The percent of disk usage after which image garbage collection is always run, expressed as an integer from 0-100 inclusive. + +If you downgrade from 1.14.0 to an earlier version, the values will be automatically converted to strings. +""" +see = [ + ["[`imageGCHighThresholdPercent` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + [ "settings", "kubernetes", "image-gc-low-threshold-percent"] +] + +[[docs.ref.image-gc-high-threshold-percent.example]] +comment = "After 1.14.0, the value can be represented as a integer or string for backwards compatiblity." +value = 85 +[[docs.ref.image-gc-high-threshold-percent.example]] +comment = "Before 1.14.0, the value must be represented as a string." +value = "\"85\"" + +[[docs.ref.kube-api-burst]] +description = "The burst to allow while talking with kubernetes." +see = [ + ["[`kubeAPIBurst` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.kube-api-qps]] +description = " The QPS to use while talking with kubernetes apiserver." +see = [ + ["[`kubeAPIQPS` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.log-level]] +description = "The logging verbosity of the kubelet process. Higher numbers enabling more verbose logging." +default = "2" +see = [ + ["[`--v Level` in Kubelet Options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options)"] +] + +[[docs.ref.memory-manager-policy]] +description = """ +The memory management policy to use: `None` or `Static`. +When using the `Static` policy you should also set `settings.kubernetes.memory-manager-reserved-memory` values. +""" +default = "`None`" +see = [ + [ "[`memoryManagerPolicy` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + [ "settings", "kubernetes","memory-manager-reserved-memory"] +] + + +[[docs.ref.memory-manager-reserved-memory]] +description = """ +Set the total amount of reserved memory for a node. +`settings.kubernetes.memory-manager-reserved-memory` is set per NUMA node. +These settings are used to configure memory manager policy when `settings.kubernetes.memory-manager-policy` is set to `Static`. +""" +warning = """ +`memory-manager-reserved-memory` settings are an advanced configuration and requires a clear understanding of what you are setting. +Misconfiguration of reserved memory settings may cause the Kubernetes `kubelet` process to fail. +It can be very difficult to recover from configuration errors. +Use the memory reservation information from `kubectl describe node` and make sure you understand the Kubernetes documentation related to the [memory manager](https://kubernetes.io/docs/tasks/administer-cluster/memory-manager/) and [how to reserve compute resources for system daemons](https://kubernetes.io/docs/tasks/administer-cluster/reserve-compute-resources/). +""" +see = [ + ["[Utilizing the NUMA-aware Memory Manager](https://kubernetes.io/docs/tasks/administer-cluster/memory-manager/#reserved-memory-flag)"] +] +[[docs.ref.memory-manager-reserved-memory.example]] +direct_toml = """ +[settings.kubernetes] +"memory-manager-policy" = "Static" + +[settings.kubernetes.memory-manager-reserved-memory.0] +# Reserve a single 1GiB huge page along with 674MiB of memory +"enabled" = true +"memory" = "674Mi" +"hugepages-1Gi" = "1Gi" + +[settings.kubernetes.memory-manager-reserved-memory.1] +# Reserve 1,074 2MiB huge pages +"enabled" = true +"hugepages-2Mi" = "2148Mi" +""" + +[[docs.ref.image-gc-low-threshold-percent]] +description = """ +The percent of disk usage before which image garbage collection is never run, expressed as an integer from 0-100 inclusive. + +If you downgrade from 1.14.0 to an earlier version, the values will be automatically converted to strings. +""" +see = [ + ["[`imageGCLowThresholdPercent` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + [ "settings", "kubernetes", "image-gc-high-threshold-percent"] +] +[[docs.ref.image-gc-low-threshold-percent.example]] +comment = "After 1.14.0, the value can be represented as a integer or string for backwards compatiblity." +value = 80 + + +[[docs.ref.image-gc-low-threshold-percent.example]] +comment = "Before 1.14.0, the value must be represented as a string." +value = "\"80\"" + +[[docs.ref.pod-pids-limit]] +description = "The maximum number of processes per pod." +see = [ + [ "[`podPidsLimit` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.provider-id]] +description = "The way an external provider identifies a node." +see = [ + [ "[`providerID` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.registry-burst]] +description = "The maximum size of bursty pulls." +see = [ + [ "[`registryBurst` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.registry-qps]] +description = "The registry pull QPS." +see = [ + [ "[`registryPullQPS` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.server-tls-bootstrap]] +description = """ +Enables or disables server certificate bootstrap. +When enabled, the kubelet will request a certificate from the certificates.k8s.io API. +This requires an approver to approve the certificate signing requests (CSR). +""" +default = "`true`" +see = [ + [ "[`serverTLSBootstrap` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.shutdown-grace-period]] +description = "Delay the node should wait for pod termination before shutdown." +default = "`0s`" +see = [ + [ "[`shutdownGracePeriod` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.shutdown-grace-period-for-critical-pods]] +description = "The portion of the shutdown delay that should be dedicated to critical pod shutdown. Default is 0s." +default = "`false`" +see = [ + [ "[`shutdownGracePeriodCriticalPods` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.system-reserved]] +description = "Resources reserved for system components." +see = [ + [ "[`systemReserved` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.system-reserved.example]] +comment = "Example user data for setting up system reserved" +[[docs.ref.system-reserved.example.multiline]] +cpu = "\"10m\"" +memory = "\"100Mi\"" +ephemeral-storage= "\"1Gi\"" + +[[docs.ref.server-certificate]] +description = "The base64 encoded content of an x509 certificate for the kubelet web server, which is used for retrieving logs and executing commands." +see = [ + ["[`--tls-cert-file` in Kubelet Options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options)"] +] + +[[docs.ref.server-key]] +description = "The base64 encoded content of an x509 private key for the kubelet web server." +see = [ + ["[`--tls-key-file` in Kubelet Options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options)"] +] + +[[docs.ref.topology-manager-policy]] +description = """ +Specifies the topology manager policy. +""" +default = "`none`" +see = [ + ["[`topologyManagerPolicy` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + ["[Utilizing the NUMA-aware Memory Manager](https://kubernetes.io/docs/tasks/administer-cluster/memory-manager/#reserved-memory-flag)"] +] +accepted_values = [ + "`none`", + "`restricted`", + "`best-effort`", + "`single-numa-node`" +] + +[[docs.ref.topology-manager-scope]] +description = """ +Specifies the topology manager scope. +If you want to group all containers in a pod to a common set of NUMA nodes, you can set this setting to pod. +""" +default = "`container`" +see = [ + ["[`topologyManagerPolicy` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + ["[Utilizing the NUMA-aware Memory Manager](https://kubernetes.io/docs/tasks/administer-cluster/memory-manager/#reserved-memory-flag)"] +] +accepted_values = [ + "`container`", + "`pod`" +] + +[[docs.ref.eviction-hard]] +description = """ +The signals and thresholds that trigger pod eviction. +Keys are signals and must be quoted since they contain a dot (`.`). +""" +see = [ + ["[`evictionHard` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + ["settings", "kubernetes", "eviction-soft"] +] + +[[docs.ref.eviction-hard.example]] +[[docs.ref.eviction-hard.example.multiline]] +"\"memory.available\"" = "\"15%\"" + + +[[docs.ref.eviction-max-pod-grace-period]] +description = "Maximum grace period, in seconds, to wait for pod termination before soft eviction." +default = "0" +see = [ + ["[`evictionMaxPodGracePeriod` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + ["settings", "kubernetes", "eviction-soft"] +] +[[docs.ref.eviction-max-pod-grace-period.example]] +value= 40 + + +[[docs.ref.eviction-soft]] +description = "The signals and thresholds that trigger pod eviction with a provided grace period (`settings.kubernetes.eviction-soft-grace-period`). Keys are signals and must be quoted since they contain a dot (`.`)." +see = [ + ["[`evictionSoft` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + ["settings", "kubernetes", "eviction-hard"], + ["settings", "kubernetes", "eviction-max-pod-grace-period"], + ["settings", "kubernetes", "eviction-soft-grace-period"] +] + +[[docs.ref.eviction-soft.example]] +[[docs.ref.eviction-soft.example.multiline]] +"\"memory.available\"" = "\"12%\"" + + +[[docs.ref.eviction-soft-grace-period]] +description = """ +Delay for each signal to wait for pod termination before eviction. +Keys are signals and must be quoted since they contain a dot (`.`). +""" +see = [ + ["[`evictionSoftGracePeriod` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)"], + ["settings", "kubernetes", "eviction-soft"] +] + +[[docs.ref.eviction-soft-grace-period.example]] +[[docs.ref.eviction-soft-grace-period.example.multiline]] +"\"memory.available\"" = "\"30s\"" + +[[docs.ref.standalone-mode]] +description = """ +It `true`, kubelet runs in standalone mode without connecting to an API server. +""" +accepted_values = [ + "`true`", + "`false`" +] +tags = [ + "static-pods" +] +default = "`false`" + +[[docs.ref.customid_enabled]] +description= "Whether the static pod is enabled." +name_override="static-pods.<custom identifier>.enabled" +tags = [ + "static-pods" +] +see = [ + [ "settings", "kubernetes", "customid_manifest" ] +] + +[[docs.ref.customid_manifest]] +description= "A base64-encoded pod manifest." +name_override="static-pods.<custom identifier>.manifest" +tags = [ + "static-pods" +] +see = [ + [ "settings", "kubernetes", "customid_enabled" ] +] + +[[docs.ref.kube-reserved]] +description = """ +Resources reserved for node components. The following keys are valid: +- `cpu`: in millicores from the total number of vCPUs available on the instance. +- `memory`: in mebibytes from the max num of pods on the instance. `memory_to_reserve = max_num_pods * 11 + 255`. +- `ephemeral-storage`: defaults to `1Gi`. +""" +see = [ + [ "[`kubeReserved` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + + +[[docs.ref.node-ip]] +description = "The IP address of the node." + +[[docs.ref.pod-infra-container-image]] +description = "The URI of the 'pause' container." +see = [ + [ "[`--pod-infra-container-image` in Kubelet Options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options)" ] +] + +[[docs.ref.max-pods]] +description = "The maximum number of pods that can be scheduled on this node (limited by number of available IPv4 addresses)." +see = [ + [ "[`maxPods` in Kubelet Configuration](https://kubernetes.io/docs/reference/config-api/kubelet-config.v1beta1/)" ] +] + +[[docs.ref.hostname-override]] +description = "The node name kubelet uses as identification instead of the hostname or the name determined by the in-tree cloud provider if that's enabled." +warning = """ +Changing this setting at runtime (not via user-data) can cause issues with kubelet registration, as hostname is closely tied to the identity of the system for both registration and certificates/authorization purposes. + +Most users don't need to change this setting. +If left unset, the system hostname will be used instead. The `settings.network.hostname` setting can be used to specify the value for both kubelet and the host. +Only set this override if you intend for the kubelet to register with a different name than the host. + +For `aws-k8s-1.26` variants, which use the "external" cloud provider, a hostname override will be automatically generated by querying the EC2 API for the private DNS name of the instance. This is done for backwards compatibility with the deprecated "aws" cloud provider, which adjusted the hostname in a similar way. Future `aws-k8s-*` variants may remove this behavior. +""" + +see = [ + ["[`--hostname-override` in Kubelet Options](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet/#options)"] +] + +[[docs.ref.seccomp-default]] +description = "Enable `RuntimeDefault` as the default seccomp profile for all workloads via `kubelet-configuration`" +default= "`false`" +accepted_values = [ + "`true`", + "`false`" +] diff --git a/data/settings/1.22.x/metrics.toml b/data/settings/1.22.x/metrics.toml new file mode 100644 index 00000000..56185f3d --- /dev/null +++ b/data/settings/1.22.x/metrics.toml @@ -0,0 +1,29 @@ +[[docs.ref.metrics-url]] +description = "The URL where Bottlerocket sends metrics." +default = "`https://metrics.bottlerocket.aws/v1/metrics`" + +[[docs.ref.send-metrics]] +description = """ +Determines if anonymous metrics are sent. +If set to `true`, Bottlerocket will send metrics to the URL defined by `settings.metrics.metrics-url` at boot and every six hours. +If `false`, Bottlerocket will not send metrics. +""" +accepted_values = [ + "`true`", + "`false`" +] +default = "`true` (except on `dev` variants, where it is `false`)" + +[[docs.ref.service-checks]] +description = "A list of systemd services that Bottlerocket will check to determine if a host is healthy." +default = """The default services vary by variant: + +- `apiserver` (all variants) +- `chronyd` (all variants) +- `containerd` (all variants) +- `host-containerd` (all variants) +- `docker` (`aws-ecs-*`, `aws-dev-*`) +- `ecs` (`aws-ecs-*`) +- `kubelet` (`*-k8s-*`) +- `vmtoolsd` (`vmware-*`) +""" diff --git a/data/settings/1.22.x/motd.toml b/data/settings/1.22.x/motd.toml new file mode 100644 index 00000000..85af356f --- /dev/null +++ b/data/settings/1.22.x/motd.toml @@ -0,0 +1,5 @@ +top_level= true +[[docs.ref]] +description= "Changes the message of the day by writing out value to `/etc/motd`. Useful, low-risk way to try out the API." +[[docs.ref.example]] +value = "\"This is a mesage of the day.\"" diff --git a/data/settings/1.22.x/network.toml b/data/settings/1.22.x/network.toml new file mode 100644 index 00000000..b0f55337 --- /dev/null +++ b/data/settings/1.22.x/network.toml @@ -0,0 +1,92 @@ +[[docs.tag.proxy-settings]] +description = """ +The proxy settings configure the behaviour of several services depending on your variant: + +- On **all variants** proxy settings affect [containerd.service](https://github.com/bottlerocket-os/bottlerocket/blob/develop/packages/containerd/containerd.service) and [host-containerd.service](https://github.com/bottlerocket-os/bottlerocket/blob/develop/packages/host-ctr/host-containerd.service). +- On **Kubernetes variants** (`*-k8s-*`) proxy settings also affect the [kubelet.service](https://github.com/bottlerocket-os/bottlerocket/blob/develop/packages/kubernetes-1.18/kubelet.service). +- On **ECS variants** (`*-ecs-*` and `*-ecs-2-*`) proxy settings also affect the [docker.service](https://github.com/bottlerocket-os/bottlerocket/blob/develop/packages/docker-engine/docker.service) and the [ecs.service](https://github.com/bottlerocket-os/bottlerocket/blob/develop/packages/ecs-agent/ecs.service). +""" +heading = "Proxy Settings" + +[[docs.ref.hostname]] +description = """ +Sets the hostname of the node to the defined value. + +Typically, you do not need to change this setting; in the majority of the cases the default will suffice. +""" +default = """ +If unset, DNS reverse lookup determines the hostname. +If DNS reverse lookup fails, the hostname is the IP address of the node. +""" +warning = """ +On Kubernetes variants changing `settings.network.hostname` at runtime (as opposed to with user data) may cause issues with kubelet registration. +""" + +[[docs.ref.hosts]] +description = """ +A mapping of IP addresses to domain names. +This setting modifies the node's `/etc/hosts` file. +""" +note = "This setting does not typically impact name resolution for orchestrated containers." +see = [ + ["[Name resolution for ECS](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_HostEntry.html) orchestrated containers."], + ["[Name resolution for Kubernetes](https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/) orchestrated containers."] +] +[[docs.ref.hosts.example]] +direct_toml = """ +[settings.network] +hosts =[ + ["10.0.0.0", ["test.example.com", "test1.example.com"] ], + ["10.1.1.1", ["test2.example.com"] ] +] + +# results in a `/etc/hosts` file: +# 10.0.0.0 test.example.com test1.example.com +# 10.1.1.1 test2.example.com +""" +[[docs.ref.hosts.example]] +direct_toml = """ +# Repeated entries are merged (including loopback entries), with the first aliases listed taking precedence. + +[settings.network] +hosts = [ + ["10.0.0.0", ["test.example.com", "test1.example.com"]], + ["10.1.1.1", ["test2.example.com"]], + ["10.0.0.0", ["test3.example.com"]], +] + +# results in `/etc/hosts` file: +# 10.0.0.0 test.example.com test1.example.com test3.example.com +# 10.1.1.1 test2.example.com +""" + +[[docs.ref.https-proxy]] +description = """ +The HTTPS proxy server used by services listed under [proxy settings](#tag-proxy-settings) section. +""" +accepted_values = [ + "A host name (with an optional port number)", + "An IP address (with an optional port number)" +] +tags = [ + "proxy-settings" +] +[[docs.ref.https-proxy.example]] +value = "\"1.2.3.4:8080\"" + +[[docs.ref.no-proxy]] +description = """ +A list of hosts that Bottlerocket will excluded from proxying. + +The no-proxy list automatically includes entries for `localhost`. + +On Kubernetes variants (`*-k8s-*`) the no-proxy lists includes the Kubernetes API server endpoint as well as other commonly used Kubernetes DNS suffixes. +""" +accepted_values = [ + "List of host names and IP addresses" +] +tags = [ + "proxy-settings" +] +[[docs.ref.no-proxy.example]] +value = "[\"localhost\", \"127.0.0.1\"]" diff --git a/data/settings/1.22.x/ntp.toml b/data/settings/1.22.x/ntp.toml new file mode 100644 index 00000000..b711dba4 --- /dev/null +++ b/data/settings/1.22.x/ntp.toml @@ -0,0 +1,7 @@ +[[docs.ref.time-servers]] +description = """ +A list of NTP servers to set and verify the system time. +""" +accepted_values = [ "hostnames", "IP addresses" ] +[[docs.ref.time-servers.example]] +value = "[\"169.254.169.123\", \"time.aws.com\"]" diff --git a/data/settings/1.22.x/oci-defaults.toml b/data/settings/1.22.x/oci-defaults.toml new file mode 100644 index 00000000..b9372b2a --- /dev/null +++ b/data/settings/1.22.x/oci-defaults.toml @@ -0,0 +1,792 @@ +# tags +[[docs.tag.capabilities]] +heading = "Capabilities Settings" +description = """Capabilities for the runtime process. +These correspond to the object [`capabilities` in the runtime spec](https://github.com/opencontainers/runtime-spec/blob/main/config.md#linux-process). +""" + +[[docs.tag.resource-limits]] +heading = "Resource Limits Settings" +description = """ +Resource limits for the runtime process. +These correspond to the object [`rlimit` in the runtime spec](https://github.com/opencontainers/runtime-spec/blob/main/config.md#posix-process). + +Unusual among Bottlerocket settings, individual key/values will not validate. You must provide both `hard-limit` and `soft-limit` for any given resource limit setting at the same time. +Consequently, using dot-notation expressions to change resource limits is not possible (e.g. `apiclient set settings.oci-defaults.resource-limits.max-locked-memory.hard-limit=9223372` will fail). +You can use TOML configuration format or the same structure expressed as JSON to set both keys simultaneously. +""" +[[docs.tag.resource-limits.example]] +tab = "TOML" +type = "toml" +source = """ +# Setting a limit +[settings.oci-defaults.resource-limits.max-core-file-size] +soft-limit = 100000000 +hard-limit = 1000000000 + +# Removing a hard limit +[settings.oci-defaults.resource-limits.max-locked-memory] +soft-limit = 100000000 +hard-limit = "unlimited" +""" + +[[docs.tag.resource-limits.example]] +tab = "API Client with JSON" +type = "shell" +source = """ +# Setting a limit +apiclient set --json <<EOF +{ + "settings": { + "oci-defaults": { + "resource-limits": { + "max-core-file-size": { + "soft-limit": 100000000, + "hard-limit": 1000000000 + } + } + } + } +} +EOF + +# Removing a hard limit +apiclient set --json <<EOF +{ + "settings": { + "oci-defaults": { + "resource-limits": { + "max-core-file-size": { + "soft-limit": 100000000, + "hard-limit": "unlimited" + } + } + } + } +} +EOF +""" + + +# settings +[[docs.ref.capabilities_audit-write]] +name_override = "capabilities.audit-write" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_AUDIT_WRITE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_chown]] +name_override = "capabilities.chown" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_CHOWN` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_dac-override]] +name_override = "capabilities.dac-override" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_DAC_OVERRIDE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_fowner]] +name_override = "capabilities.fowner" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_FOWNER` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_fsetid]] +name_override = "capabilities.fsetid" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_FSETID` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_kill]] +name_override = "capabilities.kill" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_KILL` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_mknod]] +name_override = "capabilities.mknod" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_MKNOD` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_net-bind-service]] +name_override = "capabilities.net-bind-service" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_NET_BIND_SERVICE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_setgid]] +name_override = "capabilities.setgid" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SETGID` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_setfcap]] +name_override = "capabilities.setfcap" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SETFCAP` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_setpcap]] +name_override = "capabilities.setpcap" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SETPCAP` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_setuid]] +name_override = "capabilities.setuid" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SETUID` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-chroot]] +name_override = "capabilities.sys-chroot" +tags = [ "capabilities" ] +default = "`true`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYS_CHROOT` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_audit-control]] +name_override = "capabilities.audit-control" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_AUDIT_CONTROL` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_audit-read]] +name_override = "capabilities.audit-read" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_AUDIT_READ` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_block-suspend]] +name_override = "capabilities.block-suspend" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_BLOCK_SUSPEND` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_bpf]] +name_override = "capabilities.bpf" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_BPF` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_checkpoint-restore]] +name_override = "capabilities.checkpoint-restore" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_CHECKPOINT_RESTORE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_dac-read-search]] +name_override = "capabilities.dac-read-search" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_DAC_READ_SEARCH` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_ipc-lock]] +name_override = "capabilities.ipc-lock" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_IPC_LOCK` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_ipc-owner]] +name_override = "capabilities.ipc-owner" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_IPC_OWNER` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_lease]] +name_override = "capabilities.lease" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_LEASE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_linux-immutable]] +name_override = "capabilities.linux-immutable" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_LINUX_IMMUTABLE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_mac-admin]] +name_override = "capabilities.mac-admin" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_MAC_ADMIN` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + + +[[docs.ref.capabilities_mac-override]] +name_override = "capabilities.mac-override" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_MAC_OVERRIDE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_net-admin]] +name_override = "capabilities_net-admin" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_NET_ADMIN` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_net-broadcast]] +name_override = "capabilities.net-broadcast" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_NET_BROADCAST` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_net-raw]] +name_override = "capabilities.net-raw" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_NET_RAW` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_perfmon]] +name_override = "capabilities.perfmon" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_PERFMON` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-admin]] +name_override = "capabilities.sys-admin" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYS_ADMIN` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-boot]] +name_override = "capabilities.sys-boot" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYS_BOOT` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-module]] +name_override = "capabilities.sys-module" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYS_MODULE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-nice]] +name_override = "capabilities.sys-nice" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYS_NICE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-pacct]] +name_override = "capabilities.sys-pacct" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYS_PACCT` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-ptrace]] +name_override = "capabilities.sys-ptrace" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYS_PTRACE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-rawio]] +name_override = "capabilities.sys-rawio" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYS_RAWIO` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-resource]] +name_override = "capabilities.sys-resource" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYS_RESOURCE` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-time]] +name_override = "capabilities.sys-time" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["CAP_SYS_TIME`` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_sys-tty-config]] +name_override = "capabilities.sys-tty-config" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYS_TTY_CONFIG` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_syslog]] +name_override = "capabilities.syslog" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_SYSLOG` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.capabilities_wake-alarm]] +name_override = "capabilities.wake-alarm" +tags = [ "capabilities" ] +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["`CAP_WAKE_ALARM` on the [Linux `capabilities` manual page](https://man7.org/linux/man-pages/man7/capabilities.7.html)"] +] + +[[docs.ref.resource-limits_max-address-space]] +name_override = "resource-limits.max-address-space" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +Uses *bytes* as an implicit value unit. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_AS` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-core-file-size]] +name_override = "resource-limits.max-core-file-size" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +Uses *bytes* as an implicit value unit. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_CORE` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-cpu-time]] +name_override = "resource-limits.max-cpu-time" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +Uses *seconds* as an implicit unit. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_CPU` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-data-size]] +name_override = "resource-limits.max-data-size" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +Uses *bytes* as an implicit value unit. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_DATA` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-file-locks]] +name_override = "resource-limits.max-file-locks" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +The value is unit-less, representing the *number of locks*. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_LOCKS` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-file-size]] +name_override = "resource-limits.max-file-size" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +Uses *bytes* as an implicit value unit. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_FSIZE` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-locked-memory]] +name_override = "resource-limits.max-locked-memory" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +Uses *bytes* as an implicit value unit. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_MEMLOCK` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-msgqueue-size]] +name_override = "resource-limits.max-msgqueue-size" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +Uses *bytes* as an implicit value unit. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_MSGQUEUE` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-nice-priority]] +name_override = "resource-limits.max-nice-priority" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +The value is unit-less, representing niceness. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: Practical values range from `1` to `40`, however the technically accepted values are `0` to `9223372036854775807` (i.e. `int64::MAX`).", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_NICE` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-open-files]] +name_override = "resource-limits.max-open-files" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +The value is unit-less, representing the *number of files*. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +default = "`soft-limit` is `65536` and `hard-limit` is `1048576`" +see = [ + ["`RLIMIT_NOFILE` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-pending-signals]] +name_override = "resource-limits.max-pending-signals" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +The value is unit-less, representing the *number of singals*. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_SIGPENDING` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-processes]] +name_override = "resource-limits.max-processes" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +The value is unit-less, representing the *number of procceses*. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_NPROC` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-realtime-priority]] +name_override = "resource-limits.max-realtime-priority" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +The value is unit-less, representing *priority*. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_RTPRIO` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-realtime-timeout]] +name_override = "resource-limits.max-realtime-timeout" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +Uses *microseconds* as an implicit value unit. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_RTTIME` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-resident-set]] +name_override = "resource-limits.max-resident-set" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +Uses *bytes* as an implicit value unit. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_RSS` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] + +[[docs.ref.resource-limits_max-stack-size]] +name_override = "resource-limits.max-stack-size" +description = """ +A [TOML table](https://toml.io/en/v1.0.0#table). +Validation requires a key/value for both `soft-limit` and `hard-limit`. +Uses *bytes* as an implicit value unit. +""" +tags = [ "resource-limits" ] +accepted_values = [ + "Setting a limit: `0` to `9223372036854775807` (i.e. `int64::MAX`)", + "Removing a limit: `-1` or `\"unlimited\"`" +] +see = [ + ["`RLIMIT_STACK` on the [Linux `getrlimit` manual page](https://man7.org/linux/man-pages/man2/getrlimit.2.html)"] +] diff --git a/data/settings/1.22.x/oci-hooks.toml b/data/settings/1.22.x/oci-hooks.toml new file mode 100644 index 00000000..6d934237 --- /dev/null +++ b/data/settings/1.22.x/oci-hooks.toml @@ -0,0 +1,17 @@ +[[docs.ref.log4j-hotpatch-enabled]] +deprecated = true +accepted_values = [ + "`true`", + "`false`" +] +description = """ +The log4j hotpatch functionality is no longer included in Bottlerocket as of v1.15.0. +The setting still exists for backwards compatibility. + +If set to `true`, it prints the following message to the system logs: + +``` +The setting "oci-hooks.log4j-hotpatch-enabled" has no effect. It will be removed in future versions of Bottlerocket. +``` + +""" diff --git a/data/settings/1.22.x/pki.toml b/data/settings/1.22.x/pki.toml new file mode 100644 index 00000000..354166e5 --- /dev/null +++ b/data/settings/1.22.x/pki.toml @@ -0,0 +1,37 @@ +[[docs.ref.pki_bundle-name_data]] +name_override = "<bundle-name>.data" +description = "A Base64-encoded PEM-formatted certificate bundle; this setting can contain more than one certificate." +note = """ +Defining a certificate bundle with `data` but without [`trusted`](#pki_bundle-name_trusted) results in an untrusted bundle. +""" +[[docs.ref.pki_bundle-name_data.example]] +direct_toml = """ +[settings.pki.some-bundle] +data="W3N..." +""" +direct_shell = """ +apiclient set \ + pki.some-bundle.data="W3N..." +""" + +[[docs.ref.pki_bundle-name_trusted]] +name_override = "<bundle-name>.trusted" +description = "Defines if the bundle in `<bundle-name>` should be trusted." +default = "`false`" +[[docs.ref.pki_bundle-name_trusted.example]] +direct_toml = """ +[settings.pki.my-trusted-bundle] +data="W3N..." +trusted=true + +[settings.pki.dont-trust-these] +data="W3N..." +trusted=false +""" +direct_shell = """ +apiclient set \\ + pki.my-trusted-bundle.data="W3N..." \\ + pki.my-trusted-bundle.trusted=true \\ + pki.dont-trust-these.data="N3W..." \\ + pki.dont-trust-there.trusted=false +""" diff --git a/data/settings/1.22.x/updates.toml b/data/settings/1.22.x/updates.toml new file mode 100644 index 00000000..42c74f27 --- /dev/null +++ b/data/settings/1.22.x/updates.toml @@ -0,0 +1,66 @@ +[[docs.ref.ignore-waves]] +description = """ +Typically, updates roll out in waves. +To ignore update waves, set this value to `true` which will cause the node to update immediately. +""" +default = "`false`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["[Locking to a Specific Release](../../../update/locking-to-a-specific-release/)"], + ["[_Waves_ in Publishing Bottlerocket](https://github.com/bottlerocket-os/bottlerocket/blob/develop/PUBLISHING.md#waves)"] + +] + +[[docs.ref.metadata-base-url]] +description = """ +The common portion of all URIs used to download update metadata. +""" +accepted_values = [ + "A string containing a URI fragment" +] +see = [ + ["[_Using your repo from a Bottlerocket host_ in Publishing Bottlerocket](https://github.com/bottlerocket-os/bottlerocket/blob/develop/PUBLISHING.md#using-your-repo-from-a-bottlerocket-host)"] +] +[[docs.ref.metadata-base-url.example]] +value = "\"https://my-bucket.s3-us-west-2.amazonaws.com/aws-k8s-1.24/x86_64/\"" + + +[[docs.ref.seed]] +description = """ +A value that determines how far into the update schedule the node will accept an update. +Typically, you should leave this as the default random value to ensure that randomized updates in your cluster. +""" +accepted_values = [ + "Any `u32` value" +] +default = "A randomly generated `u32` value" + +[[docs.ref.targets-base-url]] +description = """ +The common portion of all URIs used to download update files. +""" +default = "`https://updates.bottlerocket.aws/targets/`" +accepted_values = [ + "A string containing a URI fragment" +] +see = [ + ["[_Using your repo from a Bottlerocket host_ in Publishing Bottlerocket](https://github.com/bottlerocket-os/bottlerocket/blob/develop/PUBLISHING.md#using-your-repo-from-a-bottlerocket-host)"] +] +[[docs.ref.targets-base-url.example]] +value = "\"https://my-bucket.s3-us-west-2.amazonaws.com/targets/\"" + +[[docs.ref.version-lock]] +description = """ +When you issue an update request, the value determines the selected version. +""" +default = "`latest`" +accepted_values = [ + "`v` plus a 3-part, dot seperated version number (e.g. `v1.0.0`)", + "`latest`" +] +see = [ + ["[Locking to a Specific Release](../../update/locking-to-a-specific-release/)"] +] diff --git a/data/variants/1.22.x/aws-dev.toml b/data/variants/1.22.x/aws-dev.toml new file mode 100644 index 00000000..67e10f4a --- /dev/null +++ b/data/variants/1.22.x/aws-dev.toml @@ -0,0 +1,51 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-dev/Cargo.toml +[package] +name = "aws-dev" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +xfs-data-partition = true +uefi-secure-boot = true +systemd-networkd = true + +[package.metadata.build-variant] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + # Only reserve if there are at least 2GB + "crashkernel=2G-:256M", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] +included-packages = [ +# core + "release", + "kernel-6.1", +# docker + "docker-cli", + "docker-engine", + "docker-init", +# tools + "login", + "iputils", + "strace", + "chrony-tools", + "soci-snapshotter", + "socat", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +# core +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-ecs-1-nvidia.toml b/data/variants/1.22.x/aws-ecs-1-nvidia.toml new file mode 100644 index 00000000..c8bfe7ee --- /dev/null +++ b/data/variants/1.22.x/aws-ecs-1-nvidia.toml @@ -0,0 +1,43 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-ecs-1-nvidia/Cargo.toml +[package] +name = "aws-ecs-1-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "systemd.unified_cgroup_hierarchy=0", + "quiet", +] +included-packages = [ +# core + "release", + "kernel-5.10", +# docker + "docker-cli", + "docker-engine", + "docker-init", +# ecs + "ecs-agent-nvidia-config", +# NVIDIA support + "ecs-gpu-init", + "nvidia-container-toolkit-ecs", + "kmod-5.10-nvidia-tesla-470", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-ecs-1.toml b/data/variants/1.22.x/aws-ecs-1.toml new file mode 100644 index 00000000..189e329b --- /dev/null +++ b/data/variants/1.22.x/aws-ecs-1.toml @@ -0,0 +1,36 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-ecs-1/Cargo.toml +[package] +name = "aws-ecs-1" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" + +[package.metadata.build-variant] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "systemd.unified_cgroup_hierarchy=0", + "quiet", +] +included-packages = [ +# core + "release", + "kernel-5.10", +# docker + "docker-cli", + "docker-engine", + "docker-init", +# ecs + "ecs-agent-config", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-ecs-2-nvidia.toml b/data/variants/1.22.x/aws-ecs-2-nvidia.toml new file mode 100644 index 00000000..82799571 --- /dev/null +++ b/data/variants/1.22.x/aws-ecs-2-nvidia.toml @@ -0,0 +1,49 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-ecs-2-nvidia/Cargo.toml +[package] +name = "aws-ecs-2-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant] +included-packages = [ +# core + "release", + "kernel-6.1", +# docker + "docker-cli", + "docker-engine", + "docker-init", +# ecs + "ecs-agent-nvidia-config", +# NVIDIA support + "ecs-gpu-init", + "nvidia-container-toolkit-ecs", + "kmod-6.1-nvidia-tesla-535", +] + +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-ecs-2.toml b/data/variants/1.22.x/aws-ecs-2.toml new file mode 100644 index 00000000..997a93e1 --- /dev/null +++ b/data/variants/1.22.x/aws-ecs-2.toml @@ -0,0 +1,43 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-ecs-2/Cargo.toml +[package] +name = "aws-ecs-2" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +included-packages = [ +# core + "release", + "kernel-6.1", +# docker + "docker-cli", + "docker-engine", + "docker-init", +# ecs + "ecs-agent-config", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.23-nvidia.toml b/data/variants/1.22.x/aws-k8s-1.23-nvidia.toml new file mode 100644 index 00000000..26dd0d13 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.23-nvidia.toml @@ -0,0 +1,46 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.23-nvidia/Cargo.toml +[package] +# This is the aws-k8s-1.23-nvidia variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_23-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant.image-features] +grub-set-private-var = true + +[package.metadata.build-variant] +included-packages = [ + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kernel-5.10", + "kubelet-1.23", + "release", + "nvidia-container-toolkit-k8s", + "nvidia-k8s-device-plugin", + "kmod-5.10-nvidia-tesla-470", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "systemd.unified_cgroup_hierarchy=0", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.23.toml b/data/variants/1.22.x/aws-k8s-1.23.toml new file mode 100644 index 00000000..a363b745 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.23.toml @@ -0,0 +1,40 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.23/Cargo.toml +[package] +# This is the aws-k8s-1.23 variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_23" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true + +[package.metadata.build-variant] +included-packages = [ + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kernel-5.10", + "kubelet-1.23", + "release", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "systemd.unified_cgroup_hierarchy=0", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.24-nvidia.toml b/data/variants/1.22.x/aws-k8s-1.24-nvidia.toml new file mode 100644 index 00000000..87430207 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.24-nvidia.toml @@ -0,0 +1,46 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.24-nvidia/Cargo.toml +[package] +# This is the aws-k8s-1.24-nvidia variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_24-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant.image-features] +grub-set-private-var = true + +[package.metadata.build-variant] +included-packages = [ + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kernel-5.15", + "kubelet-1.24", + "release", + "nvidia-container-toolkit-k8s", + "nvidia-k8s-device-plugin", + "kmod-5.15-nvidia-tesla-535", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "systemd.unified_cgroup_hierarchy=0", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.24.toml b/data/variants/1.22.x/aws-k8s-1.24.toml new file mode 100644 index 00000000..8555efe8 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.24.toml @@ -0,0 +1,40 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.24/Cargo.toml +[package] +# This is the aws-k8s-1.24 variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_24" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true + +[package.metadata.build-variant] +included-packages = [ + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kernel-5.15", + "kubelet-1.24", + "release", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "systemd.unified_cgroup_hierarchy=0", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.25-nvidia.toml b/data/variants/1.22.x/aws-k8s-1.25-nvidia.toml new file mode 100644 index 00000000..72b1b6f9 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.25-nvidia.toml @@ -0,0 +1,46 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.25-nvidia/Cargo.toml +[package] +# This is the aws-k8s-1.25-nvidia variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_25-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant.image-features] +grub-set-private-var = true + +[package.metadata.build-variant] +included-packages = [ + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kernel-5.15", + "kubelet-1.25", + "release", + "nvidia-container-toolkit-k8s", + "nvidia-k8s-device-plugin", + "kmod-5.15-nvidia-tesla-535", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "systemd.unified_cgroup_hierarchy=0", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.25.toml b/data/variants/1.22.x/aws-k8s-1.25.toml new file mode 100644 index 00000000..411a55cf --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.25.toml @@ -0,0 +1,40 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.25/Cargo.toml +[package] +# This is the aws-k8s-1.25 variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_25" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true + +[package.metadata.build-variant] +included-packages = [ + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kernel-5.15", + "kubelet-1.25", + "release", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "systemd.unified_cgroup_hierarchy=0", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.26-nvidia.toml b/data/variants/1.22.x/aws-k8s-1.26-nvidia.toml new file mode 100644 index 00000000..4be1f183 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.26-nvidia.toml @@ -0,0 +1,45 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.26-nvidia/Cargo.toml +[package] +# This is the aws-k8s-1.26-nvidia variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_26-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant.image-features] +grub-set-private-var = true + +[package.metadata.build-variant] +included-packages = [ + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kernel-5.15", + "kubelet-1.26", + "release", + "nvidia-container-toolkit-k8s", + "nvidia-k8s-device-plugin", + "kmod-5.15-nvidia-tesla-535", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.26.toml b/data/variants/1.22.x/aws-k8s-1.26.toml new file mode 100644 index 00000000..1d8bd6ba --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.26.toml @@ -0,0 +1,39 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.26/Cargo.toml +[package] +# This is the aws-k8s-1.26 variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_26" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true + +[package.metadata.build-variant] +included-packages = [ + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kernel-5.15", + "kubelet-1.26", + "release", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.27-nvidia.toml b/data/variants/1.22.x/aws-k8s-1.27-nvidia.toml new file mode 100644 index 00000000..4171776c --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.27-nvidia.toml @@ -0,0 +1,45 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.27-nvidia/Cargo.toml +[package] +# This is the aws-k8s-1.27-nvidia variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_27-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant.image-features] +grub-set-private-var = true + +[package.metadata.build-variant] +included-packages = [ + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kernel-5.15", + "kubelet-1.27", + "release", + "nvidia-container-toolkit-k8s", + "nvidia-k8s-device-plugin", + "kmod-5.15-nvidia-tesla-535", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.27.toml b/data/variants/1.22.x/aws-k8s-1.27.toml new file mode 100644 index 00000000..b9a610b2 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.27.toml @@ -0,0 +1,39 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.27/Cargo.toml +[package] +# This is the aws-k8s-1.27 variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_27" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true + +[package.metadata.build-variant] +included-packages = [ + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kernel-5.15", + "kubelet-1.27", + "release", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.28-nvidia.toml b/data/variants/1.22.x/aws-k8s-1.28-nvidia.toml new file mode 100644 index 00000000..35ad9608 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.28-nvidia.toml @@ -0,0 +1,51 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.28-nvidia/Cargo.toml +[package] +# This is the aws-k8s-1.28-nvidia variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_28-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +included-packages = [ + # core + "release", + "kernel-6.1", + # k8s + "cni", + "cni-plugins", + "kubelet-1.28", + "aws-iam-authenticator", + # nvidia + "nvidia-container-toolkit-k8s", + "nvidia-k8s-device-plugin", + "kmod-6.1-nvidia-tesla-535", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.28.toml b/data/variants/1.22.x/aws-k8s-1.28.toml new file mode 100644 index 00000000..6ea8dd8c --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.28.toml @@ -0,0 +1,44 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.28/Cargo.toml +[package] +# This is the aws-k8s-1.28 variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_28" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +included-packages = [ +# core + "release", + "kernel-6.1", +# k8s + "cni", + "cni-plugins", + "kubelet-1.28", + "aws-iam-authenticator", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.29-nvidia.toml b/data/variants/1.22.x/aws-k8s-1.29-nvidia.toml new file mode 100644 index 00000000..43979b8b --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.29-nvidia.toml @@ -0,0 +1,51 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.29-nvidia/Cargo.toml +[package] +# This is the aws-k8s-1.29-nvidia variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_29-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +included-packages = [ + # core + "release", + "kernel-6.1", + # k8s + "cni", + "cni-plugins", + "kubelet-1.29", + "aws-iam-authenticator", + # nvidia + "nvidia-container-toolkit-k8s", + "nvidia-k8s-device-plugin", + "kmod-6.1-nvidia-tesla-535", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.29.toml b/data/variants/1.22.x/aws-k8s-1.29.toml new file mode 100644 index 00000000..901045b7 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.29.toml @@ -0,0 +1,44 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.29/Cargo.toml +[package] +# This is the aws-k8s-1.29 variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_29" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +included-packages = [ +# core + "release", + "kernel-6.1", +# k8s + "cni", + "cni-plugins", + "kubelet-1.29", + "aws-iam-authenticator", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.30-nvidia.toml b/data/variants/1.22.x/aws-k8s-1.30-nvidia.toml new file mode 100644 index 00000000..0f8fa0f3 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.30-nvidia.toml @@ -0,0 +1,51 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.30-nvidia/Cargo.toml +[package] +# This is the aws-k8s-1.30-nvidia variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_30-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +included-packages = [ + # core + "release", + "kernel-6.1", + # k8s + "cni", + "cni-plugins", + "kubelet-1.30", + "aws-iam-authenticator", + # nvidia + "nvidia-container-toolkit-k8s", + "nvidia-k8s-device-plugin", + "kmod-6.1-nvidia-tesla-535", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.30.toml b/data/variants/1.22.x/aws-k8s-1.30.toml new file mode 100644 index 00000000..330bb0fd --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.30.toml @@ -0,0 +1,44 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.30/Cargo.toml +[package] +# This is the aws-k8s-1.30 variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_30" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +included-packages = [ +# core + "release", + "kernel-6.1", +# k8s + "cni", + "cni-plugins", + "kubelet-1.30", + "aws-iam-authenticator", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.31-nvidia.toml b/data/variants/1.22.x/aws-k8s-1.31-nvidia.toml new file mode 100644 index 00000000..fd1e65b3 --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.31-nvidia.toml @@ -0,0 +1,51 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.31-nvidia/Cargo.toml +[package] +# This is the aws-k8s-1.31-nvidia variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_31-nvidia" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +included-packages = [ + # core + "release", + "kernel-6.1", + # k8s + "cni", + "cni-plugins", + "kubelet-1.31", + "aws-iam-authenticator", + # nvidia + "nvidia-container-toolkit-k8s", + "nvidia-k8s-device-plugin", + "kmod-6.1-nvidia-tesla-535", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/aws-k8s-1.31.toml b/data/variants/1.22.x/aws-k8s-1.31.toml new file mode 100644 index 00000000..6d7c452d --- /dev/null +++ b/data/variants/1.22.x/aws-k8s-1.31.toml @@ -0,0 +1,44 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/aws-k8s-1.31/Cargo.toml +[package] +# This is the aws-k8s-1.31 variant. "." is not allowed in crate names, but we +# don't use this crate name anywhere. +name = "aws-k8s-1_31" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +included-packages = [ +# core + "release", + "kernel-6.1", +# k8s + "cni", + "cni-plugins", + "kubelet-1.31", + "aws-iam-authenticator", +] +kernel-parameters = [ + "console=tty0", + "console=ttyS0,115200n8", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/metal-dev.toml b/data/variants/1.22.x/metal-dev.toml new file mode 100644 index 00000000..977ab523 --- /dev/null +++ b/data/variants/1.22.x/metal-dev.toml @@ -0,0 +1,48 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/metal-dev/Cargo.toml +[package] +name = "metal-dev" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +partition-plan = "unified" + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +xfs-data-partition = true +uefi-secure-boot = true +systemd-networkd = true + +[package.metadata.build-variant] +image-format = "raw" +kernel-parameters = [ + # Only reserve if there are at least 2GB + "crashkernel=2G-:256M" +] +included-packages = [ +# core + "release", + "kernel-6.1", + "linux-firmware", +# docker + "docker-cli", + "docker-engine", + "docker-init", +# tools + "login", + "iputils", + "strace", + "chrony-tools", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/metal-k8s-1.28.toml b/data/variants/1.22.x/metal-k8s-1.28.toml new file mode 100644 index 00000000..7770520f --- /dev/null +++ b/data/variants/1.22.x/metal-k8s-1.28.toml @@ -0,0 +1,47 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/metal-k8s-1.28/Cargo.toml +[package] +# This is the metal-k8s-1.28 variant. "." is not allowed in crate names, but +# we don't use this crate name anywhere. +name = "metal-k8s-1_28" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 +partition-plan = "unified" + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +image-format = "raw" +supported-arches = ["x86_64"] +kernel-parameters = [ + # Only reserve if there are at least 2GB + "crashkernel=2G-:256M" +] +included-packages = [ + # core + "release", + "kernel-6.1", + # k8s + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kubelet-1.28", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/metal-k8s-1.29.toml b/data/variants/1.22.x/metal-k8s-1.29.toml new file mode 100644 index 00000000..79de286a --- /dev/null +++ b/data/variants/1.22.x/metal-k8s-1.29.toml @@ -0,0 +1,47 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/metal-k8s-1.29/Cargo.toml +[package] +# This is the metal-k8s-1.29 variant. "." is not allowed in crate names, but +# we don't use this crate name anywhere. +name = "metal-k8s-1_29" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +os-image-size-gib = 4 +partition-plan = "unified" + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +image-format = "raw" +supported-arches = ["x86_64"] +kernel-parameters = [ + # Only reserve if there are at least 2GB + "crashkernel=2G-:256M" +] +included-packages = [ + # core + "release", + "kernel-6.1", + # k8s + "aws-iam-authenticator", + "cni", + "cni-plugins", + "kubelet-1.29", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/vmware-dev.toml b/data/variants/1.22.x/vmware-dev.toml new file mode 100644 index 00000000..c865cf3c --- /dev/null +++ b/data/variants/1.22.x/vmware-dev.toml @@ -0,0 +1,53 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/vmware-dev/Cargo.toml +[package] +name = "vmware-dev" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +partition-plan = "unified" + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +xfs-data-partition = true +uefi-secure-boot = true +systemd-networkd = true + +[package.metadata.build-variant] +image-format = "vmdk" +supported-arches = ["x86_64"] +kernel-parameters = [ + "console=tty1", + # Only reserve if there are at least 2GB + "crashkernel=2G-:256M", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] +included-packages = [ +# core + "release", + "kernel-6.1", + "open-vm-tools", +# docker + "docker-cli", + "docker-engine", + "docker-init", +# tools + "login", + "iputils", + "strace", + "chrony-tools", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/vmware-k8s-1.28.toml b/data/variants/1.22.x/vmware-k8s-1.28.toml new file mode 100644 index 00000000..c33fd0b6 --- /dev/null +++ b/data/variants/1.22.x/vmware-k8s-1.28.toml @@ -0,0 +1,51 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/vmware-k8s-1.28/Cargo.toml +[package] +# This is the vmware-k8s-1.28 variant. "." is not allowed in crate names, but +# we don't use this crate name anywhere. +name = "vmware-k8s-1_28" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +partition-plan = "unified" + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +image-format = "vmdk" +supported-arches = ["x86_64"] +kernel-parameters = [ + "console=tty1", + # Only reserve if there are at least 2GB + "crashkernel=2G-:256M", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] +included-packages = [ + # core + "release", + "kernel-6.1", + # k8s + "cni", + "cni-plugins", + "kubelet-1.28", + # vmware + "open-vm-tools", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/vmware-k8s-1.29.toml b/data/variants/1.22.x/vmware-k8s-1.29.toml new file mode 100644 index 00000000..9c3a308c --- /dev/null +++ b/data/variants/1.22.x/vmware-k8s-1.29.toml @@ -0,0 +1,51 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/vmware-k8s-1.29/Cargo.toml +[package] +# This is the vmware-k8s-1.29 variant. "." is not allowed in crate names, but +# we don't use this crate name anywhere. +name = "vmware-k8s-1_29" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +partition-plan = "unified" + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +image-format = "vmdk" +supported-arches = ["x86_64"] +kernel-parameters = [ + "console=tty1", + # Only reserve if there are at least 2GB + "crashkernel=2G-:256M", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] +included-packages = [ + # core + "release", + "kernel-6.1", + # k8s + "cni", + "cni-plugins", + "kubelet-1.29", + # vmware + "open-vm-tools", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/vmware-k8s-1.30.toml b/data/variants/1.22.x/vmware-k8s-1.30.toml new file mode 100644 index 00000000..8ffe02d7 --- /dev/null +++ b/data/variants/1.22.x/vmware-k8s-1.30.toml @@ -0,0 +1,51 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/vmware-k8s-1.30/Cargo.toml +[package] +# This is the vmware-k8s-1.30 variant. "." is not allowed in crate names, but +# we don't use this crate name anywhere. +name = "vmware-k8s-1_30" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +partition-plan = "unified" + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +image-format = "vmdk" +supported-arches = ["x86_64"] +kernel-parameters = [ + "console=tty1", + # Only reserve if there are at least 2GB + "crashkernel=2G-:256M", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] +included-packages = [ + # core + "release", + "kernel-6.1", + # k8s + "cni", + "cni-plugins", + "kubelet-1.30", + # vmware + "open-vm-tools", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/variants/1.22.x/vmware-k8s-1.31.toml b/data/variants/1.22.x/vmware-k8s-1.31.toml new file mode 100644 index 00000000..f1dd6973 --- /dev/null +++ b/data/variants/1.22.x/vmware-k8s-1.31.toml @@ -0,0 +1,51 @@ +# Extracted from https://github.com/bottlerocket-os/bottlerocket/variants/vmware-k8s-1.31/Cargo.toml +[package] +# This is the vmware-k8s-1.31 variant. "." is not allowed in crate names, but +# we don't use this crate name anywhere. +name = "vmware-k8s-1_31" +version = "0.1.0" +edition = "2021" +publish = false +build = "../build.rs" +# Don't rebuild crate just because of changes to README. +exclude = ["README.md"] + +[package.metadata.build-variant.image-layout] +partition-plan = "unified" + +[package.metadata.build-variant.image-features] +grub-set-private-var = true +uefi-secure-boot = true +xfs-data-partition = true +systemd-networkd = true + +[package.metadata.build-variant] +image-format = "vmdk" +supported-arches = ["x86_64"] +kernel-parameters = [ + "console=tty1", + # Only reserve if there are at least 2GB + "crashkernel=2G-:256M", + "net.ifnames=0", + "netdog.default-interface=eth0:dhcp4,dhcp6?", + "quiet", +] +included-packages = [ + # core + "release", + "kernel-6.1", + # k8s + "cni", + "cni-plugins", + "kubelet-1.31", + # vmware + "open-vm-tools", +] + +[lib] +path = "../variants.rs" + +[build-dependencies] +settings-defaults = { path = "../../packages/settings-defaults" } +settings-plugins = { path = "../../packages/settings-plugins" } +settings-migrations = { path = "../../packages/settings-migrations" } diff --git a/data/versions/current.toml b/data/versions/current.toml index 13b5903e..d675cdf3 100644 --- a/data/versions/current.toml +++ b/data/versions/current.toml @@ -1,11 +1,11 @@ [os] major = 1 - minor = 21 - patch = 1 - foldable_check_id = "#m-enos121x-check" + minor = 22 + patch = 0 + foldable_check_id = "#m-enos122x-check" # this is the HTML ID of the sidebar hidden checkmark. There is a script that will auto open the correct menu item [k8s] - versions = ["1.23","1.24","1.25","1.26","1.27","1.28","1.29","1.30"] + versions = ["1.23","1.24","1.25","1.26","1.27","1.28","1.29","1.30","1.31"] [ecs] versions = ["1","2"] From 56c994b1333d2f5d3e9a88bb83003449b4385a37 Mon Sep 17 00:00:00 2001 From: Piyush Jena <piyushjena1996@gmail.com> Date: Tue, 8 Oct 2024 19:11:03 -0700 Subject: [PATCH 3/3] Add documentation for ephemeral-storage apis and bootstrap-commands --- .../en/os/1.22.x/api/endpoints/index.markdown | 2 +- .../bootstrap-commands/_index.markdown | 8 + .../bootstrap-commands/_index.markdown | 129 +++ data/settings/1.22.x/bootstrap-commands.toml | 61 ++ .../bootstrap_commands_diagram.html | 129 +++ static/external/openapi/1.22.x/openapi.yaml | 794 ++++++++++++++++++ 6 files changed, 1122 insertions(+), 1 deletion(-) create mode 100644 content/en/os/1.22.x/api/settings/bootstrap-commands/_index.markdown create mode 100644 content/en/os/1.22.x/concepts/bootstrap-commands/_index.markdown create mode 100644 data/settings/1.22.x/bootstrap-commands.toml create mode 100644 layouts/shortcodes/bootstrap_commands_diagram.html create mode 100644 static/external/openapi/1.22.x/openapi.yaml diff --git a/content/en/os/1.22.x/api/endpoints/index.markdown b/content/en/os/1.22.x/api/endpoints/index.markdown index 51580880..06fc4044 100644 --- a/content/en/os/1.22.x/api/endpoints/index.markdown +++ b/content/en/os/1.22.x/api/endpoints/index.markdown @@ -8,4 +8,4 @@ The following output is generated from [Bottlerocket's OpenAPI Spec](https://git --- -{{< swaggerui src="../../../../external/openapi/1.15.x/openapi.yaml" >}} +{{< swaggerui src="../../../../external/openapi/1.22.x/openapi.yaml" >}} diff --git a/content/en/os/1.22.x/api/settings/bootstrap-commands/_index.markdown b/content/en/os/1.22.x/api/settings/bootstrap-commands/_index.markdown new file mode 100644 index 00000000..26e8355d --- /dev/null +++ b/content/en/os/1.22.x/api/settings/bootstrap-commands/_index.markdown @@ -0,0 +1,8 @@ ++++ +title="bootstrap-commands" +type="docs" +toc_hide=true +description="Settings related to bootstrap commands (`settings.bootstrap-commands.*`)" ++++ + +{{< settings >}} diff --git a/content/en/os/1.22.x/concepts/bootstrap-commands/_index.markdown b/content/en/os/1.22.x/concepts/bootstrap-commands/_index.markdown new file mode 100644 index 00000000..1424544a --- /dev/null +++ b/content/en/os/1.22.x/concepts/bootstrap-commands/_index.markdown @@ -0,0 +1,129 @@ ++++ +title = "Bootstrap Commands" +type = "docs" +description = "Configure the host with Bottlerocket API commands during boot." ++++ + +Bootstrap commands are a way to configure and modify a Bottlerocket instance using the Bottlerocket API at boot time. They run prior to the {{< ver-ref project="os" page="/concepts/bootstrap-containers/" >}}Bootstrap Containers{{</ ver-ref >}}. + +## Lifecycle + +When you define a bootstrap command using user-data or the Bottlerocket API, the following sequence occurs on next boot: + +- [`systemd`](https://systemd.io/) runs all the bootstrap commands in lexicographical order of their names. Each Bottlerocket API command inside a bootstrap-command runs serially in the declared order. +- `systemd` will not move to the next [target](https://www.freedesktop.org/software/systemd/man/systemd.target.html) until all of the bootstrap commands start, run and exit. +- any bootstrap command configured with `mode=once` will change to `mode=off` once complete. +- any bootstrap command set to `essential=true` that exits with a non-zero exit code halts the boot process. + +### Examples + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner colsplit="7" >}} + {{< bootstrap_commands_diagram example=1 >}} + {{</ twocol_inner >}} + {{% twocol_inner %}} +This example shows four bootstrap commands whose names begin with `001-cmd`,`002-cmd`,`003-cmd`, and `004-cmd`. +The start order of these commands is in lexicographical order of their names. +The boot does not proceed to the next stage until the last bootstrap command completes. + {{%/ twocol_inner %}} +{{</ twocol >}} + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner colsplit="7" >}} + {{< bootstrap_commands_diagram example=2 >}} + {{</ twocol_inner >}} + {{% twocol_inner %}} +This example is the same as the previous one except the bootstrap command `003-cmd` is configured with {{< ver-ref project="os" page="/api/settings/bootstrap-commands#name_essential">}}`essential=true`{{< /ver-ref >}}. +Bootstrap command `003-cmd` exits with a non-zero exit code and consequently the boot halts. As a result, `004-cmd` isn't run at all. + {{%/ twocol_inner %}} +{{</ twocol >}} + +{{< twocol + containerclass="td-max-width-on-larger-screens docs-figure" + rowclass="docs-figure" >}} + {{< twocol_inner colsplit="7" >}} + {{< bootstrap_commands_diagram example=3 >}} + {{</ twocol_inner >}} + {{% twocol_inner %}} +This example is the same as the first except bootstrap command `004-cmd` is configured with {{< ver-ref project="os" page="/api/settings/bootstrap-commands#name_mode">}}`mode=once`{{< /ver-ref >}}. +After `004-cmd` finishes, the bootstrap command `004-cmd` is turned off by settings its `mode` to `off`, and will no longer be executed in future boot sequences. + {{%/ twocol_inner %}} +{{</ twocol >}} + +### Considerations + +As a consequence of this lifecycle, you should keep a few things in mind when using bootstrap commands: + +1. Bootstrap commands **can only** run `apiclient` commands. +2. Bootstrap commands can’t run `apiclient exec` commands because host containers aren’t ready at this stage of the boot. +3. Running `apiclient reboot` in a bootstrap command with `mode=always` will cause the node to reboot endlessly. +4. `apiclient reboot` in a bootstrap command with `mode=once` will hold off the reboot until the completion of all bootstrap commands. +5. Due to serial nature of bootstrap commands, they should be short-running to reduce overhead on boot times. + +## Use cases + +The following are a few examples use cases for bootstrap commands + +### Configure ephemeral disks + +**In a Kubernetes host** + +``` +[settings.bootstrap-commands.k8s-ephemeral-storage] +commands = [ + ["apiclient", "ephemeral-storage", "init"], + ["apiclient", "ephemeral-storage" ,"bind", "--dirs", "/var/lib/containerd", "/var/lib/kubelet", "/var/log/pods"] +] +essential = true +mode = "always" +``` + +**In an ECS host** + +``` +[settings.bootstrap-commands.ecs-ephemeral-storage] +commands = [ + ["apiclient", "ephemeral-storage", "init"], + ["apiclient", "ephemeral-storage" ,"bind", "--dirs", "/var/lib/containerd", "/var/lib/docker", "/var/log/ecs"] +] +essential = true +mode = "always" +``` + +### Running the CIS reports + +**Bottlerocket CIS Benchmark** + +``` +[settings.bootstrap-commands.bottlerocket-cis-benchmark] +commands = [["apiclient", "report", "cis", "-l", "2"]] +essential = true +mode = "always" +``` + +**Kubernetes CIS Benchmark** + +``` +[settings.bootstrap-commands.kubernetes-cis-benchmark] +commands = [["apiclient", "report", "cis-k8s", "-l", "2"]] +essential = true +mode = "always" +``` + +### Checking and Applying Updates + +``` +[settings.bootstrap-commands.kubernetes-cis-benchmark] +commands = [["apiclient", "update", "apply", "--check", "--reboot"]] +essential = true +mode = "always" +``` + +## Also see +- {{< ver-ref project="os" page="/api/settings/bootstrap-commands">}} bootstrap-commands in the API Setting Reference{{< /ver-ref >}} + +{{< on-github >}} diff --git a/data/settings/1.22.x/bootstrap-commands.toml b/data/settings/1.22.x/bootstrap-commands.toml new file mode 100644 index 00000000..c356c420 --- /dev/null +++ b/data/settings/1.22.x/bootstrap-commands.toml @@ -0,0 +1,61 @@ +[[docs.ref.name_commands]] +name_override = "<name>.commands" +description = "List of API commands to be run as part of the bootstrap command. Each API command is expressed as a list of strings." +see = [ + ["[`settings.bootstrap-commands.<name>.mode`](../bootstrap-commands/#name_mode) for a full example with `settings.bootstrap-commands.<name>.commands`."], + ["The {{< ver-ref project=\"os\" page=\"/concepts/bootstrap-commands#lifecycle\" >}}bootstrap commands lifecycle{{< /ver-ref >}} documentation"] +] + +[[docs.ref.name_essential]] +name_override = "<name>.essential" +description = "If `essential` is set to `true` the bootstrap command will halt the boot process when it exits with a non-zero exit code." +default = "`false`" +accepted_values = [ + "`true`", + "`false`" +] +see = [ + ["[`settings.bootstrap-commands.<name>.mode`](../bootstrap-commands/#name_mode) for a full example with `settings.bootstrap-commands.<name>.essential`."], + ["The {{< ver-ref project=\"os\" page=\"/concepts/bootstrap-commands#lifecycle\" >}}bootstrap commands lifecycle{{< /ver-ref >}} documentation"] +] + + +[[docs.ref.name_mode]] +name_override = "<name>.mode" +description = """ +Specifies how (or if) a bootstrap command starts at boot. +If you set the value to: + +* `"always"`, the bootstrap command will start on every boot, +* `"off"`, the bootstrap command will not start at boot, +* `"once"`, the bootstrap command will start on the first boot but after exit, the `mode` changes to `off`. +""" +accepted_values = [ + "`\"always\"`", + "`\"off\"`", + "`\"once\"`" +] +see = [ + ["[`settings.bootstrap-commands.<name>.mode`](../bootstrap-commands/#name_mode) for a full example with `settings.bootstrap-commands.<name>.mode`."], + ["The {{< ver-ref project=\"os\" page=\"/concepts/bootstrap-commands#lifecycle\" >}}bootstrap commands lifecycle{{< /ver-ref >}} documentation"] +] + +[[docs.ref.name_mode.example]] +direct_toml = """ +# Creates a bootstrap command called `mybootstrap` +# It runs everytime the instance boots and if exits with a non-zero code, will halt the boot process +[settings.bootstrap-commands.mybootstrap] +commands = [["apiclient", "ephemeral-storage", "init"], ["apiclient", "ephemeral-storage" ,"bind", "--dirs", "/var/lib/containerd", "/var/lib/docker", "/var/log/ecs"]] +essential = true +mode = "always" +""" +direct_shell = """ +# Creates a bootstrap container called `mybootstrap` +# It runs everytime the instance boots and if exits with a non-zero code, will halt the boot process +apiclient apply <<EOF +[settings.bootstrap-commands.mybootstrap] +commands = [["apiclient", "ephemeral-storage", "init"], ["apiclient", "ephemeral-storage" ,"bind", "--dirs", "/var/lib/containerd", "/var/lib/docker", "/var/log/ecs"]] +essential = true +mode = "always" +EOF +""" diff --git a/layouts/shortcodes/bootstrap_commands_diagram.html b/layouts/shortcodes/bootstrap_commands_diagram.html new file mode 100644 index 00000000..89c79961 --- /dev/null +++ b/layouts/shortcodes/bootstrap_commands_diagram.html @@ -0,0 +1,129 @@ +{{- $example := .Get "example" -}} + +{{ if (eq $example 1) }} +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="100%" viewBox="-0.5 -0.5 561 361" class="bootstrap-container-diagram"> + <defs/> + <g> + <path d="M 280 60 L 280 73.63" class="sequence-arrow-line"/> + <path d="M 280 78.88 L 276.5 71.88 L 280 73.63 L 283.5 71.88 Z" class="sequence-arrow-point" /> + <rect x="0" y="0" width="560" height="60" class="systemd-box" /> + <g transform="translate(257.5,23.5)"> + <text x="23" y="12" class="systemd-box-text" >systemd</text> + </g> + <path d="M 280 280 L 280 293.63" class="sequence-arrow-line"/> + <path d="M 280 298.88 L 276.5 291.88 L 280 293.63 L 283.5 291.88 Z" class="sequence-arrow-point" /> + <rect x="0" y="80" width="560" height="200" class="bootstrap-containers-rect"/> + <rect x="10" y="70" width="130" height="20" class="bootstrap-containers-label-back" /> + <g transform="translate(20.5,73.5)"> + <text x="55" y="12" class="bootstrap-containers-text">bootstrap commands</text> + </g> + <rect x="10" y="90" width="110" height="40" class="container-b1"/> + <g transform="translate(57.5,102.5)"> + <text x="8" y="12" class="container-b1">001-cmd</text> + </g> + <rect x="153" y="130" width="110" height="30" class="container-b2"/> + <g transform="translate(200.5,137)"> + <text x="8" y="12" class="container-b2">002-cmd</text> + </g> + <rect x="297" y="160" width="110" height="50" class="container-b3"/> + <g transform="translate(344.5,177)"> + <text x="8" y="12" class="container-b3">003-cmd</text> + </g> + <rect x="440" y="210" width="110" height="60" class="container-b4"/> + <g transform="translate(487.5,230)"> + <text x="8" y="12" class="container-b4">004-cmd</text> + </g> + <rect x="0" y="300" width="560" height="60" class="next-boot-stage"/> + <g transform="translate(238.5,323.5)"> + <text x="41" y="12" class="next-boot-stage">next boot stage</text> + </g> + </g> +</svg> +{{ end }} +{{ if (eq $example 2) }} +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="100%" viewBox="-0.5 -0.5 561 274" class="bootstrap-container-diagram"> + <defs/> + <g> + <path d="M 280 60 L 280 73.63" class="sequence-arrow-line"/> + <path d="M 280 78.88 L 276.5 71.88 L 280 73.63 L 283.5 71.88 Z" class="sequence-arrow-point"/> + <rect x="0" y="0" width="560" height="60" class="systemd-box" /> + <g transform="translate(257.5,23.5)"> + <text x="23" y="12" class="systemd-box-text" >systemd</text> + </g> + <path d="M 280 180 L 280 250.63" class="sequence-arrow-line"/> + <path d="M 280 250.88 L 276.5 243.88 L 280 245.63 L 283.5 243.88 Z" class="sequence-arrow-point" /> <rect x="0" y="80" width="560" height="140" class="bootstrap-containers-rect"/> + <rect x="10" y="70" width="130" height="20" class="bootstrap-containers-label-back" /> + <rect x="10" y="90" width="110" height="40" class="container-b1"/> + <g transform="translate(57.5,102.5)"> + <text x="8" y="12" class="container-b1">001-cmd</text> + </g> + <g transform="translate(20.5,73.5)"> + <text x="55" y="12" class="bootstrap-containers-text">bootstrap commands</text> + </g> + <rect x="153" y="130" width="110" height="30" class="container-b2"/> + <g transform="translate(200.5,137)"> + <text x="8" y="12" class="container-b2">002-cmd</text> + </g> + <rect x="297" y="160" width="110" height="50" class="container-b3"/> + <g transform="translate(344.5,177)"> + <text x="8" y="8" class="container-b3">003-cmd</text> + <text x="8" y="21" class="container-b3">essential = true</text> + </g> + <g transform="translate(256.5,253.5)"> + <text x="23" y="12" class="boot-halt">boot halt</text> + </g> + <path d="M 407 210 L 437.75 190 L 510 190 Q 530 190 530 210 Q 530 230 510 230 L 437.75 230 Z" class="exit-flag"/> + <g transform="translate(441.5,203.5)"> + <text x="29" y="12" class="exit-flag">exit code 1</text> + </g> + </g> + </svg> +{{end}} +{{ if (eq $example 3) }} +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="100%" viewBox="-0.5 -0.5 561 411" class="bootstrap-container-diagram"> + <defs/> + <g> + <path d="M 280 60 L 280 73.63" class="sequence-arrow-line" /> + <path d="M 280 78.88 L 276.5 71.88 L 280 73.63 L 283.5 71.88 Z" class="sequence-arrow-point" /> + <rect x="0" y="0" width="560" height="60" class="systemd-box" /> + <g transform="translate(257.5,23.5)"> + <text x="23" y="12" class="systemd-box-text" >systemd</text> + </g> + <rect x="0" y="80" width="560" height="250" class="bootstrap-containers-rect"/> + <rect x="10" y="70" width="130" height="20" class="bootstrap-containers-label-back" /> + <g transform="translate(20.5,73.5)"> + <text x="55" y="12" class="bootstrap-containers-text">bootstrap commands</text> + </g> + <rect x="10" y="90" width="110" height="40" class="container-b1"/> + <g transform="translate(57.5,102.5)"> + <text x="8" y="12" class="container-b1">001-cmd</text> + </g> + <rect x="153" y="130" width="110" height="30" class="container-b2"/> + <g transform="translate(200.5,137)"> + <text x="8" y="12" class="container-b2">002-cmd</text> + </g> + <rect x="297" y="160" width="110" height="50" class="container-b3"/> + <g transform="translate(344.5,177)"> + <text x="8" y="8" class="container-b3">003-cmd</text> + <text x="8" y="21" class="container-b3">essential = true</text> + </g> + <path d="M 495 270 L 495 290 L 495 280 L 495 293.63" class="sequence-arrow-line"/> + <path d="M 495 298.88 L 491.5 291.88 L 495 293.63 L 498.5 291.88 Z" class="sequence-arrow-point" /> + <rect x="440" y="210" width="110" height="60" class="container-b4"/> + <g transform="translate(487.5,230)"> + <text x="8" y="12" class="container-b4">004-cmd</text> + <text x="8" y="22" class="container-b4">mode=once</text> + </g> + <g transform="translate(449.5,281.5)"> + <text x="46" y="30" class="mode-to-off">Update mode for</text> + <text x="46" y="45" class="mode-to-off">004-cmd to off</text> + </g> + <path d="M 280 330 L 280 343.63" class="sequence-arrow-line"/> + <path d="M 280 348.88 L 276.5 341.88 L 280 343.63 L 283.5 341.88 Z" class="sequence-arrow-point"/> + <rect x="0" y="350" width="560" height="60" class="next-boot-stage"/> + <g transform="translate(238.5,373.5)"> + <text x="41" y="12" class="next-boot-stage">next boot stage</text> + </g> + </g> +</svg> +{{end}} diff --git a/static/external/openapi/1.22.x/openapi.yaml b/static/external/openapi/1.22.x/openapi.yaml new file mode 100644 index 00000000..726584f3 --- /dev/null +++ b/static/external/openapi/1.22.x/openapi.yaml @@ -0,0 +1,794 @@ +openapi: "3.0.2" +info: + version: "0.1.0" + title: "Bottlerocket API" + description: "The API for the Bottlerocket OS" + license: + name: "Apache-2.0 OR MIT" + url: "https://github.com/bottlerocket-os/bottlerocket/blob/develop/COPYRIGHT" + +servers: +- url: file:///run/api.sock + description: The production API server + +components: + schemas: + HashMap: + type: object + additionalProperties: + type: string + Service: + type: object + additionalProperties: + $ref: '#/components/schemas/HashMap' + Services: + type: object + additionalProperties: + $ref: '#/components/schemas/Service' + ConfigurationFileInfo: + type: object + properties: + template-path: + type: string + path: + type: string + mode: + type: string + ConfigurationFiles: + type: object + additionalProperties: + $ref: '#/components/schemas/ConfigurationFileInfo' + Report: + type: object + properties: + name: + type: string + description: + type: string + Version: + type: object + properties: + major: + type: integer + minor: + type: integer + patch: + type: integer + UpdateImage: + type: object + properties: + arch: + type: string + variant: + type: string + version: + $ref: '#/components/schemas/Version' + StagedImage: + type: object + properties: + image: + $ref: '#/components/schemas/UpdateImage' + next_to_boot: + type: boolean + CommandResult: + type: object + properties: + cmd_type: + type: string + cmd_status: + type: string + timestamp: + type: string + exit_status: + type: integer + stderr: + type: string + UpdateStatus: + type: object + properties: + update_state: + type: string + available_updates: + type: array + items: + $ref: '#/components/schemas/Version' + chosen-update: + $ref: '#/components/schemas/UpdateImage' + active-partition: + $ref: '#/components/schemas/StagedImage' + staging-partition: + $ref: '#/components/schemas/StagedImage' + most-recent-command: + $ref: '#/components/schemas/CommandResult' + EphemeralStorageInit: + type: object + properties: + filesystem: + type: string + disks: + type: array + items: + type: string + EphemeralStorageBind: + type: object + properties: + targets: + type: array + items: + type: string + Settings: + type: object + properties: + motd: + type: string + kubernetes: + type: object + ecs: + type: object + updates: + type: object + host-containers: + type: object + ntp: + type: object + properties: + time-servers: + type: array + items: + type: string + network: + type: object + properties: + hostname: + type: string + kernel: + type: object + properties: + lockdown: + type: string + aws: + type: object + properties: + region: + type: string + config: + type: string + credentials: + type: string + profile: + type: string + metrics: + type: object + oci-defaults: + type: object + oci-hooks: + type: object + properties: + log4j-hotpatch-enabled: + type: boolean + cloudformation: + type: object + properties: + should-signal: + type: boolean + stack-name: + type: string + logical-resource-id: + type: string + autoscaling: + type: object + properties: + should-wait: + type: boolean + additionalProperties: true + BottlerocketRelease: + type: object + properties: + pretty-name: + type: string + variant-id: + type: string + version-id: + type: string + build-id: + type: string + arch: + type: string + Model: + type: object + properties: + settings: + $ref: '#/components/schemas/Settings' + services: + $ref: '#/components/schemas/Services' + configuration-files: + $ref: '#/components/schemas/ConfigurationFiles' + os: + $ref: '#/components/schemas/BottlerocketRelease' + +paths: + /: + get: + summary: "Get current model, including settings, services, configuration files, and os info" + operationId: "get_model" + parameters: + - in: query + name: prefix + description: "Specific key prefix to query" + schema: + type: string + required: false + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + $ref: "Model" + 500: + description: "Server error" + + /settings: + get: + summary: "Get current settings" + operationId: "get_settings" + parameters: + - in: query + name: keys + description: "Specific keys to query. Takes precedence over 'prefix' if both query parameters are supplied" + schema: + type: array + items: + type: string + # `style: form` and `explode: false` format parameters as such: /settings?keys=foo,bar,baz + style: form + explode: false + required: false + - in: query + name: prefix + description: "Specific key prefix to query. This parameter will be ignored if 'keys' is also supplied" + schema: + type: string + required: false + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + $ref: "Settings" + 500: + description: "Server error" + patch: + summary: "Update settings" + operationId: "set_settings" + parameters: + - in: query + name: tx + description: "Transaction in which to update settings; defaults to user 'default' transaction" + schema: + type: string + required: false + requestBody: + required: true + content: + application/json: + schema: + $ref: "Settings" + responses: + 204: + description: "Settings successfully staged for update" + 400: + description: "Invalid body" + 500: + description: "Server error" + + /tx: + get: + summary: "Get pending settings in a transaction" + operationId: "get_tx" + parameters: + - in: query + name: tx + description: "Transaction for which to retrieve pending settings; defaults to user 'default' transaction" + schema: + type: string + required: false + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + $ref: "Settings" + 500: + description: "Server error" + delete: + summary: "Delete transaction" + operationId: "delete_tx" + parameters: + - in: query + name: tx + description: "Transaction to delete; defaults to user 'default' transaction" + schema: + type: string + required: false + responses: + 200: + description: "Successful deleted pending settings - deleted keys are returned" + 500: + description: "Server error" + + /tx/list: + get: + summary: "List names of pending transactions" + operationId: "list_tx" + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + type: array + items: + type: string + 500: + description: "Server error" + + /tx/commit: + post: + summary: "Commit pending settings, without applying changes to config files or restarting services" + operationId: "commit_tx" + parameters: + - in: query + name: tx + description: "Transaction to commit; defaults to user 'default' transaction" + schema: + type: string + required: false + responses: + 200: + description: "Successfully Staged settings - changed keys are returned" + 500: + description: "Server error" + + /tx/apply: + post: + summary: "Apply changes to config files and restart services" + operationId: "apply" + parameters: + - in: query + name: keys + description: "Apply changes only if related to these keys; if not specified, applies for all known keys" + schema: + type: array + items: + type: string + # `style: form` and `explode: false` format parameters as such: /tx/apply?keys=settings.foo,settings.bar + style: form + explode: false + required: false + responses: + 204: + description: "Successfully started settings applier" + 500: + description: "Server error" + + /tx/commit_and_apply: + post: + summary: "Commit transaction, and apply any committed changes to relevant config files and services" + operationId: "commit_tx_and_apply" + parameters: + - in: query + name: tx + description: "Transaction to commit; defaults to user 'default' transaction" + schema: + type: string + required: false + responses: + 200: + description: "Successful settings update, committed keys are returned" + 500: + description: "Server error" + + /os: + get: + summary: "Get OS information such as version, variant, and architecture" + operationId: "get_os_info" + parameters: + - in: query + name: prefix + description: "Specific key prefix to query" + schema: + type: string + required: false + responses: + 200: + description: "Successful request" + content: + application/json: + # The response is a hashmap of string to string. Example: + # { "arch": "x86_64" } + schema: + type: object + additionalProperties: + type: string + 500: + description: "Server error" + + /metadata/affected-services: + get: + summary: "Get affected services" + operationId: "get_affected_services" + parameters: + - in: query + name: keys + description: "Specific keys to query" + schema: + type: array + items: + type: string + # `style: form` and `explode: false` format parameters as such: /metadata/affected-services?keys=settings.foo,settings.bar + style: form + explode: false + required: true + responses: + 200: + description: "Successful request" + content: + application/json: + # The response is a hashmap of string to array of strings. Example: + # { "settings.foo": [ "service1", "service2" ] } + schema: + type: object + additionalProperties: + type: array + items: + type: string + 400: + description: "Missing required query parameter: 'keys'" + 500: + description: "Server error" + + /metadata/setting-generators: + get: + summary: "Get programs needed to generate settings" + operationId: "get_setting_generators" + responses: + 200: + description: "Successful request" + content: + application/json: + # The response is a hashmap of string to string. Example: + # { "settings.foobar": "/usr/bin/foobar" } + schema: + type: object + additionalProperties: + type: string + 500: + description: "Server error" + + /metadata/templates: + get: + summary: "Get template strings for dynamically generated settings" + operationId: "get_templates" + responses: + 200: + description: "Successful request" + content: + application/json: + # The response is a hashmap of string to string. Example: + # { "settings.foobar": "hi {{ key }}" } + schema: + type: object + additionalProperties: + type: string + 500: + description: "Server error" + + /services: + get: + summary: "Get service data" + operationId: "get_services" + parameters: + - in: query + name: names + description: "Specific services to query" + schema: + type: array + items: + type: string + # `style: form` and `explode: false` format parameters as such: /services?names=foo,bar,baz + style: form + explode: false + required: false + - in: query + name: prefix + description: "Specific key prefix to query. This parameter will be ignored if 'names' is also supplied" + schema: + type: string + required: false + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + $ref: "Services" + 500: + description: "Server error" + + /configuration-files: + get: + summary: "Get configuration file data" + operationId: "get_config_files" + parameters: + - in: query + name: names + description: "Specific configuration files to query" + schema: + type: array + items: + type: string + # `style: form` and `explode: false` format parameters as such: /configuration-files?names=file1,file2 + style: form + explode: false + required: false + - in: query + name: prefix + description: "Specific key prefix to query. This parameter will be ignored if 'names' is also supplied" + schema: + type: string + required: false + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + $ref: "ConfigurationFiles" + 500: + description: "Server error" + + /actions/reboot: + post: + summary: "Reboot" + operationId: "reboot" + responses: + 204: + description: "Reboot requested" + 500: + description: "Server error" + + /actions/refresh-updates: + post: + summary: "Query update repository and refresh list of updates" + operationId: "refresh_update" + responses: + 204: + description: "Successful request" + 500: + description: "Server error" + 423: + description: "Update write lock held. Try again in a moment" + + /actions/prepare-update: + post: + summary: "Download the chosen update and write the update image to the inactive partition" + operationId: "prepare_update" + responses: + 204: + description: "Successful request" + 404: + description: "Chosen update does not exist" + 409: + description: "Action not allowed according to current update state" + 500: + description: "Server error" + 423: + description: "Update write lock held. Try again in a moment" + + /actions/activate-update: + post: + summary: "Mark the partition with the prepared update as active so you can reboot into the chosen version" + operationId: "activate_update" + responses: + 204: + description: "Successfully activated update" + 404: + description: "No update image applied to staging partition, need to prepare-update first" + 409: + description: "Action not allowed according to current update state" + 500: + description: "Server error" + 423: + description: "Update write lock held. Try again in a moment" + + /actions/deactivate-update: + post: + summary: "Deactivate the update by marking the running partition as active again" + operationId: "deactivate-update" + responses: + 204: + description: "Successfully deactivated update" + 404: + description: "No update image applied to staging partition, need to prepare-update first" + 409: + description: "Action not allowed according to current update state" + 500: + description: "Server error" + 423: + description: "Update write lock held. Try again in a moment" + + /actions/ephemeral-storage/init: + post: + summary: "Initialize ephemeral storage" + operationId: "init" + requestBody: + required: true + content: + application/json: + schema: + $ref: "EphemeralStorageInit" + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + type: string + 400: + description: "Bad request input" + 422: + description: "Unprocessable request" + 500: + description: "Server error" + + /actions/ephemeral-storage/bind: + post: + summary: "Bind directories to previously initialized ephemeral storage" + operationId: "bind" + requestBody: + required: true + content: + application/json: + schema: + $ref: "EphemeralStorageBind" + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + type: string + 400: + description: "Bad request input" + 422: + description: "Unprocessable request" + 500: + description: "Server error" + + /actions/ephemeral-storage/list-disks: + get: + summary: "List the discovered ephemeral disks that can be initialized" + operationId: "list-disks" + parameters: + - in: query + name: format + description: "Format of the disk listing (text or json). Default format is text." + schema: + type: string + required: false + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + type: string + 400: + description: "Bad request input" + 422: + description: "Unprocessable request" + 500: + description: "Server error" + + /actions/ephemeral-storage/list-dirs: + get: + summary: "List the directories that can be bound to ephemeral storage" + operationId: "list-dirs" + parameters: + - in: query + name: format + description: "Format of the directory listing (text or json). Default format is text." + schema: + type: string + required: false + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + type: string + 400: + description: "Bad request input" + 422: + description: "Unprocessable request" + 500: + description: "Server error" + + /updates/status: + get: + summary: "Get update status" + operationId: "get_update_status" + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + $ref: "UpdateStatus" + 500: + description: "Server error" + 423: + description: "Update write lock held. Try again in a moment" + + /exec: + get: + summary: "Request exec WebSocket" + operationId: "exec" + responses: + 101: + description: "Connection upgraded to WebSocket" + 500: + description: "Server error" + + /report: + get: + summary: "Get available report types" + operationId: "get_reports" + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + type: array + items: + $ref: "Report" + 500: + description: "Server error" + + /report/cis: + get: + summary: "Get CIS benchmark report" + operationId: "cis-report" + parameters: + - in: query + name: level + description: "The CIS compliance level to test (1 or 2). Default level is 1." + schema: + type: integer + minimum: 1 + maximum: 2 + required: false + - in: query + name: format + description: "The CIS compliance report format (text or json). Default format is text." + schema: + type: string + required: false + responses: + 200: + description: "Successful request" + content: + application/json: + schema: + type: string + 400: + description: "Bad request input" + 422: + description: "Unprocessable request" + 500: + description: "Server error"