Stack management #4712

rashedkvm · 2025-12-18T01:03:54Z

A short explanation of the proposed change:

Implement stack lifecycle management with ACTIVE, DEPRECATED, RESTRICTED, and DISABLED states to enable gradual stack deprecation without causing application downtime.

An explanation of the use cases your change solves

Implement the Stack Management RFC by adding a state field to stacks with four lifecycle states: ACTIVE, DEPRECATED, RESTRICTED, and DISABLED. This enables operators to gracefully phase out stacks through lifecycle restrictions rather than causing immediate app downtime

Links to any other associated PRs

This PR implements RFC #0045.

While the RESTRICTED state is not explicitly defined in the RFC, it is functionally identical to LOCKED. We chose the term RESTRICTED to prevent any confusion with the existing 'Locked' state used in Buildpacks.

I have reviewed the contributing guide
I have viewed, signed, and submitted the Contributor License Agreement
I have made this pull request to the main branch
I have run all the unit tests using bundle exec rake
I have run CF Acceptance Tests

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

**V2 API endpoints must not expose or accept state parameter.** Signed-off-by: Rashed Kamal <rashed.kamal@broadcom.com>

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

and integration into app creation and build workflows. Signed-off-by: Rashed Kamal <rashed.kamal@broadcom.com>

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

…APIs Sets warnings in the response hash when there are warnings Signed-off-by: Rashed Kamal <rashed.kamal@broadcom.com>

FloThinksPi · 2026-01-15T10:08:18Z

Thanks for the PR - i adapted the RFC i also think the new state naming fits better 👍🏼 cloudfoundry/community#1405

Samze · 2026-01-20T22:28:41Z

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

   "updated_at": "2018-11-09T22:43:28Z",
   "name": "my-stack",
   "description": "Here is my stack!",
+   "state": "ACTIVE",


suggestion It would be good to have a definition of each state and what it means for the user. Perhaps in https://v3-apidocs.cloudfoundry.org/version/3.209.0/index.html#stacks description?

Samze · 2026-01-20T22:31:22Z

app/messages/stack_update_message.rb

 module VCAP::CloudController
  class StackUpdateMessage < MetadataBaseMessage
-    register_allowed_keys []
+    register_allowed_keys [:state]


question In the RFC it says

To improve communication with developers, the existing description field of a stack will be leveraged. The content of the description field should be included in any warning or error message related to the stack's state. This allows operators to provide context, migration guides, or links to further documentation.

https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0045-enhance-stack-handling.md#improve-logical-stack-management-in-cf-api-cloud_controller_ng

Should we allow operators to update the description to set a user friendly message?

Samze · 2026-01-20T22:33:43Z

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


 ```shell
 curl "https://api.example.org/v3/stacks/[guid]" \
  -X PATCH \


issue Are you missing docs for create stack?

Samze · 2026-01-20T22:34:04Z

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

 Name | Type | Description
 ---- | ---- | -----------
 **metadata.labels** | [_label object_](#labels) | Labels applied to the stack
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the stack


issue Are you missing docs for state here?

Samze · 2026-01-20T22:39:18Z

lib/cloud_controller/stack_state_validator.rb

@@ -0,0 +1,32 @@
+module VCAP::CloudController
+  class StackStateValidator


question Similar to above, as per

To improve communication with developers, the existing description field of a stack will be leveraged. The content of the description field should be included in any warning or error message related to the stack's state. This allows operators to provide context, migration guides, or links to further documentation.

https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0045-enhance-stack-handling.md#improve-logical-stack-management-in-cf-api-cloud_controller_ng

Do we also want to include the stack description in the warning?

Samze · 2026-01-20T22:43:39Z

app/models/helpers/stack_states.rb

@@ -0,0 +1,17 @@
+module VCAP::CloudController
+  class StackStates


question Any reason for this to be a separate class? It seems to me to make sense to be in the main model file. See BuildModel and DeploymentModel as examples.

Samze · 2026-01-20T23:18:59Z

app/models/runtime/app_model.rb

    DEFAULT_CONTAINER_USER = 'vcap'.freeze
    DEFAULT_DOCKER_CONTAINER_USER = 'root'.freeze

+    attr_reader :stack_warnings


thought Not sure how I feel about storing the warnings on all the models here. It feels like its leaking an abstraction, especially since the warning generation is not actually happening in the model itself but as part of the action.

Perhaps this should be on the actions themselves? So the warnings are kept purely between the controller/action? Will think about it and see if theres any existing patterns for this.

rashedkvm force-pushed the stack-management branch 4 times, most recently from 46b309e to 1a3a7c6 Compare December 19, 2025 14:11

rashedkvm force-pushed the stack-management branch 4 times, most recently from 5fcdfda to e2fc6df Compare January 7, 2026 21:42

rashedkvm force-pushed the stack-management branch 4 times, most recently from 6d8a01d to f32f4bc Compare January 9, 2026 13:40

rashedkvm added 10 commits January 12, 2026 12:59

Stack Management - DB Migration

bcad068

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

Stack Management - Model update and Unit Test

c22ecae

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

Expose stack state through V3 API endpoints only

872c365

**V2 API endpoints must not expose or accept state parameter.** Signed-off-by: Rashed Kamal <rashed.kamal@broadcom.com>

Add Stack States in API documentation

5985e01

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

Additional validation and tests for v3/stacks API

6b570cf

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

Standalone Stack State Validator - State Logic class

335f60f

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

Stack state validation

a212b8d

and integration into app creation and build workflows. Signed-off-by: Rashed Kamal <rashed.kamal@broadcom.com>

V2 API stack validation and tests

83da09e

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

Add deprecation warning in build create

fb60709

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

Update stck state validation error and warning messages

22da753

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

rashedkvm force-pushed the stack-management branch 3 times, most recently from aa5f9b9 to a1eab88 Compare January 12, 2026 20:10

rashedkvm marked this pull request as ready for review January 12, 2026 20:42

Stack state validation when creating and updating apps via V2 and V3 …

3b29b53

…APIs Sets warnings in the response hash when there are warnings Signed-off-by: Rashed Kamal <rashed.kamal@broadcom.com>

rashedkvm force-pushed the stack-management branch from a1eab88 to 3b29b53 Compare January 12, 2026 21:17

sethboyles added needs_review review-requested labels Jan 12, 2026

philippthun requested a review from FloThinksPi January 13, 2026 09:24

stephanme mentioned this pull request Jan 14, 2026

[RFC0045] Enhance Stack Handling in Cloud Foundry cloudfoundry/community#1331

Open

3 tasks

This was referenced Jan 20, 2026

V8 stack management cloudfoundry/cli#3687

Open

Stack management cloudfoundry/cli#3688

Open

Samze reviewed Jan 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Stack management #4712

Stack management #4712

Uh oh!

rashedkvm commented Dec 18, 2025 •

edited

Loading

Uh oh!

FloThinksPi commented Jan 15, 2026

Uh oh!

Samze Jan 20, 2026

Uh oh!

Samze Jan 20, 2026

Uh oh!

Samze Jan 20, 2026

Uh oh!

Samze Jan 20, 2026

Uh oh!

Samze Jan 20, 2026

Uh oh!

Samze Jan 20, 2026

Uh oh!

Samze Jan 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		@@ -0,0 +1,32 @@
		module VCAP::CloudController
		class StackStateValidator

		@@ -0,0 +1,17 @@
		module VCAP::CloudController
		class StackStates

Stack management #4712

Are you sure you want to change the base?

Stack management #4712

Uh oh!

Conversation

rashedkvm commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

FloThinksPi commented Jan 15, 2026

Uh oh!

Samze Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Samze Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Samze Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Samze Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Samze Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Samze Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Samze Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rashedkvm commented Dec 18, 2025 •

edited

Loading