Adding new configuration setting: agent.upgrade.rollback.window (elastic#8065)

* Adding new configuration setting: agent.upgrade.rollback.window

* Adding CHANGELOG entry

* Update config reference template

* Run mage update

* Update _meta/config/common.reference.p2.yml.tmpl

Co-authored-by: Paolo Chilà <[email protected]>

* Update changelog/fragments/1746197293-config-rollback-window.yaml

Co-authored-by: Paolo Chilà <[email protected]>

---------

Co-authored-by: Paolo Chilà <[email protected]>

Author: ycombinator

_meta/config/common.reference.p2.yml.tmpl

@@ -119,6 +119,12 @@ inputs:
 #   # duration will increase for subsequent retry attempts in a randomized exponential backoff manner.
 #   retry_sleep_init_duration: 30s
 
+# agent.upgrade
+#   # rollback settings
+#   rollback:
+#       # duration in which an upgraded Agent may be manually rolled back.
+#       window: 168h
+
 # agent.process:
 #   # timeout for creating new processes. when process is not successfully created by this timeout
 #   # start operation is considered a failure

changelog/fragments/1746197293-config-rollback-window.yaml

@@ -0,0 +1,36 @@
+# Kind can be one of:
+# - breaking-change: a change to previously-documented behavior
+# - deprecation: functionality that is being removed in a later release
+# - bug-fix: fixes a problem in a previous version
+# - enhancement: extends functionality but does not break or fix existing behavior
+# - feature: new functionality
+# - known-issue: problems that we are aware of in a given version
+# - security: impacts on the security of a product or a user’s deployment.
+# - upgrade: important information for someone upgrading from a prior version
+# - other: does not fit into any of the other categories
+kind: feature
+
+# Change summary; a 80ish characters long description of the change.
+summary: Adds a new configuration setting, `agent.upgrade.rollback.window`
+
+# Long description; in case the summary is not enough to describe the change
+# this field accommodate a description without length limits.
+# NOTE: This field will be rendered only for breaking-change and known-issue kinds at the moment.
+description: |
+  The value of the `agent.upgrade.rollback.window` setting determines the period after upgrading
+  Elastic Agent when a rollback to the previous version can be triggered. This is an optional
+  setting, with a default value of `168h` (7 days). The value can be any string that is parseable
+  by https://pkg.go.dev/time#ParseDuration.
+
+# Affected component; usually one of "elastic-agent", "fleet-server", "filebeat", "metricbeat", "auditbeat", "all", etc.
+component: elastic-agent
+
+# PR URL; optional; the PR number that added the changeset.
+# If not present is automatically filled by the tooling finding the PR where this changelog fragment has been added.
+# NOTE: the tooling supports backports, so it's able to fill the original PR number instead of the backport PR number.
+# Please provide it if you are adding a fragment for a different PR.
+pr: https://github.com/elastic/elastic-agent/pull/8065
+
+# Issue URL; optional; the GitHub issue related to this changeset (either closes or is part of).
+# If not present is automatically filled by the tooling with the issue linked to the PR number.
+issue: https://github.com/elastic/elastic-agent/issues/6881

elastic-agent.reference.yml

@@ -125,6 +125,12 @@ inputs:
 #   # duration will increase for subsequent retry attempts in a randomized exponential backoff manner.
 #   retry_sleep_init_duration: 30s
 
+# agent.upgrade
+#   # rollback settings
+#   rollback:
+#       # duration in which an upgraded Agent may be manually rolled back.
+#       window: 168h
+
 # agent.process:
 #   # timeout for creating new processes. when process is not successfully created by this timeout
 #   # start operation is considered a failure

internal/pkg/agent/configuration/upgrade.go

@@ -12,11 +12,16 @@ const (
 
 	// interval between checks for new (upgraded) Agent returning an error status.
 	defaultStatusCheckInterval = 30 * time.Second
+
+	// period during which an upgraded Agent can be asked to rollback to the previous
+	// Agent version on disk.
+	defaultRollbackWindowDuration = 7 * 24 * time.Hour // 7 days
 )
 
 // UpgradeConfig is the configuration related to Agent upgrades.
 type UpgradeConfig struct {
-	Watcher *UpgradeWatcherConfig `yaml:"watcher" config:"watcher" json:"watcher"`
+	Watcher  *UpgradeWatcherConfig  `yaml:"watcher" config:"watcher" json:"watcher"`
+	Rollback *UpgradeRollbackConfig `yaml:"rollback" config:"rollback" json:"rollback"`
 }
 
 type UpgradeWatcherConfig struct {
@@ -27,6 +32,10 @@ type UpgradeWatcherCheckConfig struct {
 	Interval time.Duration `yaml:"interval" config:"interval" json:"interval"`
 }
 
+type UpgradeRollbackConfig struct {
+	Window time.Duration `yaml:"window" config:"window" json:"window"`
+}
+
 func DefaultUpgradeConfig() *UpgradeConfig {
 	return &UpgradeConfig{
 		Watcher: &UpgradeWatcherConfig{
@@ -35,5 +44,8 @@ func DefaultUpgradeConfig() *UpgradeConfig {
 				Interval: defaultStatusCheckInterval,
 			},
 		},
+		Rollback: &UpgradeRollbackConfig{
+			Window: defaultRollbackWindowDuration,
+		},
 	}
 }

internal/pkg/agent/configuration/upgrade_test.go

@@ -0,0 +1,99 @@
+// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+// or more contributor license agreements. Licensed under the Elastic License 2.0;
+// you may not use this file except in compliance with the Elastic License 2.0.
+
+package configuration
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/elastic/elastic-agent/internal/pkg/config"
+)
+
+func TestParseUpgradeConfig(t *testing.T) {
+	tests := map[string]struct {
+		cfg      map[string]any
+		expected UpgradeConfig
+	}{
+		"default": {
+			cfg: map[string]any{},
+			expected: UpgradeConfig{
+				Watcher: &UpgradeWatcherConfig{
+					GracePeriod: defaultGracePeriodDuration,
+					ErrorCheck: UpgradeWatcherCheckConfig{
+						Interval: defaultStatusCheckInterval,
+					},
+				},
+				Rollback: &UpgradeRollbackConfig{
+					Window: defaultRollbackWindowDuration,
+				},
+			},
+		},
+		"watcher_grace_period": {
+			cfg: map[string]any{
+				"watcher": map[string]any{
+					"grace_period": "2m",
+				},
+			},
+			expected: UpgradeConfig{
+				Watcher: &UpgradeWatcherConfig{
+					GracePeriod: 2 * time.Minute,
+					ErrorCheck: UpgradeWatcherCheckConfig{
+						Interval: defaultStatusCheckInterval,
+					},
+				},
+				Rollback: &UpgradeRollbackConfig{
+					Window: defaultRollbackWindowDuration,
+				},
+			},
+		},
+		"watcher_error_check_interval": {
+			cfg: map[string]any{
+				"watcher": map[string]any{
+					"error_check": map[string]any{
+						"interval": "1h",
+					},
+				},
+			},
+			expected: UpgradeConfig{
+				Watcher: &UpgradeWatcherConfig{
+					GracePeriod: defaultGracePeriodDuration,
+					ErrorCheck: UpgradeWatcherCheckConfig{
+						Interval: 1 * time.Hour,
+					},
+				},
+				Rollback: &UpgradeRollbackConfig{
+					Window: defaultRollbackWindowDuration,
+				},
+			},
+		},
+		"rollback_window": {
+			cfg: map[string]any{
+				"rollback.window": "8h",
+			},
+			expected: UpgradeConfig{
+				Watcher: &UpgradeWatcherConfig{
+					GracePeriod: defaultGracePeriodDuration,
+					ErrorCheck: UpgradeWatcherCheckConfig{
+						Interval: defaultStatusCheckInterval,
+					},
+				},
+				Rollback: &UpgradeRollbackConfig{
+					Window: 8 * time.Hour,
+				},
+			},
+		},
+	}
+
+	for name, test := range tests {
+		t.Run(name, func(t *testing.T) {
+			c := DefaultUpgradeConfig()
+			cfg := config.MustNewConfigFrom(test.cfg)
+			require.NoError(t, cfg.UnpackTo(c))
+			require.Equal(t, test.expected, *c)
+		})
+	}
+}