diff --git a/data/settings/1.20.x/autoscaling.toml b/data/settings/1.20.x/autoscaling.toml new file mode 100644 index 00000000..a2f2ac44 --- /dev/null +++ b/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" diff --git a/data/settings/1.20.x/aws.toml b/data/settings/1.20.x/aws.toml new file mode 100644 index 00000000..f72f9b80 --- /dev/null +++ b/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)." diff --git a/data/settings/1.20.x/boot.toml b/data/settings/1.20.x/boot.toml new file mode 100644 index 00000000..f5a03b8e --- /dev/null +++ b/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 <.source`](#name_source) for a full example with `settings.bootstrap-containers..essential`."], + ["The {{< ver-ref project=\"os\" page=\"/concepts/bootstrap-containers#lifecycle\" >}}bootstrap container lifecycle{{< /ver-ref >}} conceptual documentationion"] +] + + +[[docs.ref.name_mode]] +name_override = ".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..source`](#name_source) for a full example with `settings.bootstrap-containers..mode`."], + ["The {{< ver-ref project=\"os\" page=\"/concepts/bootstrap-containers#lifecycle\" >}}bootstrap container lifecycle{{< /ver-ref >}} conceptual documentation"] + +] + +[[docs.ref.name_source]] +name_override = ".source" +description = "Defines the URI for a container to run as a bootstrap container." +[[docs.ref.name_user-data]] +name_override = ".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//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.20.x/cloudformation.toml b/data/settings/1.20.x/cloudformation.toml new file mode 100644 index 00000000..d9e9590b --- /dev/null +++ b/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. +""" diff --git a/data/settings/1.20.x/container-registry.toml b/data/settings/1.20.x/container-registry.toml new file mode 100644 index 00000000..ecd25ff5 --- /dev/null +++ b/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://","https://"] + +[[settings.container-registry.mirrors]] +registry = "docker.io" +endpoint = [ "https://", "https://"] +""" + +[[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.20.x/container-runtime.toml b/data/settings/1.20.x/container-runtime.toml new file mode 100644 index 00000000..1291b072 --- /dev/null +++ b/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)"] +] diff --git a/data/settings/1.20.x/dns.toml b/data/settings/1.20.x/dns.toml new file mode 100644 index 00000000..0d3c259f --- /dev/null +++ b/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\"]" diff --git a/data/settings/1.20.x/ecs.toml b/data/settings/1.20.x/ecs.toml new file mode 100644 index 00000000..373296f6 --- /dev/null +++ b/data/settings/1.20.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.20.x/host-containers.toml b/data/settings/1.20.x/host-containers.toml new file mode 100644 index 00000000..fa9688ca --- /dev/null +++ b/data/settings/1.20.x/host-containers.toml @@ -0,0 +1,63 @@ + + +[[docs.ref.container_enabled]] +name_override = ".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..source` for custom host container example](#container_source)"], + ["[Shell-less host](../../../concepts/shell-less-host/)"] +] + +[[docs.ref.container_source]] +name_override = ".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 = ".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..source` for custom host container example](#container_source)"], + ["[Shell-less host](../../../concepts/shell-less-host/)"] + +] + +[[docs.ref.container_user-data]] +name_override = ".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//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.20.x/kernel.toml b/data/settings/1.20.x/kernel.toml new file mode 100644 index 00000000..b44dc4e4 --- /dev/null +++ b/data/settings/1.20.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..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 ``. +""" +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..autoload" +description = "If `true`, the kernel `` module loads automatically on boot." +see = [ + [ "settings", "boot", "kernel-parameters" ] +] +note = """ +You must use this setting in conjuction with [`settings.kernel.modules..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.20.x/kubernetes.toml b/data/settings/1.20.x/kubernetes.toml new file mode 100644 index 00000000..26a00c97 --- /dev/null +++ b/data/settings/1.20.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..enabled" +tags = [ + "static-pods" +] +see = [ + [ "settings", "kubernetes", "customid_manifest" ] +] + +[[docs.ref.customid_manifest]] +description= "A base64-encoded pod manifest." +name_override="static-pods..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.20.x/metrics.toml b/data/settings/1.20.x/metrics.toml new file mode 100644 index 00000000..56185f3d --- /dev/null +++ b/data/settings/1.20.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.20.x/motd.toml b/data/settings/1.20.x/motd.toml new file mode 100644 index 00000000..85af356f --- /dev/null +++ b/data/settings/1.20.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.20.x/network.toml b/data/settings/1.20.x/network.toml new file mode 100644 index 00000000..b0f55337 --- /dev/null +++ b/data/settings/1.20.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.20.x/ntp.toml b/data/settings/1.20.x/ntp.toml new file mode 100644 index 00000000..b711dba4 --- /dev/null +++ b/data/settings/1.20.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.20.x/oci-defaults.toml b/data/settings/1.20.x/oci-defaults.toml new file mode 100644 index 00000000..b9372b2a --- /dev/null +++ b/data/settings/1.20.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 <