App Manifest Attribute Reference

Page last updated:

This topic describes manifest formatting and provides a full list of attributes available for app manifests. You can use it alongside Deploying with App Manifests, 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 demonstrates 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

Note: 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

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

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:

  1. Create a file called vars.yml.

  2. Add attributes to your vars.yml file. For example:

    instances: 2
    memory: 1G
    
  3. Add the variables to your app manifest file using the following format: ((VARIABLE-NAME)). For 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 --vars-file /PATH/vars.yml
    

    Where PATH is the path to the file you created.

Minimize Duplication with YAML Anchors

Note: Top-level attributes are deprecated in favor of YAML anchors. For more information, see Top-Level Attributes below.

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

The example manifest above pushes two apps with the staticfile buildpack, smallapp and bigapp, with 256 M of memory for smallapp and 1 G of memory for bigapp.

App 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.

Note: 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 below.

buildpacks

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.

  • 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: 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
    

    Notes:
    • This feature does not work with the deprecated buildpack attribute. For more information, see buildpack below.
    • 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. To determine if you need to provide a custom start command, see Buildpacks.

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

To specify the custom start command in your app manifest, add it in the command: START-COMMAND format. For example:

---
  ...
  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. For example:

---
  ...
  command: null

On the command line, you can specify the custom start command by including the -c flag, similar to the following example:

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

Note: The -c option with a value of ‘null’ forces cf push to use the buildpack start command. For more information, see Forcing cf push to use the Buildpack Start Command in Starting, Restarting, and Restaging Apps.

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 usessh -c COMMANDto invoke your app. Because of this, if you override a start command, you should prefixexec` 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 &, &&, ||, and so on, can prevent your app from receiving signals that are sent to the top-level bash process. For more information, see Considerations for Designing and Running an App in the Cloud.

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

The disk_quota attribute allocates the disk space for your app instance. This attribute requires a unit of measurement: M, MB, G, or GB, in either uppercase or lowercase.

For example:

---
  ...
  disk_quota: 1024M

The -k command-line flag overrides this attribute.

docker

If your app is contained in a Docker image, the docker attribute specifies it and an optional Docker username. This attribute is a combination of push options that include --docker-image and --docker-username.

For example:

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

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

The manifest attribute docker.username is optional. If it is used, 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.

Note: Using the docker attribute in conjunction with the buildpacks or path attributes results in an error.

health-check-http-endpoint

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

For example:

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

health-check-invocation-timeout

The health-check-invocation-timeout attribute configures the timeout in seconds for individual health check requests for HTTP and port health checks.

For example:

---
  ...
  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

The health-check-type attribute sets 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.

For example:

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

The -u command-line flag overrides this attribute.

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

instances

The instances attribute configures the number of app instances.

For example:

---
  ...
  instances: 2

The default number of instances is 1.

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

log-rate-limit-per-second

The log-rate-limit-per-second attribute specifies the log rate limit for all instances of an app. This attribute requires a unit of measurement: B, K, KB, M, MB, G, or GB, in either uppercase or lowercase.

For example:

---
  ...
  log-rate-limit-per-second: 24KB

To configure each app instance to send an unlimited number of logs to Loggregator, specify -1.

The default log rate limit is 16 K. If you know that your app instances do not require the default log rate limit, you might want to specify a smaller limit in your manifest to conserve quota space.

The -l command-line flag overrides this attribute.

memory

The memory attribute specifies the memory limit for all instances of an app. This attribute requires a unit of measurement: M, MB, G, or GB, in either uppercase or lowercase.

For example:

---
  ...
  memory: 1024M

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

The -m command-line flag overrides this attribute.

metadata

The metadata attribute tags 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.

For example:

metadata:
  annotations:
    contact: "bob@example.com jane@example.com"
  labels:
    sensitive: true

For more information about metadata, see Using Metadata.

no-route

Note: If you use the no-route flag attribute in the manifest or the flag option, it overrides all route-related attributes.

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.

You can use the no-route attribute with a value of true to prevent a route from being created for your app.

For example:

---
  ...
  no-route: true

The --no-route command-line flag overrides this attribute.

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:

  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 in Deploying with App Manifests.

path

The path attribute tells TAS for VMs the directory location in which 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.

For example:

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

The -p command-line flag overrides this attribute.

For more information, see How cf push Finds the App in Getting Started with the cf CLI.

processes

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

The processes attribute pushes apps that run multiple processes, such as a web app that has a UI process and a worker process.

For 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 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 one of the following:

  • An HTTP route with a random host, if no value is specified for host

  • A TCP route with an unused port number.

For example:

---
  ...
  random-route: true

The following example use cases demonstrate when you might use the random-route attribute:

  • 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 --random-route command-line flag overrides this attribute.

routes

The routes attribute provides 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.

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.

Note: The protocol route attribute is only available for TAS for VMs deployments that use HTTP/2 routing. For information about configuring support for HTTP/2 in TAS for VMs, see Configuring HTTP/2 Support.

For example:

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

Manifest Attributes

If you use the routes attribute in conjunction with the host, hosts, domain, domains, or no-hostname attributes, an error results.

Push Flag Options

This attribute has unique interactions with different command-line options.

Flag 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

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

The sidecars attribute specifies 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.

For 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

The stack attribute specifies the stack to which your app deploys.

For example:

---
  ...
  stack: cflinuxfs3

To see a list of available stacks, run cf stacks.

The -s command-line flag overrides this attribute.

timeout

The timeout attribute defines the number of seconds that TAS for VMs 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 -t command-line flag overrides this attribute.

Warning: 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.

Notes:
  • 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:

    1. Run:
      cf env APP-NAME
    

    Where APP-NAME is the name of your app.

  • To set an individual variable:

    1. 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:

    1. 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, TAS for VMs 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 and one or more service instance names.

Whoever creates the service chooses the service instance names. These names can convey logical information, describe the nature of the service, or neither.

For example:

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

You can bind an app to a service instance by setting the VCAP_SERVICES environment variable. For more information, see Bind a Service in Delivering Service Credentials to an App.

Deprecated App Manifest Features

This section describes app manifest features that are deprecated in favor of other features.

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

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 demonstrates how this was used to manage duplicated settings:

---
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

Top-level attributes are deprecated in favor of YAML aliases.

The following example demonstrates how to specify a 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.

domain, domains, host, hosts, and no-hostname

Note: 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.

For example:

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

The following route component attributes are deprecated:

  • domain

  • domains

  • host

  • hosts

  • no-hostname

You can only specify routes by using the routes attribute:

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

Inheritance

This feature is deprecated and replaced by variable substitution. For more information, see Variable Substitution above.

With inheritance, child manifests inherited configurations from a parent manifest. The child manifests can use the inherited configurations as provided, extend them, or override them.

buildpack

The singular buildpack attribute is deprecated. It is replaced by buildpacks, which specifies multiple buildpacks. For more information, see buildpacks above.