Merge pull request #479 from bottlerocket-os/main

Move docs for 1.21.0 to production

content/en/os/1.20.x/_index.markdown

@@ -1,4 +1,4 @@
 +++
-title="1.20.x (Current)"
+title="1.20.x"
 type="docs"
 +++

content/en/os/1.21.x/_index.markdown

@@ -0,0 +1,4 @@
++++
+title="1.21.x (Current)"
+type="docs"
++++

content/en/os/1.21.x/api/_index.markdown

@@ -0,0 +1,6 @@
++++
+title = "API"
+type = "docs"
+description = "Bottlerocket's primary administrative interface"
+weight = 999
++++

content/en/os/1.21.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" >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.x/api/settings/_index.markdown

@@ -0,0 +1,5 @@
++++
+title="Settings Reference"
+type="docs"
+description="Individual settings avaliable for the `/settings` endpoint"
++++

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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).

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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.

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}

content/en/os/1.21.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 >}}