Stack management

app/actions/build_create.rb

@@ -41,6 +41,7 @@ def initialize(user_audit_info: UserAuditInfo.from_context(SecurityContext),
 
     def create_and_stage(package:, lifecycle:, metadata: nil, start_after_staging: false)
       logger.info("creating build for package #{package.guid}")
+      warnings = validate_stack_state!(lifecycle, package.app)
       staging_in_progress! if package.app.staging_in_progress?
       raise InvalidPackage.new('Cannot stage package whose state is not ready.') if package.state != PackageModel::READY_STATE
 
@@ -60,6 +61,7 @@ def create_and_stage(package:, lifecycle:, metadata: nil, start_after_staging: f
         created_by_user_name: @user_audit_info.user_name,
         created_by_user_email: @user_audit_info.user_email
       )
+      build.instance_variable_set(:@stack_warnings, warnings)
 
       BuildModel.db.transaction do
         build.save
@@ -179,5 +181,29 @@ def stagers
     def staging_in_progress!
       raise StagingInProgress
     end
+
+    def validate_stack_state!(lifecycle, app)
+      return [] if lifecycle.type == Lifecycles::DOCKER
+
+      stack = Stack.find(name: lifecycle.staging_stack)
+      return [] unless stack
+
+      warnings = if first_build_for_app?(app)
+                   StackStateValidator.validate_for_new_app!(stack)
+                 else
+                   StackStateValidator.validate_for_restaging!(stack)
+                 end
+      warnings.each { |warning| logger.warn(warning) }
+      warnings
+    rescue StackStateValidator::DisabledStackError, StackStateValidator::RestrictedStackError => e
+      raise CloudController::Errors::ApiError.new_from_details(
+        'StackValidationFailed',
+        e.message
+      )
+    end
+
+    def first_build_for_app?(app)
+      app.builds_dataset.count.zero?
+    end
   end
 end

app/actions/stack_create.rb

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

app/actions/stack_update.rb

@@ -12,6 +12,7 @@ def initialize(user_audit_info)
 
     def update(stack, message)
       stack.db.transaction do
+        stack.update(state: message.state) if message.requested?(:state)
         MetadataUpdate.update(stack, message)
         Repositories::StackEventRepository.new.record_stack_update(stack, @user_audit_info, message.audit_hash)
       end

app/actions/v2/app_stage.rb

@@ -1,8 +1,11 @@
 module VCAP::CloudController
   module V2
     class AppStage
+      attr_reader :warnings
+
       def initialize(stagers:)
         @stagers = stagers
+        @warnings = []
       end
 
       def stage(process)
@@ -25,6 +28,9 @@ def stage(process)
           lifecycle: lifecycle,
           start_after_staging: true
         )
+
+        @warnings = build.instance_variable_get(:@stack_warnings) || []
+
         TelemetryLogger.v2_emit(
           'create-build',
           {

app/actions/v2/app_update.rb

@@ -4,9 +4,12 @@
 module VCAP::CloudController
   module V2
     class AppUpdate
+      attr_reader :warnings
+
       def initialize(access_validator:, stagers:)
         @access_validator = access_validator
         @stagers          = stagers
+        @warnings         = []
       end
 
       def update(app, process, request_attrs)
@@ -116,7 +119,9 @@ def prepare_to_stage(app)
       end
 
       def stage(process)
-        V2::AppStage.new(stagers: @stagers).stage(process)
+        app_stage = V2::AppStage.new(stagers: @stagers)
+        app_stage.stage(process)
+        @warnings = app_stage.warnings
       end
 
       def start_or_stop(app, request_attrs)

app/controllers/runtime/apps_controller.rb

@@ -294,6 +294,7 @@ def update(guid)
 
       updater = V2::AppUpdate.new(access_validator: self, stagers: @stagers)
       updater.update(app, process, request_attrs)
+      updater.warnings.each { |warning| add_warning(warning) }
 
       after_update(process)
 

app/controllers/runtime/restages_controller.rb

@@ -35,7 +35,10 @@ def restage(guid)
         process.app.update(droplet_guid: nil)
         AppStart.start_without_event(process.app, create_revision: false)
       end
-      V2::AppStage.new(stagers: @stagers).stage(process)
+      # V2::AppStage.new(stagers: @stagers).stage(process)
+      app_stage = V2::AppStage.new(stagers: @stagers)
+      app_stage.stage(process)
+      app_stage.warnings.each { |warning| add_warning(warning) }
 
       @app_event_repository.record_app_restage(process, UserAuditInfo.from_context(SecurityContext))
 

app/controllers/v3/builds_controller.rb

@@ -65,6 +65,8 @@ def create
       }
     )
 
+    add_warning_headers(build.stack_warnings) if build.stack_warnings&.any?
+
     render status: :created, json: Presenters::V3::BuildPresenter.new(build)
   rescue BuildCreate::InvalidPackage => e
     bad_request!(e.message)

app/messages/stack_create_message.rb

@@ -1,10 +1,22 @@
 require 'messages/metadata_base_message'
+require 'models/helpers/stack_states'
 
 module VCAP::CloudController
   class StackCreateMessage < MetadataBaseMessage
-    register_allowed_keys %i[name description]
+    register_allowed_keys %i[name description state]
 
     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?
+
+    def state_requested?
+      requested?(:state)
+    end
+
+    def state
+      return @state if defined?(@state)
+
+      @state = requested?(:state) ? super : StackStates::DEFAULT_STATE
+    end
   end
 end

app/messages/stack_update_message.rb

@@ -1,9 +1,15 @@
 require 'messages/metadata_base_message'
+require 'models/helpers/stack_states'
 
 module VCAP::CloudController
   class StackUpdateMessage < MetadataBaseMessage
-    register_allowed_keys []
+    register_allowed_keys [:state]
 
     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?
+
+    def state_requested?
+      requested?(:state)
+    end
   end
 end

app/models/helpers/stack_states.rb

@@ -0,0 +1,17 @@
+module VCAP::CloudController
+  class StackStates
+    STACK_ACTIVE = 'ACTIVE'.freeze
+    STACK_RESTRICTED = 'RESTRICTED'.freeze
+    STACK_DEPRECATED = 'DEPRECATED'.freeze
+    STACK_DISABLED = 'DISABLED'.freeze
+
+    DEFAULT_STATE = STACK_ACTIVE
+
+    VALID_STATES = [
+      STACK_ACTIVE,
+      STACK_RESTRICTED,
+      STACK_DEPRECATED,
+      STACK_DISABLED
+    ].freeze
+  end
+end

app/models/runtime/build_model.rb

@@ -17,6 +17,8 @@ class BuildModel < Sequel::Model(:builds)
                                 CNBGenericBuildFailed CNBDownloadBuildpackFailed CNBDetectFailed
                                 CNBBuildFailed CNBExportFailed CNBLaunchFailed CNBRestoreFailed].map(&:freeze).freeze
 
+    attr_reader :stack_warnings
+
     many_to_one :app,
                 class: 'VCAP::CloudController::AppModel',
                 key: :app_guid,

app/models/runtime/stack.rb

@@ -1,5 +1,6 @@
 require 'models/helpers/process_types'
 require 'models/helpers/stack_config_file'
+require 'models/helpers/stack_states'
 
 module VCAP::CloudController
   class Stack < Sequel::Model
@@ -43,6 +44,7 @@ def around_save
     def validate
       validates_presence :name
       validates_unique :name
+      validates_includes StackStates::VALID_STATES, :state, allow_nil: true
     end
 
     def before_destroy
@@ -98,5 +100,29 @@ def self.populate_from_hash(hash)
         create(hash.slice('name', 'description', 'build_rootfs_image', 'run_rootfs_image'))
       end
     end
+
+    def active?
+      state == StackStates::STACK_ACTIVE
+    end
+
+    def deprecated?
+      state == StackStates::STACK_DEPRECATED
+    end
+
+    def restricted?
+      state == StackStates::STACK_RESTRICTED
+    end
+
+    def disabled?
+      state == StackStates::STACK_DISABLED
+    end
+
+    def can_stage_new_app?
+      !restricted? && !disabled?
+    end
+
+    def can_restage_apps?
+      !disabled?
+    end
   end
 end

app/presenters/v3/build_presenter.rb

@@ -30,6 +30,7 @@ def to_hash
             },
             package: { guid: build.package_guid },
             droplet: droplet,
+            warnings: build_warnings,
             created_by: {
               guid: build.created_by_user_guid,
               name: build.created_by_user_name,
@@ -61,6 +62,12 @@ def error
           e.presence
         end
 
+        def build_warnings
+          return nil unless build.stack_warnings&.any?
+
+          build.stack_warnings.map { |warning| { detail: warning } }
+        end
+
         def build_links
           {
             self: { href: url_builder.build_url(path: "/v3/builds/#{build.guid}") },

app/presenters/v3/stack_presenter.rb

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

db/migrations/20251117123719_add_state_to_stacks.rb

@@ -0,0 +1,13 @@
+Sequel.migration do
+  up do
+    alter_table :stacks do
+      add_column :state, String, null: false, default: 'ACTIVE', size: 255 unless @db.schema(:stacks).map(&:first).include?(:state)
+    end
+  end
+
+  down do
+    alter_table :stacks do
+      drop_column :state if @db.schema(:stacks).map(&:first).include?(:state)
+    end
+  end
+end

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

@@ -5,6 +5,7 @@
    "updated_at": "2018-11-09T22:43:28Z",
    "name": "my-stack",
    "description": "Here is my stack!",
+   "state": "ACTIVE",
    "build_rootfs_image": "my-stack",
    "run_rootfs_image": "my-stack",
    "default": true,
@@ -45,6 +46,7 @@
       "build_rootfs_image": "my-stack-1-build",
       "run_rootfs_image": "my-stack-1-run",
       "description": "This is my first stack!",
+      "state": "ACTIVE",
       "default": true,
       "metadata": {
         "labels": {},
@@ -64,6 +66,7 @@
       "description": "This is my second stack!",
       "build_rootfs_image": "my-stack-2-build",
       "run_rootfs_image": "my-stack-2-run",
+      "state": "DEPRECATED",
       "default": false,
       "metadata": {
         "labels": {},
@@ -79,3 +82,26 @@
 }
 
 <% end %>
+
+<% content_for :single_stack_disabled do | metadata={} |  %>
+{
+   "guid": "11c916c9-c2f9-440e-8e73-102e79c4704d",
+   "created_at": "2018-11-09T22:43:28Z",
+   "updated_at": "2018-11-09T22:43:28Z",
+   "name": "my-stack",
+   "description": "Here is my stack!",
+   "state": "ACTIVE",
+   "build_rootfs_image": "my-stack",
+   "run_rootfs_image": "my-stack",
+   "default": true,
+   "metadata": {
+     "labels": <%= metadata.fetch(:labels, {}).to_json(space: ' ', object_nl: ' ')%>,
+     "annotations": <%= metadata.fetch(:annotations, {}).to_json(space: ' ', object_nl: ' ')%>
+   },
+   "links": {
+      "self": {
+         "href": "https://api.example.com/v3/stacks/11c916c9-c2f9-440e-8e73-102e79c4704d"
+      }
+   }
+}
+<% end %>

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

@@ -14,6 +14,7 @@ Name | Type | Description
 **updated_at** | _[timestamp](#timestamps)_ | The time with zone when the object was last updated
 **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`
 **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"}}}'
+  -d '{ "metadata": { "labels": { "key": "value" }, "annotations": {"note": "detailed information"}, "state": "DISABLED" }}'
 
 ```
 
@@ -21,7 +21,7 @@ Example Response
 HTTP/1.1 200 OK
 Content-Type: application/json
 
-<%= yield_content :single_stack, labels: { "key" => "value" }, "annotations": {"note" => "detailed information"} %>
+<%= yield_content :single_stack_disabled, labels: { "key" => "value" }, "annotations": {"note" => "detailed information"} %>
 ```
 
 #### Definition
@@ -33,6 +33,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`
 
 #### Permitted roles
  |

errors/v2.yml

@@ -863,6 +863,11 @@
   http_code: 404
   message: "The stack could not be found: %s"
 
+250004:
+  name: StackValidationFailed
+  http_code: 422
+  message: "%s"
+
 260001:
   name: ServicePlanVisibilityInvalid
   http_code: 400

lib/cloud_controller.rb

@@ -117,3 +117,5 @@ module VCAP::CloudController; end
 require 'cloud_controller/errands/rotate_database_key'
 
 require 'services'
+
+require 'cloud_controller/stack_state_validator'