Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Cloud Foundry API Documentation

branch: master
Octocat-spinner-32 _includes DEA vcap.component.*: fix json messages April 03, 2012
Octocat-spinner-32 _layouts Reorganizing to better handle http endpoints April 01, 2012
Octocat-spinner-32 _plugins Tweak to file modification to not break if the file isnt committed yet March 30, 2012
Octocat-spinner-32 _posts Updated some styling and added error codes to http apps section May 24, 2012
Octocat-spinner-32 public Some style changes for the header on subpages March 30, 2012
Octocat-spinner-32 .gitignore initial commit March 29, 2012
Octocat-spinner-32 AUTHORS Add email April 02, 2012
Octocat-spinner-32 Gemfile Added plugin to set the post date to when it was committed to git... … March 30, 2012
Octocat-spinner-32 Gemfile.lock Added plugin to set the post date to when it was committed to git... … March 30, 2012
Octocat-spinner-32 LICENSE initial commit March 29, 2012
Octocat-spinner-32 README.md Added some missing publish/requests from the cloud controller March 29, 2012
Octocat-spinner-32 _config.yml Add /varz endpoints April 03, 2012
Octocat-spinner-32 cloud-controller.md Changed side nav to be main categories and added the categories with … March 29, 2012
Octocat-spinner-32 config.ru initial commit March 29, 2012
Octocat-spinner-32 dea.md Changed side nav to be main categories and added the categories with … March 29, 2012
Octocat-spinner-32 health-manager.md Changed side nav to be main categories and added the categories with … March 29, 2012
Octocat-spinner-32 http-apps.md Reorganizing to better handle http endpoints April 01, 2012
Octocat-spinner-32 http-authentication.md Reorganizing to better handle http endpoints April 01, 2012
Octocat-spinner-32 http-info.md Reorganizing to better handle http endpoints April 01, 2012
Octocat-spinner-32 http-services.md Reorganizing to better handle http endpoints April 01, 2012
Octocat-spinner-32 http-users.md Updated user account API information to point to UAA April 20, 2012
Octocat-spinner-32 http-varz.md Add /varz missing files April 03, 2012
Octocat-spinner-32 index.md Updated statuses April 02, 2012
Octocat-spinner-32 manifest.yml initial commit March 29, 2012
Octocat-spinner-32 router.md Changed side nav to be main categories and added the categories with … March 29, 2012
Octocat-spinner-32 service-gateway.md Changed side nav to be main categories and added the categories with … March 29, 2012
Octocat-spinner-32 service-node.md Changed side nav to be main categories and added the categories with … March 29, 2012
Octocat-spinner-32 stager.md Changed side nav to be main categories and added the categories with … March 29, 2012
README.md

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

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]].

Capturing output

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.

NATS messages

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 dea.advertise, router.start, and others that include just a single period. It won't include dea.{uuid}.start though.

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 @nats_conn.publish.

HTTP endpoints

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 ~/.vmc_token.
  • 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.
Something went wrong with that request. Please try again.