App Manifest attribute reference

This topic describes manifest formatting and provides a full list of attributes available for app manifests. You can use it alongside the Deploying with App Manifests topic, which provides basic procedures and guidance for deploying apps with manifests.

For more information about V3 manifest properties, see the Cloud Foundry API (CAPI) V3 documentation.

Manifest Format

Manifests are written in YAML. The manifest below illustrates some YAML conventions, as follows:

• The manifest begins with three dashes.
• The version property specifies a manifest schema version. This property is optional. For more information, see Add Schema Version to a Manifest below.
• The applications block begins with a heading followed by a colon.
• The app name is preceded by a single dash and one space.
• Subsequent lines in the block are indented two spaces to align with name.

---
version: 1
applications:
- name: my-app
  memory: 512M
  instances: 2

Important If your app name begins with the dash character (-), you cannot interact with the app using the cf CLI. This is because the cf CLI interprets the dash as a flag.

Add Schema Version to a Manifest

Important This attribute is available with CAPI V3 only. To push a manifest that uses this attribute, do one of the following:

• Use cf CLI v7 or v8. See Upgrading to cf CLI v7 or Upgrading to cf CLI v8.
• Run cf v3-push APP-NAME. See v3-push - Cloud Foundry CLI.

You can specify the schema version in the versions property of the manifest. This property is optional.

The only supported version is 1. If not specified, the versions property defaults to 1.

Add Variables to a Manifest

You can use variables to create app manifests with values shared across all applicable environments in combination with references to environment-specific differences defined in separate files.

To add variables to an app manifest, do the following:

1. Create a file called vars.yml.

2. Add attributes to your vars.yml file. See the following example:

   instances: 2
   memory: 1G
   

3. Add the variables to your app manifest file using the following format: ((VARIABLE-NAME)). See the following example:

   ---
   applications:
   - name: test-app
     instances: ((instances))
     memory: ((memory))
     buildpacks:
     - go_buildpack
     env:
       GOPACKAGENAME: go_calls_ruby
     command: go_calls_ruby
   

   Note You can also use variables for partial values. For example, you can specify host in your variables file and - route: ((host)).env.com in your manifest file.

4. Run cf push:

   cf push --vars-file /PATH/vars.yml
   

   Where PATH is the path to the file you created.

Minimize Duplication with YAML Anchors

Top-level attributes are deprecated in favor of YAML anchors. For more information, see <a href="#deprecated>Deprecated App Manifest Features.

In manifests where multiple apps share settings or services, you may see duplicated content. While the manifests still work, duplication increases the risk of typographical errors, which cause deployments to fail.

You can declare shared configuration using a YAML anchor, which the manifest refers to in app declarations by using an alias.

---
defaults: &defaults
  buildpacks:
    - staticfile_buildpack
  memory: 1G


applications:
- name: bigapp
  <<: *defaults
- name: smallapp
  <<: *defaults
  memory: 256M

This manifest pushes two apps, smallapp and bigapp, with the staticfile buildpack but with 256M memory for smallapp and 1G for bigapp.

Application Attributes

This section explains how to describe optional app attributes in manifests. Each of these attributes can also be specified by a command line option. Command line options override the manifest.

Important In cf CLI v6, the route component attributes domain, domains, host, hosts, and no-hostname have been deprecated in favor of the routes attribute. In cf CLI v7, these attributes are removed. For more information, see Deprecated App Manifest Features.

Important In cf CLI v6, the route component attributes domain, domains, host, hosts, and no-hostname are deprecated in favor of the routes attribute. In cf CLI v7, these attributes are removed. For more information, see domain, domains, host, hosts, and no-hostname.

You can refer to a buildpack by name in a manifest or a command line option. The cf buildpacks command lists the buildpacks that you can use.

See below for information on referencing buildpacks in a manifest. The command line option that overrides this attribute is -b.

• Custom buildpacks: If your app requires a custom buildpack, you can use the buildpacks attribute to specify it in a number of ways:

  • By name: MY-BUILDPACK.
  • By GitHub URL: https://github.com/cloudfoundry/java-buildpack.git.

  • By GitHub URL with a branch or tag: https://github.com/cloudfoundry/java-buildpack.git#v3.3.0 for the v3.3.0 tag.

    ---
    ...
    buildpacks:
      - buildpack_URL
    

• Multiple buildpacks: If you are using multiple buildpacks, you can provide an additional -b flag or add an additional value to your manifest:

  ---
    ...
    buildpacks:
      - buildpack_URL
      - buildpack_URL
  

  Important

  • This feature does not work with Deprecated App Manifest Features.
  • You must specify multiple buildpacks in the correct order: the buildpack uses the app start command given by the final buildpack. For more information, see the multi-buildpack repository on GitHub.

The -b command-line flag overrides this attribute.

For more information, see Pushing an App with Multiple Buildpacks.

command

Some languages and frameworks require that you provide a custom command to start an app. Refer to the buildpack documentation to determine if you need to provide a custom start command.

You can provide the custom start command in your app manifest or on the command line. See Starting, Restarting, and Restaging Apps for more information about how Cloud Foundry determines its default start command.

To specify the custom start command in your app manifest, add it in the command: START-COMMAND format as the following example shows:

---
  ...
  command: bundle exec rake VERBOSE=true

The start command you specify becomes the default for your app. To return to using the original default start command set by your buildpack, you must explicitly set the attribute to null as follows:

---
  ...
  command: null

On the command line, use the -c option to specify the custom start command as the following example shows:

$ cf push my-app -c "bundle exec rake VERBOSE=true"

The -c option with a value of ‘null’ forces cf push to use the buildpack start command. See Forcing cf push to use the Buildpack Start Command for more information.

If you override the start command for a Buildpack app, Linux uses bash -c COMMAND to invoke your app. If you override the start command for a Docker app, Linux uses sh -c COMMAND to invoke your app. Because of this, if you override a start command, you should prefix exec to the final command in your custom composite start command.

An app needs to catch termination signals and clean itself up appropriately. Because of the way that shells manage process trees, the use of custom composite shell commands, particularly those that create child processes using &, &&, ||, etc., can prevent your app from receiving signals that are sent to the top level bash process.

To resolve this issue, you can use exec to replace the bash process with your own process. For example:

• bin/rake cf:on_first_instance db:migrate && bin/rails server -p $PORT -e $RAILS_ENV The process tree is bash -> ruby, so on graceful shutdown only the bash process receives the TERM signal, not the ruby process.

• bin/rake cf:on_first_instance db:migrate && exec bin/rails server -p $PORT -e $RAILS_ENV Because of the exec prefix included on the final command, the ruby process invoked by rails takes over the bash process managing the execution of the composite command. The process tree is only ruby, so the ruby web server receives the TERM signal and can shutdown gracefully for 10 seconds.

In more complex situations, like making a custom buildpack, you may want to use bash trap, wait, and backgrounded processes to manage your process tree and shut down apps gracefully. In most situations, however, a well-placed exec should be sufficient.

disk_quota

Use the disk_quota attribute to allocate the disk space for your app instance. This attribute requires a unit of measurement: M, MB, G, or GB, in upper case or lower case.

---
  ...
  disk_quota: 1024M

The command line option that overrides this attribute is -k.

docker

If your app is contained in a Docker image, then you may use the docker attribute to specify it and an optional Docker username.

This attribute is a combination of push options that include --docker-image and --docker-username.

---
  ...
  docker:
    image: docker-image-repository/docker-image-name
    username: docker-user-name

The command line option --docker-image or -o overrides docker.image. The command line option --docker-username overrides docker.username.

The manifest attribute docker.username is optional. If it is used, then the password must be provided in the environment variable CF_DOCKER_PASSWORD. Additionally, if a Docker username is specified, then a Docker image must also be specified.

Important Don't use the docker attribute with the buildpacks or path attributes. This causes an error.

health-check-http-endpoint

Use the health-check-http-endpoint attribute to customize the endpoint for the http health check type. If you do not provide a health-check-http-endpoint attribute, it uses endpoint /.

---
  ...
  health-check-type: http
  health-check-http-endpoint: /health

health-check-invocation-timeout

Use the health-check-invocation-timeout attribute to set the timeout in seconds for individual health check requests for HTTP and port health checks.

---
  ...
  health-check-invocation-timeout: 30

To override this attribute, run:

cf set-health-check APP-NAME http --invocation-timeout 10

Where APP-NAME is the name of your app.

Within the manifest, the health check timeout is controlled by the timeout attribute.

health-check-type

Use the health-check-type attribute to set the health_check_type flag to either port, process or http. If you do not provide a health-check-type attribute, it defaults to port.

---
  ...
  health-check-type: port

The command line option that overrides this attribute is -u.

In cf CLI v6, the value of none is deprecated in favor of process. In cf CLI v7, none is removed.

instances

Use the instances attribute to set the number of app instances.

---
  ...
  instances: 2

The default number of instances is 1.

To ensure that platform maintenance does not interrupt your app, run at least two instances.

memory

Use the memory attribute to specify the memory limit for all instances of an app. This attribute requires a unit of measurement: M, MB, G, or GB, in upper case or lower case. For example:

---
  ...
  memory: 1024M

The default memory limit is 1G. You might want to specify a smaller limit to conserve quota space if you know that your app instances do not require 1G of memory.

The command line option that overrides this attribute is -m.

metadata

Use the metadata information to tag your apps with additional information. You can specify two types of metadata: labels and annotations. For more information, see Types of Metadata in Using Metadata.

See the following example:

metadata:
  annotations:
    contact: "[email protected] [email protected]"
  labels:
    sensitive: true

For more information about metadata, see Using Metadata.

no-route

By default, cf push assigns a route to every app. But, some apps process data while running in the background and should not be assigned routes. Using the no-route flag attribute in the manifest or the flag option overrides all route-related attributes. You can use the no-route attribute with a value of true to prevent a route from being created for your app.

---
  ...
  no-route: true

The command line option that overrides this attribute is `--no-route`.

In the Diego architecture, no-route skips creating and binding a route for the app, but does not specify which type of health check to perform. If your app does not listen on a port because it is a worker or a scheduler app, then it does not satisfy the port-based health check, and TAS for VMs marks it as crashed. To prevent this, disable the port-based health check by running:

cf set-health-check APP-NAME process

Where APP-NAME is the name of your app.

To remove a route from an existing app, perform the following steps:

1. Remove the route using the cf unmap-route command.
2. Push the app again with the no-route: true attribute in the manifest or the --no-route command line option.

For more information, see Deploy Multiple Apps with One Manifest.

path

You can use the path attribute to tell Cloud Foundry the directory location where it can find your app.

The directory specified as the path, either as an attribute or as a parameter on the command line, becomes the location where the buildpack Detect script executes.

The command line option that overrides this attribute is -p.

---
  ...
  path: /path/to/app/bits

For more information, see How cf push Finds the App.

processes

Important This attribute is available with CAPI V3 only. To push a manifest that uses this attribute, do one of the following:

• Use cf CLI v7 or v8. See Upgrading to cf CLI v7 or Upgrading to cf CLI v8.
• Run cf v3-push APP-NAME. See v3-push - Cloud Foundry CLI.

Use the processes attribute to push apps that run multiple processes, such as a web app that has a UI process and a worker process. See the following example:

processes:
- type: web
  command: start-web.sh
  disk_quota: 512M
  health-check-http-endpoint: /healthcheck
  health-check-type: http
  health-check-invocation-timeout: 10
  instances: 3
  memory: 500M
  timeout: 10
- type: worker
  command: start-worker.sh
  disk_quota: 1G
  health-check-type: process
  instances: 2
  memory: 256M
  timeout: 15

For detailed information about the process-level configuration, see The app manifest specification in the CAPI documentation.

For more information about pushing an app with multiple processes, see Pushing an App with Multiple Processes.

random-route

If you push your app without specifying any route-related CLI options or app manifest flags, the cf CLI attempts to generate a route based on the app name, which can cause collisions.

You can use the random-route attribute to generate a unique route and avoid name collisions. When you use random-route, the cf CLI generates an HTTP route with a random host (if host is not set) or a TCP route with an unused port number.

See the following example use cases:

• You deploy the same app to multiple spaces for testing purposes. In this situation, you can use random-route to randomize routes declared with the route attribute in the app manifest.
• You use an app manifest for a classroom training exercise in which multiple users deploy the same app to the same space.

The command line option that overrides this attribute is --random-route.

---
  ...
  random-route: true

routes

Use the routes attribute to provide multiple HTTP and TCP routes. Each route for this app is created if it does not already exist.

This attribute is a combination of push options that include --hostname, -d, and --route-path that were used in cf CLI v6. These flags are not supported in cf CLI v7. You must use the routes property in the manifest from cf CLI v7 on.

Optionally, specify the protocol attribute to configure which network protocol the route uses for app ingress traffic. The available protocols are http2, http1, and tcp.

Important The protocol route attribute is only available for TAS for VMs deployments with HTTP/2 routing enabled. For information about configuring support for HTTP/2 in TAS for VMs, see Configuring HTTP/2 Support.

Optionally, specify the protocol attribute to configure which network protocol the route uses for app ingress traffic. The available protocols are http2, http1, and tcp.

Important The protocol route attribute is only available for TAS for VMs deployments with HTTP/2 routing enabled. For information about configuring support for HTTP/2 in TAS for VMs, see Configuring HTTP/2 Support.

---
  ...
  routes:
  - route: example.com
    protocol: http2
  - route: www.example.com/foo
  - route: tcp-example.com:1234

Manifest Attributes

The routes attribute cannot be used in conjunction with the following attributes: host, hosts, domain, domains, and no-hostname. An error will result.

Push Flag Options

This attribute has unique interactions with different command-line options. The table shows the cf push flags supported in cf CLI v6. In cf CLI v7, these cf push flags are no longer supported:

• --no-route
• -d1
• --hostname
• --route-path

Flag supported in cf CLI v6	Result
--no-route	All declared routes are ignored.
-d	Overrides the DOMAIN in all declared HTTP and TCP routes.
--hostname, -n	Sets or overrides the HOSTNAME in all HTTP routes. Does not impact TCP routes.
--route-path	Sets or overrides the PATH in all HTTP routes. Does not impact TCP routes.
--random-route	Sets or overrides the HOSTNAME in all HTTP routes. Sets or overrides the PORT in all TCP routes. The PORT and HOSTNAME are randomly generated.

sidecars

Important This attribute is available with CAPI V3 only. To push a manifest that uses this attribute, do one of the following:

• Use cf CLI v7 or v8. See Upgrading to cf CLI v7 or Upgrading to cf CLI v8.
• Run cf v3-push APP-NAME. See v3-push - Cloud Foundry CLI.

Use the sidecars attribute to specify additional processes to run in the same container as your app. Each sidecar must have values for name, process_types, and command, whereas memory is optional. See the following example:

sidecars:
- name: authenticator
  process_types: [ 'web', 'worker' ]
  command: bundle exec run-authenticator
  memory: 800M
- name: upcaser
  process_types: [ 'worker' ]
  command: ./tr-server
  memory: 900M

For more information about sidecars, see Pushing Apps with Sidecar Processes.

stack

Use the stack attribute to specify which stack to deploy your app to.

To see a list of available stacks, run cf stacks from the cf CLI.

---
  ...
  stack: cflinuxfs3

The command line option that overrides this attribute is -s.

timeout

The timeout attribute defines the number of seconds that Cloud Foundry allocates for starting your app. It is related to the health-check-type attribute.

For example:

---
  ...
  timeout: 80

You can increase the timeout length for very large apps that require more time to start. The timeout attribute defaults to 60, but you can set it to any value up to the Cloud Controller’s cc.maximum_health_check_timeout property.

cc.maximum_health_check_timeout has a maximum value of 600 seconds.

The command line option that overrides the timeout attribute is -t.

Important: If you configure timeout with a value greater than cc.maximum_health_check_timeout, the Cloud Controller reports a validation error with the maximum limit.

Environment Variables

The env block consists of a heading, then one or more environment variable/value pairs.

For example:

---
  ...
  env:
    RAILS_ENV: production
    RACK_ENV: production

cf push deploys the app to a container on the server. The variables belong to the container environment.

Important

• You must name variables with alphanumeric characters and underscores. Non-conforming variable names may cause unpredictable behavior.
• Do not use user-provided environment variables for security sensitive information such as credentials, because they might unintentionally show up in cf CLI output and Cloud Controller logs. Use user-provided service instances instead. The system-provided environment variable VCAP_SERVICES is properly redacted for user roles such as Space Supporter and in Cloud Controller log files.

While the app is running, you can modify environment variables in the following ways:

• To view all variables, run:

  cf env APP-NAME
  

  Where APP-NAME is the name of your app.

• To set an individual variable, run:

  cf set-env APP-NAME VARIABLE-NAME VARIABLE-VALUE
  

  Where:

  • APP-NAME is the name of your app.
  • VARIABLE-NAME is the environment variable you want to set.
  • VARIABLE-VALUE is the value of the environment value.

• To unset an individual variable, run:

  cf unset-env APP-NAME VARIABLE-NAME VARIABLE-VALUE
  

  Where:

  • APP-NAME is the name of your app.
  • VARIABLE-NAME is the environment variable you want to set.
  • VARIABLE-VALUE is the value of the environment value.

Environment variables interact with manifests in the following ways:

• When you deploy an app for the first time, Cloud Foundry reads the variables described in the environment block of the manifest and adds them to the environment of the container where the app is staged, and the environment of the container where the app is deployed.

• When you stop and then restart an app, its environment variables persist.

Services

Apps can bind to services such as databases, messaging, and key-value stores.

Apps are deployed into App Spaces. An app can only bind to services instances that exist in the target App Space before the app is deployed.

The services block consists of a heading, then one or more service instance names.

Whoever creates the service chooses the service instance names. These names can convey logical information, as in backend_queue, describe the nature of the service, as in mysql_5.x, or do neither, as in the example below.

---
  ...
  services:
   - instance_ABC
   - instance_XYZ

Binding to a service instance is a special case of setting an environment variable, namely VCAP_SERVICES. See the Bind a Service section of the Delivering Service Credentials to an App topic.

Deprecated App Manifest Features

These app manifest features have been deprecated in favor of other options, as described below.

Caution Running cf push app -f manifest.yml fails if your manifest uses any of these deprecated features along with the feature that replaces it.

YAML Anchors Replace Top-Level Attributes

Previously, you could declare top-level attributes, which are also known as global attributes. For example, you can move an attribute above the applications block, where it need appear only once.

The following example illustrates how this was used to manage duplicated settings.

---
# all apps use these settings and services
domain: shared-domain.example.com
memory: 1G
instances: 1
services:
- clockwork-mysql
applications:
- name: springtock
  host: tock09876
  path: ./spring-music/build/libs/spring-music.war
- name: springtick
  host: tick09875
  path: ./spring-music/build/libs/spring-music.war

Now, you can use YAML aliases instead.

The following example illustrates how to declare shared configuration using a YAML anchor, which the manifest refers to in app declarations by using an alias.

---
defaults: &defaults
  buildpacks:
    - staticfile_buildpack
  memory: 1G


applications:
- name: bigapp
  <<: *defaults
- name: smallapp
  <<: *defaults
  memory: 256M

When pushing the app, make explicit the attributes in each app’s declaration. To do this, assign the anchors and include the app-level attributes with YAML aliases in each app declaration.

Attribute routes Replaces domain, domains, host, hosts, and no-hostname

Important These properties are removed in cf CLI v7.

Previously, you could specify routes by listing them all at once using the routes attribute, or by using their hosts and domains as shown below.

---
applications:
- name: webapp
  host: www
  domains:
  - example.com
  - example.io

The following route component attributes have been deprecated:

• domain
• domains
• host
• hosts
• no-hostname

Now you can only specify routes by using the routes attribute:

---
applications:
- name: webapp
  routes:
  - route: www.example.com/foo
  - route: tcp.example.com:1234

This app manifest feature has been deprecated, and a replacement option is under consideration.

Inheritance

This feature has been deprecated, and has been replaced by Variable Substitution.

With inheritance, child manifests inherited configurations from a parent manifest, and the child manifests could use inherited configurations as provided, extend them, or override them. This feature has been deprecated, and has been replaced by Variable Substitution.

Buildpack Field in Manifest Is Deprecated

The singular buildpack field in manifests is deprecated. It has been replaced by buildpacks, which is now an array which takes as a value multiple buildpacks.