Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Action Execution #1

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Action Execution #1

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
60e80f8
Action Execution
rohitkshetty May 14, 2017
3d0fc5c
updating status strings
rohitkshetty May 16, 2017
5442a65
Update spec.md
rohitkshetty May 16, 2017
a597cf8
Update
rohitkshetty May 16, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
259 changes: 259 additions & 0 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -746,6 +746,265 @@ For success responses, the following fields are supported. Others will be ignore
}
</pre>

# Service Instance Actions
These are any actions that a broker allows w.r.t the service instances that it manages. The actions here could be anything that the service broker wants to provide and the platform shouldnt have to care what these are. The actions are discoverable by the platform and since the platform has absolutely no clue what these actions are there would be user interaction involved where the actions are presented to the user by the platform and the user performs the action with any input thats required.

## Action Discovery
By Implementing this endpoint the broker allows the platform to query the actions allowed on a service instance at any point in time. The list of actions returned by the endpoint is dynamic and could depend on the service instance and its internal state.

##### Route #####
`GET /v2/service_instances/:instance_id/actions`

The `:instance_id` of a service instance that has been provisioned previously.

#### cURL ####
<pre class="terminal">
$ curl -H "X-Broker-API-Version: 2.11" http://username:password@broker-url/v2/service_instances/:instance_id/actions
</pre>

### Response ###

| Status Code | Description |
|---|---|
| 200 OK | The expected response body is below. |

##### Action <a name="action"></a> #####

| Response field | Type | Description |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of coming up with our own definition for describing APIs, I'd like to understand why .../actions can't just return a swagger spec. Seems like at the very least we should figure out why it is not sufficient for our needs.
https://github.com/OAI/OpenAPI-Specification

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I understand the comment. /actions returns the list of actions that can be performed on a service instance and not the list of API's that exist.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, so the question you're asking from the endpoint is what actions can be performed. I presume each action that you call is an HTTP request and if so, then you're describing an API? Inputs/outputs, etc. and it seems like if you call the /actions, returning a swagger document which is an open spec for describing APIs rather than defining our own format would seem better unless there's a strong reason not to do that?

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Each action execution (see line 887 onwards) is a POST /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id with action id and parameters. So any action is just a call to a single API to execute that action.

What you are referring to is a way to discover the actions that a service brker supports for a service instance. The actions once discovered can be executed using the API mentioned above. I believe what I have here is very similar to the proposals here openservicebrokerapi#114 from gberche-orange . I think the big difference is breaking up the relationship of the actions from plans and allowing a broker to dynamically publish the actions it supports for a service instance.

Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vaikas-google The /actions get gives you a lot of information about the tasks that you can use to render to the user.

As I mentioned earlier, these are broker defined actions .i.e. what the task is, what it does is completely controlled by the broker and a broker could introduce any type of action. The platform shouldnt have to care what the action actually does, but just that there are a set of actions available and each action might require user input. The data returned by the /actions allows the platform to present the list of actions available to the end user in the context of a service instance and if the user selects a particular action, present the user with a UI to collect the required parameters and finally submit the action for execution.

|---|---|---|
| id* | string | A unique identifier for the action. Using a GUID is RECOMMENDED. |
| name* | string | The CLI-friendly name of the action. MUST be unique within the service. All lowercase, no spaces. |
| displayName* | string | The display friendly name of the action that would be used for display in the UI and CLI |
| description* | string | A short description of the action. |
| parameters | array-of-objects | An array of parameters required by the action. |


##### Parameter <a name="parameter"></a> #####

| Response field | Type | Description |
|---|---|---|
| name* | string | The CLI-friendly name of the parameter. MUST be unique within the action. All lowercase, no spaces. |
| displayName* | string | The display friendly name of the parameter that would be used for display in the UI and CLI |
| description* | string | A short description of the parameter. |
| value | string | An indication to the platform to provide a default value for the parameter. |
| options | array-of-strings | A array of values that can be provided as a list of choices to the user. |

\* Fields with an asterisk are REQUIRED.

<pre>
{
"actions": [{
"name": "fake-backup-action",
"displayName": "Run periodic backup",
"id": "acb56222-XXXX-XXXX-XXXX-feb140a59a66",
"description": "Runs and enables periodic service instance backup",
"parameters": [{
"name": "fake-backup-int-param",
"displayName": "Backup Interval (days)",
"id": "d3031751-XXXX-XXXX-XXXX-a42377d33222",
"description": "Provide the interval at which the service instance data should be backed up",
"value": "1",
"options": ["1", "2", "3"]
}, {
"name": "fake-backup-retention-param",
"displayName": "Retention Period (days)",
"description": "Provide the retention period for the backed up data",
"value": "90"
}]
}, {
"name": "fake-restart-action",
"displayName": "Restart Service",
"description": "Restart the service"
}]
}
</pre>

## Get an Action
Retrieve a single action

##### Route #####
`GET /v2/service_instances/:instance_id/actions/:action_id`

The `:action_id` of a action.
The `:instance_id` of a service instance that has been provisioned previously.

#### cURL ####
<pre class="terminal">
$ curl -H "X-Broker-API-Version: 2.11" http://username:password@broker-url/v2/service_instances/:instance_id/actions/:action_id
</pre>

### Response ###

| Status Code | Description |
|---|---|
| 200 OK | The expected response body is below. |

##### Action <a name="action"></a> #####

| Response field | Type | Description |
|---|---|---|
| id* | string | A unique identifier for the action. Using a GUID is RECOMMENDED. |
| name* | string | The CLI-friendly name of the action. MUST be unique within the service. All lowercase, no spaces. |
| displayName* | string | The display friendly name of the action that would be used for display in the UI and CLI |
| description* | string | A short description of the action. |
| parameters | array-of-objects | An array of parameters required by the action. |


##### Parameter <a name="parameter"></a> #####

| Response field | Type | Description |
|---|---|---|
| name* | string | The CLI-friendly name of the parameter. MUST be unique within the action. All lowercase, no spaces. |
| displayName* | string | The display friendly name of the parameter that would be used for display in the UI and CLI |
| description* | string | A short description of the parameter. |
| value | string | An indication to the platform to provide a default value for the parameter. |
| options | array-of-strings | A array of values that can be provided as a list of choices to the user. |

\* Fields with an asterisk are REQUIRED.

<pre>
{
"name": "fake-backup-action",
"displayName": "Run periodic backup",
"id": "acb56222-XXXX-XXXX-XXXX-feb140a59a66",
"description": "Runs and enables periodic service instance backup",
"parameters": [{
"name": "fake-backup-int-param",
"displayName": "Backup Interval (days)",
"description": "Provide the interval at which the service instance data should be backed up",
"value": "1",
"options": ["1", "2", "3"]
}, {
"name": "fake-backup-retention-param",
"displayName": "Retention Period (days)",
"description": "Provide the retention period for the backed up data",
"value": "90"
}]
}
</pre>

## Action Execution
Platform invokes this endpoint to submit execution requests for the actions for a service instance. The requests are assynchronous by nature and the status can be queried by the platform.

##### Route #####
`POST /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id`

The `:action_id` of a action being executed.
The `:instance_id` of a service instance that has been provisioned previously.
The `:execution_id` of an execution is provided by the platform. This ID will be used for future requests (get status and cancel), so the broker will use it to correlate the action it performs.

##### Body #####
| Request field | Type | Description |
|---|---|---|
| action_id* | string | The ID of the action (from the action discovery). MUST be globally unique. |
| parameters | array-of-objects | An array of parameters required by the action. |

\* Fields with an asterisk are REQUIRED.

<pre class="terminal">
{
"action_id": "action-guid-here",
"parameters": [{
"name": "fake-backup-int-param",
"value": "1"
}, {
"name": "fake-backup-retention-param",
"value": "90"
}]
}
</pre>

##### cURL #####
<pre class="terminal">
$ curl http://username:password@broker-url//v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id -d '{
"action_id": "action-guid-here",
"parameters": [{
"name": "fake-backup-int-param",
"value": "1"
}, {
"name": "fake-backup-retention-param",
"value": "90"
}]
}' -X PUT -H "X-Broker-API-Version: 2.11" -H "Content-Type: application/json"
</pre>

## Get Action Execution status
Retrieve the status of an action execution.

##### Route #####
`GET /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id`

The `:action_id` of a action being executed.
The `:instance_id` of a service instance that has been provisioned previously.
The `:execution_id` of an execution is provided by the platform.

#### cURL ####
<pre class="terminal">
$ curl -H "X-Broker-API-Version: 2.11" http://username:password@broker-url/v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id
</pre>

### Response ###

| Status Code | Description |
|---|---|
| 200 OK | The expected response body is below. |

##### Body #####

| Response field | Type | Description |
|---|---|---|
| state* | string | Valid values are <code>in progress</code>, <code>succeeded</code>, <code>cancelled</code>, and <code>failed</code>.
| description* | string | Description or message about the status of the operation.
| detailedMessage | string | Detailed stdout/stderr from the action being performed.

\* Fields with an asterisk are REQUIRED.

<pre class="terminal">
{
"state": "in progress",
"description": "Restarting (10% complete).",
"detailedMessage": "space for detailed stdout/stderr"
}
</pre>

## Cancel Action Execution
Cancel the execution of an action.

##### Route #####
`PUT /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id`

The `:action_id` of a action being executed.
The `:instance_id` of a service instance that has been provisioned previously.
The `:execution_id` of an execution is provided by the platform. This ID will be used for future requests (get status and cancel), so the broker will use it to correlate the action it performs.

##### Body #####
| Request field | Type | Description |
|---|---|---|
| state* | string | The ID of the action (from the action discovery). MUST be globally unique. |
| parameters | array-of-objects | An array of parameters required by the action. |

\* Fields with an asterisk are REQUIRED.

<pre class="terminal">
{
"state": "cancelled"
}
</pre>

##### cURL #####
<pre class="terminal">
$ curl http://username:password@broker-url//v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id -d '{
"state": "cancelled"
}' -X PUT -H "X-Broker-API-Version: 2.11" -H "Content-Type: application/json"
</pre>

### Response ###

| Status Code | Description |
|---|---|
| 202 Accepted | Action execution cancellation is in progress and a get execution status would return a "cancelled" status.
| 409 Conflict | If the action execution cannot be cancelled.

## Broker Errors

### Response ###
Expand Down