[main] RFC-0045: Stack management reason

actor/v7action/cloud_controller_client.go

@@ -138,7 +138,7 @@ type CloudControllerClient interface {
 	GetAppFeature(appGUID string, featureName string) (resources.ApplicationFeature, ccv3.Warnings, error)
 	GetStacks(query ...ccv3.Query) ([]resources.Stack, ccv3.Warnings, error)
 	GetStagingSecurityGroups(spaceGUID string, queries ...ccv3.Query) ([]resources.SecurityGroup, ccv3.Warnings, error)
-	UpdateStack(stackGUID string, state string) (resources.Stack, ccv3.Warnings, error)
+	UpdateStack(stackGUID string, state string, reason string) (resources.Stack, ccv3.Warnings, error)
 	GetTask(guid string) (resources.Task, ccv3.Warnings, error)
 	GetUser(userGUID string) (resources.User, ccv3.Warnings, error)
 	GetUsers(query ...ccv3.Query) ([]resources.User, ccv3.Warnings, error)

actor/v7action/stack.go

@@ -47,8 +47,8 @@ func (actor Actor) GetStacks(labelSelector string) ([]resources.Stack, Warnings,
 	return stacks, Warnings(warnings), nil
 }
 
-func (actor Actor) UpdateStack(stackGUID string, state string) (resources.Stack, Warnings, error) {
-	stack, warnings, err := actor.CloudControllerClient.UpdateStack(stackGUID, state)
+func (actor Actor) UpdateStack(stackGUID string, state string, reason string) (resources.Stack, Warnings, error) {
+	stack, warnings, err := actor.CloudControllerClient.UpdateStack(stackGUID, state, reason)
 	if err != nil {
 		return resources.Stack{}, Warnings(warnings), err
 	}

actor/v7action/stack_test.go

@@ -238,6 +238,7 @@ var _ = Describe("Stack", func() {
 		var (
 			stackGUID  string
 			state      string
+			reason     string
 			stack      resources.Stack
 			warnings   Warnings
 			executeErr error
@@ -246,10 +247,11 @@ var _ = Describe("Stack", func() {
 		BeforeEach(func() {
 			stackGUID = "some-stack-guid"
 			state = "DEPRECATED"
+			reason = ""
 		})
 
 		JustBeforeEach(func() {
-			stack, warnings, executeErr = actor.UpdateStack(stackGUID, state)
+			stack, warnings, executeErr = actor.UpdateStack(stackGUID, state, reason)
 		})
 
 		When("the cloud controller request is successful", func() {
@@ -277,9 +279,10 @@ var _ = Describe("Stack", func() {
 				}))
 
 				Expect(fakeCloudControllerClient.UpdateStackCallCount()).To(Equal(1))
-				actualGUID, actualState := fakeCloudControllerClient.UpdateStackArgsForCall(0)
+				actualGUID, actualState, actualReason := fakeCloudControllerClient.UpdateStackArgsForCall(0)
 				Expect(actualGUID).To(Equal(stackGUID))
 				Expect(actualState).To(Equal(state))
+				Expect(actualReason).To(Equal(reason))
 			})
 		})
 

api/cloudcontroller/ccv3/stack.go

@@ -22,18 +22,19 @@ func (client *Client) GetStacks(query ...Query) ([]resources.Stack, Warnings, er
 	return stacks, warnings, err
 }
 
-// UpdateStack updates a stack's state.
-func (client *Client) UpdateStack(stackGUID string, state string) (resources.Stack, Warnings, error) {
+// UpdateStack updates a stack's state and optionally its state reason.
+func (client *Client) UpdateStack(stackGUID string, state string, reason string) (resources.Stack, Warnings, error) {
 	var responseStack resources.Stack
 
 	type StackUpdate struct {
-		State string `json:"state"`
+		State       string `json:"state"`
+		StateReason string `json:"state_reason,omitempty"`
 	}
 
 	_, warnings, err := client.MakeRequest(RequestParams{
 		RequestName:  internal.PatchStackRequest,
 		URIParams:    internal.Params{"stack_guid": stackGUID},
-		RequestBody:  StackUpdate{State: state},
+		RequestBody:  StackUpdate{State: state, StateReason: reason},
 		ResponseBody: &responseStack,
 	})
 

api/cloudcontroller/ccv3/stack_test.go

@@ -148,6 +148,7 @@ var _ = Describe("Stacks", func() {
 		var (
 			stackGUID string
 			state     string
+			reason    string
 			stack     resources.Stack
 			warnings  Warnings
 			err       error
@@ -156,10 +157,11 @@ var _ = Describe("Stacks", func() {
 		BeforeEach(func() {
 			stackGUID = "some-stack-guid"
 			state = "DEPRECATED"
+			reason = ""
 		})
 
 		JustBeforeEach(func() {
-			stack, warnings, err = client.UpdateStack(stackGUID, state)
+			stack, warnings, err = client.UpdateStack(stackGUID, state, reason)
 		})
 
 		When("the request succeeds", func() {
@@ -192,6 +194,40 @@ var _ = Describe("Stacks", func() {
 			})
 		})
 
+		When("a reason is provided", func() {
+			BeforeEach(func() {
+				reason = "Use cflinuxfs4 instead"
+				server.AppendHandlers(
+					CombineHandlers(
+						VerifyRequest(http.MethodPatch, "/v3/stacks/some-stack-guid"),
+						VerifyJSONRepresenting(map[string]string{
+							"state":        "DEPRECATED",
+							"state_reason": "Use cflinuxfs4 instead",
+						}),
+						RespondWith(http.StatusOK, `{
+						"guid": "some-stack-guid",
+						"name": "some-stack",
+						"description": "some description",
+						"state": "DEPRECATED",
+						"state_reason": "Use cflinuxfs4 instead"
+					}`, http.Header{"X-Cf-Warnings": {"this is a warning"}}),
+					),
+				)
+			})
+
+			It("returns the updated stack with reason and warnings", func() {
+				Expect(err).ToNot(HaveOccurred())
+				Expect(warnings).To(ConsistOf("this is a warning"))
+				Expect(stack).To(Equal(resources.Stack{
+					GUID:        "some-stack-guid",
+					Name:        "some-stack",
+					Description: "some description",
+					State:       "DEPRECATED",
+					StateReason: "Use cflinuxfs4 instead",
+				}))
+			})
+		})
+
 		When("the cloud controller returns an error", func() {
 			BeforeEach(func() {
 				server.AppendHandlers(

api/cloudcontroller/ccversion/minimum_version.go

@@ -19,5 +19,5 @@ const (
 
 	MinVersionServiceBindingStrategy = "3.205.0"
 
-	MinVersionUpdateStack = "3.210.0"
+	MinVersionUpdateStack = "3.211.0"
 )

command/v7/actor.go

@@ -179,7 +179,7 @@ type Actor interface {
 	GetStackByName(stackName string) (resources.Stack, v7action.Warnings, error)
 	GetStackLabels(stackName string) (map[string]types.NullString, v7action.Warnings, error)
 	GetStacks(string) ([]resources.Stack, v7action.Warnings, error)
-	UpdateStack(stackGUID string, state string) (resources.Stack, v7action.Warnings, error)
+	UpdateStack(stackGUID string, state string, reason string) (resources.Stack, v7action.Warnings, error)
 	GetStreamingLogsForApplicationByNameAndSpace(appName string, spaceGUID string, client sharedaction.LogCacheClient) (<-chan sharedaction.LogMessage, <-chan error, context.CancelFunc, v7action.Warnings, error)
 	GetTaskBySequenceIDAndApplication(sequenceID int, appGUID string) (resources.Task, v7action.Warnings, error)
 	GetUAAAPIVersion() (string, error)

command/v7/stack_command.go

@@ -69,6 +69,11 @@ func (cmd *StackCommand) displayStackInfo() error {
 	// Add state only if it's present
 	if stack.State != "" {
 		displayTable = append(displayTable, []string{cmd.UI.TranslateText("state:"), stack.State})
+
+		// Add reason whenever state is not ACTIVE
+		if stack.State != resources.StackStateActive {
+			displayTable = append(displayTable, []string{cmd.UI.TranslateText("reason:"), stack.StateReason})
+		}
 	}
 
 	cmd.UI.DisplayKeyValueTable("", displayTable, 3)

command/v7/stack_command_test.go

@@ -149,26 +149,76 @@ var _ = Describe("Stack Command", func() {
 		})
 
 		Context("When the stack has a state", func() {
+			Context("When the state is ACTIVE", func() {
+				BeforeEach(func() {
+					stack := resources.Stack{
+						Name:        "some-stack-name",
+						GUID:        "some-stack-guid",
+						Description: "some-stack-desc",
+						State:       "ACTIVE",
+					}
+					fakeActor.GetStackByNameReturns(stack, v7action.Warnings{}, nil)
+				})
+
+				It("Displays the stack information with state but no reason", func() {
+					Expect(executeErr).ToNot(HaveOccurred())
+					Expect(fakeActor.GetStackByNameArgsForCall(0)).To(Equal("some-stack-name"))
+					Expect(fakeActor.GetStackByNameCallCount()).To(Equal(1))
+
+					Expect(testUI.Out).To(Say("name:\\s+some-stack-name"))
+					Expect(testUI.Out).To(Say("description:\\s+some-stack-desc"))
+					Expect(testUI.Out).To(Say("state:\\s+ACTIVE"))
+					Expect(testUI.Out).NotTo(Say("reason:"))
+				})
+			})
+
+			Context("When the state is not ACTIVE and has a reason", func() {
+				BeforeEach(func() {
+					stack := resources.Stack{
+						Name:        "some-stack-name",
+						GUID:        "some-stack-guid",
+						Description: "some-stack-desc",
+						State:       "DEPRECATED",
+						StateReason: "This stack is being phased out",
+					}
+					fakeActor.GetStackByNameReturns(stack, v7action.Warnings{}, nil)
+				})
+
+				It("Displays the stack information with state and reason", func() {
+					Expect(executeErr).ToNot(HaveOccurred())
+					Expect(fakeActor.GetStackByNameArgsForCall(0)).To(Equal("some-stack-name"))
+					Expect(fakeActor.GetStackByNameCallCount()).To(Equal(1))
+
+					Expect(testUI.Out).To(Say("name:\\s+some-stack-name"))
+					Expect(testUI.Out).To(Say("description:\\s+some-stack-desc"))
+					Expect(testUI.Out).To(Say("state:\\s+DEPRECATED"))
+					Expect(testUI.Out).To(Say("reason:\\s+This stack is being phased out"))
+				})
+			})
+
+		Context("When the state is not ACTIVE but has no reason", func() {
 			BeforeEach(func() {
 				stack := resources.Stack{
 					Name:        "some-stack-name",
 					GUID:        "some-stack-guid",
 					Description: "some-stack-desc",
-					State:       "ACTIVE",
+					State:       "RESTRICTED",
 				}
 				fakeActor.GetStackByNameReturns(stack, v7action.Warnings{}, nil)
 			})
 
-			It("Displays the stack information with state", func() {
+			It("Displays the stack information with state and empty reason", func() {
 				Expect(executeErr).ToNot(HaveOccurred())
 				Expect(fakeActor.GetStackByNameArgsForCall(0)).To(Equal("some-stack-name"))
 				Expect(fakeActor.GetStackByNameCallCount()).To(Equal(1))
 
 				Expect(testUI.Out).To(Say("name:\\s+some-stack-name"))
 				Expect(testUI.Out).To(Say("description:\\s+some-stack-desc"))
-				Expect(testUI.Out).To(Say("state:\\s+ACTIVE"))
+				Expect(testUI.Out).To(Say("state:\\s+RESTRICTED"))
+				Expect(testUI.Out).To(Say("reason:"))
 			})
 		})
+		})
 
 		When("The Stack does not Exist", func() {
 			expectedError := actionerror.StackNotFoundError{Name: "some-stack-name"}

command/v7/update_stack_command.go

@@ -15,7 +15,8 @@ type UpdateStackCommand struct {
 
 	RequiredArgs    flag.StackName `positional-args:"yes"`
 	State           string         `long:"state" description:"State to transition the stack to (active, restricted, deprecated, disabled)" required:"true"`
-	usage           interface{}    `usage:"CF_NAME update-stack STACK_NAME [--state (active | restricted | deprecated | disabled)]\n\nEXAMPLES:\n   CF_NAME update-stack cflinuxfs3 --state disabled"`
+	Reason          string         `long:"reason" description:"Optional plain text describing the stack state change"`
+	usage           interface{}    `usage:"CF_NAME update-stack STACK_NAME [--state (active | restricted | deprecated | disabled)] [--reason text]\n\nEXAMPLES:\n   CF_NAME update-stack cflinuxfs3 --state disabled\n   CF_NAME update-stack cflinuxfs3 --state deprecated --reason \"This stack is based on Ubuntu 18.04, which is no longer supported. Please migrate your applications to 'cflinuxfs4'. For more information, see: <link-to-docs>.\""`
 	relatedCommands interface{}    `related_commands:"stack, stacks"`
 }
 
@@ -56,7 +57,7 @@ func (cmd UpdateStackCommand) Execute(args []string) error {
 	}
 
 	// Update the stack
-	updatedStack, warnings, err := cmd.Actor.UpdateStack(stack.GUID, stateValue)
+	updatedStack, warnings, err := cmd.Actor.UpdateStack(stack.GUID, stateValue, cmd.Reason)
 	cmd.UI.DisplayWarnings(warnings)
 	if err != nil {
 		return err
@@ -66,11 +67,18 @@ func (cmd UpdateStackCommand) Execute(args []string) error {
 	cmd.UI.DisplayNewline()
 
 	// Display the updated stack info
-	cmd.UI.DisplayKeyValueTable("", [][]string{
+	displayTable := [][]string{
 		{cmd.UI.TranslateText("name:"), updatedStack.Name},
 		{cmd.UI.TranslateText("description:"), updatedStack.Description},
 		{cmd.UI.TranslateText("state:"), updatedStack.State},
-	}, 3)
+	}
+
+	// Add reason whenever state is not ACTIVE
+	if updatedStack.State != resources.StackStateActive {
+		displayTable = append(displayTable, []string{cmd.UI.TranslateText("reason:"), updatedStack.StateReason})
+	}
+
+	cmd.UI.DisplayKeyValueTable("", displayTable, 3)
 
 	return nil
 }