Include upgrade details in output of elastic-agent status during ongoing upgrade (elastic#3615)

* Remove context and handle cancellation internally instead

* More optimizations

* Add back context

* Adding FSM for upgrades

* Implementing TODO

* WIP

* WIP

* Reorganizing imports

* Running go mod tidy

* Add unit tests

* Remove Fleet changes

* Fixing booboos introduced during conflict resolution

* Add nil guard

* Setting logger in test

* Adding upgrade details to V2 control protocol

* Regenerating protobuf implementation files

* Including upgrade details in Agent state

* Adding test case

* Adding CHANGELOG entry

* Newline fixes

* Fix data types

* Generating protobuf implementations

* Running mage update

* Add generated protobuf code files to sonar exclusions list

* Try removing comments

* Include upgrade details in elastic-agent status output --full

* Increase test coverage

Author: ycombinator

changelog/fragments/1697508156-upgrade-details-in-status.yaml

@@ -0,0 +1,32 @@
+# 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: enhancement
+
+# Change summary; a 80ish characters long description of the change.
+summary: Include upgrade details in output of `elastic-agent status`.
+
+# 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:
+
+# 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/3615
+
+# 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/owner/repo/1234

control_v2.proto

@@ -171,7 +171,7 @@ message StateAgentInfo {
 }
 
 // StateResponse is the current state of Elastic Agent.
-// Next unused id: 7
+// Next unused id: 8
 message StateResponse {
   // Overall information of Elastic Agent.
   StateAgentInfo info = 1;
@@ -188,6 +188,43 @@ message StateResponse {
 
   // State of each component in Elastic Agent.
   repeated ComponentState components = 4;
+
+  // Upgrade details
+  UpgradeDetails upgrade_details = 7;
+}
+
+// UpgradeDetails captures the details of an ongoing Agent upgrade.
+message UpgradeDetails {
+  // Version the Agent is being upgraded to.
+  string target_version = 1;
+
+  // Current state of the upgrade process.
+  string state = 2;
+
+  // Fleet Action ID that initiated the upgrade, if in managed mode.
+  string action_id = 3;
+
+  // Metadata about the upgrade process.
+  UpgradeDetailsMetadata metadata = 4;
+}
+
+// UpgradeDetailsMetadata has additional information about an Agent's
+// ongoing upgrade.
+message UpgradeDetailsMetadata {
+  // If the upgrade is a scheduled upgrade, the timestamp of when the
+  // upgrade is expected to start.
+  google.protobuf.Timestamp scheduled_at = 1;
+
+  // If the upgrade is in the UPG_DOWNLOADING state, the percentage of
+  // the Elastic Agent artifact that has already been downloaded, to
+  // serve as an indicator of download progress.
+  float download_percent = 2;
+
+  // If the upgrade has failed, what upgrade state failed.
+  string failed_state = 3;
+
+  // Any error encountered during the upgrade process.
+  string error_msg = 4;
 }
 
 // DiagnosticFileResult is a file result from a diagnostic result.

internal/pkg/agent/application/upgrade/details/details_test.go

@@ -91,5 +91,4 @@ func TestDetailsDownloadRateJSON(t *testing.T) {
 		require.Equal(t, math.Inf(1), float64(unmarshalledDetails.Metadata.DownloadRate))
 		require.Equal(t, 0.99, unmarshalledDetails.Metadata.DownloadPercent)
 	})
-
 }

internal/pkg/agent/cmd/status.go

@@ -13,7 +13,9 @@ import (
 	"sort"
 	"time"
 
+	"github.com/elastic/elastic-agent/internal/pkg/agent/application/upgrade/details"
 	"github.com/elastic/elastic-agent/pkg/control/v2/client"
+	"github.com/elastic/elastic-agent/pkg/control/v2/cproto"
 
 	"gopkg.in/yaml.v2"
 
@@ -145,6 +147,43 @@ func listAgentState(l list.Writer, state *client.AgentState, all bool) {
 	}
 	l.UnIndent()
 	listComponentState(l, state.Components, all)
+
+	// Upgrade details
+	listUpgradeDetails(l, state.UpgradeDetails)
+}
+
+func listUpgradeDetails(l list.Writer, upgradeDetails *cproto.UpgradeDetails) {
+	if upgradeDetails == nil {
+		return
+	}
+
+	l.AppendItem("upgrade_details")
+	l.Indent()
+	l.AppendItem("target_version: " + upgradeDetails.TargetVersion)
+	l.AppendItem("state: " + upgradeDetails.State)
+	if upgradeDetails.ActionId != "" {
+		l.AppendItem("action_id: " + upgradeDetails.ActionId)
+	}
+
+	if upgradeDetails.Metadata != nil {
+		l.AppendItem("metadata")
+		l.Indent()
+		if upgradeDetails.Metadata.ScheduledAt != nil && !upgradeDetails.Metadata.ScheduledAt.AsTime().IsZero() {
+			l.AppendItem("scheduled_at: " + upgradeDetails.Metadata.ScheduledAt.AsTime().UTC().Format(time.RFC3339))
+		}
+		if upgradeDetails.Metadata.FailedState != "" {
+			l.AppendItem("failed_state: " + upgradeDetails.Metadata.FailedState)
+		}
+		if upgradeDetails.Metadata.ErrorMsg != "" {
+			l.AppendItem("error_msg: " + upgradeDetails.Metadata.ErrorMsg)
+		}
+		if upgradeDetails.State == string(details.StateDownloading) {
+			l.AppendItem(fmt.Sprintf("download_percent: %.2f%%", upgradeDetails.Metadata.DownloadPercent*100))
+		}
+		l.UnIndent()
+	}
+
+	l.UnIndent()
 }
 
 func listFleetState(l list.Writer, state *client.AgentState, all bool) {

internal/pkg/agent/cmd/status_test.go

@@ -6,13 +6,20 @@ package cmd
 
 import (
 	"bytes"
+	"fmt"
 	"os"
 	"path/filepath"
 	"testing"
+	"time"
+
+	"google.golang.org/protobuf/types/known/timestamppb"
+
+	"github.com/jedib0t/go-pretty/v6/list"
 
 	"github.com/stretchr/testify/require"
 
 	"github.com/elastic/elastic-agent/pkg/control/v2/client"
+	"github.com/elastic/elastic-agent/pkg/control/v2/cproto"
 )
 
 func TestHumanOutput(t *testing.T) {
@@ -148,3 +155,79 @@ func TestHumanOutput(t *testing.T) {
 		require.Equalf(t, string(expected), b.String(), "unexpected input with output: %s, state: %s", test.output, test.state_name)
 	}
 }
+
+func TestListUpgradeDetails(t *testing.T) {
+	now := time.Now().UTC()
+	cases := map[string]struct {
+		upgradeDetails *cproto.UpgradeDetails
+		expectedOutput string
+	}{
+		"no_details": {
+			upgradeDetails: nil,
+			expectedOutput: "",
+		},
+		"no_metadata": {
+			upgradeDetails: &cproto.UpgradeDetails{
+				TargetVersion: "8.12.0",
+				State:         "UPG_REQUESTED",
+				ActionId:      "foobar",
+			},
+			expectedOutput: `── upgrade_details
+   ├─ target_version: 8.12.0
+   ├─ state: UPG_REQUESTED
+   └─ action_id: foobar`,
+		},
+		"no_action_id": {
+			upgradeDetails: &cproto.UpgradeDetails{
+				TargetVersion: "8.12.0",
+				State:         "UPG_REQUESTED",
+			},
+			expectedOutput: `── upgrade_details
+   ├─ target_version: 8.12.0
+   └─ state: UPG_REQUESTED`,
+		},
+		"no_scheduled_at": {
+			upgradeDetails: &cproto.UpgradeDetails{
+				TargetVersion: "8.12.0",
+				State:         "UPG_FAILED",
+				Metadata: &cproto.UpgradeDetailsMetadata{
+					FailedState:     "UPG_DOWNLOADING",
+					ErrorMsg:        "error downloading",
+					DownloadPercent: 0.104,
+				},
+			},
+			expectedOutput: `── upgrade_details
+   ├─ target_version: 8.12.0
+   ├─ state: UPG_FAILED
+   └─ metadata
+      ├─ failed_state: UPG_DOWNLOADING
+      └─ error_msg: error downloading`,
+		},
+		"no_failed_state": {
+			upgradeDetails: &cproto.UpgradeDetails{
+				TargetVersion: "8.12.0",
+				State:         "UPG_DOWNLOADING",
+				Metadata: &cproto.UpgradeDetailsMetadata{
+					ScheduledAt:     timestamppb.New(now),
+					DownloadPercent: 0.17679,
+				},
+			},
+			expectedOutput: fmt.Sprintf(`── upgrade_details
+   ├─ target_version: 8.12.0
+   ├─ state: UPG_DOWNLOADING
+   └─ metadata
+      ├─ scheduled_at: %s
+      └─ download_percent: 17.68%%`, now.Format(time.RFC3339)),
+		}}
+
+	for name, test := range cases {
+		t.Run(name, func(t *testing.T) {
+			l := list.NewWriter()
+			l.SetStyle(list.StyleConnectedLight)
+
+			listUpgradeDetails(l, test.upgradeDetails)
+			actualOutput := l.Render()
+			require.Equal(t, test.expectedOutput, actualOutput)
+		})
+	}
+}

pkg/control/v1/proto/control_v1.pb.go

@@ -111,12 +111,13 @@ type AgentStateInfo struct {
 
 // AgentState is the current state of the Elastic Agent.
 type AgentState struct {
-	Info         AgentStateInfo   `json:"info" yaml:"info"`
-	State        State            `json:"state" yaml:"state"`
-	Message      string           `json:"message" yaml:"message"`
-	Components   []ComponentState `json:"components" yaml:"components"`
-	FleetState   State            `yaml:"fleet_state"`
-	FleetMessage string           `yaml:"fleet_message"`
+	Info           AgentStateInfo         `json:"info" yaml:"info"`
+	State          State                  `json:"state" yaml:"state"`
+	Message        string                 `json:"message" yaml:"message"`
+	Components     []ComponentState       `json:"components" yaml:"components"`
+	FleetState     State                  `yaml:"fleet_state"`
+	FleetMessage   string                 `yaml:"fleet_message"`
+	UpgradeDetails *cproto.UpgradeDetails `json:"upgrade_details,omitempty" yaml:"upgrade_details,omitempty"`
 }
 
 // DiagnosticFileResult is a diagnostic file result.
@@ -475,10 +476,11 @@ func toState(res *cproto.StateResponse) (*AgentState, error) {
 			Snapshot:  res.Info.Snapshot,
 			PID:       res.Info.Pid,
 		},
-		State:        res.State,
-		Message:      res.Message,
-		FleetState:   res.FleetState,
-		FleetMessage: res.FleetMessage,
+		State:          res.State,
+		Message:        res.Message,
+		FleetState:     res.FleetState,
+		FleetMessage:   res.FleetMessage,
+		UpgradeDetails: res.UpgradeDetails,
 
 		Components: make([]ComponentState, 0, len(res.Components)),
 	}

pkg/control/v1/proto/control_v1_grpc.pb.go

@@ -362,6 +362,22 @@ func stateToProto(state *coordinator.State, agentInfo *info.AgentInfo) (*cproto.
 			},
 		})
 	}
+
+	var upgradeDetails *cproto.UpgradeDetails
+	if state.UpgradeDetails != nil {
+		upgradeDetails = &cproto.UpgradeDetails{
+			TargetVersion: state.UpgradeDetails.TargetVersion,
+			State:         string(state.UpgradeDetails.State),
+			ActionId:      state.UpgradeDetails.ActionID,
+			Metadata: &cproto.UpgradeDetailsMetadata{
+				ScheduledAt:     timestamppb.New(state.UpgradeDetails.Metadata.ScheduledAt),
+				DownloadPercent: float32(state.UpgradeDetails.Metadata.DownloadPercent),
+				FailedState:     string(state.UpgradeDetails.Metadata.FailedState),
+				ErrorMsg:        state.UpgradeDetails.Metadata.ErrorMsg,
+			},
+		}
+	}
+
 	return &cproto.StateResponse{
 		Info: &cproto.StateAgentInfo{
 			Id:        agentInfo.AgentID(),
@@ -371,10 +387,11 @@ func stateToProto(state *coordinator.State, agentInfo *info.AgentInfo) (*cproto.
 			Snapshot:  release.Snapshot(),
 			Pid:       int32(os.Getpid()),
 		},
-		State:        state.State,
-		Message:      state.Message,
-		FleetState:   state.FleetState,
-		FleetMessage: state.FleetMessage,
-		Components:   components,
+		State:          state.State,
+		Message:        state.Message,
+		FleetState:     state.FleetState,
+		FleetMessage:   state.FleetMessage,
+		Components:     components,
+		UpgradeDetails: upgradeDetails,
 	}, nil
 }

pkg/control/v2/client/client.go

@@ -7,13 +7,16 @@ package server
 import (
 	"testing"
 
+	"google.golang.org/protobuf/types/known/timestamppb"
+
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	"github.com/elastic/elastic-agent-client/v7/pkg/client"
 	"github.com/elastic/elastic-agent-libs/logp"
 	"github.com/elastic/elastic-agent/internal/pkg/agent/application/coordinator"
 	"github.com/elastic/elastic-agent/internal/pkg/agent/application/info"
+	"github.com/elastic/elastic-agent/internal/pkg/agent/application/upgrade/details"
 	"github.com/elastic/elastic-agent/pkg/component"
 	"github.com/elastic/elastic-agent/pkg/component/runtime"
 	"github.com/elastic/elastic-agent/pkg/control/v2/cproto"
@@ -22,11 +25,12 @@ import (
 func TestStateMapping(t *testing.T) {
 
 	testcases := []struct {
-		name         string
-		agentState   cproto.State
-		agentMessage string
-		fleetState   cproto.State
-		fleetMessage string
+		name           string
+		agentState     cproto.State
+		agentMessage   string
+		fleetState     cproto.State
+		fleetMessage   string
+		upgradeDetails *details.Details
 	}{
 		{
 			name:         "waiting first checkin response",
@@ -49,6 +53,21 @@ func TestStateMapping(t *testing.T) {
 			fleetState:   cproto.State_FAILED,
 			fleetMessage: "<error value coming from fleet gateway>",
 		},
+		{
+			name:         "with upgrade details",
+			agentState:   cproto.State_UPGRADING,
+			agentMessage: "Upgrading to version 8.13.0",
+			fleetState:   cproto.State_STOPPED,
+			fleetMessage: "Not enrolled into Fleet",
+			upgradeDetails: &details.Details{
+				TargetVersion: "8.13.0",
+				State:         details.StateDownloading,
+				ActionID:      "",
+				Metadata: details.Metadata{
+					DownloadPercent: 1.7,
+				},
+			},
+		},
 	}
 
 	for _, tc := range testcases {
@@ -101,6 +120,15 @@ func TestStateMapping(t *testing.T) {
 				},
 			}
 
+			if tc.upgradeDetails != nil {
+				inputState.UpgradeDetails = &details.Details{
+					TargetVersion: tc.upgradeDetails.TargetVersion,
+					State:         tc.upgradeDetails.State,
+					ActionID:      tc.upgradeDetails.ActionID,
+					Metadata:      tc.upgradeDetails.Metadata,
+				}
+			}
+
 			agentInfo := new(info.AgentInfo)
 
 			stateResponse, err := stateToProto(inputState, agentInfo)
@@ -134,7 +162,18 @@ func TestStateMapping(t *testing.T) {
 				assert.Equal(t, expectedCompState, stateResponse.Components[0])
 			}
 
+			if tc.upgradeDetails != nil {
+				expectedMetadata := &cproto.UpgradeDetailsMetadata{
+					ScheduledAt:     timestamppb.New(tc.upgradeDetails.Metadata.ScheduledAt),
+					DownloadPercent: float32(tc.upgradeDetails.Metadata.DownloadPercent),
+					FailedState:     string(tc.upgradeDetails.Metadata.FailedState),
+					ErrorMsg:        tc.upgradeDetails.Metadata.ErrorMsg,
+				}
+				assert.Equal(t, string(tc.upgradeDetails.State), stateResponse.UpgradeDetails.State)
+				assert.Equal(t, tc.upgradeDetails.TargetVersion, stateResponse.UpgradeDetails.TargetVersion)
+				assert.Equal(t, tc.upgradeDetails.ActionID, stateResponse.UpgradeDetails.ActionId)
+				assert.Equal(t, expectedMetadata, stateResponse.UpgradeDetails.Metadata)
+			}
 		})
 	}
-
 }

pkg/control/v2/cproto/control_v2.pb.go

@@ -2,7 +2,10 @@ sonar.projectKey=elastic_elastic-agent_AYluowg0xMq8P7b4moiZ
 sonar.host.url=https://sonar.elastic.dev
 
 sonar.sources=.
-sonar.exclusions=**/*_test.go, .git/**, dev-tools/**, /magefile.go, changelog/**, _meta/**, deploy/**, docs/**, img/**, specs/**, pkg/testing/**, pkg/component/fake/**, testing/**, **/mocks/*.go
+sonar.exclusions=.git/**, dev-tools/**, /magefile.go, changelog/**, \
+  _meta/**, deploy/**, docs/**, img/**, specs/**, \
+  */*_test.go, pkg/testing/**, pkg/component/fake/**, testing/**, **/mocks/*.go, \
+  pkg/control/v1/proto/*.pb.go, pkg/control/v2/cproto/*.pb.go
 sonar.tests=.
 sonar.test.inclusions=**/*_test.go