{"id":13472663,"url":"https://github.com/bottlerocket-os/bottlerocket","last_synced_at":"2026-04-08T03:03:28.646Z","repository":{"id":37051518,"uuid":"179385712","full_name":"bottlerocket-os/bottlerocket","owner":"bottlerocket-os","description":"An operating system designed for hosting containers","archived":false,"fork":false,"pushed_at":"2026-02-25T19:29:47.000Z","size":16873,"stargazers_count":9534,"open_issues_count":173,"forks_count":564,"subscribers_count":124,"default_branch":"develop","last_synced_at":"2026-02-25T21:56:40.835Z","etag":null,"topics":["containers","linux","operating-system","rust"],"latest_commit_sha":null,"homepage":"https://bottlerocket.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bottlerocket-os.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORTED-HARDWARE.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":"COPYRIGHT","agents":null,"dco":null,"cla":null}},"created_at":"2019-04-03T23:28:55.000Z","updated_at":"2026-02-25T19:29:52.000Z","dependencies_parsed_at":"2023-10-02T20:33:06.129Z","dependency_job_id":"ad8b4e07-4590-4f54-a8e3-9de011127325","html_url":"https://github.com/bottlerocket-os/bottlerocket","commit_stats":{"total_commits":4763,"total_committers":102,"mean_commits":46.69607843137255,"dds":0.8389670375813563,"last_synced_commit":"95d4e5b446d129632b4985b09911c78f364c2ccf"},"previous_names":[],"tags_count":123,"template":false,"template_full_name":null,"purl":"pkg:github/bottlerocket-os/bottlerocket","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bottlerocket-os%2Fbottlerocket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bottlerocket-os%2Fbottlerocket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bottlerocket-os%2Fbottlerocket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bottlerocket-os%2Fbottlerocket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bottlerocket-os","download_url":"https://codeload.github.com/bottlerocket-os/bottlerocket/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bottlerocket-os%2Fbottlerocket/sbom","scorecard":{"id":248951,"data":{"date":"2025-08-11","repo":{"name":"github.com/bottlerocket-os/bottlerocket","commit":"fc729f6affb64bfe059a4bc17e096cd25deb420d"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":7,"checks":[{"name":"Code-Review","score":10,"reason":"all changesets reviewed","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":10,"reason":"30 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/build.yml:1","Warn: no topLevel permission defined: .github/workflows/cache.yml:1","Warn: no topLevel permission defined: .github/workflows/weekly.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":10,"reason":"all dependencies are pinned","details":["Info:   3 out of   3 GitHub-owned GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE-APACHE:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during GetBranch(1.22.x): error during branchesHandler.query: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":8,"reason":"2 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: RUSTSEC-2024-0014","Warn: Project is vulnerable to: RUSTSEC-2024-0436"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-17T08:07:01.227Z","repository_id":37051518,"created_at":"2025-08-17T08:07:01.227Z","updated_at":"2025-08-17T08:07:01.227Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30068551,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T01:03:42.280Z","status":"ssl_error","status_checked_at":"2026-03-04T01:03:23.410Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","linux","operating-system","rust"],"created_at":"2024-07-31T16:00:56.889Z","updated_at":"2026-04-08T03:03:28.639Z","avatar_url":"https://github.com/bottlerocket-os.png","language":"Rust","readme":"# Bottlerocket OS\n\nWelcome to Bottlerocket!\n\nBottlerocket is a free and open-source Linux-based operating system meant for hosting containers.\n\nTo learn more about Bottlerocket, visit the [official Bottlerocket website and documentation](https://bottlerocket.dev/).\nOtherwise, if you’re ready to jump right in, read one of our setup guides for running Bottlerocket in [Amazon EKS](QUICKSTART-EKS.md), [Amazon ECS](QUICKSTART-ECS.md), or [VMware](QUICKSTART-VMWARE.md).\nIf you're interested in running Bottlerocket on bare metal servers, please refer to the [provisioning guide](PROVISIONING-METAL.md) to get started.\n\nBottlerocket focuses on security and maintainability, providing a reliable, consistent, and safe platform for container-based workloads.\nThis is a reflection of what we've learned building operating systems and services at Amazon.\nYou can read more about what drives us in [our charter](CHARTER.md).\n\nThe base operating system has just what you need to run containers reliably, and is built with standard open-source components.\nBottlerocket-specific additions focus on reliable updates and on the API.\nInstead of making configuration changes manually, you can change settings with an API call, and these changes are automatically migrated through updates.\n\nSome notable features include:\n\n* [API access](#api) for configuring your system, with secure out-of-band [access methods](#exploration) when you need them.\n* [Updates](#updates) based on partition flips, for fast and reliable system updates.\n* [Modeled configuration](#settings) that's automatically migrated through updates.\n* [Security](#security) as a top priority.\n\n## Participate in the Community\n\nThere are many ways to take part in the Bottlerocket community:\n\n- [Join us on Meetup](https://www.meetup.com/bottlerocket-community/) to hear about the latest Bottlerocket (virtual/in-person) events and community meetings.\n  Community meetings are typically every other week.\n\n  Details can be found under the [Events section on Meetup](https://www.meetup.com/bottlerocket-community/events/), and you will receive email notifications if you become a member of the Meetup group. (It's free to join!)\n\n- [Start or join a discussion](https://github.com/bottlerocket-os/bottlerocket/discussions) if you have questions about Bottlerocket.\n- If you're interested in contributing, thank you!\n  Please see our [contributor's guide](CONTRIBUTING.md).\n\n## Contact us\n\nIf you find a security issue, please [contact our security team](https://github.com/bottlerocket-os/bottlerocket/security/policy) rather than opening an issue.\n\nWe use GitHub issues to track other bug reports and feature requests.\nYou can look at [existing issues](https://github.com/bottlerocket-os/bottlerocket/issues) to see whether your concern is already known.\n\nIf not, you can select from a few templates and get some guidance on the type of information that would be most helpful.\n[Contact us with a new issue here.](https://github.com/bottlerocket-os/bottlerocket/issues/new/choose)\n\nWe don't have other communication channels set up quite yet, but don't worry about making an issue or a discussion thread!\nYou can let us know about things that seem difficult, or even ways you might like to help.\n\n## Variants\n\nTo start, we're focusing on the use of Bottlerocket as a host OS in AWS EKS Kubernetes clusters and Amazon ECS clusters.\nWe’re excited to get early feedback and to continue working on more use cases!\n\nBottlerocket is architected such that different cloud environments and container orchestrators can be supported in the future.\nA build of Bottlerocket that supports different features or integration characteristics is known as a 'variant'.\nThe artifacts of a build will include the architecture and variant name.\nFor example, an `x86_64` build of the `aws-k8s-1.32` variant will produce an image named `bottlerocket-aws-k8s-1.32-x86_64-\u003cversion\u003e-\u003ccommit\u003e.img`.\n\nThe following variants support EKS, as described above:\n\n* `aws-k8s-1.30`\n* `aws-k8s-1.31`\n* `aws-k8s-1.32`\n* `aws-k8s-1.33`\n* `aws-k8s-1.34`\n* `aws-k8s-1.35`\n* `aws-k8s-1.30-nvidia`\n* `aws-k8s-1.31-nvidia`\n* `aws-k8s-1.32-nvidia`\n* `aws-k8s-1.33-nvidia`\n* `aws-k8s-1.34-nvidia`\n* `aws-k8s-1.35-nvidia`\n\nThe following variants support ECS:\n\n* `aws-ecs-2`\n* `aws-ecs-2-nvidia`\n* `aws-ecs-3`\n* `aws-ecs-3-fips`\n* `aws-ecs-3-nvidia`\n\nWe also have variants that are designed to be Kubernetes worker nodes in VMware:\n\n* `vmware-k8s-1.30`\n* `vmware-k8s-1.31`\n* `vmware-k8s-1.32`\n* `vmware-k8s-1.33`\n* `vmware-k8s-1.34`\n* `vmware-k8s-1.35`\n\nThe following variants are no longer supported:\n\n* All Kubernetes variants using Kubernetes 1.29 and earlier\n* VMware variants using Kubernetes 1.29 and earlier\n* Bare metal variants for Kubernetes\n* ECS-1 variants\n\nWe recommend users replace nodes running these variants with the [latest variant compatible with their cluster](variants/).\n\n## Architectures\n\nOur supported architectures include `x86_64` and `aarch64` (written as `arm64` in some contexts).\n\n## Setup\n\n:walking: :running:\n\nBottlerocket is best used with a container orchestrator.\nTo get started with Kubernetes in Amazon EKS, please see [QUICKSTART-EKS](QUICKSTART-EKS.md).\nTo get started with Kubernetes in VMware, please see [QUICKSTART-VMWARE](QUICKSTART-VMWARE.md).\nTo get started with Amazon ECS, please see [QUICKSTART-ECS](QUICKSTART-ECS.md).\nThese guides describe:\n\n* how to set up a cluster with the orchestrator, so your Bottlerocket instance can run containers\n* how to launch a Bottlerocket instance in EC2 or VMware\n\nTo see how to provision Bottlerocket on bare metal, see [PROVISIONING-METAL](PROVISIONING-METAL.md).\n\nTo build your own Bottlerocket images, please see [BUILDING](BUILDING.md).\nIt describes:\n\n* how to build an image\n* how to register an EC2 AMI from an image\n\nTo publish your built Bottlerocket images, please see [PUBLISHING](PUBLISHING.md).\nIt describes:\n\n* how to make TUF repos including your image\n* how to copy your AMI across regions\n* how to mark your AMIs public or grant access to specific accounts\n* how to make your AMIs discoverable using [SSM parameters](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)\n\n## Exploration\n\nTo improve security, there's no SSH server in a Bottlerocket image, and not even a shell.\n\nDon't panic!\n\nThere are a couple out-of-band access methods you can use to explore Bottlerocket like you would a typical Linux system.\nEither option will give you a shell within Bottlerocket.\nFrom there, you can [change settings](#settings), manually [update Bottlerocket](#updates), debug problems, and generally explore.\n\n**Note:** These methods require that your instance has permission to access the ECR repository where these containers live; the appropriate policy to add to your instance's IAM role is `AmazonEC2ContainerRegistryReadOnly`.\n\n### Control container\n\nBottlerocket has a [\"control\" container](https://github.com/bottlerocket-os/bottlerocket-control-container), enabled by default, that runs outside of the orchestrator in a separate instance of containerd.\nThis container runs the [AWS SSM agent](https://github.com/aws/amazon-ssm-agent) that lets you run commands, or start shell sessions, on Bottlerocket instances in EC2.\n(You can easily replace this control container with your own just by changing the URI; see [Settings](#settings).)\n\nIn AWS, you need to give your instance the SSM role for this to work; see the [setup guide](QUICKSTART-EKS.md#enabling-ssm).\nOutside of AWS, you can use [AWS Systems Manager for hybrid environments](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-managedinstances.html).\nThere's more detail about hybrid environments in the [control container documentation](https://github.com/bottlerocket-os/bottlerocket-control-container/#connecting-to-aws-systems-manager-ssm).\n\nOnce the instance is started, you can start a session:\n\n* Go to AWS SSM's [Session Manager](https://console.aws.amazon.com/systems-manager/session-manager/sessions)\n* Select \"Start session\" and choose your Bottlerocket instance\n* Select \"Start session\" again to get a shell\n\nIf you prefer a command-line tool, you can start a session with a recent [AWS CLI](https://aws.amazon.com/cli/) and the [session-manager-plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html).\nThen you'd be able to start a session using only your instance ID, like this:\n\n```shell\naws ssm start-session --target INSTANCE_ID --region REGION_CODE\n```\n\nWith the [default control container](https://github.com/bottlerocket-os/bottlerocket-control-container), you can make [API calls](#api) to configure and manage your Bottlerocket host.\nTo do even more, read the next section about the [admin container](#admin-container).\nYou can access the admin container from the control container like this:\n\n```shell\nenter-admin-container\n```\n\n### Admin container\n\nBottlerocket has an [administrative container](https://github.com/bottlerocket-os/bottlerocket-admin-container), disabled by default, that runs outside of the orchestrator in a separate instance of containerd.\nThis container has an SSH server that lets you log in as `ec2-user` using your EC2-registered SSH key.\nOutside of AWS, you can [pass in your own SSH keys](https://github.com/bottlerocket-os/bottlerocket-admin-container#authenticating-with-the-admin-container).\n(You can easily replace this admin container with your own just by changing the URI; see [Settings](#settings).\n\nTo enable the container, you can change the setting in user data when starting Bottlerocket, for example EC2 instance user data:\n\n```toml\n[settings.host-containers.admin]\nenabled = true\n```\n\nIf Bottlerocket is already running, you can enable the admin container from the default [control container](#control-container) like this:\n\n```shell\nenable-admin-container\n```\n\nOr you can start an interactive session immediately like this:\n\n```shell\nenter-admin-container\n```\n\nIf you're using a custom control container, or want to make the API calls directly, you can enable the admin container like this instead:\n\n```shell\napiclient set host-containers.admin.enabled=true\n```\n\nOnce you've enabled the admin container, you can either access it through SSH or execute commands from the control container like this:\n\n```shell\napiclient exec admin bash\n```\n\nOnce you're in the admin container, you can run `sheltie` to get a full root shell in the Bottlerocket host.\nBe careful; while you can inspect and change even more as root, Bottlerocket's filesystem and dm-verity setup will prevent most changes from persisting over a restart - see [Security](#security).\n\n## Updates\n\nRather than a package manager that updates individual pieces of software, Bottlerocket downloads a full filesystem image and reboots into it.\nIt can automatically roll back if boot failures occur, and workload failures can trigger manual rollbacks.\n\nThe update process uses images secured by [TUF](https://theupdateframework.github.io/).\nFor more details, see the [update system documentation](sources/updater/).\n\n### Update methods\n\nThere are several ways of updating your Bottlerocket hosts.\nWe provide tools for automatically updating hosts, as well as an API for direct control of updates.\n\n#### Automated updates\n\nFor EKS variants of Bottlerocket, we recommend using the [Bottlerocket update operator](https://github.com/bottlerocket-os/bottlerocket-update-operator) for automated updates.\n\nFor the ECS variant of Bottlerocket, we recommend using the [Bottlerocket ECS updater](https://github.com/bottlerocket-os/bottlerocket-ecs-updater/) for automated updates.\n\n#### Update API\n\nThe [Bottlerocket API](#api) includes methods for checking and starting system updates.\nYou can read more about the update APIs in our [update system documentation](sources/updater/README.md#update-api).\n\napiclient knows how to handle those update APIs for you, and you can run it from the [control](#control-container) or [admin](#admin-container) containers.\n\nTo see what updates are available:\n\n```shell\napiclient update check\n```\n\nIf an update is available, it will show up in the `chosen_update` field.\nThe `available_updates` field will show the full list of available versions, including older versions, because Bottlerocket supports safely rolling back.\n\nTo apply the latest update:\n\n```shell\napiclient update apply\n```\n\nThe next time you reboot, you'll start up in the new version, and system configuration will be automatically [migrated](sources/api/migration/).\nTo reboot right away:\n\n```shell\napiclient reboot\n```\n\nIf you're confident about updating, the `apiclient update apply` command has `--check` and `--reboot` flags to combine the above actions, so you can accomplish all of the above steps like this:\n\n```shell\napiclient update apply --check --reboot\n```\n\nSee the [apiclient documentation](sources/api/apiclient/) for more details.\n\n### Update rollback\n\nThe system will automatically roll back if it's unable to boot.\nIf the update is not functional for a given container workload, you can do a manual rollback:\n\n```shell\nsignpost rollback-to-inactive\nreboot\n```\n\nThis doesn't require any external communication, so it's quicker than `apiclient`, and it's made to be as reliable as possible.\n\n## Settings\n\nHere we'll describe the settings you can configure on your Bottlerocket instance, and how to do it.\n\n(API endpoints are defined in our [OpenAPI spec](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/sources/api/openapi.yaml) if you want more detail.)\n\n### Interacting with settings\n\n#### Using the API client\n\nYou can see the current settings with an API request:\n\n```shell\napiclient get settings\n```\n\nThis will return all of the current settings in JSON format.\nFor example, here's an abbreviated response:\n\n```json\n{\"motd\": \"...\", {\"kubernetes\": {}}}\n```\n\nYou can change settings like this:\n\n```shell\napiclient set motd=\"hi there\" kubernetes.node-labels.environment=test\n```\n\nYou can also use a JSON input mode to help change many related settings at once, and a \"raw\" mode if you want more control over how the settings are committed and applied to the system.\nSee the [apiclient README](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/sources/api/apiclient/) for details.\n\n#### Using user data\n\nIf you know what settings you want to change when you start your Bottlerocket instance, you can send them in the user data.\n\nIn user data, we structure the settings in TOML form to make things a bit simpler.\nHere's the user data to change the message of the day setting, as we did in the last section:\n\n```toml\n[settings]\nmotd = \"my own value!\"\n```\n\nIf your user data is over the size limit of the platform (e.g. 16KiB for EC2) you can compress the contents with gzip.\n(With [aws-cli](https://aws.amazon.com/cli/), you can use `--user-data fileb:///path/to/gz-file` to pass binary data.)\n\n### Description of settings\n\nHere we'll describe each setting you can change.\n\n**Note:** You can see the default values (for any settings that are not generated at runtime) by looking in the `defaults.d` directory for a variant, for example [aws-ecs-2](sources/models/src/aws-ecs-2/defaults.d/).\n\nWhen you're sending settings to the API, or receiving settings from the API, they're in a structured JSON format.\nThis allows modification of any number of keys at once.\nIt also lets us ensure that they fit the definition of the Bottlerocket data model - requests with invalid settings won't even parse correctly, helping ensure safety.\n\nHere, however, we'll use the shortcut \"dotted key\" syntax for referring to keys.\nThis is used in some API endpoints with less-structured requests or responses.\nIt's also more compact for our needs here.\n\nIn this format, \"settings.kubernetes.cluster-name\" refers to the same key as in the JSON `{\"settings\": {\"kubernetes\": {\"cluster-name\": \"value\"}}}`.\n\n**NOTE:** [bottlerocket.dev](https://bottlerocket.dev/en/os/latest/#/api/settings/) now contains a complete, versioned setting reference.\nThis documents retains the headings below for existing link and bookmark compatability.\nPlease update your bookmarks and check out [bottlerocket.dev](https://bottlerocket.dev/) for future updates to the setting reference.\n\n#### Top-level settings\n\nSee the [`settings.motd` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/motd/).\n\n#### Kubernetes settings\n\nSee the [`settings.kubernetes.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/kubernetes/).\n\n#### Amazon ECS settings\n\nSee the [`settings.ecs.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/ecs/).\n\n#### CloudFormation signal helper settings\n\nSee the [`settings.cloudformation.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/cloudformation/).\n\n#### Auto Scaling group settings\n\nSee the [`settings.autoscaling.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/autoscaling/).\n\n#### OCI Hooks settings\n\nSee the [`settings.oci-hooks.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/oci-hooks/).\n\n#### OCI Defaults settings\n\nSee the [`settings.oci-defaults.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/oci-defaults/).\n\n##### OCI Defaults: Capabilities\n\nSee the [\"Capabilities Settings\" section in the `settings.oci-defaults.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/oci-defaults/).\n\n##### OCI Defaults: Resource Limits\n\nSee the [\"Resource Limits Settings\" section in the `settings.oci-defaults.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/oci-defaults/).\n\n#### Container image registry settings\n\nSee the [`settings.container-registry.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/container-registry/).\n\n#### Container runtime settings\n\nSee the [`settings.container-runtime.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/container-runtime/).\n\n#### Updates settings\n\nSee the [`settings.updates.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/updates/).\n\n#### Network settings\n\nSee the [`settings.network.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/network/).\n\n##### Proxy settings\n\nSee the [\"Proxy Settings\" section in the `settings.networks.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/network/).\n\n#### Metrics settings\n\nSee the [`settings.metrics.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/metrics/).\n\n#### Time settings\n\nSee the [`settings.ntp.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/ntp/).\n\n#### Kernel settings\n\nSee the [`settings.kernel.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/kernel/).\n\n#### Boot-related settings\n\nSee the [`settings.boot.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/boot/).\n\n#### Custom CA certificates settings\n\nSee the [`settings.pki.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/pki/).\n\n#### Host containers settings\n\nSee the [`settings.host-containers.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/host-containers/).\n\n##### Custom host containers\n\nSee the [Host Containers documentation](https://bottlerocket.dev/en/os/latest/#/concepts/host-containers/).\n\n#### Bootstrap commands settings\n\nSee the [`settings.bootstrap-commands.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/bootstrap-commands/) as well as the [Bootstrap Commands documentation](https://bottlerocket.dev/en/os/latest/#/concepts/bootstrap-commands/)\n\n#### Bootstrap containers settings\n\nSee the [`settings.bootstrap-containers.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/bootstrap-containers/) as well as the [Bootstrap Containers documentation](https://bottlerocket.dev/en/os/latest/#/concepts/bootstrap-containers/)\n\n##### Mount propagations in bootstrap and superpowered containers\n\nBoth bootstrap and superpowered host containers are configured with the `/.bottlerocket/rootfs/mnt` bind mount that points to `/mnt` in the host, which itself is a bind mount of `/local/mnt`.\nThis bind mount is set up with shared propagations, so any new mount point created underneath `/.bottlerocket/rootfs/mnt` in any bootstrap or superpowered host container will propagate across mount namespaces.\nYou can use this feature to configure ephemeral disks attached to your hosts that you may want to use on your workloads.\n\n#### Platform-specific settings\n\nPlatform-specific settings are automatically set at boot time by [early-boot-config](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/sources/early-boot-config/early-boot-config) based on metadata available on the running platform.\nThey can be overridden for testing purposes in [the same way as other settings](#interacting-with-settings).\n\n##### AWS-specific settings\n\nSee the [`settings.aws.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/aws/).\n\n### Logs\n\nYou can use `logdog` through the [admin container](#admin-container) to obtain an archive of log files from your Bottlerocket host.\n\nFor a list of what is collected, see the logdog [command list](https://github.com/bottlerocket-os/bottlerocket-core-kit/blob/develop/sources/logdog/src/log_request.rs).\n\n#### Generating logs\n\nSSH to the Bottlerocket host or `apiclient exec admin bash` to access the admin container, then run:\n\n```shell\nsudo sheltie\nlogdog\n```\n\nThis will write an archive of the logs to `/var/log/support/bottlerocket-logs.tar.gz`.\nThis archive is accessible from host containers at `/.bottlerocket/support`.\n\n#### Fetching logs\n\nThere are multiple methods to retrieve the generated log archive.\n\n- **Via SSH if already enabled**\n\n    Once you have exited from the Bottlerocket host, run a command like:\n\n    ```shell\n    ssh -i YOUR_KEY_FILE \\\n    ec2-user@YOUR_HOST \\\n    \"cat /.bottlerocket/support/bottlerocket-logs.tar.gz\" \u003e bottlerocket-logs.tar.gz\n    ```\n\n- **With `kubectl get` if running Kubernetes**\n\n    ```shell\n    kubectl get --raw \\\n    \"/api/v1/nodes/NODE_NAME/proxy/logs/support/bottlerocket-logs.tar.gz\" \u003e bottlerocket-logs.tar.gz\n    ```\n\n- **Using [SSH over SSM](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started-enable-ssh-connections.html) if your instance isn't accessible through SSH or Kubernetes**\n\n### Kdump Support\n\nBottlerocket provides support to collect kernel crash dumps whenever the system kernel panics.\nOnce this happens, both the dmesg log and vmcore dump are stored at `/var/log/kdump`, and the system reboots.\n\nThere are a few important caveats about the provided kdump support:\n\n* Currently, only vmware variants have kdump support enabled\n* The system kernel will reserve 256MB for the crash kernel, only when the host has at least 2GB of memory; the reserved space won't be available for processes running in the host\n* The crash kernel will only be loaded when the `crashkernel` parameter is present in the kernel's cmdline and if there is memory reserved for it\n\n### NVIDIA GPUs Support\n\nBottlerocket's `nvidia` variants include the required packages and configurations to leverage NVIDIA GPUs.\nCurrently, the following NVIDIA driver versions are supported in Bottlerocket:\n\n* 470.X\n* 515.X\n\nThe official AMIs for these variants can be used with EC2 GPU-equipped instance types such as: `p2`, `p3`, `p4`, `g3`, `g4dn`, `g5` and `g5g`.\nNote that older instance types, such as `p2`, are not supported by NVIDIA driver `515.X` and above.\nYou need to make sure you select the appropriate AMI depending on the instance type you are planning to use.\nPlease see [QUICKSTART-EKS](QUICKSTART-EKS.md#aws-k8s--nvidia-variants) for further details about Kubernetes variants, and [QUICKSTART-ECS](QUICKSTART-ECS.md#aws-ecs--nvidia-variants) for ECS variants.\n\n### Neuron Accelerated Instance Support\n\nBottlerocket variants, from `v1.30.0+`, include the required packages and configurations to leverage [AWS Neuron Accelerated Instances](https://aws.amazon.com/ai/machine-learning/neuron/).\n\nThe AMIs can be used with EC2 Neuron-equipped instance types such as: `inf1`, `inf2`, `trn1`, and `trn2`.\n\nPlease see [QUICKSTART-EKS](QUICKSTART-EKS.md#Neuron-Support) for further details about Kubernetes variants, and [QUICKSTART-ECS](QUICKSTART-ECS.md#Neuron-Support) for ECS variants.\n\n## Details\n\n### Security\n\n:shield: :crab:\n\nTo learn more about security features in Bottlerocket, please see [SECURITY FEATURES](SECURITY_FEATURES.md).\nIt describes how we use features like [dm-verity](https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity) and [SELinux](https://selinuxproject.org/) to protect the system from security threats.\n\nTo learn more about security recommendations for Bottlerocket, please see [SECURITY GUIDANCE](SECURITY_GUIDANCE.md).\nIt documents additional steps you can take to secure the OS, and includes resources such as a [Pod Security Policy](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) for your reference.\n\nIn addition, almost all first-party components are written in [Rust](https://www.rust-lang.org/).\nRust eliminates some classes of memory safety issues, and encourages design patterns that help security.\n\n### Packaging\n\nBottlerocket is built from source using a container toolchain.\nWe use RPM package definitions to build and install individual packages into an image.\nRPM itself is not in the image - it's just a common and convenient package definition format.\n\nWe currently package the following major third-party components:\n\n* Linux kernel ([background](https://en.wikipedia.org/wiki/Linux), [5.10 packaging](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/kernel-5.10/), [5.15 packaging](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/kernel-5.15/))\n* glibc ([background](https://www.gnu.org/software/libc/), [packaging](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/glibc/))\n* Buildroot as build toolchain ([background](https://buildroot.org/), via the [SDK](https://github.com/bottlerocket-os/bottlerocket-sdk))\n* GRUB, with patches for partition flip updates ([background](https://www.gnu.org/software/grub/), [packaging](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/grub/))\n* systemd as init ([background](https://en.wikipedia.org/wiki/Systemd), [packaging](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/systemd/))\n* wicked for networking ([background](https://github.com/openSUSE/wicked), [packaging](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/wicked/))\n* containerd ([background](https://containerd.io/), [packaging](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/containerd/))\n* Kubernetes ([background](https://kubernetes.io/), [packaging](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/kubernetes-1.30/))\n* aws-iam-authenticator ([background](https://github.com/kubernetes-sigs/aws-iam-authenticator), [packaging](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/aws-iam-authenticator/))\n* Amazon ECS agent ([background](https://github.com/aws/amazon-ecs-agent), [packaging](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/ecs-agent/))\n\nFor further documentation or to see the rest of the packages, see the [packaging directory](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/packages/).\n\n### Updates\n\nThe Bottlerocket image has two identical sets of partitions, A and B.\nWhen updating Bottlerocket, the partition table is updated to point from set A to set B, or vice versa.\n\nWe also track successful boots, and if there are failures it will automatically revert back to the prior working partition set.\n\nThe update process uses images secured by [TUF](https://theupdateframework.github.io/).\nFor more details, see the [update system documentation](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/sources/updater).\n\n### API\n\nThere are two main ways you'd interact with a production Bottlerocket instance.\n(There are a couple more [exploration](#exploration) methods above for test instances.)\n\nThe first method is through a container orchestrator, for when you want to run or manage containers.\nThis uses the standard channel for your orchestrator, for example a tool like `kubectl` for Kubernetes.\n\nThe second method is through the Bottlerocket API, for example when you want to configure the system.\n\nThere's an HTTP API server that listens on a local Unix-domain socket.\nRemote access to the API requires an authenticated transport such as SSM's RunCommand or Session Manager, as described above.\nFor more details, see the [apiserver documentation](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/sources/api/apiserver/).\n\nThe [apiclient](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/sources/api/apiclient/) can be used to make requests.\nThey're just HTTP requests, but the API client simplifies making requests with the Unix-domain socket.\n\nTo make configuration easier, we have [early-boot-config](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/sources/early-boot-config/early-boot-config), which can send an API request for you based on instance user data.\nIf you start a virtual machine, like an EC2 instance, it will read TOML-formatted Bottlerocket configuration from user data and send it to the API server.\nThis way, you can configure your Bottlerocket instance without having to make API calls after launch.\n\nSee [Settings](#settings) above for examples and to understand what you can configure.\n\nYou can also access host containers through the API using [apiclient exec](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/sources/api/apiclient#exec-mode).\n\nThe server and client are the user-facing components of the API system, but there are a number of other components that work together to make sure your settings are applied, and that they survive upgrades of Bottlerocket.\n\nFor more details, see the [API system documentation](https://github.com/bottlerocket-os/bottlerocket-core-kit/tree/develop/sources/api).\n\n### Default Volumes\n\nBottlerocket operates with two default storage volumes.\n\n* The root device, holds the active and passive [partition sets](#updates-1).\n  It also contains the bootloader, the dm-verity hash tree for verifying the [immutable root filesystem](SECURITY_FEATURES.md#immutable-rootfs-backed-by-dm-verity), and the data store for the Bottlerocket API.\n* The data device is used as persistent storage for container images, container orchestration, [host-containers](#Custom-host-containers), and [bootstrap containers](#Bootstrap-containers-settings).\n  The operating system does not typically make changes to this volume during regular updates, though changes to upstream software such as containerd or kubelet could result in changes to their stored data.\n  This device (mounted to `/local` on the host) can be used for application storage for orchestrated workloads; however, we recommend using an additional volume if possible for such cases.\n  See [this section of the Security Guidance documentation](./SECURITY_GUIDANCE.md#limit-access-to-system-mounts) for more information.\n\nOn boot Bottlerocket will increase the data partition size to use all of the data device.\nIf you increase the size of the device, you can reboot Bottlerocket to extend the data partition.\nIf you need to extend the data partition without rebooting, have a look at this [discussion](https://github.com/bottlerocket-os/bottlerocket/discussions/2011).\n","funding_links":[],"categories":["Rust","HarmonyOS","Operating System","Rust-based Operating Systems","Open Source Operating Systems","Rust (42)","其他__大数据","rust","Cloud","Uncategorized"],"sub_categories":["Windows Manager","In-memory data grids","Interfaces","网络服务_其他","VS Code Extensions for Developer Productivity","Mesh networks","JavaScript Libraries for Machine Learning","AWS","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbottlerocket-os%2Fbottlerocket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbottlerocket-os%2Fbottlerocket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbottlerocket-os%2Fbottlerocket/lists"}