Director HTTP API

Note

Before using the Director API directly, we strongly encourage to consider using the CLI for automation such as performing a scheduled deploy from a CI. We hope that you will open a GitHub issue to share your use cases so that we can suggest or possibly make additions to the CLI.

The Director can be configured in two authentication modes: basic auth and UAA. Info endpoint does not require any authentication and can be used to determine which authentication mechanism to use. All other endpoints require authentication.

401 Unauthorized will be returned for requests that contain an invalid basic auth credentials or an invalid/expired UAA access token.

Any request may result in a redirection. Receiving an HTTP redirection is not an error and clients should follow that redirect. Redirect responses will have a Location header field. Clients should use same authentication method when following a redirect.

Certain requests result in complex and potentially long running operations against the IaaS, blobstore, or other resources. POST /deployments is a good example. Such requests start a Director task and continue running on the Director after response is returned. Response to such request will be a 302 Moved Temporarily redirect to a created task resource.

Once a Director task is created, clients can follow its progress by polling GET /tasks/{id} to find out its state. While waiting for the task to finish, different types of logs (event, result, debug information, etc.) can be followed to gain insight into what the task is doing.

recreate [Boolean]: Whether or not to ignore deletion errors. Possible values: true or not present. Default is not present.

skip_drain [String]: Comma separated list of job names that should not run drain scripts during the update. Possible values: * to represent all jobs, <job1>,<job2> to list job names, or not present. Default is not present.

Instances represent the expected state of the VMs of a deployment. The actual state of the VMs can be retrieved with the vms endpoints. instances is similar to vms, but also contains instances that do not have a VM.