migration: add ntp refclock and chrony access settings

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.

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/).

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"
 ]

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",

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

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);
+    }
+}