Merge branch 'main' into prod

data/settings/1.20.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"

data/settings/1.20.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)."

data/settings/1.20.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"

data/settings/1.20.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
+"""

data/settings/1.20.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.
+"""

data/settings/1.20.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"
+      }
+    ]
+  }
+}'
+"""

data/settings/1.20.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)"]
+]

data/settings/1.20.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\"]"