Permalink
Fetching contributors…
Cannot retrieve contributors at this time
670 lines (579 sloc) 19.1 KB
---
title: Cloud Foundry Environment Variables
owner: CAPI
---
<strong><%= modified_date %></strong>
Environment variables are the means by which the Cloud Foundry (CF) runtime
communicates with a deployed application about its environment.
This page describes the environment variables that the runtime and buildpacks
set for applications.
For information about setting your own application-specific environment
variables, see the [Environment Variable](./manifest.html#env-block) section of the _Deploying with Application Manifests_ topic.
## <a id='view-env'></a>View Environment Variables ##
Install the Cloud Foundry Command Line Interface (cf CLI), and use the [cf env](http://cli.cloudfoundry.org/en-US/cf/env.html) command to view the Cloud
Foundry environment variables for your application.
The `cf env` command displays the following environment variables:
* The `VCAP_APPLICATION` and `VCAP_SERVICES` variables provided in the container environment
* The user-provided variables set using the [cf set-env](http://cli.cloudfoundry.org/en-US/cf/set-env.html) command
<pre class="terminal">
$ 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.192.0.2.34.xip.io"
],
"application_version": "fb8fbcc6-8d58-479e-bcc7-3b4ce5a7f0ca",
"cf_api": "https://api.example.com",
"limits": {
"disk": 1024,
"fds": 16384,
"mem": 256
},
"name": "my-app",
"space_id": "06450c72-4669-4dc6-8096-45f9777db68a",
"space_name": "my-space",
"uris": [
"my-app.192.0.2.34.xip.io"
],
"users": null,
"version": "fb8fbcc6-8d58-479e-bcc7-3b4ce5a7f0ca"
}
User-Provided:
MY_DRAIN: http://drain.example.com
MY_ENV_VARIABLE: 100
</pre>
## <a id='app-system-env'></a>Application-Specific System Variables ##
The subsections that follow describe the environment variables that Cloud
Foundry makes available to your application container.
Some of these variables are the same across instances of a single application,
and some vary from instance to instance.
You can access environment variables programmatically, including variables
defined by the buildpack.
For more information, refer to the buildpack documentation for
[Java](../../buildpacks/java/java-tips.html#env-var),
[Node.js](../../buildpacks/node/node-tips.html#env-var), and
[Ruby](../../buildpacks/ruby/ruby-tips.html#env-var).
<table border="1" class="nice">
<tr>
<th>Env Var</th>
<th>Running</th>
<th>Staging</th>
<th>Task</th>
</tr>
<tr>
<td><code>CF_INSTANCE_ADDR</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>CF_INSTANCE_GUID</code></td>
<td>x</td>
<td></td>
<td>x</td>
</tr>
<tr>
<td><code>CF_INSTANCE_INDEX</code></td>
<td>x</td>
<td></td>
<td></td>
</tr>
<tr>
<td><code>CF_INSTANCE_INTERNAL_IP</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>CF_INSTANCE_IP</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>CF_INSTANCE_PORT</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>CF_INSTANCE_PORTS</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>CF_STACK</code></td>
<td></td>
<td>x</td>
<td></td>
</tr>
<tr>
<td><code>DATABASE_URL</code></td>
<td>x</td>
<td></td>
<td>x</td>
</tr>
<tr>
<td><code>HOME</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>INSTANCE_GUID</code></td>
<td>x</td>
<td></td>
<td></td>
</tr>
<tr>
<td><code>INSTANCE_INDEX</code></td>
<td>x</td>
<td></td>
<td></td>
</tr>
<tr>
<td><code>LANG</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>MEMORY_LIMIT</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>PATH</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>PORT</code></td>
<td>x</td>
<td></td>
<td></td>
</tr>
<tr>
<td><code>PWD</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>TMPDIR</code></td>
<td>x</td>
<td></td>
<td>x</td>
</tr>
<tr>
<td><code>USER</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>VCAP_APP_HOST</code></td>
<td>x</td>
<td></td>
<td></td>
</tr>
<tr>
<td><code>VCAP_APP_PORT</code></td>
<td>x</td>
<td></td>
<td></td>
</tr>
<tr>
<td><code>VCAP_APPLICATION</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
<tr>
<td><code>VCAP_SERVICES</code></td>
<td>x</td>
<td>x</td>
<td>x</td>
</tr>
</table>
### <a id='CF-INSTANCE-ADDR'></a>CF\_INSTANCE\_ADDR ###
The [CF\_INSTANCE\_IP](#CF-INSTANCE-IP) and
[CF\_INSTANCE\_PORT](#CF-INSTANCE-PORT) of the app instance in the format
`IP:PORT`.
Example: `CF_INSTANCE_ADDR=1.2.3.4:5678`
### <a id='CF-INSTANCE-GUID'></a>CF\_INSTANCE\_GUID ###
The UUID of the particular instance of the app.
Example: `CF_INSTANCE_GUID=41653aa4-3a3a-486a-4431-ef258b39f042`
### <a id='CF-INSTANCE-INDEX'></a>CF\_INSTANCE\_INDEX ###
The index number of the app instance.
Example: `CF_INSTANCE_INDEX=0`
### <a id='CF-INSTANCE-IP'></a>CF\_INSTANCE\_IP ###
The external IP address of the host running the app instance.
Example: `CF_INSTANCE_IP=1.2.3.4`
### <a id='CF-INSTANCE-INTERNAL-IP'></a>CF\_INSTANCE\_INTERNAL_IP ###
The internal IP address of the container running the app instance.
Example: `CF_INSTANCE_INTERNAL_IP=5.6.7.8`
### <a id='CF-INSTANCE-PORT'></a>CF\_INSTANCE\_PORT ###
The external, or *host-side*, port corresponding to the internal, or *container-side*, port with value [PORT](#PORT).
This value is generally different from the
[PORT](#PORT) of the app instance.
Example: `CF_INSTANCE_PORT=61045`
### <a id='CF-INSTANCE-PORTS'></a>CF\_INSTANCE\_PORTS ###
The list of mappings between internal, or *container-side*, and external, or *host-side*, ports allocated to the instance's container.
Not all of the internal ports are necessarily available for the application to
bind to, as some of them may be used by system-provided services that also run
inside the container. These internal and external values may differ.
Example: `CF_INSTANCE_PORTS=[{external:61045,internal:8080},{external:61046,internal:2222}]`
### <a id='DATABASE-URL'></a>DATABASE\_URL ###
For apps bound to certain services that use a database, CF creates a `DATABASE_URL` environment variable based on the [VCAP_SERVICES](#VCAP-SERVICES) environment variable at runtime.
CF uses the structure of the `VCAP_SERVICES` environment variable to populate `DATABASE_URL`.
CF recognizes any service containing a JSON object with the following form as a candidate for `DATABASE_URL` and uses the first candidate it finds.
{
"some-service": [
{
"credentials": {
"uri": "SOME-DATABASE-URL"
}
}
]
}
For example, consider the following `VCAP_SERVICES`:
VCAP_SERVICES =
{
"elephantsql": [
{
"name": "elephantsql-c6c60",
"label": "elephantsql",
"credentials": {
"uri": "postgres://exampleuser:examplepass@babar.elephantsql.com:5432/exampledb"
}
}
]
}
Based on this `VCAP_SERVICES`, CF creates the following
`DATABASE_URL` environment variable:
DATABASE_URL = postgres://exampleuser:examplepass@babar.elephantsql.com:5432/exampledb
### <a id='HOME'></a>HOME ###
Root folder for the deployed application.
Example: `HOME=/home/vcap/app`
### <a id='LANG'></a>LANG ###
LANG is required by buildpacks to ensure consistent script load order.
Example: `LANG=en_US.UTF-8`
### <a id='memory'></a>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 exceeds the maximum limit, it will be restarted.
If Cloud Foundry is asked to restart an instance too frequently, the instance will instead be terminated.
Example: `MEMORY_LIMIT=512M`
### <a id='PORT'></a>PORT ###
The port on which the app should listen for requests.
The Cloud Foundry runtime allocates a port dynamically for each instance of the
application, so code that obtains or uses the app port should refer to
it using the `PORT` environment variable.
Example: `PORT=8080`
### <a id='PWD'></a>PWD ###
Identifies the present working directory, where the buildpack that processed
the application ran.
Example: `PWD=/home/vcap/app`
### <a id='TMPDIR'></a>TMPDIR###
Directory location where temporary and staging files are stored.
Example: `TMPDIR=/home/vcap/tmp`
### <a id='USER'></a>USER###
The user account under which the application runs.
Example: `USER=vcap`
### <a id='VCAP-APP-PORT'></a>VCAP\_APP\_PORT ###
Deprecated name for the [PORT](#PORT) variable defined above.
### <a id='VCAP-APPLICATION'></a>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.
<table border="1" class="nice">
<tr>
<th>Attribute</th>
<th>Description</th>
</tr>
<tr>
<td><code>application_id</code></td>
<td>GUID identifying the application.</td>
</tr>
<tr>
<td><code>application_name</code></td>
<td>The name assigned to the application when it was pushed.</td>
</tr>
<tr>
<td><code>application_uris</code></td>
<td>The URIs assigned to the application.</td>
</tr>
<tr>
<td><code>application_version</code></td>
<td>GUID identifying a version of the application. Each time an application is pushed or restarted, this value is updated.</td>
</tr>
<tr>
<td><code>cf_api</code></td>
<td>Location of the Cloud Controller API for the CF Deployment where the app runs.</td>
</tr>
<tr>
<td><code>host</code></td>
<td>Deprecated. IP address of the application instance. </td>
</tr>
<tr>
<td><code>limits</code></td>
<td>The limits to disk space, number of files, and memory permitted to the app. Memory and disk space limits are supplied when the application is deployed, either on the command line or in the application manifest. The number of files allowed is operator-defined.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>Identical to <code>application_name</code>.</td>
</tr>
<tr>
<td><code>space_id</code></td>
<td>GUID identifying the application's space.</td>
</tr>
<tr>
<td><code>space_name</code></td>
<td>Human-readable name of the space where the app is deployed.</td>
</tr>
<tr>
<td><code>start</code></td>
<td>Human-readable timestamp for the time the instance was started. Not provided on Diego Cells.</td>
</tr>
<tr>
<td><code>started_at</code></td>
<td>Identical to <code>start</code>. Not provided on Diego Cells.</td>
</tr>
<tr>
<td><code>started_at_timestamp</code></td>
<td>Unix epoch timestamp for the time the instance was started. Not provided on Diego Cells.</td>
</tr>
<tr>
<td><code>state_timestamp</code></td>
<td>Identical to <code>started_at_timestamp</code>. Not provided on Diego Cells.</td>
</tr>
<tr>
<td><code>uris</code></td>
<td>Identical to <code>application_uris</code>. You must ensure that both <code>application_uris</code> and <code>uris</code> are set to the same value.</td>
</tr>
<tr>
<td><code>users</code></td>
<td>Deprecated. Not provided on Diego Cells.</td>
</tr>
<tr>
<td><code>version</code></td>
<td>Identical to <code>application_version</code>.</td>
</tr>
</table>
The following example shows how to set the `VCAP_APPLICATION` environment variable:
~~~
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":["my-app.example.com"],"version":"ab1
2cd34-5678-abcd-0123-abcdef987654","name":"my-app","uris":["my-app.example.com"]
,"users":null}
~~~
### <a id='VCAP-SERVICES'></a>VCAP\_SERVICES ###
For [bindable services](../services/), Cloud Foundry adds 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.
<table border="1" class="nice">
<tr>
<th>Attribute</th>
<th>Description</th>
</tr>
<tr>
<td><code>binding_name</code></td>
<td>The name assigned to the service binding by the user.</td>
</tr>
<tr>
<td><code>instance_name</code></td>
<td>The name assigned to the service instance by the user.</td>
</tr>
<tr>
<td><code>name</code></td>
<td>The <code>binding_name</code> if it exists; otherwise the <code>instance_name</code>.</td>
</tr>
<tr>
<td><code>label</code></td>
<td>The name of the service offering.</td>
</tr>
<tr>
<td><code>tags</code></td>
<td>An array of strings an app can use to identify a service instance.</td>
</tr>
<tr>
<td><code>plan</code></td>
<td>The service plan selected when the service instance was created.</td>
</tr>
<tr>
<td><code>credentials</code></td>
<td>A JSON object containing the service-specific credentials needed to access the service instance.</td>
</tr>
</table>
To see the value of VCAP\_SERVICES for an application pushed to Cloud Foundry,
see [View Environment Variable Values](#view-env).
The example below shows the value of VCAP_SERVICES for bound instances of several services available in the
[Pivotal Web Services](http://run.pivotal.io) Marketplace.
~~~
VCAP_SERVICES=
{
"elephantsql": [
{
"name": "elephantsql-binding-c6c60",
"binding_name": "elephantsql-binding-c6c60",
"instance_name": "elephantsql-c6c60",
"label": "elephantsql",
"tags": [
"postgres",
"postgresql",
"relational"
],
"plan": "turtle",
"credentials": {
"uri": "postgres://exampleuser:examplepass@babar.elephantsql.com:5432/exampleuser"
}
}
],
"sendgrid": [
{
"name": "mysendgrid",
"binding_name": null,
"instance_name": "mysendgrid",
"label": "sendgrid",
"tags": [
"smtp"
],
"plan": "free",
"credentials": {
"hostname": "smtp.sendgrid.net",
"username": "QvsXMbJ3rK",
"password": "HCHMOYluTv"
}
}
]
}
~~~
## <a id='evgroups'></a>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.
<table border="1" class="nice">
<tr>
<th>CLI Command</th>
<th>Description</th>
</tr>
<tr>
<td><code>running-environment-variable-group</code> or <code>revg</code></td>
<td>Retrieves the contents of the running environment variable group.</td>
</tr>
<tr>
<td><code>staging-environment-variable-group</code> or <code>sevg</code></td>
<td>Retrieves the contents of the staging environment variable group.</td>
</tr>
<tr>
<td><code>set-staging-environment-variable-group</code> or <code>ssevg</code></td>
<td>Passes parameters as JSON to create a staging environment variable group.</td>
</tr>
<tr>
<td><code>set-running-environment-variable-group</code> or <code>srevg</code></td>
<td>Passes parameters as JSON to create a running environment variable group.</td>
</tr>
</table>
The following examples demonstrate how to retrieve the environment variables:
<pre class="terminal">
$ cf revg
Retrieving the contents of the running environment variable group as
sampledeveloper@example.com...
OK
Variable Name Assigned Value
HTTP Proxy 198.51.100.130
$ cf sevg
Retrieving the contents of the staging environment variable group as
sampledeveloper@example.com...
OK
Variable Name Assigned Value
HTTP Proxy 203.0.113.105
EXAMPLE-GROUP 2001
$ cf apps
Getting apps in org SAMPLE-ORG-NAME / space dev as
sampledeveloper@example.com...
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
sampledeveloper@example.com...
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: 198.51.100.130
Staging Environment Variable Groups:
EXAMPLE-GROUP: 2001
HTTP Proxy: 203.0.113.105
</pre>
The following examples demonstrate how to set environment variables:
<pre class="terminal">
$ cf ssevg '{"test":"198.51.100.130","test2":"203.0.113.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 198.51.100.130
test2 203.0.113.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
</pre>