top of page

VCAP_SERVICES environment variable and its use in cloud foundry applications

Today we will learn about an important element in application development in Cloud Foundry, the VCAP_SERVICES. It is an integral part of application development in Cloud Foundry. Every developer has to use this element while working on cloud native development in Cloud Foundry.

For decades developers used environment variables of a host OS to set some values that can be fetched by the application at run time. Environment variables work as a key-value pair to store a few basic information needed by the application that does not change. We use them mainly to store application configuration parameters. The configuration parameters are needed by the application either at the application start-up or during the time when the application is alive. Once an environment variable is set the application can access them at any time.




What is VCAP_SERVICES environment variable?

Cloud Foundry also uses the idea of environment variables heavily. When Cloud Foundry hosts an application it always makes one environment variable available and it is named VCAP_SERVICES. Once an application is starting up any information available in VCAP_SERVICES are available to the application. Also, when the application is up and running VCAP_SERVICES can be accessed. VCAP_SERVICES variables provided in the container environment in which the application runs. VCAP_SERVICES environment variable is in JSON data structure. Cloud Foundry makes sure that multiple JSON elements can be set in the VCAP_SERVICES JSON.

The format looks like as follows:

  "element_1": [
      "property_1": "property_value",
  "element_2": [
      "property_1": [
  "element_3": [
      "property_2": {
        "key_1": "value_1",
        "key_2": "value_2"

We can see there can be multiple elements inside the VCAP_SERVICES environment variable as it is a JSON itself. Each of the elements are JSOn arrays. The sub elements of the top level element can be a key-value pair, an JSON array, or a JSON itself with sub elements. The name of the sub elements can match with the sub elements of another top level element. Only the top elements should have a unique name. The values are always strings.

Each of the top level elements in the JSON is produced for different reasons.

What configuration information are there in VCAP_SERVICES ? Who sets values in VCAP_SERVICES ?

When an instance of a reusable service is bound to the application, the application needs some configuration parameters related to the reusable service instance. These information are made available in the top level elements with their name. The Service Broker of the reusable service along with the Cloud Controller makes this available to the VCAP_SERVICES. Whenever an instance is bound to an application the VCAP_SERVICES is updated. For example, when we bind an instance of a postgres database to our application, an top level element with name “postgres” is added. The json inside the element will contain all the necessary information for the application to communicate to the database. The information will include the database host and port , the username and password and a few more items. These information are only visible to an application who has bound to the database instance. This is how the database instance can securely communicate the credentials or configuration parameters needed by the application. the application needs to be rebound to the reusable service instance again if these information are changed the application has to read fresh information. After an instance is bound to a running application we need to restart the application.

How To use VCAP_SERVICES Environment Variable In Cloud Foundry Applications ?

Accessing VCAP_SERVICES environment variable is the same as accessing any other environment variable by an application which is deployed in any machine in any OS. It depends on the programming language used.

In Java we will use System.getenv(“VCAP_SERVICES”)

In node.js we will use process.env.VCAP_SERVICES

In Python we will use os.getenv('VCAP_SERVICES')

In node the variable used will be automatically in a JSON format. In Java we need to convert it from a string to a JSON object.

You can read the Cloud Foundry documentation for more details on VCAP_SERVICES.

To manually view the environment variables you can use this command. It will show all environment variables supplied by the platform and the developers. Read Cloud Foundry documentation on this command.

$ cf env app_name

Today in this port we have seen what is VCAP_SERVICES environment variable, how it is used by the Cloud Foundry platform and how applications can access the environment variable.

Recent Posts

See All


bottom of page