Cloud Foundry Environment Variables

Page last updated: September 23, 2015

This page assumes you are using cf CLI v6.

Environment variables are the means by which the Cloud Foundry runtime communicates with a deployed application about its environment. This page describes the environment variables that Droplet Execution Agents (DEAs) and buildpacks set for applications.

For information about setting your own application-specific environment variables, refer to the Set Environment Variable in a Manifest section in the Application Manifests topic.

View Environment Variables

Use the cf env command to view the Cloud Foundry environment variables for your application. cf env displays the following environment variables:

• The VCAP_SERVICES variables existing in the container environment
• The user-provided variables set using the cf set-env command

$ cf env my-app
Getting env variables for app my-app in org my-org / space my-space as
admin...
OK

System-Provided:

{
 "VCAP_APPLICATION": {
  "application_id": "fa05c1a9-0fc1-4fbd-bae1-139850dec7a3",
  "application_name": "my-app",
  "application_uris": [
    "my-app.10.244.0.34.xip.io"
  ],
  "application_version": "fb8fbcc6-8d58-479e-bcc7-3b4ce5a7f0ca",
  "limits": {
  "disk": 1024,
  "fds": 16384,
  "mem": 256
  },
  "name": "my-app",
  "space_id": "06450c72-4669-4dc6-8096-45f9777db68a",
  "space_name": "my-space",
  "uris": [
    "my-app.10.244.0.34.xip.io"
  ],
  "users": null,
  "version": "fb8fbcc6-8d58-479e-bcc7-3b4ce5a7f0ca"
  }

User-Provided:
MY_DRAIN: http://drain.example.com
MY_ENV_VARIABLE: 100

Variables Available to Your Application

The subsections that follow describe the environment variables that Cloud Foundry makes available for your application container.

You can access environment variables programmatically, including variables defined by the buildpack. Refer to the buildpack documentation for Java, Node.js, and Ruby.

HOME

Root folder for the deployed application.

HOME=/home/vcap/app

MEMORY_LIMIT

The maximum amount of memory that each instance of the application can consume. You specify this value in an application manifest or with the cf CLI when pushing an application. The value is limited by space and org quotas.

If an instance goes over the maximum limit, it will be restarted. If it has to be restarted too often, it will be terminated.

MEMORY_LIMIT=512m

PORT

The port on the DEA for communication with the application. The DEA allocates a port to the application during staging. For this reason, code that obtains or uses the application port should reference it using PORT.

PORT=61857

PWD

Identifies the present working directory, where the buildpack that processed the application ran.

PWD=/home/vcap

TMPDIR

Directory location where temporary and staging files are stored.

TMPDIR=/home/vcap/tmp

USER

The user account under which the DEA runs.

USER=vcap

VCAP_APP_HOST

The IP address of the DEA host.

VCAP_APP_HOST=0.0.0.0

VCAP_APPLICATION

This variable contains the associated attributes for a deployed application. Results are returned in JSON format. The table below lists the attributes that are returned.

For example:

VCAP_APPLICATION={"instance_id":"fe98dc76ba549876543210abcd1234",
"instance_index":0,"host":"0.0.0.0","port":61857,"started_at":"2013-08-12
00:05:29 +0000","started_at_timestamp":1376265929,"start":"2013-08-12 00:05:29
+0000","state_timestamp":1376265929,"limits":{"mem":512,"disk":1024,"fds":16384}
,"application_version":"ab12cd34-5678-abcd-0123-abcdef987654","application_name"
:"styx-james","application_uris":["styx-james.a1-app.cf-app.com"],"version":"ab1
2cd34-5678-abcd-0123-abcdef987654","name":"my-app","uris":["my-app.example.com"]
,"users":null}

VCAP_APP_PORT

Deprecated name for the PORT variable, defined above.

VCAP_SERVICES

For bindable services Cloud Foundry will add connection details to the VCAP_SERVICES environment variable when you restart your application, after binding a service instance to your application.

The results are returned as a JSON document that contains an object for each service for which one or more instances are bound to the application. The service object contains a child object for each service instance of that service that is bound to the application. The attributes that describe a bound service are defined in the table below.

The key for each service in the JSON document is the same as the value of the “label” attribute.

To see the value of VCAP_SERVICES for an application pushed to Cloud Foundry, see View Environment Variable Values.

The example below shows the value of VCAP_SERVICES for bound instances of several services available in the Pivotal Web Services Marketplace.

VCAP_SERVICES=
{
  "elephantsql": [
    {
      "name": "elephantsql-c6c60",
      "label": "elephantsql",
      "tags": [
        "postgres",
        "postgresql",
        "relational"
      ],
      "plan": "turtle",
      "credentials": {
        "uri": "postgres://seilbmbd:[email protected]:5432/seilbmbd"
      }
    }
  ],
  "sendgrid": [
    {
      "name": "mysendgrid",
      "label": "sendgrid",
      "tags": [
        "smtp"
      ],
      "plan": "free",
      "credentials": {
        "hostname": "smtp.sendgrid.net",
        "username": "QvsXMbJ3rK",
        "password": "HCHMOYluTv"
      }
    }
  ]
}

Application Instance-Specific Variables

Each instance of an application can access a set of variables with the CF_INSTANCE prefix. These variables provide information for a given application instance, including identification of the host DEA by its IP address.

CF_INSTANCE_ADDR

The CF_INSTANCE_IP and CF_INSTANCE_PORT of the app instance in the format particular-DEA-IP:particular-app-instance-port.

CF_INSTANCE_ADDR=1.2.3.4:5678

CF_INSTANCE_INDEX

The index number of the app instance.

CF_INSTANCE_INDEX=0

CF_INSTANCE_IP

The external IP address of the DEA running the container with the app instance.

CF_INSTANCE_IP=1.2.3.4

CF_INSTANCE_PORT

The PORT of the app instance.

CF_INSTANCE_PORT=5678

CF_INSTANCE_PORTS

The external and internal ports allocated to the app instance.

CF_INSTANCE_PORTS=[{external:5678,internal:5678}]

Environment Variable Groups

Environment variable groups are system-wide variables that enable operators to apply a group of environment variables to all running applications and all staging applications separately.

An environment variable group consists of a single hash of name-value pairs that are later inserted into an application container at runtime or at staging. These values can contain information such as HTTP proxy information. The values for variables set in an environment variable group are case-sensitive.

When creating environment variable groups, consider the following:

• Only the Cloud Foundry operator can set the hash value for each group.
• All authenticated users can get the environment variables assigned to their application.
• All variable changes take effect after the operator restarts or restages the applications.
• Any user-defined variable takes precedence over environment variables provided by these groups.

The table below lists the commands for environment variable groups.

The following examples demonstrate how to retrieve the environment variables:

$ cf revg
Retrieving the contents of the running environment variable group as
[email protected]...
OK
Variable Name   Assigned Value
HTTP Proxy      87.226.68.130

$ cf sevg
Retrieving the contents of the staging environment variable group as
[email protected]...
OK
Variable Name   Assigned Value
HTTP Proxy      27.145.145.105
EXAMPLE-GROUP   2001

$ cf apps
Getting apps in org SAMPLE-ORG-NAME / space dev as
[email protected]...
OK

name    requested state   instances   memory   disk   urls
my-app  started           1/1         256M     1G     my-app.com

$ cf env APP-NAME
Getting env variables for app APP-NAME in org SAMPLE-ORG-NAME / space dev as
[email protected]...
OK

System-Provided:

{
  "VCAP_APPLICATION": {
  "application_name": "APP-NAME",
  "application_uris": [
    "my-app.example.com"
  ],
  "application_version": "7d0d64be-7f6f-406a-9d21-504643147d63",
  "limits": {
  "disk": 1024,
  "fds": 16384,
  "mem": 256
  },
  "name": "APP-NAME",
  "space_id": "37189599-2407-9946-865e-8ebd0e2df89a",
  "space_name": "dev",
  "uris": [
    "my-app.example.com"
  ],
  "users": null,
  "version": "7d0d64be-7f6f-406a-9d21-504643147d63"
 }
}

Running Environment Variable Groups:
HTTP Proxy: 87.226.68.130

Staging Environment Variable Groups:
EXAMPLE-GROUP: 2001
HTTP Proxy: 27.145.145.105

The following examples demonstrate how to set environment variables:

$ cf ssevg '{"test":"87.226.68.130","test2":"27.145.145.105"}'
Setting the contents of the staging environment variable group as admin...
OK
$ cf sevg
Retrieving the contents of the staging environment variable group as admin...
OK
Variable Name   Assigned Value
test            87.226.68.130
test2           27.145.145.105

$ cf srevg '{"test3":"2001","test4":"2010"}'
Setting the contents of the running environment variable group as admin...
OK
$ cf revg
Retrieving the contents of the running environment variable group as admin...
OK
Variable Name   Assigned Value
test3           2001
test4           2010