Add state_reason in Stack object (#4823)

* Add state_reason in Stack object
See RFC#0045 (Stack Management)
Includes state_reason in Stack Validation Error and Warning

---------

Signed-off-by: Rashed Kamal <rashed.kamal@broadcom.com>

Author: rashedkvm

app/actions/stack_create.rb

@@ -13,7 +13,8 @@ def create(message)
       stack = VCAP::CloudController::Stack.create(
         name: message.name,
         description: message.description,
-        state: message.state
+        state: message.state,
+        state_reason: message.state_reason
       )
 
       MetadataUpdate.update(stack, message)

app/actions/stack_update.rb

@@ -12,7 +12,11 @@ def initialize(user_audit_info)
 
     def update(stack, message)
       stack.db.transaction do
-        stack.update(state: message.state) if message.requested?(:state)
+        stack_updates = {}
+        stack_updates[:state] = message.state if message.requested?(:state)
+        stack_updates[:state_reason] = message.state_reason if message.state_reason_requested?
+        stack.update(stack_updates) if stack_updates.any?
+
         MetadataUpdate.update(stack, message)
         Repositories::StackEventRepository.new.record_stack_update(stack, @user_audit_info, message.audit_hash)
       end

app/messages/stack_create_message.rb

@@ -3,11 +3,12 @@
 
 module VCAP::CloudController
   class StackCreateMessage < MetadataBaseMessage
-    register_allowed_keys %i[name description state]
+    register_allowed_keys %i[name description state state_reason]
 
     validates :name, presence: true, length: { maximum: 250 }
     validates :description, length: { maximum: 250 }
     validates :state, inclusion: { in: StackStates::VALID_STATES, message: "must be one of #{StackStates::VALID_STATES.join(', ')}" }, allow_nil: false, if: :state_requested?
+    validates :state_reason, length: { maximum: 5000 }, allow_nil: true
 
     def state_requested?
       requested?(:state)

app/messages/stack_update_message.rb

@@ -3,13 +3,18 @@
 
 module VCAP::CloudController
   class StackUpdateMessage < MetadataBaseMessage
-    register_allowed_keys [:state]
+    register_allowed_keys %i[state state_reason]
 
     validates_with NoAdditionalKeysValidator
     validates :state, inclusion: { in: StackStates::VALID_STATES, message: "must be one of #{StackStates::VALID_STATES.join(', ')}" }, allow_nil: false, if: :state_requested?
+    validates :state_reason, length: { maximum: 5000 }, allow_nil: true
 
     def state_requested?
       requested?(:state)
     end
+
+    def state_reason_requested?
+      requested?(:state_reason)
+    end
   end
 end

app/presenters/v3/stack_presenter.rb

@@ -13,6 +13,7 @@ def to_hash
         name: stack.name,
         description: stack.description,
         state: stack.state,
+        state_reason: stack.state_reason,
         run_rootfs_image: stack.run_rootfs_image,
         build_rootfs_image: stack.build_rootfs_image,
         default: stack.default?,

db/migrations/20260202105042_add_state_reason_to_stacks.rb

@@ -0,0 +1,13 @@
+Sequel.migration do
+  up do
+    alter_table :stacks do
+      add_column :state_reason, String, null: true, size: 5000 unless @db.schema(:stacks).map(&:first).include?(:state_reason)
+    end
+  end
+
+  down do
+    alter_table :stacks do
+      drop_column :state_reason if @db.schema(:stacks).map(&:first).include?(:state_reason)
+    end
+  end
+end

docs/v3/source/includes/api_resources/_stacks.erb

@@ -6,6 +6,7 @@
    "name": "my-stack",
    "description": "Here is my stack!",
    "state": "ACTIVE",
+   "state_reason": null,
    "build_rootfs_image": "my-stack",
    "run_rootfs_image": "my-stack",
    "default": true,
@@ -47,6 +48,7 @@
       "run_rootfs_image": "my-stack-1-run",
       "description": "This is my first stack!",
       "state": "ACTIVE",
+      "state_reason": null,
       "default": true,
       "metadata": {
         "labels": {},
@@ -67,6 +69,7 @@
       "build_rootfs_image": "my-stack-2-build",
       "run_rootfs_image": "my-stack-2-run",
       "state": "DEPRECATED",
+      "state_reason": "Stack deprecated and will be removed in future release",
       "default": false,
       "metadata": {
         "labels": {},
@@ -91,6 +94,7 @@
    "name": "my-stack",
    "description": "Here is my stack!",
    "state": "DISABLED",
+   "state_reason": "Stack disabled and cannot be used for staging new application",
    "build_rootfs_image": "my-stack",
    "run_rootfs_image": "my-stack",
    "default": true,

docs/v3/source/includes/resources/stacks/_create.md.erb

@@ -13,6 +13,7 @@ curl "https://api.example.org/v3/stacks" \
     "name": "my-stack",
     "description": "Here is my stack!",
     "state": "ACTIVE",
+    "state_reason": "",
   }'
 ```
 
@@ -44,6 +45,7 @@ Name | Type | Description | Default
 **metadata.labels** | [_label object_](#labels) | Labels applied to the stack
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the stack
 **state** | string | The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`
+**state_reason** | string | Optional plain text describing the stack state change
 
 #### Permitted roles
  |

docs/v3/source/includes/resources/stacks/_object.md.erb

@@ -15,6 +15,7 @@ Name | Type | Description
 **name** | _string_ | The name of the stack
 **description** | _string_ | The description of the stack
 **state** | string | The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`
+**state_reason** | string | Optional plain text describing the stack state change
 **build_rootfs_image** | _string | The name of the stack image associated with staging/building Apps. If a stack does not have unique images, this will be the same as the stack name.
 **run_rootfs_image** | _string | The name of the stack image associated with running Apps + Tasks. If a stack does not have unique images, this will be the same as the stack name.
 **default** | _boolean_ | Whether the stack is configured to be the default stack for new applications.

docs/v3/source/includes/resources/stacks/_update.md.erb

@@ -9,7 +9,7 @@ curl "https://api.example.org/v3/stacks/[guid]" \
   -X PATCH \
   -H "Authorization: bearer [token]" \
   -H "Content-Type: application/json" \
-  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}},"state":"ACTIVE"}'
+  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}},"state":"ACTIVE", "state_reason": "Optional plain text describing the stack state change" }'
 
 ```
 
@@ -34,6 +34,7 @@ Name | Type | Description
 **metadata.labels** | [_label object_](#labels) | Labels applied to the stack
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the stack
 **state** | string | The state of the stack; valid states are: `ACTIVE`, `RESTRICTED`, `DEPRECATED`, `DISABLED`
+**state_reason** | string | Optional plain text describing the stack state change
 
 #### Permitted roles
  |