docs/apidocs/cloud-api-source/source/includes/action.md

Actions

Action

Example

{
    "action": "Cluster Create",
    "end_date": "Wed, 17 Sep 2014 08:26:22 +0000",
    "ip": "56.78.90.12",
    "is_user_action": true,
    "can_be_canceled": false,
    "location": "New York, USA",
    "method": "POST",
    "object": "/api/infra/v1/cluster/eea638f4-b77a-4183-b241-22dbd7866f22/",
    "path": "/api/infra/v1/cluster/",
    "resource_uri": "/api/audit/v1/action/6246c558-976c-4df6-ba60-eb1a344a17af/",
    "start_date": "Wed, 17 Sep 2014 08:26:22 +0000",
    "state": "Success",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_4) AppleWebKit/537.78.2 (KHTML, like Gecko) Version/7.0.6 Safari/537.78.2",
    "uuid": "6246c558-976c-4df6-ba60-eb1a344a17af"
}

An action represents an API call by a user. Details of the API call such as timestamp, origin IP address, and user agent are logged in the action object.

Simple API calls that do not require asynchronous execution will return immediately with the appropiate HTTP error code and an action object will be created either in Success or Failed states. API calls that do require asynchronous execution will return HTTP code 202 Accepted immediately and create an action object in In progress state, which will change to Success or Failed state depending on the outcome of the operation being performed. In both cases the response will include a X-DockerCloud-Action-URI header with the resource URI of the created action.

Attributes

Attribute	Description
resource_uri	A unique API endpoint that represents the action
uuid	A unique identifier for the action generated automatically on creation
object	The API object (resource URI) to which the action applies to
action	Name of the operation performed/being performed
method	HTTP method used to access the API
path	HTTP path of the API accessed
user_agent	The user agent provided by the client when accessing the API endpoint
start_date	Date and time when the API call was performed and the operation started processing
end_date	Date and time when the API call finished processing
state	State of the operation (see table below)
ip	IP address of the user that performed the API call
location	Geographic location of the IP address of the user that performed the API call
is_user_action	If the action has been triggered by the user
can_be_canceled	If the action can be canceled by the user in the middle of its execution
can_be_retried	If the action can be retried by the user

Action states

State	Description
Pending	The action needed asynchronous execution and it is waiting for an in progress action
In progress	The action needed asynchronous execution and is being performed
Canceling	The action is being canceled by user request
Canceled	The action has been canceled
Success	The action was executed successfully
Failed	There was an issue when the action was being performed. Check the logs for more information.

List all actions

import dockercloud

actions = dockercloud.Action.list()

import "github.com/docker/go-dockercloud/dockercloud"

actionList, err := dockercloud.ListActions()

if err != nil {
  log.Println(err)
}

log.Println(actionList)

GET /api/audit/v1/action/ HTTP/1.1
Host: cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

docker-cloud action ls

Lists all actions in chronological order. Returns a list of Action objects.

Endpoint Type

Available in Docker Cloud's REST API

HTTP Request

GET /api/audit/v1/action/

Query Parameters

Parameter	Description
uuid	Filter by UUID.
state	Filter by state. Possible values: In progress, Success, Failed
start_date	Filter by start date. Valid filtering values are start_date__gte (after or on the date supplied) and start_date__lte (before or on the date supplied)
end_date	Filter by end date. Valid filtering values are end_date__gte (after or on the date supplied) and end_date__lte (before or on the date supplied)
object	Filter by resource URI of the related object. This filter can only be combined with 'include_related' filter
include_related	There is a parent-child relationship between Docker Cloud objects, described in table Relationships between Docker Cloud objects. If set to 'true', will include the actions of the related objects to the object specified in "object" filter parameter. Possible values: 'true' or 'false'

Relationships between Docker Cloud objects

Object	Relationships
Container	Container, service, stack (if any)
Service	All containers in the service, service, stack (if any)
Stack	All services in the stack, all containers in every service in the stack, stack
Node	Node, node cluster (if any)
Node cluster	All nodes in the cluster, node cluster

Get an action by UUID

import dockercloud

action = dockercloud.Action.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

import "github.com/docker/go-dockercloud/dockercloud"

action, err := dockercloud.GetAction("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
  log.Println(err)
}

log.Println(action)

GET /api/audit/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

docker-cloud action inspect 7eaf7fff

Get all the details of an specific action

Endpoint Type

Available in Docker Cloud's REST API

HTTP Request

GET /api/audit/v1/action/(uuid)/

Path Parameters

Parameter	Description
uuid	The UUID of the action to retrieve

Get the logs of an action

Example log line

{
    "type": "log",
    "log": "Log line from the action",
    "timestamp": 1433779324
}

import dockercloud

def log_handler(message):
    print message

action = dockercloud.Action.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
action.logs(tail=300, follow=True, log_handler=log_handler)

import "github.com/docker/go-dockercloud/dockercloud"

c := make(chan dockercloud.Logs)
action, err := dockercloud.GetAction("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
    log.Println(err)
}

go action.GetLogs(c)

for {
	log.Println(<-c)
}

GET /api/audit/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/logs/ HTTP/1.1
Host: ws.cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Connection: Upgrade
Upgrade: websocket

docker-cloud action logs 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce

Get the logs of the specified action.

Endpoint Type

Available in Docker Cloud's STREAM API

HTTP Request

GET /api/audit/v1/action/(uuid)/logs/

Path Parameters

Parameter	Description
uuid	The UUID of the action to retrieve logs

Query Parameters

Parameter	Description
tail	Number of lines to show from the end of the logs (default: 300)
follow	Whether to stream logs or close the connection immediately (default: true)

Cancel an action

POST /api/audit/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/cancel/ HTTP/1.1
Host: cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

import "github.com/docker/go-dockercloud/dockercloud"

action, err := dockercloud.GetAction("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
  log.Println(err)
}

action, err = action.Cancel()

if err != nil {
  log.Println(err)
}

log.Println(action)

Cancels an action in Pending or In progress state.

Endpoint Type

Available in Docker Cloud's REST API

HTTP Request

POST /api/audit/v1/action/(uuid)/cancel/

Path Parameters

Parameter	Description
uuid	The UUID of the action to cancel

Retry an action

import dockercloud

def log_handler(message):
  print message

action = dockercloud.Action.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
action.logs(tail=300, follow=True, log_handler=log_handler)

POST /api/audit/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/retry/ HTTP/1.1
Host: cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

import "github.com/docker/go-dockercloud/dockercloud"

action, err := dockercloud.GetAction("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
  log.Println(err)
}

action, err = action.Retry()

if err != nil {
  log.Println(err)
}

log.Println(action)

docker-cloud action logs 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce

Retries an action in Success, Failed or Canceled state.

Endpoint Type

Available in Docker Cloud's REST API

HTTP Request

POST /api/audit/v1/action/(uuid)/retry/

Path Parameters

Parameter	Description
uuid	The UUID of the action to retry