Skip to content

RPC Interface

All CPIs are expected to implement a basic RPC interface through STDIN/STDOUT.

Invocation

Since CPI is just an executable, following takes place for each CPI method call (where "caller" is often the director):

  1. Caller starts a new CPI executable OS process (shells out)
  2. Caller sends a single JSON request over STDIN
  3. CPI optionally sends logging debugging information to STDERR
  4. CPI responds with a single JSON response over STDOUT
  5. CPI executable exits
  6. Caller parses and interprets JSON response ignoring process exit code

For reference, there are two primary implementations of the "caller" which invoke the CPI...

  • BOSH Director - invokes the CPI through typical deploy/stemcell commands, internally using its external_cpi.rb wrapper.
  • bosh CLI - invokes the CPI through create-env/delete-env commands, internally using its cpi_cmd_runner.go.

API

Request

  • method [String]: Name of the CPI method. Example: create_vm.
  • arguments [Array]: Array of arguments that are specific to the CPI method.
  • context [Hash]: Additional information provided as a context of this execution. Specified for backwards compatibility and should be ignored.

An example request for delete_disk might look like:

{
  "method": "delete_disk",
  "arguments": ["vol-1b7fb8fd"],
  "context": { "director_uuid":"fefb87c8-38d1-46a5-4552-9749d6b1195c" }
}

Response

  • result [Null or simple values]: Single return value. It must be null if error is returned.
  • error [Null or hash]: Occurred error. It must be null if result is returned.
  • type [String]: Type of the error.
    • message [String]: Description of the error.
    • ok_to_retry [Boolean]: Indicates whether callee should try calling the method again without changing any of the arguments.
  • log [String]: Additional information that may be useful for auditing, debugging and understanding what actions CPI took while executing a method. Typically includes info and debug logs, error backtraces.

An example response to create_vm might look like:

{
  "result": "i-384959",
  "error": null,
  "log": ""
}

An example error response to create_vm might look like:

{
  "result": null,
  "error": {
    "type": "Bosh::Clouds::CloudError",
    "message": "Flavor `m1.2xlarge' not found",
    "ok_to_retry": false
  },
  "log": "Rescued error: 'Flavor `m1.2xlarge' not found'. Backtrace: ~/.bosh_init/ins..."
}

Methods