Technical Specification: Translation of VCAP_SERVICES to Service Binding Files

[philippthun]

This document describes how service binding details, exposed to application processes in the VCAP_SERVICES environment variable, are translated into a list (tree) of files known as Service Binding Files.

Translation Process

1. The translation process begins with the system checking if the application process is enabled for file-based service bindings. If enabled, it builds a set of valid service binding files.

2. Each service binding's name is validated for uniqueness and compatibility. Duplicate or invalid binding names result in an IncompatibleBindings error. Binding names must match [a-z0-9\-.]{1,253} as specified in the Service Binding Specification for Kubernetes [1].

3. Multiple service binding files are generated for each service binding. The service binding's name acts as the directory name, while various properties of the service binding (such as credentials and attributes) act as file names.

4. The credentials attribute in VCAP_SERVICES is a JSON object. Each top-level key within this object will be matched to a file within the service binding's directory, and the corresponding value will be the file content. In case credentials contain a deeply nested structure, still only the top-level keys will be represented as files. Nested structures inside their value will be serialized as JSON objects. The same applies if the value is a list. (See example no. 1)

5. Existing credential keys can be overwritten by other attributes, that are VCAP_SERVICES attributes as defined in the Cloud Foundry Documentation [2] plus type and provider. The full list of reserved file names is: binding-guid, binding-name, instance-guid, instance-name, name, label, tags, plan, syslog-drain-url, volume-mounts, type, and provider. Overwriting an existing key does not result in an error. (See example no. 2)

6. All file names must match the same schema as the service binding's name. An invalid name results in an IncompatibleBindings error. The VCAP_SERVICES attributes are transformed to comply to this schema, i.e. underscores are replaced by hyphens, so that e.g. VCAP_SERVICES attribute binding_guid becomes file name binding-guid. (See example no. 3)

7. If a service binding value represents a list (like it is the case for tags and volume mounts), the file content will be a JSON representation of the array.

8. Empty lists or null values are omitted, i.e. no file will be created. (See example no. 3)

9. The total bytesize of the generated files is validated. If the total bytesize (of file paths and contents) exceeds the maximum allowed bytesize limit (default is 1,000,000 bytes), an IncompatibleBindings error is raised.

Examples

Example No. 1
-------------

VCAP_SERVICES= {
  "foo": [
    {
      "name": "foo",
      "credentials": {
        "simple": "value",
        "deeply": {
          "nested": "value"
        },
        "list": ["v", "a", "l", "u", "e"]
      }
    }
  ]
}

Service Binding Files:
  foo/name: foo
  foo/simple: value
  foo/deeply: {"nested":"value"}
  foo/list: ["v","a","l","u","e"]


Example No. 2
-------------

VCAP_SERVICES= {
  "foo": [
    {
      "name": "foo",
      "credentials": {
        "name": "user",
        "secret": "password"
      }
    }
  ]
}

Service Binding Files:
  foo/name: foo
  foo/secret: password


Example No. 3
-------------

VCAP_SERVICES= {
  "foo": [
    {
      "name": "foo",
      "binding_guid": "45436ca8-0a7c-45e3-9439-ca1b44db7a2b",
      "syslog_drain_url": null,
      "volume_mounts": []
    }
  ]
}

Service Binding Files:
  foo/name: foo
  foo/binding-guid: 45436ca8-0a7c-45e3-9439-ca1b44db7a2b

[1] https://servicebinding.io/spec/core/1.1.0/#workload-projection
[2] https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES