App Manifest Attribute Reference

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

For manifest properties for the v7 beta cf CLI, see the CC API documentation for v3 app manifest properties.

Manifest Format

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

  • The manifest begins with three dashes.
  • 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.
---
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 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.

In addition, using variables enables you to store sensitive data in a separate file that the app manifest would reference, making the security sensitive data easier to manage and keep secure.

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

Note: Top-level attributes have been deprecated in favor of YAML anchors. For more information, see 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.

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

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.

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
    

    Note: This feature does not work with Deprecated App Manifest Features.

    Note: You must specify multiple buildpacks in the correct order: the buildpack will use the app start command given by the final buildpack. See the multi-buildpack repository for more information.

Also see Pushing an App with Multiple Buildpacks for more information.

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"

Note: 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 YOUR-COMMAND to invoke your app. If you override the start command for a Docker app, Linux uses sh -c YOUR-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.

Note: Using the docker attribute in conjunction with the buildpacks or path attributes will result in 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-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.

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.

no-route

Note: If you use the `no-route` flag attribute in the manifest or the flag option, it will override 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.

---
  ...
  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 Cloud Foundry marks it as crashed. To prevent this, disable the port-based health check with cf set-health-check APP_NAME process.

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.

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.

---
  ...
  routes:
  - route: example.com
  - 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.

Push Flag Option Resulting Behaviour
--no-route All declared routes are ignored.
-d Overrides DOMAIN part of all declared HTTP and TCP routes.
--hostname, -n Sets or overrides HOSTNAME in all HTTP routes.
It has no impact on TCP routes.
--route-path Sets or overrides the PATH in all HTTP routes.
It has no impact on 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 will be randomly generated.

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 defaults to the maximum of 180. Your Cloud Foundry operator can set to any value.

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

Warning: Cloud Controller reports a validation error with the maximum limit if you to configure timeout with a value greater than it.

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.

Note: You must name variables with alphanumeric characters and underscores. Non-conforming variable names may cause unpredictable behavior.

While the app is running, you can modify environment variables.

  • View all variables: cf env my-app
  • Set an individual variable: cf set-env my-app my-variable_name my-variable_value
  • Unset an individual variable: cf unset-env my-app my-variable_name my-variable_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.

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.

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

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

Create a pull request or raise an issue on the source for this page in GitHub