From d62d22a7ebf7c9892d42124cdabe3a6a8a0c81df Mon Sep 17 00:00:00 2001 From: Nate Smith Date: Wed, 22 Jul 2026 14:58:41 -0400 Subject: [PATCH] migration: add ntp refclock and chrony access settings Add the v1.64.0 settings migration for the new settings.ntp keys (refclocks, allow, cmdallow, bindcmdaddress) so they are removed from the datastore on downgrade to versions that don't understand them, and register it in Release.toml. Also document the Amazon Time Sync Service PTP hardware clock setup in the EKS quickstart and the settings reference in the README. Addresses #4407 and #4473. Signed-off-by: Nate Smith --- QUICKSTART-EKS.md | 18 +++++++++++++ README.md | 10 +++++++ Release.toml | 3 ++- sources/Cargo.lock | 7 +++++ sources/Cargo.toml | 1 + .../Cargo.toml | 10 +++++++ .../src/main.rs | 26 +++++++++++++++++++ 7 files changed, 74 insertions(+), 1 deletion(-) create mode 100644 sources/settings-migrations/v1.64.0/add-ntp-refclocks-and-access-settings/Cargo.toml create mode 100644 sources/settings-migrations/v1.64.0/add-ntp-refclocks-and-access-settings/src/main.rs diff --git a/QUICKSTART-EKS.md b/QUICKSTART-EKS.md index f1385a8a92c..a30a2372da9 100644 --- a/QUICKSTART-EKS.md +++ b/QUICKSTART-EKS.md @@ -409,3 +409,21 @@ spec: ``` Along with the `device-ownership-from-secuirity-context` setting, you will need to deploy the [neuron-device-plugin](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/containers/kubernetes-getting-started.html#neuron-device-plugin), and optionally, the [neuron-scheduler](https://awsdocs-neuron.readthedocs-hosted.com/en/latest/containers/kubernetes-getting-started.html#neuron-scheduler-extension). + +### Amazon Time Sync Service PTP Hardware Clock + +On [supported instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configure-ec2-ntp.html#connect-to-the-ptp-hardware-clock), the [Amazon Time Sync Service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configure-ec2-ntp.html) exposes a PTP Hardware Clock (PHC) through the ENA driver for higher-accuracy timekeeping. To let chrony synchronize from it, enable the PHC in the ENA driver and add it as a reference clock: + +```toml +[settings.boot.kernel-parameters] +# Enable the PHC device in the ENA driver. +"ena.phc_enable" = ["1"] + +[[settings.ntp.refclocks]] +# chrony's `refclock PHC /dev/ptp_ena poll 0 delay 0.000010 prefer` directive. +driver = "PHC" +parameter = "/dev/ptp_ena" +options = ["poll", "0", "delay", "0.000010", "prefer"] +``` + +Bottlerocket ships a udev rule that creates the stable `/dev/ptp_ena` symlink for the ENA PHC device. For the best accuracy, launch your instances in a [placement group with the `precision-time` strategy](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configure-ec2-ntp.html). Once the node is up, you can confirm chrony is using the clock with `chronyc sources` (look for a selected `PHC0` reference) from the admin container. diff --git a/README.md b/README.md index 89eebb8c358..1410fe3a7ff 100644 --- a/README.md +++ b/README.md @@ -416,6 +416,16 @@ See the [`settings.metrics.*` reference](https://bottlerocket.dev/en/os/latest/# See the [`settings.ntp.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/ntp/). +In addition to NTP time servers, you can point chrony at reference clocks such as the [Amazon Time Sync Service PTP Hardware Clock (PHC)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configure-ec2-ntp.html#connect-to-the-ptp-hardware-clock). +For example, to use the ENA PHC device (see the [PTP hardware clock example](QUICKSTART-EKS.md#amazon-time-sync-service-ptp-hardware-clock)): + +```toml +[[settings.ntp.refclocks]] +driver = "PHC" +parameter = "/dev/ptp_ena" +options = ["poll", "0", "delay", "0.000010", "prefer"] +``` + #### Kernel settings See the [`settings.kernel.*` reference](https://bottlerocket.dev/en/os/latest/#/api/settings/kernel/). diff --git a/Release.toml b/Release.toml index 802c3b6a33d..83c352bdabe 100644 --- a/Release.toml +++ b/Release.toml @@ -477,5 +477,6 @@ version = "1.64.0" ] "(1.63.0, 1.64.0)" = [ "migrate_v1.64.0_kubernetes-container-runtime-endpoint.lz4", - "migrate_v1.64.0_hugepages-settings.lz4" + "migrate_v1.64.0_hugepages-settings.lz4", + "migrate_v1.64.0_add-ntp-refclocks-and-access-settings.lz4" ] diff --git a/sources/Cargo.lock b/sources/Cargo.lock index 578573211e6..491dfdfac86 100644 --- a/sources/Cargo.lock +++ b/sources/Cargo.lock @@ -50,6 +50,13 @@ dependencies = [ "core_extensions", ] +[[package]] +name = "add-ntp-refclocks-and-access-settings" +version = "0.1.0" +dependencies = [ + "migration-helpers", +] + [[package]] name = "addr2line" version = "0.25.1" diff --git a/sources/Cargo.toml b/sources/Cargo.toml index f3318f335c0..1efe5fc6078 100644 --- a/sources/Cargo.toml +++ b/sources/Cargo.toml @@ -67,6 +67,7 @@ members = [ "settings-migrations/v1.63.0/nvidia-k8s-device-plugin-enabled", "settings-migrations/v1.64.0/kubernetes-container-runtime-endpoint", "settings-migrations/v1.64.0/hugepages-settings", + "settings-migrations/v1.64.0/add-ntp-refclocks-and-access-settings", "settings-plugins/aws-dev", "settings-plugins/aws-ecs-2", diff --git a/sources/settings-migrations/v1.64.0/add-ntp-refclocks-and-access-settings/Cargo.toml b/sources/settings-migrations/v1.64.0/add-ntp-refclocks-and-access-settings/Cargo.toml new file mode 100644 index 00000000000..6f3fe6d9191 --- /dev/null +++ b/sources/settings-migrations/v1.64.0/add-ntp-refclocks-and-access-settings/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "add-ntp-refclocks-and-access-settings" +version = "0.1.0" +license = "Apache-2.0 OR MIT" +edition = "2021" +publish = false +exclude = ["README.md"] + +[dependencies] +migration-helpers.workspace = true diff --git a/sources/settings-migrations/v1.64.0/add-ntp-refclocks-and-access-settings/src/main.rs b/sources/settings-migrations/v1.64.0/add-ntp-refclocks-and-access-settings/src/main.rs new file mode 100644 index 00000000000..45db4387c1d --- /dev/null +++ b/sources/settings-migrations/v1.64.0/add-ntp-refclocks-and-access-settings/src/main.rs @@ -0,0 +1,26 @@ +use migration_helpers::common_migrations::AddSettingsMigration; +use migration_helpers::{migrate, Result}; +use std::process; + +/// We added new `settings.ntp` options for configuring chrony: +/// - `refclocks` to point chrony at hardware or software reference clocks, such as the PTP +/// hardware clock exposed by the Amazon ENA driver +/// - `allow`, `cmdallow`, and `bindcmdaddress` to grant remote access to the chrony daemon +fn run() -> Result<()> { + migrate(AddSettingsMigration(&[ + "settings.ntp.refclocks", + "settings.ntp.allow", + "settings.ntp.cmdallow", + "settings.ntp.bindcmdaddress", + ])) +} + +// Returning a Result from main makes it print a Debug representation of the error, but with Snafu +// we have nice Display representations of the error, so we wrap "main" (run) and print any error. +// https://github.com/shepmaster/snafu/issues/110 +fn main() { + if let Err(e) = run() { + eprintln!("{e}"); + process::exit(1); + } +}