Using the Stack Auditor Plugin

This topic describes how to use the Stack Auditor plugin for the Cloud Foundry Command Line Interface (cf CLI).

Overview

Stack Auditor is a cf CLI plugin that provides commands for listing apps and their stacks, migrating apps to a new stack, and deleting a stack.

One use case for Stack Auditor is when you must migrate a large number of apps to a new stack. This includes moving from cflinuxfs2 to cflinuxfs3 in preparation to upgrade your deployment to a version that does not contain cflinuxfs3. The following table describes the workflow you can use:

Stage Description
1 Operator audits stack usage to determine which apps need to be migrated. See List Apps and Their Stacks.
2 Operator communicates with developers that they must migrate their existing apps to a new stack and begin pushing all new apps to the a new stack.
3 Developers migrate their apps to a new stack. See Change Stacks.
4 Operator confirms apps have been migrated.
5 Operator deletes buildpacks associated with the old stack.
6 Operator deletes the old stack. See Delete a Stack.

Note: If you upgrade your deployment to a version that contains the stack you deleted, the stack returns on upgrade.

7 If applicable, operator upgrades the deployment to the version that does not contain the old stack.

Install Stack Auditor

To install Stack Auditor, do the following:

  1. Download the Stack Auditor binary for your OS from Buildpack Extensions on Pivotal Network.

  2. Unzip the binary file you downloaded:

    tar xvzf PATH-TO-BINARY
    
  3. Install the plugin with the cf CLI:

    cf install-plugin PATH-TO-BINARY
    

Use Stack Auditor

The sections below describe how to use Stack Auditor.

List Apps and Their Stacks

This section describes how to see the apps in each org and space and what stack they are using.

  1. To see which apps are using which stack, run the following command. It lists apps for each org you have access to. To see all the apps in your deployment, ensure that you are logged in to the cf CLI as a user who can access all orgs.

    cf audit-stack
    

    See the following example output:

    $ cf audit-stack
    first-org/development/first-app cflinuxfs2 
    first-org/staging/first-app cflinuxfs2
    first-org/production/first-app cflinuxfs2
    second-org/development/second-app cflinuxfs3
    second-org/staging/second-app cflinuxfs3
    second-org/production/second-app cflinuxfs3
    ...
    

Change Stacks

This section describes how to change the stack that an app uses. Stack Auditor rebuilds the app onto the new stack without a change in the source code of the app. If you want to move the app to a new stack with updated source code, follow the procedure in the Changing Stacks topic.

WARNING: Stack Auditor rebuilds the app, which causes downtime. To avoid downtime, use a blue-green deployment strategy. See Using Blue-Green Deployment to Reduce Downtime and Risk.

To change the stack an app uses, do the following:

  1. Target the org and space of the app:

    cf target ORG SPACE
    

    Where:

    • ORG is the org the app is in
    • SPACE is the space the app is in
  2. Run the following command:

    Note: If the app is in a stopped state, it remains stopped after changing stacks.

    cf change-stack APP-NAME STACK-NAME
    

    Where:

    • APP-NAME is the app that you want to move to a new stack
    • STACK-NAME is the stack you want to move the app to

    See the following example output:

    $ cf change-stack my-app cflinuxfs3
    Attempting to change stack to cflinuxfs3 for my-app...
    Starting app my-app in org pivotal-pubtools / space pivotalcf-staging as ljarzynski@pivotal.io...
    Downloading staticfile_buildpack...
    
    . . . 
    
    requested state: started
    instances: 1/1
    usage: 64M x 1 instance
    urls: example.com
    last uploaded: Thu Mar 28 17:44:46 UTC 2019
    stack: cflinuxfs3
    buildpack: staticfile_buildpack
    
         state     since                    cpu    memory        disk         details
    #0   running   2019-04-02 03:18:57 PM   0.0%   8.2M of 64M   6.9M of 1G
    
    Application my-app was successfully changed to Stack cflinuxfs3 
    

Delete a Stack

This section describes how to delete a stack from your deployment. You must be an admin user to complete this step.

  1. To delete a stack, run the following command. This action cannot be undone, with the following exception: If you upgrade your deployment to a version that contains the stack you deleted, the stack returns on upgrade.

    cf delete-stack STACK-NAME
    

    Where STACK-NAME is the name of the stack you want to delete.

    $ cf delete-stack cflinuxfs2
    Are you sure you want to remove the cflinuxfs2 stack? If so, type the name of the stack [cflinuxfs2]
    >cflinuxfs2
    Deleting stack cflinuxfs2...
    Stack cflinuxfs2 has been deleted. 
    

    If you have any apps still running on cflinuxfs2, the command returns the following error:

    Failed to delete stack cflinuxfs2 with error: Please delete the app associations for your stack.   
    
Create a pull request or raise an issue on the source for this page in GitHub