stack-auditor.html.md.erb

---
title: Using Stack Auditor in Cloud Foundry
owner: Buildpacks
---

<%# Reset page title based on platform type %>
<% if vars.platform_code != 'CF' %>

<% set_title("Using Stack Auditor in", vars.app_runtime_abbr) %>

<% end %>

Stack Auditor is a cf CLI plug-in that allows you to list apps and their stacks, migrate apps to a new stack, and delete a stack. Learn how to use it on this page.

A typical use for Stack Auditor is migrating a large number of apps to a new stack.
This includes moving apps from `cflinuxfs3` to `cflinuxfs4` in preparation to upgrade your deployment
to a version that does not contain `cflinuxfs3`.
The following table describes the workflow you can use:

<table class="table">
	<thead>
	<tr>
		<th>Stage</th>
		<th>Description</th>
	</tr>
	</thead>
	<tr>
		<td>1</td>
		<td>Operator audits stack usage to determine which apps need to be migrated. See <a href="#list-stacks">List Apps and Their Stacks</a>.</td>
	</tr>
	<tr>
		<td>2</td>
		<td>Operator communicates with developers that they must migrate their existing apps to a new stack and begin pushing all new apps to the new stack.</td>
	</tr>
	<tr>
		<td>3</td>
		<td>Developers migrate their apps to the new stack. See <a href="#change-stacks">Change Stacks</a>.</td>
	</tr>
	<tr>
		<td>4</td>
		<td>Operator confirms apps have been migrated.</td>
	</tr>
	<tr>
		<td>5</td>
		<td>Operator deletes buildpacks associated with the old stack.</td>
	</tr>
	<tr>
		<td>6</td>
		<td>Operator deletes the old stack. See <a href="#delete-stacks">Delete a Stack</a>.
		<p>If you upgrade your deployment to a version that contains the stack you deleted, the stack returns on upgrade.</p></td>
	</tr>
	<tr>
		<td>7</td>
		<td>If applicable, operator upgrades the deployment to the version that does not contain the old stack.</td>
	</tr>
</table>

## <a id="install"></a> Install Stack Auditor

To install Stack Auditor:

1. <%= vars.get_auditor_binary %>

1. Install the plug-in with the cf CLI:

	```
	cf install-plugin PATH-TO-BINARY
	```

	Or install from the community repo by running:

	```
	cf install-plugin StackAuditor
	```

## <a id="use"></a> Using Stack Auditor

The following sections describe how to use Stack Auditor.

### <a id="list-stacks"></a> List apps and their stacks

With Stack Auditor, you can get a list of the apps in each org and space and see what stack they are using.

To see which apps are using which stack, run the following command. The output lists apps for each org you have access to. To see all the apps in your deployment, be sure to log in to the cf CLI as a user who can access all orgs.

```
cf audit-stack
```

Here is example output:

  <pre class="terminal">
  $ cf audit-stack
  first-org/development/first-app cflinuxfs3
  first-org/staging/first-app cflinuxfs3
  first-org/production/first-app cflinuxfs3
  second-org/development/second-app cflinuxfs4
  second-org/staging/second-app cflinuxfs4
  second-org/production/second-app cflinuxfs4
  ...
  </pre>

### <a id="change-stacks"></a> Change stacks for a single app

Stack Auditor allows you 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 [Changing Stacks](../devguide/deploy-apps/stacks.html).

To change the stack an app uses:

1. Target the org and space of the app:

	```
	cf target -o ORG -s SPACE
	```

    Where:

    <ul>
      <li><code>ORG</code> is the org the app is in.</li>
      <li><code>SPACE</code> is the space the app is in.</li>
    </ul>

1. Run the following command:

	```
	cf change-stack APP-NAME STACK-NAME
	```

    Where:

    <ul>
      <li><code>APP-NAME</code> is the app that you want to move to a new stack.</li>
      <li><code>STACK-NAME</code> is the stack you want to move the app to.</li>
    </ul>

	Here is example output:

	<pre class="terminal">
	$ cf change-stack my-app cflinuxfs4
	Attempting to change stack to cflinuxfs4 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: Wed 17 Jul 22:57:04 UTC 2024
	stack: cflinuxfs4
	buildpack: staticfile_buildpack

	     state     since                  cpu    memory        disk           logging         cpu entitlement   details
	#0   running   2024-07-17T22:57:22Z   0.3%   8.2M of 64M   130.2M of 1G   0B/s of 16K/s   2.4%


	Application my-app was successfully changed to Stack cflinuxfs4
	</pre>

<p class="note important">
If the app is in a <code>stopped</code> state, it remains stopped after changing stacks. Also, when attempting to change stacks, your app is stopped. If the app fails on <code>cflinuxfs4</code>, Stack Auditor attempts to restage your app on <code>cflinuxfs3</code>.</p>

### <a id="change-stacks-all-apps"></a> Change stacks for all apps in a space

Stack Auditor also allows you to migrate all apps in a space to a new stack. For example, using jq you can write a script to find all apps in a space and migrate them to cflinuxfs4:

```jq
cf audit-stack --json | jq -r 'map(select(.stack == "cflinuxfs3")) | .[] |"cf target -o \(.org) -s \(.space) && cf change-stack \(.name) cflinuxfs4"' | xargs -i{} bash -c {}
```

### <a id="delete-stacks"></a> Delete a stack

Stack Auditor allows you to delete a stack from your deployment. You must be an admin user to delete a stack.

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.

  Here is example output:

	<pre class="terminal">
    $ cf delete-stack cflinuxfs3
    Are you sure you want to remove the cflinuxfs3 stack? If so, type the name of the stack [cflinuxfs3]
    >cflinuxfs3
    Deleting stack cflinuxfs3...
    Stack cflinuxfs3 has been deleted.
    </pre>

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

    <pre class="terminal">
    Failed to delete stack cflinuxfs3 with error: Please delete the app associations for your stack.
    </pre>

### <a id="contact-users"></a> Contacting users of apps

If you are having problems with an app and need help, you can use the cf CLI to get a list of email addresses of users in a space. For example, run:

```
cf space-users ORG-NAME SPACE-NAME
```

Where:

  * `ORG-NAME` is the org the app is in.
  * `SPACE-NAME` is the space the app is in.

## <a id="known-issues"></a> Known issues

The following are known issues with changing stacks from cflinuxfs3 to cflinuxfs4.

### <a id="openssl1.1"></a> OpenSSL1.1 is not included in cflinuxfs4

cflinuxfs4 does not include OpenSSL1.1. If your application depends on OpenSSL1.1, for example, a static file buildpack containing an executable but using the system libraries for SSL, it will fail to run. Ensure that your application can be rebuilt against OpenSSL3 or include the OpenSSL1.1 libraries with your application.

### <a id="dotnet-gss"></a> .NET 6 and GSS requires legacy provider

If your application is .NET 6 and uses GSS, you may see the following error message:

<pre class="terminal">
GSSAPI operation failed with error - Unspecified GSS failure. Minor code may provide more information (Crypto routine failure).
</pre>

There is an existing .NET issue about this failure, which is related to legacy usage of OpenSSL3. For more information, see <a href=https://github.com/dotnet/runtime/issues/67353>GSS failures in System.Net.Http.Functional.Tests on Ubuntu 22.04re</a> on GitHub. The workaround is listed <a href=https://github.com/dotnet/runtime/issues/67353#issuecomment-1085003764>on the same page</a> and involves explicitly loading the legacy provider.

### <a id="dotnet-gss"></a> .NET Core apps and LDAP

If your application is .NET Core and using LDAP connectivity, you may see the following error message if you are using cflinuxfs4 prior to v1.45.0:

<pre class="terminal">
"ThreadName": ".NET ThreadPool Worker", "Message": "#414 Failed to establish connection to domain: [{\"Domain\":\"myldap-domain.com\",\"Host\":\"dc=emea,dc=org,dc=com\",\"Base\":\"emea\",\"Name\":\"EUROPE\"}] exception: The type initializer for 'Ldap' threw an exception.", "Description": "#414 Failed to establish connection to domain: [{\"Domain\":\"myldap-domain.com\",\"Host\":\"dc=emea,dc=org,dc=com\",\"Base\":\"emea\",\"Name\":\"EUROPE\"}] exception: The type initializer for 'Ldap' threw an exception.", "Environment": "ge4-sit", "Exception": " ", "RequestHandler": "Controller: Action:", "CallStack": "Org.DSA.Shared.Logger.ApiLogger.Log" }
</pre>

The issue is related to a stack-level LDAP package that wasn't available in cflinuxfs4 until v1.45.0 and its interaction with the `System.DirectoryServices.Protocols` package.

To resolve the problem:
* Upgrade the cflinuxfs4 stack.
* Upgrade the `System.DirectoryServices` NuGet package to version 8.0.0 or higher. You can do this in the application using the following command:

    <pre class="terminal">
    <PackageReference Include="System.DirectoryServices.Protocols" Version="8.0.0" />
    </pre>

### <a id="ruby-buildpack"></a> Ruby 3.1 or later is required

Ruby 3.1, introduced in Ruby buildpack v1.8.51, or later is required for the Ruby buildpack running on cflinuxfs4. Upgrade your application to work with Ruby 3.1 or later by specifying it in your application's Gemfile and working through any issues that result. If an application specifies a version of Ruby in its Gemfile not included in the buildpack, it results in the following error message:

<pre class="terminal">
**ERROR** Unable to determine ruby: Unable to determine ruby version: Running ruby: No Matching versions, ruby = 2.7.6 not found in this buildpack                                                                ·······
Failed to compile droplet: Failed to run all supply scripts: exit status 15
</pre>

This happens because Ruby v2.7 and v3.0 are incompatible with OpenSSL3, which is the version of OpenSSL in cflinuxfs4.