Cloud Foundry API Documentation
This project is to provide thorough documentation of the main communication points between Cloud Foundry components.
The primary emphasis will be on HTTP endpoints within the cloud controller, NATS messages that are published/subscribed by the components, as well as the varz/healthz data exposed by most components.
Contributing to the documentation is as easy as:
- Fork the repository on GitHub
- Make your changes
- Send a pull request
Generating the site locally
To generate the site locally, simply run the following:
$ bundle install $ jekyll $ rackup
The site will then be accessible on [[http://localhost:9292]].
Since the documentation focuses on the raw messages, you will often times need to capture those messages from a running Cloud Foundry instance. Use the tips below to get some of the raw output.
Whenever you are adding raw output, be sure to sanitize it before committing. This will help to avoid accidentially exposing sensitive information.
To capture NATS messages, the easiest way is to listen in on a running Cloud
Foundry instance using the
nats-sub tool included with NATS.
This will show you any
dea.advertise message going through NATS:
$ nats-sub dea.advertise
If you have protected your NATS instance, then you can pass the connection
parameters just as they'd be in the
mbus setting for the component configuration:
$ nats-sub -s nats://localhost:4222/ dea.advertise
You can also specify wildcards, however wildcards don't go beyond periods. For instance:
$ nats-sub -s nats://localhost:4222/ '*.*'
This will return messages for
router.start, and others that
include just a single period. It won't include
NATS publish/subscribe messages
Finding which messages a components published or subscribes to on the NATS bus can be done rather low tech. Personally, I've just done the following within whichever component I'm curious about:
$ grep -R publish * $ grep -R timed_request * $ grep -R subscribe *
Typically ignore the occurances in the spec folders and look for the ones in lib
or other portions. Don't look specfically for
NATS.publish because some
components might have the NATS connection as a local variable and do a
To capture raw HTTP messages, a common tool that can be useful if you're on OS X would be HTTP Client. It allows you to do raw HTTP requests, specifying any headers or request body you might need.
When issuing raw HTTP requests against the cloud controller, there are a few headers that you will commonly need. These include:
Authorization- If the endpoint requires you to log in, set this header to your user token. If you have logged into the site with VMC, you can get your token from
Content-Type- Some of the endpoints, even for GET requests, seem to want the content-type set to
application/json. In some places I've used
Accept, however a before hook is used in order to specifically want the content-type.
X-VCAP-Service-Token- This header is used with the service gateways and the service endpoints of the cloud controller. It is set to the token value configured in your cloud controller configuration.