Cloud Management API 1.5

Inputs

Inputs help extract dynamic information, usually specified at runtime, from repeatable configuration operations that can be codified. Inputs are variables defined in and used by RightScripts/Recipes. The two main attributes of an input are 'name' and 'value'. The 'name' identifies the input and the 'value', although a string encodes what type it is. It could be a text encoded as 'text:myvalue' or a credential encoded as 'cred:MY_CRED' or a key etc. Please see support.rightscale.com for more info on input hierarchies and their different types.

Actions

index

Retrieves the full list of existing inputs of the specified resource.

URLs
GET /api/clouds/:cloud_id/instances/:instance_id/inputs
GET /api/deployments/:deployment_id/inputs
GET /api/server_templates/:server_template_id/inputs
HTTP response code
200 OK
Content-type
application/vnd.rightscale.input;type=collection

Required roles

Parameters

name required type values regexp blank? description
view no String default, inputs_2_0 * no Specifies how many attributes and/or expanded nested relationships to include.

Example Responses

Click on a format below to see an example response for the 'default' view:

JSON XML
[{
  "name": "input_definition_3604220013",
  "value": "text:"
},{
  "name": "input_definition_422628238",
  "value": "text:"
}]
<?xml version="1.0" encoding="UTF-8"?>
<inputs>
  <input>
    <name>input_definition_3604220013</name>
    <value>text:</value>
  </input>
  <input>
    <name>input_definition_422628238</name>
    <value>text:</value>
  </input>
</inputs>

Click on a format below to see an example response for the 'inputs_2_0' view:

JSON XML
[{
  "name": "input_definition_3604220013",
  "value": "blank"
},{
  "name": "input_definition_422628238",
  "value": "blank"
}]
<?xml version="1.0" encoding="UTF-8"?>
<inputs>
  <input>
    <name>input_definition_3604220013</name>
    <value>blank</value>
  </input>
  <input>
    <name>input_definition_422628238</name>
    <value>blank</value>
  </input>
</inputs>

multi_update

Performs a bulk update of inputs on the specified resource.

If an input exists with the same name, its value will be updated. If an input does not exist with a specified name, it will be ignored.

Input values are represented as strings.

There are two notations for inputs:

Although the two notations are similar, they have a few important differences, in particular:

  1. With 2.0 notation, values MUST begin with a prefix identifying their type, followed by a colon (example: "text:foo"). With 1.0 notation, unprefixed values are generally taken to be text-type.
  2. With 2.0 notation, a sentinel value "inherit" is used to express that an input should use an inherited value. With 1.0 notation the empty string was used to express the same thing. (Due to requirement 1, empty string is no longer a valid input.)
  3. With 2.0 notation, each element of an array is an entire input value; arrays can contain cred, env, or even other arrays. With 1.0 notation, array elements are implicitly text values and there is no way to specify anything else.
    Note that the UI does not support complex-valued arrays; please use this feature with caution!

The following types of inputs are supported:

Type Format 1.0 Example(s) 2.0 Example(s)
Text string <value> (1.0 only)
text:<value>
foo
text:foo
text:multi word value
text:foo
text:multi word value
Blank string
(input is present but its value is empty-string)
text:
blank (2.0 only)
text: blank
Ignore (input is not present, input will inherit) ignore
$ignore (1.0 only)
ignore:$ignore (1.0 only)
ignore
$ignore
ignore:$ignore
ignore
Dynamically-substituted environment value env:<value>
env:<component>:<value>
env:MY_ENV_VAR
env:my_server:MY_ENV_VAR
env:MY_ENV_VAR
env:my_server:MY_ENV_VAR
Credential value cred:<value> cred:abcd1234wxyz cred:abcd1234wxyz
Private SSH key key:<value>
key:<value>:<cloud_id>
key:1234abcd5678
key:1234abcd5678:1
key:1234abcd5678
key:1234abcd5678:1
Array of values array:<value>,... (1.0 only)
array:["<type>:<value>",...] (2.0 only)
array:x,y
(NOTE: 1.0 only supports text inputs for arrays)
array:["text:v1","text:v2"]
array:["text:x","env:server_x:MY_VAR"]

Note that in the case of array inputs, the portion after the colon must be valid JSON. In particular, when enclosing the input within double-quotes (e.g. for use in cURL or Ruby), the double-quotes must be escaped. Single-quotes may not be used within the array input, since they are not valid for JSON strings.

The legacy format for providing inputs is as an array of name-value pairs (ex: -d inputs[][name]="MY_INPUT" -d inputs[][value]="text:foobar"), however the new format is supported for inputs provided as a hash (ex: -d inputs[MY_INPUT]="text:foobar").

If the old format is used, the input is parsed using 1.0 semantics. If the new format is used, the input is parsed using the new 2.0 semantics.

URLs
PUT /api/clouds/:cloud_id/instances/:instance_id/inputs/multi_update
PUT /api/deployments/:deployment_id/inputs/multi_update
PUT /api/server_templates/:server_template_id/inputs/multi_update
HTTP response code
204 No Content

Required roles

Parameters

name required type values regexp blank? description
inputs yes Enumerable * * no
inputs[*] no String * * no The format used for passing 2.0-style Inputs. The key is the name of the input, and the value is the value to assign to the input.
inputs[][name] no String * * no The name of the input to be updated.
inputs[][value] no String * * no The value to be updated with. Should be of the form 'text:my_value' or 'cred:MY_CRED' etc.