Managing Stack Lifecycle in Cloud Foundry

Page last updated:

This topic describes how Cloud Foundry operators manage the lifecycle of stacks using stack states and the cf update-stack command.

A stack in Cloud Foundry is a prebuilt root filesystem that apps use when staging. As stacks age or become unsupported, operators need a way to communicate upcoming changes to developers and gradually restrict stack usage before removing a stack entirely.

Cloud Foundry provides a stack state field that controls what operations are permitted on apps using that stack, and an optional state reason field that lets operators communicate a human-readable explanation or migration guide to developers.

Stack States

The following states are available for each stack:

What Each State Allows

The following table summarizes which app lifecycle operations are permitted per state:

State Reason

Each stack can have an optional state_reason field — a free-text message set by the operator. The reason is shown to developers in:

• The output of cf stack STACK_NAME (when state is not ACTIVE)
• Warning or error messages during cf push or cf restage

Use this field to provide migration guidance or links to documentation, for example:

This stack is based on Ubuntu 18.04, which is no longer supported.
Please migrate your applications to 'cflinuxfs4'.
For more information, see: https://docs.example.com/migrate-stacks

Viewing stack states

List All Stacks

To list all stacks and their current states, run:

cf stacks

Here is example output:

Getting stacks as admin...

name        description                                                    state
cflinuxfs4  Cloud Foundry Linux-based filesystem - Ubuntu Jammy 22.04 LTS ACTIVE
windows     Windows Server                                                 RESTRICTED

View a Single Stack

To view details for a specific stack, including its state and reason (if set), run:

cf stack STACK_NAME

Where STACK_NAME is the name of the stack.

Here is example output:

$ cf stack windows
Getting info for stack windows as admin...

name:        windows
description: Windows Server
state:       RESTRICTED
reason:      Windows Server 2019 is no longer supported. Please update your
             application to use windows2022. For more information,
             see https://docs.example.com/migrate-windows-stack

The reason field is only shown when the stack state is not ACTIVE.

Updating a stack state

To transition a stack to a new state or update its reason message, run:

cf update-stack STACK_NAME [--state STATE] [--reason REASON]

Where:

• STACK_NAME is the name of the stack to update.
• --state STATE (Optional) is the target state. Valid values are active, deprecated, restricted, and disabled.
• --reason REASON (Optional) is a plain-text message explaining the state change. Developers see this in warnings and errors.

You must be an administrator to run cf update-stack.

Example: Deprecating a stack

When you deprecate a stack, developers receive a warning during cf push and cf restage but their operations still succeed. This state is appropriate for early notification:

$ cf 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: https://docs.example.com/migrate-stacks."

Developers pushing an app on the deprecated stack see output similar to:

WARNING: The stack 'cflinuxfs3' is DEPRECATED and will be removed in the future:
This stack is based on Ubuntu 18.04, which is no longer supported.
Please migrate your applications to 'cflinuxfs4'.
For more information, see: https://docs.example.com/migrate-stacks.

Example: Restricting a stack

When you restrict a stack, no new apps can be pushed using it. Existing apps continue to operate normally:

$ cf update-stack cflinuxfs3 --state restricted \
  --reason "New apps can no longer be staged on cflinuxfs3. Existing apps remain unaffected. \
Please migrate to 'cflinuxfs4'."

Developers attempting to push a new app using the restricted stack see:

ERROR: Staging failed. The stack 'cflinuxfs3' is RESTRICTED and cannot be used for new applications:
New apps can no longer be staged on cflinuxfs3. Existing apps remain unaffected.
Please migrate to 'cflinuxfs4'.

Example: Disabling a stack

When you disable a stack, no app can be staged or restaged using it. Existing running apps continue to run and can be restarted and scaled:

$ cf update-stack cflinuxfs3 --state disabled \
  --reason "cflinuxfs3 is based on Ubuntu 18.04, which reached end-of-life. \
The stack has been disabled. Please migrate to 'cflinuxfs4'."

Developers attempting to restage an existing app on the disabled stack see:

ERROR: Staging failed. The stack 'cflinuxfs3' is DISABLED and can no longer be used for staging:
cflinuxfs3 is based on Ubuntu 18.04, which reached end-of-life.
The stack has been disabled. Please migrate to 'cflinuxfs4'.

Example: Re-activating a stack

To restore full access to a stack, transition it back to active:

$ cf update-stack cflinuxfs3 --state active

Recommended stack deprecation workflow

The following staged approach lets you phase out a stack without causing unexpected downtime for developers:

For more information about auditing and deleting stacks, see Using the Stack Auditor Plug-In.

Related topics

• Changing Stacks
• Using the Stack Auditor Plug-In
• CF API Stacks Documentation