NAV
http go python shell

Introduction

Tutum currently offers a HTTP REST API and a Websocket Stream API which are used by both the Web UI and the CLI. In this document you will find all API operations currently supported in the platform and examples on how to execute them using our Python SDK and Go SDK.

Authentication

In order to be able to make requests to the Tutum API, you should first obtain an ApiKey for your account. For this, log into Tutum, click on the menu on the upper right corner of the screen, select Account info and then select API keys.

REST API

import tutum
tutum.user = "username"
tutum.apikey = "apikey"
import "github.com/tutumcloud/go-tutum/tutum"

tutum.User = "username"
tutum.ApiKey = "apikey"
GET /api/v1/service/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
export TUTUM_USER=username
export TUTUM_APIKEY=apikey

Make sure to replace username with your username and apikey with your API key.

The Tutum REST API is reachable through the following hostname:

https://dashboard.tutum.co/

All requests should be sent to this endpoint using Basic authentication using your API key as password:

Authorization: Basic dXNlcm5hbWU6YXBpa2V5

HTTP responses are given in JSON format, so the following Accept header is required for every API call:

Accept: application/json

Stream API

import websocket
import base64

header = "Authorization: Basic %s" % base64.b64encode("%s:%s" % (username, password))
ws = websocket.WebSocketApp('wss://stream.tutum.co/v1/events', header=[header])
import "github.com/gorilla/websocket"
import "encoding/base64"

var StreamUrl = "wss://stream.tutum.co:443/v1/events"

sEnc := base64.StdEncoding.EncodeToString([]byte(User + ":" + ApiKey))
header := http.Header{}
header.Add("Authorization", fmt.Sprintf("Basic %s", sEnc))

var Dialer websocket.Dialer
ws, _, err := Dialer.Dial(url, header)
if err != nil {
    log.Println(err)
}
GET /v1/events HTTP/1.1
Host: stream.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Connection: Upgrade
Upgrade: websocket
export TUTUM_USER=username
export TUTUM_APIKEY=apikey

Make sure to replace username with your username and apikey with your API key.

The Tutum Stream API is reachable through the following hostname:

wss://stream.tutum.co/

The Stream API requires the same authentication mechanism as the REST API:

Authorization: Basic dXNlcm5hbWU6YXBpa2V5

API roles

The CLI and the SDKs will detect this environment variable and automatically use it

If you give an API role to a container, the environment variable TUTUM_AUTH inside the container will have the contents of the Authorization header that you can use to authenticate against the REST or Stream APIs:

curl -H "Authorization: $TUTUM_AUTH" https://dashboard.tutum.co/api/v1/service/

Actions

Action

Example

{
    "action": "Cluster Create",
    "body": "{\"image_tag\": \"/api/v1/image/tutum/ubuntu-quantal/tag/latest/\", \"name\": \"test_cluster\"}",
    "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/v1/cluster/eea638f4-b77a-4183-b241-22dbd7866f22/",
    "path": "/api/v1/cluster/",
    "resource_uri": "/api/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-Tutum-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
body Data of 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 tutum

actions = tutum.Action.list()
import "github.com/tutumcloud/go-tutum/tutum"

actionList, err := tutum.ListActions()

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

log.Println(actionList)
GET /api/v1/action/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum action list

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

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/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 Tutum objects, described in table Relationships between Tutum 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 Tutum 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 tutum

action = tutum.Action.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
import "github.com/tutumcloud/go-tutum/tutum"

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

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

log.Println(action)
GET /api/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum action inspect 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce

Get all the details of an specific action

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/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 tutum

def log_handler(message):
    print message

action = tutum.Action.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
action.logs(tail=300, follow=True, log_handler=log_handler)
import "github.com/tutumcloud/go-tutum/tutum"

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

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

go action.GetLogs(c)

for {
    log.Println(<-c)
}
GET /v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/logs/ HTTP/1.1
Host: stream.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Connection: Upgrade
Upgrade: websocket
tutum action logs 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce

Get the logs of the specified action.

Endpoint Type

Available in Tutum’s STREAM API

HTTP Request

GET /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/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/cancel/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

action, err := tutum.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 Tutum’s REST API

HTTP Request

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

Path Parameters

Parameter Description
uuid The UUID of the action to cancel

Retry an action

POST /api/v1/action/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/retry/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

action, err := tutum.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)

Retries an action in Success, Failed or Canceled state.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

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

Path Parameters

Parameter Description
uuid The UUID of the action to retry

Providers

Provider

Example

{
    "available": true,
    "label": "Digital Ocean",
    "name": "digitalocean",
    "regions": [
        "/api/v1/region/digitalocean/ams1/",
        "/api/v1/region/digitalocean/ams2/",
        "/api/v1/region/digitalocean/ams3/",
        "/api/v1/region/digitalocean/lon1/",
        "/api/v1/region/digitalocean/nyc1/",
        "/api/v1/region/digitalocean/nyc2/",
        "/api/v1/region/digitalocean/nyc3/",
        "/api/v1/region/digitalocean/sfo1/",
        "/api/v1/region/digitalocean/sgp1/"
    ],
    "resource_uri": "/api/v1/provider/digitalocean/"
}

A provider is a representation of a cloud provider supported by Tutum. Providers have one or more regions where nodes are deployed.

Attributes

Attribute Description
resource_uri A unique API endpoint that represents the provider
name A unique identifier for the provider
label A user-friendly name for the provider
regions A list of resource URIs of the regions available in this provider
available Whether the provider is currently available for new node deployments

List all providers

import tutum

providers = tutum.Provider.list()
GET /api/v1/provider/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

providerList, err := tutum.ListProviders()

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

log.Println(providerList)
tutum nodecluster provider

Lists all supported cloud providers. Returns a list of Provider objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/provider/

Query Parameters

Parameter Description
name Filter by provider name

Get an individual provider

import tutum

provider = tutum.Provider.fetch("digitalocean")
import "github.com/tutumcloud/go-tutum/tutum"

provider, err := tutum.GetProvider("digitalocean")

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

log.Println(provider)
GET /api/v1/provider/digitalocean/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Get all the details of a specific provider

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/provider/(name)/

Path Parameters

Parameter Description
name The name of the provider to retrieve

Regions

Region

Example

{
    "availability_zones": [],
    "available": true,
    "label": "Amsterdam 2",
    "name": "ams2",
    "node_types": [
        "/api/v1/nodetype/digitalocean/1gb/",
        "/api/v1/nodetype/digitalocean/2gb/",
        "/api/v1/nodetype/digitalocean/4gb/",
        "/api/v1/nodetype/digitalocean/8gb/",
        "/api/v1/nodetype/digitalocean/16gb/",
        "/api/v1/nodetype/digitalocean/32gb/",
        "/api/v1/nodetype/digitalocean/48gb/",
        "/api/v1/nodetype/digitalocean/64gb/"
    ],
    "provider": "/api/v1/provider/digitalocean/",
    "resource_uri": "/api/v1/region/digitalocean/ams2/"
}

A region is a representation of an entire or a subset of a data center of a cloud provider. It can contain availability zones (depending on the provider) and one or more node types.

Attributes

Attribute Description
resource_uri A unique API endpoint that represents the region
name An identifier for the region
label A user-friendly name for the region
node_types A list of resource URIs of the node types available in the region
availability_zones A list of resource URIs of the availability zones available in the region
provider The resource URI of the provider of the region
available Whether the region is currently available for new node deployments

List all regions

import tutum

regions = tutum.Region.list()
GET /api/v1/region/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

regionList, err := tutum.ListRegions()

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

log.Println(regionList)
tutum nodecluster region

Lists all regions of all supported cloud providers. Returns a list of Region objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/region/

Query Parameters

Parameter Description
name Filter by region name
provider Filter by resource URI of the target provider

Get an individual region

import tutum

region = tutum.Region.fetch("digitalocean/lon1")
import "github.com/tutumcloud/go-tutum/tutum"

region, err := tutum.GetRegion("digitalocean","lon1")

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

log.Println(region)
GET /api/v1/region/digitalocean/lon1/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Get all the details of a specific region

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/region/(provider.name)/(name)/

Path Parameters

Parameter Description
name The name of the region to retrieve
provider.name The name of the provider of the region

Availability Zones

Availability Zone

Example

{
    "available": true,
    "name": "ap-northeast-1a",
    "region": "/api/v1/region/az/ap-northeast-1/",
    "resource_uri": "/api/v1/az/aws/ap-northeast-1/ap-northeast-1a/"
}

An Availability Zone is an isolated location inside a region. Providers that support availability zones: AWS

Attributes

Attribute Description
available Whether the availability zone is currently available for new node deployments
name An identifier for the availability zone
region The resource URI of the region where the availability zone is allocated
resource_uri A unique API endpoint that represents the region

List all availability zones

import tutum

az = tutum.AZ.list()
GET /api/v1/az/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

az, err := tutum.ListAZ()
if err != nil {
    log.Println(err)
}

log.Println(az)
tutum nodecluster az

Lists all availability zones from all regions of all supported cloud providers. Returns a list of Availability Zone objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/az/

Query Parameters

Parameter Description
name Filter by availability zone name
region Filter by resource URI of the target region

Get an individual availability zone

import tutum

az = tutum.AZ.fetch("aws/sa-east-1/sa-east-1a")
import "github.com/tutumcloud/go-tutum/tutum"

az, err := tutum.GetAZ("aws/sa-east-1/sa-east-1a")
if err != nil {
    log.Println(err)
}

log.Println(az)
GET /api/v1/az/aws/sa-east-1/sa-east-1a/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Get all the details of a specific availability zone

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/az/(provider.name)/(region.name)/(name)/

Path Parameters

Parameter Description
name The name of the availability zone to retrieve
provider The name of the provider
region The name of the region

Node Types

Node Type

Example

{
    "availability_zones": [],
    "available": true,
    "label": "1GB",
    "name": "1gb",
    "provider": "/api/v1/provider/digitalocean/",
    "regions": [
        "/api/v1/region/digitalocean/ams1/",
        "/api/v1/region/digitalocean/sfo1/",
        "/api/v1/region/digitalocean/nyc2/",
        "/api/v1/region/digitalocean/ams2/",
        "/api/v1/region/digitalocean/sgp1/",
        "/api/v1/region/digitalocean/lon1/",
        "/api/v1/region/digitalocean/nyc3/",
        "/api/v1/region/digitalocean/nyc1/"
    ],
    "resource_uri": "/api/v1/nodetype/digitalocean/1gb/"
}

A node type is a representation of an instance size supported by a certain cloud provider in a certain region and/or availability zone.

Attributes

Attribute Description
resource_uri A unique API endpoint that represents the node type
name An identifier for the node type
label A user-friendly name for the node type
regions A list of resource URIs of the regions to which this node type can be deployed to
availability_zones A list of resource URIs of the availability zones to which this node type can be deployed to
provider The resource URI of the provider of the node type
available Whether the node type is currently available for new node deployments

List all node types

import tutum

nodetypes = tutum.NodeType.list()
import "github.com/tutumcloud/go-tutum/tutum"

nodetypeList, err := tutum.ListNodeTypes()

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

log.Println(nodetypeList)
GET /api/v1/nodetype/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum nodecluster nodetype

Lists all node types of all supported cloud providers. Returns a list of NodeType objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/nodetype/

Query Parameters

Parameter Description
name Filter by node type name
regions Filter by resource URI of the target regions
availability_zones Filter by resource URI of the target availability zones

Get an individual node type

import tutum

nodetype = tutum.NodeType.fetch("digitalocean/1gb")
import "github.com/tutumcloud/go-tutum/tutum"

nodetype, err := tutum.GetNodeType("digitalocean","1gb")

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

log.Println(nodetype)
GET /api/v1/nodetype/digitalocean/1gb/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Get all the details of a specific node type

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/nodetype/(provider.name)/(name)/

Path Parameters

Parameter Description
name The name of the node type to retrieve
provider.name The name of the provider of the node type

Node Clusters

Node Cluster

Example

{
    "current_num_nodes": 1,
    "deployed_datetime": "Tue, 16 Sep 2014 17:01:15 +0000",
    "destroyed_datetime": null,
    "disk": 60,
    "nickname": "my test cluster",
    "name": "TestCluster",
    "node_type": "/api/v1/nodetype/aws/t2.micro/",
    "nodes": [
        "/api/v1/node/75d20367-0948-4f10-8ba4-ffb4d16ed3c6/"
    ],
    "region": "/api/v1/region/aws/us-east-1/",
    "resource_uri": "/api/v1/nodecluster/5516df0b-721e-4470-b350-741ff22e63a0/",
    "state": "Deployed",
    "tags": [
        {"name": "tag_one"},
        {"name": "tag-two"},
        {"name": "tagthree3"}
    ],
    "target_num_nodes": 2,
    "uuid": "5516df0b-721e-4470-b350-741ff22e63a0",
    "provider_options": {
        "vpc": {
            "id": "vpc-aa1c70d4",
            "subnets": ["subnet-aaa7d94f", "subnet-aa15fa64"],
            "security_groups": ["sg-aa1c70d4"]
        },
        "iam": {
            "instance_profile_name": "my_instance_profile"
        }
    }
}

A node cluster is a group of nodes that share the same provider, region and/or availability zone, and node type. They are on the same private network.

Attributes

Attribute Description
uuid A unique identifier for the node cluster generated automatically on creation
resource_uri A unique API endpoint that represents the node cluster
name A user provided name for the node cluster
state The state of the node cluster. See the below table for a list of possible states.
node_type The resource URI of the node type used for the node cluster
disk The size of the disk where images and containers are stored (in GB)
nodes A list of resource URIs of the Node objects on the node cluster
region The resource URI of the Region object where the node cluster is deployed
target_num_nodes The desired number of nodes for the node cluster
current_num_nodes The actual number of nodes in the node cluster. This may differ from target_num_nodes if the node cluster is being deployed or scaled
deployed_datetime The date and time when this node cluster was deployed
destroyed_datetime The date and time when this node cluster was terminated (if applicable)
tags List of tags to identify the node cluster nodes when deploying services (see Tags for more information)
provider_options Provider-specific extra options for the deployment of the node (see Provider options table below for more information)
nickname A user-friendly name for the node cluster (name by default)

Node Cluster states

State Description
Init The node cluster has been created and has no deployed containers yet. Possible actions in this state: deploy, terminate.
Deploying All nodes in the cluster are either deployed or being deployed. No actions allowed in this state.
Deployed All nodes in the cluster are deployed and provisioned. Possible actions in this state: terminate.
Partly deployed One or more nodes of the cluster are deployed and running. Possible actions in this state: terminate.
Scaling The cluster is either deploying new nodes or terminating existing ones responding to a scaling request. No actions allowed in this state.
Terminating All nodes in the cluster are either being terminated or already terminated. No actions allowed in this state.
Terminated The node cluster and all its nodes have been terminated. No actions allowed in this state.
Empty cluster There are no nodes deployed in this cluster. Possible actions in this state: terminate.

Provider options

You can specify the following options when using the Amazon Web Services provider:

List all node clusters

import tutum

nodeclusters = tutum.NodeCluster.list()
import "github.com/tutumcloud/go-tutum/tutum"

nodeclusters, err := tutum.ListNodeClusters()

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

log.Println(nodeclusters)
GET /api/v1/nodecluster/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum nodecluster list

Lists all current and recently terminated node clusters. Returns a list of NodeCluster objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/nodecluster/

Query Parameters

Parameter Description
uuid Filter by UUID
state Filter by state. Possible values: Init, Deploying, Deployed, Partly deployed, Scaling, Terminating, Terminated, Empty cluster
name Filter by node cluster name
region Filter by resource URI of the target region
node_type Filter by resource URI of the target node type

Create a new node cluster

import tutum

region = tutum.Region.fetch("digitalocean/lon1")
node_type = tutum.NodeType.fetch("digitalocean/1gb")
nodecluster = tutum.NodeCluster.create(name="my_cluster", node_type=node_type, region=region, disk=60)
nodecluster.save()
import "github.com/tutumcloud/go-tutum/tutum"

nodecluster, err := tutum.CreateNodeCluster(tutum.NodeCreateRequest{Name: "my_cluster", Region: "/api/v1/region/digitalocean/lon1/", NodeType: "/api/v1/nodetype/digitalocean/1gb/", Target_num_nodes: 2})

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

log.Println(nodecluster)
POST /api/v1/nodecluster/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

{"name": "my_cluster", "region": "/api/v1/region/digitalocean/lon1/", "node_type": "/api/v1/nodetype/digitalocean/1gb/", "disk": 60}
tutum nodecluster create my_cluster digitalocean lon1 1gb

Creates a new node cluster without deploying it.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/nodecluster/

JSON Parameters

Parameter Description
name (required) A user provided name for the node cluster
node_type (required) The resource URI of the node type to be used for the node cluster
region (required) The resource URI of the region where the node cluster is to be deployed
disk (optional) The size of the volume to create where images and containers will be stored, in GB (default: 60). Not available for Digital Ocean. To create Softlayer nodes you must select one of the following sizes (in GBs): 10, 20, 25, 30, 40, 50, 75, 100, 125, 150, 175, 200, 250, 300, 350, 400, 500, 750, 1000, 1500 or 2000
nickname (optional) A user-friendly name for the node cluster (name by default)
target_num_nodes (optional) The desired number of nodes for the node cluster (default: 1)
tags (optional) List of tags of the node cluster to be used when deploying services see Tags for more information) (default: [])
provider_options Provider-specific extra options for the deployment of the node (see table Provider options above for more information)

Get an existing node cluster

import tutum

service = tutum.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
import "github.com/tutumcloud/go-tutum/tutum"

nodecluster, err := tutum.GetNodeCluster("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

log.Println(nodecluster)
GET /api/v1/nodecluster/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum nodecluster inspect 7eaf7fff

Get all the details of an specific node cluster

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/nodecluster/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the node cluster to retrieve

Deploy a node cluster

import tutum

nodecluster = tutum.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
nodecluster.deploy()
import "github.com/tutumcloud/go-tutum/tutum"

nodecluster, err := tutum.GetNodeCluster("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = nodecluster.Deploy(); err != nil {
   log.Println(err)
}
POST /api/v1/nodecluster/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/deploy/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Deploys and provisions a recently created node cluster in the specified region and cloud provider.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/nodecluster/(uuid)/deploy/

Path Parameters

Parameter Description
uuid The UUID of the node cluster to deploy

Update an existing node cluster

import tutum

nodecluster = tutum.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
nodecluster.target_num_nodes = 3
nodecluster.tags.add("tag-1")
nodecluster.save()
import "github.com/tutumcloud/go-tutum/tutum"

nodecluster, err := tutum.GetNodeCluster("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = nodecluster.Update(tutum.NodeCreateRequest{Target_num_nodes: 4}); err != nil {
   log.Println(err)
}
PATCH /api/v1/nodecluster/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

{"target_num_nodes": 3, "tags": [{"name": "tag-1"}]}
tutum nodecluster scale 7eaf7fff 3
tutum tag add -t tag-1 7eaf7fff
tutum tag set -t tag-2 7eaf7fff

Updates the node cluster details and applies the changes automatically.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

PATCH /api/v1/nodecluster/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the node cluster to update

JSON Parameters

Parameter Description
target_num_nodes (optional) The number of nodes to scale this node cluster to
tags (optional) List of tags the node cluster (and nodes within the node cluster) will have. This operation replaces the user tag list.

Terminate a node cluster

import tutum

nodecluster = tutum.NodeCluster.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
nodecluster.delete()
import "github.com/tutumcloud/go-tutum/tutum"

nodecluster, err := tutum.GetNodeCluster("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = nodecluster.Terminate(); err != nil {
   log.Println(err)
}
DELETE /api/v1/nodecluster/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum nodecluster rm 7eaf7fff

Terminates all the nodes in a node cluster and the node cluster itself. This is not reversible.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

DELETE /api/v1/nodecluster/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the node cluster to terminate

Nodes

Node

Example

{
    "availability_zone": "/api/v1/az/testing-provider/testing-region/testing-az/",
    "cpu": 1,
    "current_num_containers": 4,
    "deployed_datetime": "Tue, 16 Sep 2014 17:01:15 +0000",
    "destroyed_datetime": null,
    "disk": 60,
    "docker_execdriver": "native-0.2",
    "docker_graphdriver": "aufs",
    "docker_version": "1.5.0",
    "external_fqdn": "fc1a5bb9-user.node.tutum.io",
    "last_seen": "Thu, 25 Sep 2014 13:14:44 +0000",
    "memory": 1792,
    "nickname": "fc1a5bb9-user.node.tutum.io",
    "last_metric": {
        "cpu": 1.3278507035616,
        "disk": 462479360,
        "memory": 763170816
    },
    "node_cluster": "/api/v1/nodecluster/d787a4b7-d525-4061-97a0-f423e8f1d229/",
    "node_type": "/api/v1/nodetype/testing-provider/testing-type/",
    "public_ip": "10.45.2.11",
    "region": "/api/v1/region/testing-provider/testing-region/",
    "resource_uri": "/api/v1/node/fc1a5bb9-17f5-4819-b667-8c7cd819e949/",
    "state": "Deployed",
    "tags": [
        {"name": "tag_one"},
        {"name": "tag-two"}
    ],
    "tunnel": "https://tunnel01.tutum.co:12345",
    "uuid": "fc1a5bb9-17f5-4819-b667-8c7cd819e949"
}

A node is a virtual machine provided by a cloud provider where containers can be deployed.

Attributes

Attribute Description
availability_zone The resource URI of the availability zone where the node is deployed, if any
uuid A unique identifier for the node generated automatically on creation
resource_uri A unique API endpoint that represents the node
external_fqdn An automatically generated FQDN for the node. Containers deployed on this node will inherit this FQDN.
state The state of the node. See the below table for a list of possible states.
node_cluster The resource URI of the node cluster to which this node belongs to (if applicable)
node_type The resource URI of the node type used for the node
region The resource URI of the region where the node is deployed
docker_execdriver Docker’s execution driver used in the node
docker_graphdriver Docker’s storage driver used in the node
docker_version Docker’s version used in the node
cpu Node number of CPUs
disk Node storage size in GB
memory Node memory in MB
last_metric Last reported metric from the node (see table Node Last Metric attributes below for more information)
current_num_containers The actual number of containers deployed in this node
last_seen Date and time of the last time the node was contacted by Tutum
public_ip The public IP allocated to the node
tunnel If the node does not accept incoming connections to port 2375, the address of the reverse tunnel to access the docker daemon, or null otherwise
deployed_datetime The date and time when this node cluster was deployed
destroyed_datetime The date and time when this node cluster was terminated (if applicable)
tags List of tags to identify the node when deploying services (see Tags for more information)
nickname A user-friendly name for the node (external_fqdn by default)

Node states

State Description
Deploying The node is being deployed in the cloud provider. No actions allowed in this state.
Deployed The node is deployed and provisioned and is ready to deploy containers. Possible actions in this state: terminate, docker-upgrade.
Unreachable The node is deployed but Tutum cannot connect to the docker daemon. Possible actions in this state: health-check and terminate.
Upgrading The node docker daemon is being upgraded. No actions allowed in this state.
Terminating The node is being terminated in the cloud provider. No actions allowed in this state.
Terminated The node has been terminated and is no longer present in the cloud provider. No actions allowed in this state.

Node Last Metric attributes

Attribute Description
cpu CPU percentage usage
memory Memory usage in bytes
disk Disk storage usage in bytes

List all nodes

import tutum

nodes = tutum.Node.list()
import "github.com/tutumcloud/go-tutum/tutum"

nodeList, err := tutum.ListNodes()

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

log.Println(nodeList)
GET /api/v1/node/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum node list

Lists all current and recently terminated nodes. Returns a list of Node objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/node/

Query Parameters

Parameter Description
uuid Filter by UUID
state Filter by state. Possible values: Deploying, Deployed, Unreachable, Upgrading, Terminating, Terminated
node_cluster Filter by resource URI of the target node cluster
node_type Filter by resource URI of the target node type
region Filter by resource URI of the target region
docker_version Filter by Docker engine version running in the nodes

Get an existing node

import tutum

node = tutum.Node.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
import "github.com/tutumcloud/go-tutum/tutum"

node, err := tutum.GetNode("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

log.Println(node)
GET /api/v1/node/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum node inspect 7eaf7fff

Get all the details of an specific node

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/node/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the node to retrieve

Update a node

import tutum

node = tutum.Node.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
node.tags.add(["tag-1"])
node.save()
import "github.com/tutumcloud/go-tutum/tutum"

node, err := tutum.GetNode("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = node.Update(tutum.Node{Tags: []string{{Name: "tag-1"}}}); err != nil {
            log.Println(err)
}
PATCH /api/v1/node/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

{"tags": [{"name": "tag-1"}], "nickname": "dev node"}
tutum tag add -t tag-1 7eaf7fff
tutum tag set -t tag-2 7eaf7fff

Names the node with a user-friendly name and/or replaces the old tags for the new list provided.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

PATCH /api/v1/node/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the node to retrieve

JSON Parameters

Parameter Description
nickname (optional) A user-friendly name for the node (external_fqdn by default)
tags (optional) List of tags the node will have. This operation replaces the user tag list.

Upgrade Docker Daemon

import tutum

node = tutum.Node.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
node.upgrade_docker()
import "github.com/tutumcloud/go-tutum/tutum"

node, err := tutum.GetNode("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = node.Upgrade(); err != nil {
       log.Println(err)
   }
POST /api/v1/node/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/docker-upgrade/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum node upgrade 7eaf7fff

Upgrades the docker daemon of the node. This will restart your containers on that node. See Docker upgrade for more information.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/node/(uuid)/docker-upgrade/

Path Parameters

Parameter Description
uuid The UUID of the node to upgrade

Perform a health check of a node

POST /api/v1/node/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/health-check/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Tests connectivity between Tutum and the node. Updates the node status to Deployed if the check was successful, or to Unreachable otherwise.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/node/(uuid)/health-check/

Path Parameters

Parameter Description
uuid The UUID of the node to perform the health check to

Terminate a node

import tutum

node = tutum.Node.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
node.delete()
DELETE /api/v1/node/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

node, err := tutum.GetNode("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = node.Terminate(); err != nil {
   log.Println(err)
}
tutum node rm 7eaf7fff

Terminates the specified node.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

DELETE /api/v1/node/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the node to terminate

Tokens

Token

Example

{
    "token": "21268a001bcf40acb5c0884679d4fd1f"
}

A token allows authentication for agents running in Nodes

Attributes

Attribute Description
token Value of the token

Create a new token

import "github.com/tutumcloud/go-tutum/tutum"

token, err := tutum.CreateToken()

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

log.Println(token)
POST /api/v1/token/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

Creates a new token.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/token/

Registries

Registry

Example

{
  "host": "registry.local",
  "icon_url": "",
  "is_ssl": true,
  "is_tutum_registry": true,
  "name": "Tutum TEST",
  "resource_uri": "/api/v1/registry/registry.local/",
}

A registry where image repositories are hosted

Attributes

Attribute Description
resource_uri A unique API endpoint that represents the registry
name Human-readable name of the registry
host FQDN of the registry, i.e. ‘tutum.co’
icon_url URL of the registry icon
is_tutum_registry Whether this registry is run by Tutum
is_ssl Whether this registry has SSL activated or not

List all registries

GET /api/v1/registry/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Lists all current registries. Returns a list of Registry objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/registry/

Query Parameters

Parameter Description
uuid Filter by UUID.
name Filter by registry name
host Filter by registry host.
is_tutum_registry Filter by whether the registry is a Tutum registry or not. Possible values: ‘true’ or ‘false’

Get an existing registry

GET /api/v1/registry/registry.local/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Gets all the details of an specific registry

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/registry/(host)/

Path Parameters

Parameter Description
host The host of the registry to retrieve

Images

Image

Example

{
  "build_source": {
    "autotests": "OFF",
    "build_settings": [
      "/api/v1/image/registry.local/user1/image1/buildsetting/latest/",
      "/api/v1/image/registry.local/user1/image1/buildsetting/staging/"
    ],
    "owner": "tutumcloud",
    "repository": "test-private-repo",
    "type": "GITHUB",
    "envvars": [
        {
            "key": "test_envvar",
            "value": "test_value"
        },
        {
            "key": "test_envvar2",
            "value": "test_value"
        }
    ]
  },
  "categories": [
    {
      "name": "test"
    }
  ],
  "description": "Test image",
  "registry": "/api/v1/registry/registry.local/",
  "icon_url": "/_static/assets/images/dockerimages/docker-64.png",
  "in_use": false,
  "is_private_image": true,
  "last_build_date": "Fri, 8 Nov 2013 00:22:26 +0000",
  "name": "registry.local/user1/image1",
  "public_url": "",
  "resource_uri": "/api/v1/image/registry.local/user1/image1/",
  "star_count": 0,
  "state": "SUCCESS",
  "jumpstart": false,
  "tags": [
    "/api/v1/image/registry.local/user1/image1/tag/latest/",
    "/api/v1/image/registry.local/user1/image1/tag/staging/"
  ]
}

An image is a repository from a registry. Public DockerHub images are created when inspected. Private images must be added to Tutum before using them. For Tutum private registry images, they are also automatically added when pushing the image to the Tutum private registry.

Attributes

Attribute Description
resource_uri A unique API endpoint that represents the image
name Name of the image with docker format, i.e. ‘ubuntu’ or ‘tutum/hello-world’
description Description of the image
icon_url URL of the image icon
state The state of the image (see table Image states below)
star_count How many people starred the image
jumpstart Whether the image is a jumpstart or not
in_use If the image is being used by any of your services
categories List of categories associated with this image (see table Image Category attributes below)
is_private_image Whether this image is hosted in a private registry or not
public_url URL of the detailed information page in the public docker index
registry Resource URI of the registry where this image is hosted
last_build_data Date of the last successfully build on any of the image tags
build_source The build source for this image (see table Image Build Source attributes below)
tags List of resource URIs of the tags associated with this docker image

Image States

State Description
Empty The image has no built tags available yet.
Success All image tags are successfully built.
Building Any of the images tags is being built.
Failed There is at least an image tag whose last build failed.

Image Category attributes

Attribute Description
name Name of the category

Image Build Source attributes

Attribute Description
type Type of the build source
repository The repository where images are built from
owner The owner of the repository
autotests Whether to execute tests for new commits or external pull requests (see table Image Build Source Autotests values below)
build_settings List of resource URIs of the build settings associated with this docker image
envvars List of user-defined environment variables to be used for Docker repository builds and tests

Image Build Source Autotests values

Value Description
OFF Ignore tests for repository commits or external pull requests.
SOURCE_ONLY Execute tests for commits in this source repository.
SOURCE_AND_FORKS Execute tests for commits in this repository and for external pull requests.

List all images

import tutum

images = tutum.Image.list()
GET /api/v1/image/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

imagesList, err := tutum.ListImages()

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

log.Pringln(imagesList)
tutum image list

Lists all current images. Returns a list of Image objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/image/

Query Parameters

Parameter Description
name Filter by image name
jumpstart Filter by whether the image is a jumpstart or not
is_private_image Filter by whether the image is private or not
is_user_image Filter by whether the image has been added as user repository or not
registry Filter by resource URI of the target image registry
categories Filter by the name of the image category, HTML quoted. Example: /api/v1/image/?categories__name=Database%20Servers

Creates a new image.

import tutum

image = tutum.Image.create(name=repository, username=username, password=password, description=description)
image.save()
POST /api/v1/image/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

{"name": "registry.local/user1/image1"}
import "github.com/tutumcloud/go-tutum/tutum"

image, err := tutum.CreateImage(tutum.ImageCreateRequest{
    BuildSource: tutum.BuildSource{
        Build_Settings: []tutum.BuildSettings{{
            Branch:     "master",
            Dockerfile: "/",
            Tag:        "latest",
        },{
            Branch:     "staging",
            Dockerfile: "/",
            Tag:        "staging"
        }},
        Owner:      "user1",
        Repository: "repository1",
    },
    Name:        "registry.local/user1/image1",
    Description: "Image1",
})

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

log.Println(image)
tutum image register -u username -p password registry.local/user1/image1

Creates a new private image.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/image/

JSON Parameters

Parameter Description
name Name of the image with docker format, i.e. ‘ubuntu’ or ‘tutum/hello-world’
username (optional) Username to authenticate with the private registry (not needed for Tutum private registry)
password (optional) Password to authenticate with the private registry (not needed for Tutum private registry)
description (optional) Description of the image
build_source The build source for this image (see table Related Build Source attributes below)
Attribute Description
type (optional) Type of the build source (currently only GITHUB is supported)
repository The repository where images are built from
owner (optional) The owner of the repository (default: the owner of the linked Github account)
autotests (optional) Whether to execute tests for new commits (default: OFF)
build_settings List of associations between image tags and repository branches to do builds (see table Related Build Setting attributes below)
envvars (optional) List of user-defined environment variables to be used for Docker repository builds and tests
Attribute Description
tag The name of the tag to be built
branch The Github repository branch where the image is build from
dockerfile The path of the Dockerfile file in the branch
autobuild (optional) Whether to build the image tag on new commits on this branch (default: false)

Get an existing image

import tutum

image = tutum.Image.fetch("registry.local/user1/image1")
GET /api/v1/image/registry.local/user1/image1/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

image, err = tutum.GetImage("registry.local/user1/image1")

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

log.Println(image)
tutum image inspect registry.local/user1/image1

Gets all the details of an specific image

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/image/(name)/

Path Parameters

Parameter Description
name The name of the image to retrieve

Update an existing image

import tutum

image = tutum.Image.fetch("registry.local/user1/image1")
image.description = "New image description"
image.save()
PATCH /api/v1/image/registry.local/user1/image1/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

{"description": "New image description"}
tutum image update -d "New image description" registry.local/user1/image1

Updates the image details.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

PATCH /api/v1/image/(name)/

Path Parameters

Parameter Description
name The name of the image to update

JSON Parameters

Parameter Description
username (optional) Username to authenticate with the private registry (not needed for Tutum private registry)
password (optional) Password to authenticate with the private registry (not needed for Tutum private registry)
description Description of the image
build_source The build source for this image (see table Image Build Source attributes)

Delete an image

import tutum

image = tutum.Image.fetch("registry.local/user1/image1")
image.delete()
DELETE /api/v1/image/registry.local/user1/image1/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

image, err = tutum.GetImage("registry.local/user1/image1")

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

image.Remove()
tutum image rm registry.local/user1/image1

Deletes the image from Tutum.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

DELETE /api/v1/image/registry.local/user1/image1/

Path Parameters

Parameter Description
name The name of the image to delete

Image Tags

Image Tag

Example

{
  "full_name": "registry.local/user1/image1:latest",
  "layer": {
    "author": "Fernando Mayo <fernando@tutum.co>",
    "creation": "Fri, 8 Nov 2013 00:22:26 +0000",
    "docker_id": "bca93ea41953afd3e0bea21625636526d6ac743297886a3520069544a00e3a70",
    "entrypoint": "",
    "envvars": [
      {
        "key": "HOME",
        "value": "/"
      },
      {
        "key": "PATH",
        "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
      }
    ],
    "labels": [
      {
        "key": "Tutum",
        "value" "Pure awesomeness"
      }
    ],
    "ports": [
      {
        "port": 80,
        "protocol": "'tcp"
      }
    ],
    "resource_uri": "/api/v1/layer/bca93ea41953afd3e0bea21625636526d6ac743297886a3520069544a00e3a70/",
    "run_command": "/run.sh",
    "volumes": [
      {
        "container_path": "/app"
      }
    ]
  },
  "image": "/api/v1/image/registry.local/user1/image1/",
  "name": "latest",
  "resource_uri": "/api/v1/image/registry.local/user1/image1/tag/latest/"
}

An image tag from a registry.

Attributes

Attribute Description
resource_uri A unique API endpoint that represents the image tag
name Name of the tag
full_name Full name of the image tag with docker format, i.e. ‘ubuntu:latest’ or ‘tutum/hello-world:staging’
layer Specification of the current layer associated to this image tag (see table Image Tag Layer attributes below)

Image Tag Layer attributes

Attribute Description
author The author of this image layer
creation The date and time of this image layer creation
docker_id The docker id of this image layer
entrypoint Entrypoint used on launch for containers using this image layer
run_command Run command used on launch for containers using this image layer
envvars List of image-defined environment variables (see table Image Tag Layer Environment Variable attributes below)
labels List of image-defined labels (see table Image Tag Layer Label attributes below)
ports List of image-defined ports (see table Image Tag Layer Port attributes below)
volumes List of image-defined volumes (see table Image Tag Layer Volume attributes below)

Image Tag Layer Environment Variable

Attribute Description
key The name of the environment variable
value The value of the environment variable

Image Tag Layer Label Variable

Attribute Description
key The name of the label
value The value of the label

Image Tag Layer Port attributes

Attribute Description
protocol The protocol of the port, either tcp or udp
port The port number inside the container

Image Tag Layer Volume attributes

Attribute Description
container_path The container path where the volume is mounted

Get an existing image tag

import tutum

image_tag = tutum.ImageTag.fetch("registry.local/user1/image1", "latest")
GET /api/v1/image/registry.local/user1/image1/tag/latest/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

imageTag, err := tutum.GetImageTag("registry.local/user1/image1", "latest")

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

log.Println(imageTag)
tutum image tag inspect registry.local/user1/image1:latest

Gets all the details of an specific image tag

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/image/(name)/tag/(tag)/

Path Parameters

Parameter Description
name The name of the image to retrieve the tag
tag The name of the tag

Build Settings

Build Setting

Example

{
  "resource_uri": "/api/v1/image/registry.local/user1/image1/buildsetting/latest/",
  "image": "/api/v1/image/registry.local/user1/image1/",
  "tag": "latest",
  "state": "SUCCESS",
  "dockerfile": "/",
  "branch": "master",
  "autobuild": false
}

A build setting to customize automated builds.

Image Build Setting attributes

Attribute Description
resource_uri A unique API endpoint that represents the image build setting
image The resource URI of the image to which this build setting belongs to
tag The name of the tag to be built
state The state of the build setting (see table Build Setting states below)
branch The git repository branch where the image is build from
dockerfile The path of the Dockerfile file in the branch
autobuild Whether to build the build setting tag on new commits on this branch

Build Setting States

State Description
Empty The build setting tag has not been built yet.
Success The last build on this build setting tag finished successfully.
Building The build setting tag is being built.
Failed The last build on this build setting tag failed.

Get an existing build setting

GET /api/v1/image/registry.local/user1/image1/buildsetting/latest/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Build an existing build setting tag

POST /api/v1/service/registry.local/user1/image1/buildsetting/latest/build/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

Builds the build setting tag from its associated git repository branch.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/image/(name)/buildsetting/(tag)/build/

Path Parameters

Parameter Description
name The name of the image to build
tag The name of the tag to build

Stacks

Stack

Example

{
  "deployed_datetime": "Mon, 13 Oct 2014 11:01:43 +0000",
  "destroyed_datetime": null,
  "nickname": "deployment stack",
  "name": "tutum-app",
  "resource_uri": "/api/v1/stack/7fe7ec85-58be-4904-81da-de2219098d7c/",
  "services": [
    "/api/v1/service/09cbcf8d-a727-40d9-b420-c8e18b7fa55b/"
  ],
  "state": "Running",
  "synchronized": true,
  "uuid": "09cbcf8d-a727-40d9-b420-c8e18b7fa55b"
}

A stack is a logical grouping of closely related services, that may be linked with one another.

Attributes

Attribute Description
uuid A unique identifier for the stack generated automatically on creation
resource_uri A unique API endpoint that represents the stack
name A user provided name for the stack.
state The state of the stack (see table Stack states below)
synchronized Flag indicating if the current stack definition is synchronized with their services.
services List of service resource URIs belonging to the stack
deployed_datetime The date and time of the last deployment of the stack (if applicable, null otherwise)
destroyed_datetime The date and time of the terminate operation on the stack (if applicable, null otherwise)
nickname A user-friendly name for the stack (name by default)

Stack states

State Description
Not Running The stack has been created and has no deployed services yet. Possible actions in this state: start, terminate.
Starting All services for the stack are either starting or already running. No actions allowed in this state.
Running All services for the service are deployed and running. Possible actions in this state: redeploy, terminate.
Partly running One or more services of the stack are deployed and running. Possible actions in this state: redeploy, terminate.
Stopping All services for the stack are either stopping or already stopped. No actions allowed in this state.
Stopped All services for the service are stopped. Possible actions in this state: start, redeploy, terminate.
Redeploying The stack is redeploying all its services with the updated configuration. No actions allowed in this state.
Terminating All services for the stack are either being terminated or already terminated. No actions allowed in this state.
Terminated The stack and all its services have been terminated. No actions allowed in this state.

List all stacks

import tutum

stacks = tutum.Stack.list()
import "github.com/tutumcloud/go-tutum/tutum"

stackList, err := tutum.ListStacks()

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

log.Println(stackList)
GET /api/v1/stack/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum stack list

Lists all current and recently terminated stacks. Returns a list of Stack objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/stack/

Query Parameters

Parameter Description
uuid Filter by UUID
name Filter by stack name

Create a new stack

import tutum

stack = tutum.Stack.create(name="my-new-stack", services=[{"name": "hello-word", "image": "tutum/hello-world", "target_num_containers": 2}])
stack.save()
import "github.com/tutumcloud/go-tutum/tutum"

stack, err := tutum.CreateStack(tutum.StackCreateRequest{Name: "my-new-stack", Services: []tutum.ServiceCreateRequest{{Image: "tutum/hello-world", Name: "test", Target_num_containers: 2}}})

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

log.Println(stack)
POST /api/v1/stack/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

{
    "name": "my-new-stack",
    "services": [
        {
            "name": "hello-word",
            "image": "tutum/hello-world",
            "target_num_containers": 2,
            "linked_to_service": [
                {
                    "to_service": "database",
                    "name": "DB"
                }
            ]
        },
        {
            "name": "database",
            "image": "tutum/mysql"
        }
    ]
}
tutum stack create --name hello-world -f tutum.yml

Creates a new stack without starting it. Note that the JSON syntax is abstracted by both, the Tutum CLI and our UI, in order to use Stack YAML files.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/stack/

JSON Parameters

Parameter Description
name (required) A human-readable name for the stack, i.e. my-hello-world-stack
nickname (optional) A user-friendly name for the stack (name by default)
services (optional) List of services belonging to the stack. Each service accepts the same parameters as a Create new service operation (default: []) plus the ability to refer “links” and “volumes-from” by the name of another service in the stack (see example).

Export an existing stack

import "github.com/tutumcloud/go-tutum/tutum"

stack, err := tutum.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

if err = stack.Export(); err != nil {
   log.Println(err)
}
GET /api/v1/stack/46aca402-2109-4a70-a378-760cfed43816/export/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Get a JSON representation of the stack following the Stack YAML representation.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/stack/(uuid)/export/

Path Parameters

Parameter Description
uuid The UUID of the stack to retrieve

Get an existing stack

import tutum

stack = tutum.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
import "github.com/tutumcloud/go-tutum/tutum"

stack, err := tutum.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

log.Println(stack)
GET /api/v1/stack/46aca402-2109-4a70-a378-760cfed43816/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum stack inspect 46aca402-2109-4a70-a378-760cfed43816

Get all the details of an specific stack

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/stack/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the stack to retrieve

Update an existing stack

import tutum

stack = tutum.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
stack.services = {"services": [{"name": "hello-word", "image": "tutum/hello-world", "target_num_containers": 2}]}
stack.save()
import "github.com/tutumcloud/go-tutum/tutum"

stack, err := tutum.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

if err = stack.Update(tutum.StackCreateRequest{Services: []tutum.ServiceCreateRequest{{Name: "hello-world", Image: "tutum/hello-world", Target_num_containers: 2}}}); err != nil {
   log.Println(err)
}
PATCH /api/v1/stack/46aca402-2109-4a70-a378-760cfed43816/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

{
    "services": [
        {
            "name": "hello-word",
            "image": "tutum/hello-world",
            "target_num_containers": 3,
            "linked_to_service": [
                {
                    "to_service": "database",
                    "name": "DB"
                }
            ]
        },
        {
            "name": "database",
            "image": "tutum/mysql"
        }
    ]
}
tutum stack update -f tutum.yml 46aca402-2109-4a70-a378-760cfed43816

Updates the details of every service in the stack.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

PATCH /api/v1/stack/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the stack to update

JSON Parameters

Parameter Description
services (optional) List of services belonging to the stack. Each service accepts the same parameters as a Update an existing service operation (default: []) plus the ability to refer “links” and “volumes-from” by the name of another service in the stack (see example).

Stop a stack

import tutum

stack = tutum.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
stack.stop()
import "github.com/tutumcloud/go-tutum/tutum"

stack, err := tutum.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

if err = stack.Stop(); err != nil {
   log.Println(err)
}
POST /api/v1/stack/46aca402-2109-4a70-a378-760cfed43816/stop/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum stack stop 46aca402-2109-4a70-a378-760cfed43816

Stops the services in the stack.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/stack/(uuid)/stop/

Path Parameters

Parameter Description
uuid The UUID of the stack to stop

Start a stack

import tutum

stack = tutum.Stack.fetch()
stack.start()
import "github.com/tutumcloud/go-tutum/tutum"

stack, err := tutum.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

if err = stack.Start(); err != nil {
   log.Println(err)
}
POST /api/v1/stack/46aca402-2109-4a70-a378-760cfed43816/start/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum stack start 46aca402-2109-4a70-a378-760cfed43816

Starts the services in the stack.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/stack/(uuid)/start/

Path Parameters

Parameter Description
uuid The UUID of the stack to start

Redeploy a stack

import tutum

stack = tutum.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
stack.redeploy()
import "github.com/tutumcloud/go-tutum/tutum"

stack, err := tutum.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

//Redeploy(tutum.ReuseVolumesOption{Reuse: true}) to reuse the existing volumes
//Redeploy(tutum.ReuseVolumesOption{Reuse: false}) to not reuse the existing volumes
if err = stack.Redeploy(tutum.ReuseVolumesOption{Reuse: false}); err != nil {
   log.Println(err)
}
POST /api/v1/stack/46aca402-2109-4a70-a378-760cfed43816/redeploy/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum stack redeploy 46aca402-2109-4a70-a378-760cfed43816

Redeploys all the services in the stack.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/stack/(uuid)/redeploy/

Path Parameters

Parameter Description
uuid The UUID of the stack to redeploy

Query Parameters

Parameter Description
reuse_volumes Wheather to reuse container volumes for this redeploy operation or not (default: true).

Terminate a stack

import tutum

stack = tutum.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
stack.delete()
import "github.com/tutumcloud/go-tutum/tutum"

stack, err := tutum.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

if err = stack.Terminate(); err != nil {
   log.Println(err)
}
DELETE /api/v1/stack/46aca402-2109-4a70-a378-760cfed43816/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum stack terminate 46aca402-2109-4a70-a378-760cfed43816

Terminate all the services in a the stack and the stack itself.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

DELETE /api/v1/stack/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the stack to terminate

Services

Service

Example

{
  "autodestroy": "OFF",
  "autoredeploy": false,
  "autorestart": "ON_FAILURE",
  "bindings": [
    {
        "host_path": null,
        "container_path": "/tmp",
        "rewritable": true,
        "volumes_from": null
    },
    {
        "host_path": "/etc",
        "container_path": "/etc",
        "rewritable": true,
        "volumes_from": null
    },
    {
        "host_path": null,
        "container_path": null,
        "rewritable": true,
        "volumes_from": "/api/v1/service/2f4f54e5-9d3b-4ac1-85ad-a2d4ff25a179/"
    }
  ],
  "cap_add": [
    "ALL"
  ],
  "cap_drop": [
    "NET_ADMIN",
    "SYS_ADMIN"
  ],
  "container_envvars": [
    {
      "key": "DB_PASS",
      "value": "test"
    }
  ],
  "container_ports": [
    {
      "endpoint_uri": "http://wordpress-stackable.admin.srv.tutum.io:80/",
      "inner_port": 80,
      "outer_port": 80,
      "port_name": "http",
      "protocol": "tcp",
      "published": true
    }
  ],
  "containers": [
    "/api/v1/container/6f8ee454-9dc3-4387-80c3-57aac1be3cc6/",
    "/api/v1/container/fdf9c116-7c08-4a60-b0ce-c54ca72c2f25/"
  ],
  "cpu_shares": 100,
  "cpuset": "0,1",
  "cgroup_parent": "m-executor-abcd",
  "current_num_containers": 2,
  "deployed_datetime": "Mon, 13 Oct 2014 11:01:43 +0000",
  "deployment_strategy": "EMPTIEST_NODE",
  "destroyed_datetime": null,
  "devices": [
    "/dev/ttyUSB0:/dev/ttyUSB0"
  ],
  "dns": [
    "8.8.8.8"
  ],
  "dns_search": [
    "example.com",
  ],
  "domainname": "domainname",
  "entrypoint": "",
  "extra_hosts": [
    "onehost:50.31.209.229"
  ],
  "hostname": "hostname",
  "image_name": "tutum/wordpress-stackable:latest",
  "image_tag": "/api/v1/image/tutum/wordpress-stackable/tag/latest/",
  "nickname": "wordpress-stackable",
  "labels": {
    "com.example.description": "Accounting webapp",
    "com.example.department": "Finance",
    "com.example.label-with-empty-value": ""
  },
  "link_variables": {
    "WORDPRESS_STACKABLE_1_ENV_DB_HOST": "**LinkMe**",
    "WORDPRESS_STACKABLE_1_ENV_DB_NAME": "wordpress",
    "WORDPRESS_STACKABLE_1_ENV_DB_PASS": "szVaPz925B7I",
    "WORDPRESS_STACKABLE_1_ENV_DB_PORT": "**LinkMe**",
    "WORDPRESS_STACKABLE_1_ENV_DB_USER": "admin",
    "WORDPRESS_STACKABLE_1_ENV_DEBIAN_FRONTEND": "noninteractive",
    "WORDPRESS_STACKABLE_1_ENV_HOME": "/",
    "WORDPRESS_STACKABLE_1_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
    "WORDPRESS_STACKABLE_1_PORT": "tcp://wordpress-stackable-1.admin.cont.tutum.io:49153",
    "WORDPRESS_STACKABLE_1_PORT_80_TCP": "tcp://wordpress-stackable-1.admin.cont.tutum.io:49153",
    "WORDPRESS_STACKABLE_1_PORT_80_TCP_ADDR": "wordpress-stackable-1.admin.cont.tutum.io",
    "WORDPRESS_STACKABLE_1_PORT_80_TCP_PORT": "49153",
    "WORDPRESS_STACKABLE_1_PORT_80_TCP_PROTO": "tcp",
    "WORDPRESS_STACKABLE_2_ENV_DB_HOST": "**LinkMe**",
    "WORDPRESS_STACKABLE_2_ENV_DB_NAME": "wordpress",
    "WORDPRESS_STACKABLE_2_ENV_DB_PASS": "szVaPz925B7I",
    "WORDPRESS_STACKABLE_2_ENV_DB_PORT": "**LinkMe**",
    "WORDPRESS_STACKABLE_2_ENV_DB_USER": "admin",
    "WORDPRESS_STACKABLE_2_ENV_DEBIAN_FRONTEND": "noninteractive",
    "WORDPRESS_STACKABLE_2_ENV_HOME": "/",
    "WORDPRESS_STACKABLE_2_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
    "WORDPRESS_STACKABLE_2_PORT": "tcp://wordpress-stackable-2.admin.cont.tutum.io:49154",
    "WORDPRESS_STACKABLE_2_PORT_80_TCP": "tcp://wordpress-stackable-2.admin.cont.tutum.io:49154",
    "WORDPRESS_STACKABLE_2_PORT_80_TCP_ADDR": "wordpress-stackable-2.admin.cont.tutum.io",
    "WORDPRESS_STACKABLE_2_PORT_80_TCP_PORT": "49154",
    "WORDPRESS_STACKABLE_2_PORT_80_TCP_PROTO": "tcp",
    "WORDPRESS_STACKABLE_ENV_DB_HOST": "**LinkMe**",
    "WORDPRESS_STACKABLE_ENV_DB_NAME": "wordpress",
    "WORDPRESS_STACKABLE_ENV_DB_PASS": "szVaPz925B7I",
    "WORDPRESS_STACKABLE_ENV_DB_PORT": "**LinkMe**",
    "WORDPRESS_STACKABLE_ENV_DB_USER": "admin",
    "WORDPRESS_STACKABLE_ENV_DEBIAN_FRONTEND": "noninteractive",
    "WORDPRESS_STACKABLE_ENV_HOME": "/",
    "WORDPRESS_STACKABLE_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
    "WORDPRESS_STACKABLE_PORT": "tcp://wordpress-stackable-1.admin.cont.tutum.io:49153",
    "WORDPRESS_STACKABLE_PORT_80_TCP": "tcp://wordpress-stackable-1.admin.cont.tutum.io:49153",
    "WORDPRESS_STACKABLE_PORT_80_TCP_ADDR": "wordpress-stackable-1.admin.cont.tutum.io",
    "WORDPRESS_STACKABLE_PORT_80_TCP_PORT": "49153",
    "WORDPRESS_STACKABLE_PORT_80_TCP_PROTO": "tcp",
    "WORDPRESS_STACKABLE_TUTUM_API_URL": "https://app-test.tutum.co/api/v1/service/adeebc1b-1b81-4af0-b8f2-cefffc69d7fb/"
  },
  "linked_from_service": [],
  "linked_to_service": [
    {
      "from_service": "/api/v1/service/09cbcf8d-a727-40d9-b420-c8e18b7fa55b/",
      "name": "DB",
      "to_service": "/api/v1/service/72f175bd-390b-46e3-9463-830aca32ce3e/"
    }
  ],
  "mac_address": "02:42:ac:11:65:43",
  "memory": 2048,
  "memory_swap": 8192,
  "name": "wordpress-stackable",
  "net": "bridge",
  "privileged": false,
  "public_dns": "wordpress-stackable.admin.svc.tutum.io",
  "read_only": true,
  "resource_uri": "/api/v1/service/09cbcf8d-a727-40d9-b420-c8e18b7fa55b/",
  "roles": ["global"],
  "run_command": "/run-wordpress.sh",
  "running_num_containers": 1,
  "security_opt": [
  ],
  "sequential_deployment": false,
  "started_datetime": "Mon, 13 Oct 2014 11:01:43 +0000",
  "state": "Partly running",
  "stack": "/api/v1/stack/46aca402-2109-4a70-a378-760cfed43816/",
  "stdin_open": false,
  "stopped_datetime": null,
  "stopped_num_containers": 0,
  "synchronized": true,
  "tags": [
        {"name": "tag_one"},
        {"name": "tag-two"},
        {"name": "tagthree3"}
  ],
  "target_num_containers": 2,
  "tty": false,
  "user": "root",
  "uuid": "09cbcf8d-a727-40d9-b420-c8e18b7fa55b",
  "working_dir": "/app"
}

A service is a template used to deploy one or more containers.

Attributes

Attribute Description
uuid A unique identifier for the service generated automatically on creation
resource_uri A unique API endpoint that represents the service
image_name The Docker image name and tag used for the service containers
image_tag Resource URI of the image (including tag) used for the service containers
name A user provided name for the service. This name will be inherited by the service containers and will be used in endpoint URLs, environment variable names, etc.
public_dns An external FQDN that resolves to all IPs of the nodes where the service containers are running on (as an A record with multiple IP entries which will be used by clients in a round-robin fashion). If the service is not publishing any ports, this FQDN will fail to resolve.
state The state of the service (see table Service states below)
net Network mode to set on the containers (see table Network Modes below, more information https://docs.docker.com/reference/run/#network-settings)
pid Set the PID (Process) Namespace mode for the containers (more information https://docs.docker.com/reference/run/#pid-settings-pid)
synchronized Flag indicating if the current service definition is synchronized with the current containers.
deployed_datetime The date and time of the last deployment of the service (if applicable, null otherwise)
started_datetime The date and time of the last start operation on the service (if applicable, null otherwise)
stopped_datetime The date and time of the last stop operation on the service (if applicable, null otherwise)
destroyed_datetime The date and time of the terminate operation on the service (if applicable, null otherwise)
target_num_containers The requested number of containers to deploy for the service
current_num_containers The actual number of containers deployed for the service
running_num_containers The actual number of containers deployed for the service in Running state
stopped_num_containers The actual number of containers deployed for the service in Stopped state
stack Resource URIs of the stack that the service belongs to
containers List of resource URIs of the containers launched as part of the service
container_ports List of ports to be published on the containers of this service (see table Service Port attributes below)
container_envvars List of user-defined environment variables to set on the containers of the service, which will override the image environment variables (see table Service Environment Variable attributes below)
labels Metadata in form of dictionary used for every container of this service
working_dir Working directory for running binaries within a container of this service
user Set the user used on containers of this service (root by default)
hostname Set the hostname used on containers of this service
domainname Set the domainname used on containers of this service
mac_address Ethernet device’s MAC address used on containers of this service
cgroup_name Optional parent cgroup used on containers of this service.
tty If the containers of this service have the tty enable (false by default)
stdin_open If the containers of this service have stdin opened (false by default)
dns Custom DNS servers for containers of this service
dns_search Custom DNS search domain for containers of this service
cap_add Added capabilities for containers of this service
cap_drop Dropped capabilities for containers of this service
devices List of device mappings for containers of this service
extra_hosrs List of hostname mappings for containers of this service
secuirty_opt Labeling scheme for containers of this service
entrypoint Entrypoint to be set on the containers launched as part of the service, which will override the image entrypoint
run_command Run command to be set on the containers launched as part of the service, which will override the image run command
sequential_deployment Whether the containers for this service should be deployed in sequence, linking each of them to the previous containers (see Service scaling for more information)
cpu_shares The relative CPU priority of the containers of the service (see Runtime Constraints on CPU and Memory for more information)
cpuset CPUs in which to allow execution
memory The memory limit of the containers of the service in MB (see Runtime Constraints on CPU and Memory for more information)
memory_swap Total memory limit (memory + swap) of the containers of the service in MB
linked_from_service A list of services that are linked to this one (see table Related services attributes below)
linked_to_service A list of services that the service is linked to (see table Related services attributes below)
bindings A list of volume bindings that the service has mounted (see table Service binding attributes below)
autorestart Whether to restart the containers of the service automatically if they stop (see Crash recovery for more information)
autodestroy Whether to terminate the containers of the service automatically if they stop (see Autodestroy for more information)
roles List of Tutum roles assigned to this service (see Service links for more information)
link_variables List of environment variables that would be exposed in the containers if they are linked to this service
privileged Whether to start the containers with Docker’s privileged flag set or not, which allows containers to access all devices on the host among other things (see Runtime privilege for more information)
read_only Whether the filesystem of every service container is read-only or not (false by default)
deployment_strategy Container distribution among nodes (see table Deployment strategies below and Deployment strategies for more information)
tags List of tags to be used to deploy the service (see Tags for more information)
autoredeploy Whether to redeploy the containers of the service when its image is updated in Tutum registry (see Tutum’s private registry for more information)
nickname A user-friendly name for the service (name by default)

Service binding attributes

Attribute Description
host_path The host path of the volume
container_path The container path where the volume is mounted
rewritable true is the volume has writable permissions
volumes_from The resource URI of the service

Service Port attributes

Attribute Description
protocol The protocol of the port, either tcp or udp
inner_port The published port number inside the container
outer_port The published port number in the node public network interface
port_name Name of the service associated to this port
endpoint_uri The URI of the service endpoint for this port
published Whether the port has been published in the host public network interface or not. Non-published ports can only be accessed via links.

Service Environment Variable attributes

Attribute Description
key The name of the environment variable
value The value of the environment variable
Attribute Description
name The link name
from_service The resource URI of the origin of the link
to_service The resource URI of the target of the link

Service states

State Description
Not running The service has been created and has no deployed containers yet. Possible actions in this state: start, terminate.
Starting All containers for the service are either starting or already running. No actions allowed in this state.
Running All containers for the service are deployed and running. Possible actions in this state: stop, redeploy, terminate.
Partly running One or more containers of the service are deployed and running. Possible actions in this state: stop, redeploy, terminate.
Scaling The service is either deploying new containers or destroying existing ones responding to a scaling request. No actions allowed in this state.
Redeploying The service is redeploying all its containers with the updated configuration. No actions allowed in this state.
Stopping All containers for the service are either stopping or already stopped. No actions allowed in this state.
Stopped All containers for the service are stopped. Possible actions in this state: start, redeploy, terminate.
Terminating All containers for the service are either being terminated or already terminated. No actions allowed in this state.
Terminated The service and all its containers have been terminated. No actions allowed in this state.

Deployment strategies

Strategy Description
EMPTIEST_NODE It will deploy containers to the node with the lower total amount of running containers (default).
HIGH_AVAILABILITY It will deploy containers to the node with the lower amount of running containers of the same service.
EVERY_NODE It will deploy one container on every node. The service won’t be able to scale manually. New containers will be deployed to new nodes automatically.

Network Modes

Strategy Description
bridge Creates a new network stack for the container on the docker bridge.
host Uses the host network stack inside the container.

List all services

import tutum

services = tutum.Service.list()
import "github.com/tutumcloud/go-tutum/tutum"

serviceList, err := tutum.ListServices()

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

log.Println(serviceList)
GET /api/v1/service/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum service ps

Lists all current and recently terminated services. Returns a list of Service objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/service/

Query Parameters

Parameter Description
uuid Filter by UUID
state Filter by state. Possible values: Not running, Starting, Running, Partly running, Scaling, Redeploying, Stopping, Stopped, Terminating, Terminated
name Filter by service name
stack Filter by resource URI of the target stack.

Create a new service

import tutum

service = tutum.Service.create(image="tutum/hello-world", name="my-new-app", target_num_containers=2)
service.save()
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.CreateService(tutum.ServiceCreateRequest{Image: "tutum/hello-world",  Name: "my-new-app", Target_num_containers: 2})

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

log.Println(service)
POST /api/v1/service/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

{"image": "tutum/hello-world", "name": "my-new-app", "target_num_containers": 2}
tutum service create -t 2 --name my-new-app tutum/hello-world

Creates a new service without starting it.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/service/

JSON Parameters

Parameter Description
image (required) The image used to deploy this service in docker format, i.e. tutum/hello-world
name (optional) A human-readable name for the service, i.e. my-hello-world-app (default: image without namespace)
target_num_containers (optional) The number of containers to run for this service initially (default: 1)
run_command (optional) The command used to start the containers of this service, overriding the value specified in the image, i.e. /run.sh (default: null)
entrypoint (optional) The command prefix used to start the containers of this service, overriding the value specified in the image, i.e. /usr/sbin/sshd (default: null)
container_ports (optional) An array of objects with port information to be published in the containers for this service, which will be added to the image port information, i.e. [{"protocol": "tcp", "inner_port": 80, "outer_port": 80}] (default: []) (See table Service Port attributes below)
container_envvars (optional) An array of objects with environment variables to be added in the service containers on launch (overriding any image-defined environment variables), i.e. [{"key": "DB_PASSWORD", "value": "mypass"}] (default: []) (See table Service Environment Variable attributes below)
linked_to_service (optional) An array of service resource URIs to link this service to, including the link name, i.e. [{"to_service": "/api/v1/service/80ff1635-2d56-478d-a97f-9b59c720e513/", "name": "db"}] (default: []) (See table Related services attributes below)
bindings (optional) An array of bindings this service has to mount, i.e. [{"volumes_from": "/api/v1/service/80ff1635-2d56-478d-a97f-9b59c720e513/", "rewritable": true}] (default: []) (See table Related bindings attributes below)
autorestart (optional) Whether the containers for this service should be restarted if they stop, i.e. ALWAYS (default: OFF, possible values: OFF, ON_FAILURE, ALWAYS) (see Crash recovery for more information)
autodestroy (optional) Whether the containers should be terminated if they stop, i.e. OFF (default: OFF, possible values: OFF, ON_SUCCESS, ALWAYS) (see Autodestroy for more information)
sequential_deployment (optional) Whether the containers should be launched and scaled in sequence, i.e. true (default: false) (see Service scaling for more information)
roles (optional) A list of Tutum API roles to grant the service, i.e. ["global"] (default: [], possible values: global) (see Service links for more information)
privileged (optional) Whether to start the containers with Docker’s privileged flag set or not, i.e. false (default: false) (see Runtime privilege for more information)
deployment_strategy (optional) Container distribution among nodes (default: EMPTIEST_NODE, see table Deployment strategies above and Deployment strategies for more information)
tags (optional) A list of tags to be used to deploy the service (see Tags for more information) (default: [])
autoredeploy (optional) Whether to redeploy the containers of the service when its image is updated in Tutum registry (default: false) (see Tutum’s private registry for more information)
net (optional) Set the network mode to the containers (default: bridge, possible values: bridge, host)
pid (optional) Set the PID (Process) Namespace mode for the containers (default: none value, possible values: none, host)
working_dir (optional) Working directory for running binaries within a container of this service (default: /)
nickname (optional) A user-friendly name for the service (name by default)
Attribute Description
host_path (optional) The host path of the volume
container_path (required if volumes_from is omitted) The container path where the volume is mounted
rewritable (optional) true is the volume has writable permissions (default: true)
volumes_from (required if container_path is omitted) The resource URI of the service

Service Port attributes

Attribute Description
protocol (required) The protocol of the port, either tcp or udp
inner_port (required) The port number inside the container to be published
outer_port (optional) The port number in the node public network interface to be published (default: dynamic allocation if published is true)
published (optional) Whether to publish the port in the host public network interface or not. Non-published ports can only be accessed via links. (default: false)

Service Environment Variable attributes

Attribute Description
key (required) The name of the environment variable
value (required) The value of the environment variable
Attribute Description
to_service (required) The resource URI of the target of the link
name (optional) The link name

Get an existing service

import tutum

service = tutum.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

log.Println(service)
GET /api/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum service inspect 7eaf7fff

Get all the details of an specific service

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/service/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the service to retrieve

Get the logs of a service

Example log line

{
    "type": "log",
    "source": "wordpress-stackable-1",
    "log": "Log line from the container indicated by 'source'",
    "streamType": "stdout",
    "timestamp": 1433779324
}
import tutum

def log_handler(message):
    print message

service = tutum.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
service.logs(tail=300, follow=True, log_handler=log_handler)
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

c := make(chan Logs)

go service.Logs(c)
    for {
        s := <-c
        log.Println(s)
    }
GET /v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/logs/ HTTP/1.1
Host: stream.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Connection: Upgrade
Upgrade: websocket
tutum service logs 7eaf7fff

Get the aggregated logs of all the containers of the service.

Endpoint Type

Available in Tutum’s STREAM API

HTTP Request

GET /v1/service/(uuid)/logs/

Path Parameters

Parameter Description
uuid The UUID of the service 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)

Update an existing service

import tutum

service = tutum.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
service.target_num_containers = 3
service.tags.append({"name":"tag-1"})
service.save()
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = service.Update(tutum.ServiceCreateRequest{Target_num_containers: 3}); err != nil {
   log.Println(err)
}
PATCH /api/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

{"autorestart": "ON_FAILURE", "autodestroy": "OFF", "container_envvars": [{"key": "DB_PASSWORD", "value": "mypass"}],
"container_ports": [{"protocol": "tcp", "inner_port": 80, "outer_port": 80}], "cpu_shares": 512,
"entrypoint": "/usr/sbin/sshd", "image": "tutum/hello-world",
"linked_to_service": [{"to_service": "/api/v1/service/80ff1635-2d56-478d-a97f-9b59c720e513/", "name": "db"}],
"memory": 2048, "privileged": True, "roles": ["global"], "run_command": "/run.sh", "sequential_deployment": False,
"tags": [{"name": "tag-1"}], "target_num_containers": 3, "autoredeploy": False}

tutum service scale 7eaf7fff 3
tutum tag add -t tag-1 7eaf7fff
tutum tag set -t tag-2 7eaf7fff

Updates the service details.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

PATCH /api/v1/service/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the service to update

JSON Parameters

Parameter Description
autorestart (optional) Whether the containers for this service should be restarted if they stop, i.e. ALWAYS (possible values: OFF, ON_FAILURE, ALWAYS) (see Crash recovery for more information)
autodestroy (optional) Whether the containers should be terminated if they stop, i.e. OFF (possible values: OFF, ON_SUCCESS, ALWAYS) (see Autodestroy for more information)
container_envvars (optional) An array of objects with environment variables to be added in the service containers on launch (overriding any image-defined environment variables), i.e. [{"key": "DB_PASSWORD", "value": "mypass"}] (See table Service Environment Variable attributes)
container_ports (optional) An array of objects with port information to be published in the containers for this service, which will be added to the image port information, i.e. [{"protocol": "tcp", "inner_port": 80, "outer_port": 80}] (See table Service Port attributes)
cpu_shares (optional) The relative CPU priority of the containers the service describes (see Runtime Constraints on CPU and Memory for more information)
entrypoint (optional) The command prefix used to start the containers of this service, overriding the value specified in the image, i.e. /usr/sbin/sshd
image (optional) The image used to deploy this service in docker format, i.e. tutum/hello-world, tutum/ubuntu:5.6. If no tag is indicated, it will be set to latest by default
linked_to_service (optional) An array of service resource URIs to link this service to, including the link name, i.e. [{"to_service": "/api/v1/service/80ff1635-2d56-478d-a97f-9b59c720e513/", "name": "db"}] (See table Related services attributes below)
memory (optional) The memory limit of the containers of the service in MB (see Runtime Constraints on CPU and Memory for more information)
privileged (optional) Whether to start the containers with Docker’s privileged flag set or not, i.e. false (see Runtime privilege for more information)
roles (optional) A list of Tutum API roles to grant the service, i.e. ["global"] (possible values: global) (see Service links for more information)
run_command (optional) The command used to start the containers of this service, overriding the value specified in the image, i.e. /run.sh
sequential_deployment (optional) Whether the containers should be launched and scaled in sequence, i.e. true (see Service scaling for more information)
tags (optional) List of new tags the service will have. This operation replaces the tag list
target_num_containers (optional) The number of containers to scale this service to
deployment_strategy (optional) Container distribution among nodes. A service cannot be updated to or from a deployment strategy of EVERY_NODE. (See table Deployment strategies above and Deployment strategies for more information)
autoredeploy Whether to redeploy the containers of the service when its image is updated in Tutum registry (see Tutum’s private registry for more information)
net (optional) Set the network mode to the containers (default: bridge, possible values: bridge, host)
pid (optional) Set the PID (Process) Namespace mode for the containers (default: none value, possible values: none, host)
working_dir (optional) Working directory for running binaries within a container of this service (default: /)
nickname (optional) A user-friendly name for the service (name by default)

Start a service

import tutum

service = tutum.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
service.start()
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = service.Start(); err != nil {
   log.Println(err)
}
POST /api/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/start/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum service start 7eaf7fff

Starts all containers in a stopped or partly running service.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/service/(uuid)/start/

Path Parameters

Parameter Description
uuid The UUID of the service to start

Stop a service

import tutum

service = tutum.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
service.stop()
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = service.Stop(); err != nil {
   log.Println(err)
}
POST /api/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/stop/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum service stop 7eaf7fff

Stops all containers in a running or partly running service.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/service/(uuid)/stop/

Path Parameters

Parameter Description
uuid The UUID of the service to stop

Scale a service

import tutum

service = tutum.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
service.target_num_containers = 3
service.save()
service.scale()
POST /api/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/scale/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum service scale 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce 3

Scales the service to its current target_num_containers field.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/service/(uuid)/scale/

Path Parameters

Parameter Description
uuid The UUID of the service to scale

Redeploy a service

import tutum

service = tutum.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
service.redeploy()
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

//Redeploy(tutum.ReuseVolumesOption{Reuse: true}) to reuse the existing volumes
//Redeploy(tutum.ReuseVolumesOption{Reuse: false}) to not reuse the existing volumes
if err = service.Redeploy(tutum.ReuseVolumesOption{Reuse: false}); err != nil {
   log.Println(err)
}
POST /api/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/redeploy/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum service redeploy 7eaf7fff

Redeploys all containers in the service with the current service configuration.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/service/(uuid)/redeploy/

Path Parameters

Parameter Description
uuid The UUID of the service to redeploy

Query Parameters

Parameter Description
reuse_volumes Wheather to reuse container volumes for this redeploy operation or not (default: true).

Terminate a service

import tutum

service = tutum.Service.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
service.delete()
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = service.Terminate(); err != nil {
   log.Println(err)
}
DELETE /api/v1/service/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum service terminate 7eaf7fff

Terminate all the containers in a service and the service itself. This is not reversible. All the data stored in all containers of the service will be permanently deleted.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

DELETE /api/v1/service/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the service to terminate

Containers

Container

Example

{
    "autodestroy": "OFF",
    "autorestart": "OFF",
    "bindings": [
        {
            "volume": "/api/v1/volume/1863e34d-6a7d-4945-aefc-8f27a4ab1a9e/",
            "host_path": null,
            "container_path": "/data",
            "rewritable": true
        },
        {
            "volume": null,
            "host_path": "/etc",
            "container_path": "/etc",
            "rewritable": true
        }
    ],
    "cap_add": [
        "ALL"
    ],
    "cap_drop": [
        "NET_ADMIN",
        "SYS_ADMIN"
    ],
    "container_envvars": [
        {
            "key": "DB_1_ENV_DEBIAN_FRONTEND",
            "value": "noninteractive"
        },
        {
            "key": "DB_1_ENV_MYSQL_PASS",
            "value": "**Random**"
        },
        {
            "key": "DB_1_ENV_MYSQL_USER",
            "value": "admin"
        },
        {
            "key": "DB_1_ENV_PATH",
            "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
        },
        {
            "key": "DB_1_ENV_REPLICATION_MASTER",
            "value": "**False**"
        },
        {
            "key": "DB_1_ENV_REPLICATION_PASS",
            "value": "replica"
        },
        {
            "key": "DB_1_ENV_REPLICATION_SLAVE",
            "value": "**False**"
        },
        {
            "key": "DB_1_ENV_REPLICATION_USER",
            "value": "replica"
        },
        {
            "key": "DB_1_PORT",
            "value": "tcp://172.16.0.3:3306"
        },
        {
            "key": "DB_1_PORT_3306_TCP",
            "value": "tcp://172.16.0.3:3306"
        },
        {
            "key": "DB_1_PORT_3306_TCP_ADDR",
            "value": "172.16.0.3"
        },
        {
            "key": "DB_1_PORT_3306_TCP_PORT",
            "value": "3306"
        },
        {
            "key": "DB_1_PORT_3306_TCP_PROTO",
            "value": "tcp"
        },
        {
            "key": "DB_ENV_DEBIAN_FRONTEND",
            "value": "noninteractive"
        },
        {
            "key": "DB_ENV_MYSQL_PASS",
            "value": "**Random**"
        },
        {
            "key": "DB_ENV_MYSQL_USER",
            "value": "admin"
        },
        {
            "key": "DB_ENV_PATH",
            "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
        },
        {
            "key": "DB_ENV_REPLICATION_MASTER",
            "value": "**False**"
        },
        {
            "key": "DB_ENV_REPLICATION_PASS",
            "value": "replica"
        },
        {
            "key": "DB_ENV_REPLICATION_SLAVE",
            "value": "**False**"
        },
        {
            "key": "DB_ENV_REPLICATION_USER",
            "value": "replica"
        },
        {
            "key": "DB_PASS",
            "value": "szVaPz925B7I"
        },
        {
            "key": "DB_PORT",
            "value": "tcp://172.16.0.3:3306"
        },
        {
            "key": "DB_PORT_3306_TCP",
            "value": "tcp://172.16.0.3:3306"
        },
        {
            "key": "DB_PORT_3306_TCP_ADDR",
            "value": "172.16.0.3"
        },
        {
            "key": "DB_PORT_3306_TCP_PORT",
            "value": "3306"
        },
        {
            "key": "DB_PORT_3306_TCP_PROTO",
            "value": "tcp"
        },
        {
            "key": "DB_TUTUM_API_URL",
            "value": "https://app-test.tutum.co/api/v1/service/c0fed1dc-c528-40c9-aa4c-dc00672ebcbf/"
        }
    ],
    "container_ports": [
        {
            "endpoint_uri": "http://wordpress-stackable-1.admin.cont.tutum.io:49153/",
            "inner_port": 80,
            "outer_port": 49153,
            "port_name": "http",
            "protocol": "tcp",
            "published": true,
            "uri_protocol": "http"
        }
    ],
    "cpu_shares": 100,
    "cpuset": "0,1",
    "cgroup_parent": "m-executor-abcd",
    "deployed_datetime": "Thu, 16 Oct 2014 12:04:08 +0000",
    "destroyed_datetime": null,
    "devices": [
        "/dev/ttyUSB0:/dev/ttyUSB0"
    ],
    "dns": [
        "8.8.8.8"
    ],
    "dns_search": [
        "example.com",
        "c1dd4e1e-1356-411c-8613-e15146633640.local.tutum.io"
    ],
    "domainname": "domainname",
    "entrypoint": "",
    "exit_code": null,
    "exit_code_msg": null,
    "extra_hosts": [
        "onehost:50.31.209.229"
    ],
    "hostname": "hostname",
    "image_name": "tutum/wordpress-stackable:latest",
    "image_tag": "/api/v1/image/tutum/wordpress-stackable/tag/latest/",
    "labels": {
        "com.example.description": "Accounting webapp",
        "com.example.department": "Finance",
        "com.example.label-with-empty-value": ""
    },
    "last_metric": {
        "cpu": 1.3278507035616,
        "disk": 462479360,
        "memory": 763170816
    },
    "linked_to_container": [
        {
            "endpoints": {
                "3306/tcp": "tcp://172.16.0.3:3306"
            },
            "from_container": "/api/v1/container/c1dd4e1e-1356-411c-8613-e15146633640/",
            "name": "DB_1",
            "to_container": "/api/v1/container/ba434e1e-1234-411c-8613-e15146633640/"
        }
    ],
    "link_variables": {
        "WORDPRESS_STACKABLE_1_ENV_DB_HOST": "**LinkMe**",
        "WORDPRESS_STACKABLE_1_ENV_DB_NAME": "wordpress",
        "WORDPRESS_STACKABLE_1_ENV_DB_PASS": "szVaPz925B7I",
        "WORDPRESS_STACKABLE_1_ENV_DB_PORT": "**LinkMe**",
        "WORDPRESS_STACKABLE_1_ENV_DB_USER": "admin",
        "WORDPRESS_STACKABLE_1_ENV_DEBIAN_FRONTEND": "noninteractive",
        "WORDPRESS_STACKABLE_1_ENV_HOME": "/",
        "WORDPRESS_STACKABLE_1_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
        "WORDPRESS_STACKABLE_1_PORT": "tcp://172.16.0.2:80",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP": "tcp://172.16.0.2:80",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP_ADDR": "172.16.0.2",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP_PORT": "80",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP_PROTO": "tcp",
        "WORDPRESS_STACKABLE_ENV_DB_HOST": "**LinkMe**",
        "WORDPRESS_STACKABLE_ENV_DB_NAME": "wordpress",
        "WORDPRESS_STACKABLE_ENV_DB_PASS": "szVaPz925B7I",
        "WORDPRESS_STACKABLE_ENV_DB_PORT": "**LinkMe**",
        "WORDPRESS_STACKABLE_ENV_DB_USER": "admin",
        "WORDPRESS_STACKABLE_ENV_DEBIAN_FRONTEND": "noninteractive",
        "WORDPRESS_STACKABLE_ENV_HOME": "/",
        "WORDPRESS_STACKABLE_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
        "WORDPRESS_STACKABLE_PORT": "tcp://172.16.0.2:80",
        "WORDPRESS_STACKABLE_PORT_80_TCP": "tcp://172.16.0.2:80",
        "WORDPRESS_STACKABLE_PORT_80_TCP_ADDR": "172.16.0.2",
        "WORDPRESS_STACKABLE_PORT_80_TCP_PORT": "80",
        "WORDPRESS_STACKABLE_PORT_80_TCP_PROTO": "tcp"
    },
    "mac_address": "02:42:ac:11:65:43",
    "memory": 1024,
    "memory_swap": 4096,
    "name": "wordpress-stackable",
    "net": "bridge",
    "node": "/api/v1/node/9691c44e-3155-4ca2-958d-c9571aac0a14/",
    "pid": "none",
    "private_ip": "10.7.0.1",
    "privileged": false,
    "public_dns": "wordpress-stackable-1.admin.cont.tutum.io",
    "read_only": true,
    "resource_uri": "/api/v1/container/c1dd4e1e-1356-411c-8613-e15146633640/",
    "roles": ["global"],
    "run_command": "/run-wordpress.sh",
    "security_opt": [
        "label:user:USER",
        "label:role:ROLE"
    ],
    "service": "/api/v1/service/adeebc1b-1b81-4af0-b8f2-cefffc69d7fb/",
    "started_datetime": "Thu, 16 Oct 2014 12:04:08 +0000",
    "state": "Running",
    "stdin_open": false,
    "stopped_datetime": null,
    "synchronized": true,
    "tty": false,
    "user": "root",
    "uuid": "c1dd4e1e-1356-411c-8613-e15146633640",
    "working_dir": "/app"
}

A container is a representation of a Docker container in a node.

Attributes

Attribute Description
uuid A unique identifier for the container generated automatically on creation
resource_uri A unique API endpoint that represents the container
image_name The Docker image name and tag of the container
image_tag Resource URI of the image (including tag) of the container
bindings A list of volume bindings that the container has mounted (see table Container Binding attributes below)
name A user provided name for the container (inherited from the service)
node The resource URI of the node where this container is running
service The resource URI of the service which this container is part of
public_dns The external FQDN of the container
state The state of the container (see table Container states below)
synchronized Flag indicating if the container is synchronized with the current service definition.
exit_code The numeric exit code of the container (if applicable, null otherwise)
exit_code_msg A string representation of the exit code of the container (if applicable, null otherwise)
deployed_datetime The date and time of the last deployment of the container (if applicable, null otherwise)
started_datetime The date and time of the last start operation on the container (if applicable, null otherwise)
stopped_datetime The date and time of the last stop operation on the container (if applicable, null otherwise)
destroyed_datetime The date and time of the terminate operation on the container (if applicable, null otherwise)
container_ports List of published ports of this container (see table Container Port attributes below)
container_envvars List of user-defined environment variables set on the containers of the service, which will override the container environment variables (see table Container Environment Variable attributes below)
labels Container metadata in form of dictionary
working_dir Working directory for running binaries within a container
user User used on the container on launch
hostname Hostname used on the container on launch
domainname Domainname used on the container on launch
mac_address Ethernet device’s MAC address used on the container on launch
cgroup_name Optional parent cgroup for the container.
tty If the container has the tty enable
stdin_open If the container has stdin opened
dns Container custom DNS servers
dns_search Container custom DNS search domain
cap_add Container added capabilities
cap_drop Container dropped capabilities
devices List of container device mappings
extra_hosts List of container hostname mappings
secuirty_opt Labeling scheme of this container
entrypoint Entrypoint used on the container on launch
run_command Run command used on the container on launch
cpu_shares The relative CPU priority of the container (see Runtime Constraints on CPU and Memory for more information)
cpuset CPUs in which execution is allowed
memory The memory limit of the container in MB (see Runtime Constraints on CPU and Memory for more information)
memory_swap Total memory limit (memory + swap) of the container in MB
last_metric Last reported metric for the container (see table Container Last Metric attributes below for more information)
autorestart Whether to restart the container automatically if it stops (see Crash recovery for more information)
autodestroy Whether to terminate the container automatically if it stops (see Autodestroy for more information)
roles List of Tutum roles asigned to this container (see API roles for more information))
linked_to_container List of IP addresses of the linked containers (see table Container Link attributes below and Service links for more information)
link_variables List of environment variables that would be exposed in any container that is linked to this one
privileged Whether the container has Docker’s privileged flag set or not (see Runtime privilege for more information)
read_only Whether the container filesystem is read-only or not
private_ip IP address of the container on the overlay network. This IP will be reachable from any other container.
net Network mode set on the container (see table Network Modes below, more information https://docs.docker.com/reference/run/#network-settings)
pid PID (Process) Namespace mode for the container (more information https://docs.docker.com/reference/run/#pid-settings-pid)

Container Binding attributes

Attribute Description
host_path The host path of the volume
container_path The container path where the volume is mounted
rewritable true is the volume has writable permissions
volume The resource URI of the volume

Container Port attributes

Attribute Description
protocol The protocol of the port, either tcp or udp
inner_port The published port number inside the container
outer_port The published port number in the node public network interface
port_name Name of the service associated to this port
uri_protocol The protocol to be used in the endpoint for this port (i.e. http)
endpoint_uri The URI of the endpoint for this port
published Whether the port has been published in the host public network interface or not. Non-published ports can only be accessed via links.

Container Environment Variable attributes

Attribute Description
key The name of the environment variable
value The value of the environment variable

Container States

State Description
Starting The container is being deployed or started (from Stopped). No actions allowed in this state.
Running The container is deployed and running. Possible actions in this state: stop, terminate.
Stopping The container is being stopped. No actions allowed in this state.
Stopped The container is stopped. Possible actions in this state: start, terminate.
Terminating The container is being deleted. No actions allowed in this state.
Terminated The container has been deleted. No actions allowed in this state.

Network Modes

Strategy Description
bridge Creates a new network stack for the container on the docker bridge.
host Uses the host network stack inside the container.

Container Last Metric attributes

Attribute Description
cpu CPU percentage usage
memory Memory usage in bytes
disk Disk storage usage in bytes
Attribute Description
name The name given to the link
from_container The resource URI of the “client” container
to_container The resource URI of the “server” container being linked
endpoints A dictionary with the endpoints (protocol, IP and port) to be used to reach each of the “server” container exposed ports

List all containers

import tutum

containers = tutum.Container.list()
import "github.com/tutumcloud/go-tutum/tutum"

containerList, err := tutum.ListContainers()

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

log.Println(containerList)
GET /api/v1/container/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum container ps

Lists all current and recently terminated containers. Returns a list of Container objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/container/

Query Parameters

Parameter Description
uuid Filter by UUID
state Filter by state. Possible values: Starting, Running, Stopping, Stopped, Terminating, Terminated
name Filter by container name
service Filter by resource URI of the target service.
node Filter by resource URI of the target node.

Get an existing container

import tutum

container = tutum.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
import "github.com/tutumcloud/go-tutum/tutum"

container, err := tutum.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

log.Println(container)
GET /api/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum container inspect 7eaf7fff

Get all the details of an specific container

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/container/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the container to retrieve

Get the logs of a container

Example log line

{
    "type": "log",
    "log": "Log line from the container",
    "streamType": "stdout",
    "timestamp": 1433779324
}
import tutum

def log_handler(message):
    print message

container = tutum.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.logs(tail=300, follow=True, log_handler=log_handler)
import "github.com/tutumcloud/go-tutum/tutum"

container, err := tutum.GetContainer("447ecddc-2890-4ea2-849b-99392e0dd7a6")

if err != nil {
    log.Fatal(err)
}
c := make(chan tutum.Logs)

go container.Logs(c)
    for {
        s := <-c
        log.Println(s)
    }
GET /v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/logs/ HTTP/1.1
Host: stream.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Connection: Upgrade
Upgrade: websocket
tutum container logs 7eaf7fff

Get the logs of the specified container.

Endpoint Type

Available in Tutum’s STREAM API

HTTP Request

GET /v1/container/(uuid)/logs/

Path Parameters

Parameter Description
uuid The UUID of the container 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)
service Filter by service (resource URI)

Start a container

import tutum

container = tutum.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.start()
import "github.com/tutumcloud/go-tutum/tutum"

container, err := tutum.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = container.Start(); err != nil {
  log.Println(err)
}
POST /api/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/start/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum container start 7eaf7fff

Starts a stopped container.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/container/(uuid)/start/

Path Parameters

Parameter Description
uuid The UUID of the container to start

Stop a container

import tutum

container = tutum.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.stop()
import "github.com/tutumcloud/go-tutum/tutum"

container, err := tutum.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = container.Stop(); err != nil {
       log.Println(err)
   }
POST /api/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/stop/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum container stop 7eaf7fff

Stops a running container.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/container/(uuid)/stop/

Path Parameters

Parameter Description
uuid The UUID of the container to stop

Redeploy a container

import tutum

container = tutum.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.redeploy()
import "github.com/tutumcloud/go-tutum/tutum"

container, err := tutum.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
    log.Println(err)
}
//Redeploy(tutum.ReuseVolumesOption{Reuse: true) to reuse the existing volumes
//Redeploy(tutum.ReuseVolumesOption{Reuse: false}) to not reuse the existing volumes
if err = container.Redeploy(tutum.ReuseVolumesOption{Reuse: false}); err != nil {
  log.Println(err)
}
POST /api/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/start/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum container redeploy 7eaf7fff

Redeploys a container.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/container/(uuid)/redeploy/

Path Parameters

Parameter Description
uuid The UUID of the container to redeploy

Query Parameters

Parameter Description
reuse_volumes Wheather to reuse container volumes for this redeploy operation or not (default: true).

Terminate a container

import tutum

container = tutum.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.delete()
import "github.com/tutumcloud/go-tutum/tutum"

container, err := tutum.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

if err = container.Terminate(); err != nil {
       log.Println(err)
   }
DELETE /api/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum container terminate 7eaf7fff

Terminates the specified container. This is not reversible. All data stored in the container will be permanently deleted.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

DELETE /api/v1/container/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the container to terminate

Execute command inside a container

import "github.com/tutumcloud/go-tutum/tutum"

container, err := tutum.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

c := make(chan tutum.Exec)

container.Exec("ls", c)

GET /v1/container/(uuid)/exec/ HTTP/1.1
Host: stream.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Connection: Upgrade
Upgrade: websocket

Executes a command inside the specified running container, creating a bi-directional stream for the process' standard input and output. This endpoint can be connected to using a bi-directional Secure Web Socket wss://stream.tutum.co/v1/container/(uuid)/exec/

Endpoint Type

Available in Tutum’s STREAM API

HTTP Request

GET /v1/container/(uuid)/exec/

Path Parameters

Parameter Description
uuid The UUID of the container where the command will be executed

Query Parameters

Parameter Description
command Command to be executed (default: sh)

Volume Groups

Volume Group

Example

{
    "name": "mysql_etc",
    "resource_uri": "/api/v1/volume/1863e34d-6a7d-4945-aefc-8f27a4ab1a9e/",
    "services": [
        "/api/v1/service/1ddb524a-e7f5-4b68-b99c-50bf7c57602d/"
    ],
    "state": "Created",
    "uuid": "1863e34d-6a7d-4945-aefc-8f27a4ab1a9e",
    "volumes": [
        "/api/v1/volume/1863e34d-6a7d-4945-aefc-8f27a4ab1a9e/"
     ]
}

A volume group is a representation of a group of Docker volumes belonging to a service and sharing the same container mount point.

Attributes

Attribute Description
uuid A unique identifier for the volume group generated automatically on creation
name The name of the volume group
resource_uri A unique API endpoint that represents the volume group
state The state of the volume group (see table Volume Group states below)
services List of the resource URIs of the services using this volume group
volumes List of the resource URIs of the volumes belonging to this volume group

Volume Group states

State Description
Created The volume group object has been created and it is available
Terminated The volume group and its associated volumes have been deleted

List all volume groups

import tutum

volumegroups = tutum.VolumeGroup.list()
GET /api/v1/volumegroup/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

volumeGroupList, err := tutum.ListVolumeGroups()

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

log.Println(volumeGroupList)
tutum volumegroup list

Lists all volume groups. Returns a list of VolumeGroup objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/volumegroup/

Query Parameters

Parameter Description
uuid Filter by UUID
name Filter by volume group name
volumes Filter by resource URI of the target volumes
services Filter by resource URI of the target services

Get an existing volume group

import tutum

volumegroup = tutum.VolumeGroup.inspect("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
import "github.com/tutumcloud/go-tutum/tutum"

volumeGroup, err := tutum.GetVolumeGroup("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

log.Println(volumeGroup)
GET /api/v1/volumegroup/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum volumegroup inspect 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce

Get all the details of an specific volume group

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/volumegroup/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the volume group to retrieve

Volumes

Volume

Example

{
    "containers": [
        "/api/v1/container/55b07a2e-fa72-481f-984b-0e94f275de0b/"
    ],
    "node": "/api/v1/node/fc1a5bb9-17f5-4819-b667-8c7cd819e950/",
    "resource_uri": "/api/v1/volume/1863e34d-6a7d-4945-aefc-8f27a4ab1a9e/",
    "state": "Created",
    "uuid": "1863e34d-6a7d-4945-aefc-8f27a4ab1a9e",
    "volume_group": "/api/v1/volumegroup/2f4f54e5-9d3b-4ac1-85ad-a2d4ff25a173/"
}

A volume is a representation of a Docker volume in a node.

Attributes

Attribute Description
uuid A unique identifier for the volume generated automatically on creation
resource_uri A unique API endpoint that represents the volume
node The resource URI of the node where the volume is
state The state of the volume (see table Volume states below)
containers List of the resource URIs of the containers using this volume
volume_group The resource URI of the volume group this volume belongs to

Volume states

State Description
Created The volume object has been created in the node and it is available
Terminated The volume has been deleted in the node.

List all volumes

import tutum

volumes = tutum.Volume.list()
import "github.com/tutumcloud/go-tutum/tutum"

volumeList, err := tutum.ListVolumes()

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

log.Println(volumeList)
GET /api/v1/volume/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum volume list

Lists all volumes. Returns a list of Volume objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/volume/

Query Parameters

Parameter Description
uuid Filter by UUID
node Filter by resource URI of the target node
containers Filter by resource URI of the target containers

Get an existing volume

import tutum

volume = tutum.Volume.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
import "github.com/tutumcloud/go-tutum/tutum"

volume, err := tutum.GetVolume("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

log.Println(volume)
GET /api/v1/volume/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum volume inspect 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce

Get all the details of an specific volume

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/volume/(uuid)/

Path Parameters

Parameter Description
uuid The UUID of the volume to retrieve

Triggers

Service triggers

Example

{
  "url": "/api/v1/service/82d4a246-52d8-468d-903d-9da9ef05ff28/trigger/0224815a-c156-44e4-92d7-997c69354438/call/",
  "operation": "REDEPLOY",
  "name": "docker_trigger",
  "resource_uri": "/api/v1/service/82d4a246-52d8-468d-903d-9da9ef05ff28/trigger/0224815a-c156-44e4-92d7-997c69354438/"
}

Triggers are URLs that will start a redeploy of the service whenever a POST request is sent to them. They require no authorization headers, so they should be treated as access tokens. Triggers can be revoked if they are leaked or no longer used for security purposes. See Triggers for more information.

Attributes

Attribute Description
url Address to be used to call the trigger with a POST request
name A user provided name for the trigger
operation The operation that the trigger call performs (see table Operations below)
resource_uri A unique API endpoint that represents the trigger

Operations

Operation Description
REDEPLOY Performs a redeploy service operation.
SCALEUP Performs a scale up service operation.

List all triggers

import tutum

service = tutum.Service.fetch('61a29874-9134-48f9-b460-f37d4bec4826')
trigger = tutum.Trigger.fetch(service)
trigger.list()
GET /api/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("61a29874-9134-48f9-b460-f37d4bec4826")

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

trigger, err := service.ListTriggers()

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

    log.Println(trigger)
tutum trigger list 61a29874-9134-48f9-b460-f37d4bec4826

Lists all current triggers the service has associated to. Returns a list of Service Trigger objects.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/service/(uuid)/trigger/

Path Parameters

Parameter Description
uuid The UUID of the service the triggers are associated to

Create a new trigger

import tutum

service = tutum.Service.fetch('61a29874-9134-48f9-b460-f37d4bec4826')
trigger = tutum.Trigger.fetch(service)
trigger.add(name="mytrigger_name", operation="REDEPLOY")
trigger.save()
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("61a29874-9134-48f9-b460-f37d4bec4826")

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

trigger, err := service.CreateTrigger(tutum.TriggerCreateRequest{Name: "test-trigger", Operation: "REDEPLOY"})

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

log.Println(trigger)
POST /api/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
Content-Type: application/json

{"name": "mytrigger_name", "operation": "REDEPLOY"}
tutum trigger create --name mytrigger_name --operation REDEPLOY 61a29874-9134-48f9-b460-f37d4bec4826

Creates a new service trigger.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/service/(uuid)/trigger/

JSON Parameters

Parameter Description
name (optional) A user provided name for the trigger
operation (optional) The operation to be performed by the trigger (default: “REDEPLOY”)

Get an existing trigger

import tutum

service = tutum.Service.fetch('61a29874-9134-48f9-b460-f37d4bec4826')
trigger = tutum.Trigger.fetch(service)
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("61a29874-9134-48f9-b460-f37d4bec4826")

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

trigger, err := service.GetTrigger("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

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

log.Println(trigger)
GET /api/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json

Get all the details of an specific trigger

Endpoint Type

Available in Tutum’s REST API

HTTP Request

GET /api/v1/service/(uuid)/trigger/(trigger_uuid)/

Path Parameters

Parameter Description
uuid The UUID of the service the triggers are associated to
trigger_uuid The UUID of the trigger to retrieve

Delete a trigger

import tutum

service = tutum.Service.fetch('61a29874-9134-48f9-b460-f37d4bec4826')
trigger = tutum.Trigger.fetch(service)
trigger.delete("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("61a29874-9134-48f9-b460-f37d4bec4826")

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

service.DeleteTrigger("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
DELETE /api/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: dashboard.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
tutum trigger rm 61a29874-9134-48f9-b460-f37d4bec4826 7eaf7fff-882c-4f3d-9a8f-a22317ac00ce

Deletes specific trigger. It will be no longer available to be called.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

DELETE /api/v1/service/(uuid)/trigger/(trigger_uuid)/

Path Parameters

Parameter Description
uuid The UUID of the associated service
trigger_uuid The UUID of the trigger to delete

Call a trigger

import tutum

service = tutum.Service.fetch('61a29874-9134-48f9-b460-f37d4bec4826')
trigger = tutum.Trigger.fetch(service)
trigger.call("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
import "github.com/tutumcloud/go-tutum/tutum"

service, err := tutum.GetService("61a29874-9134-48f9-b460-f37d4bec4826")

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

service.CallTrigger("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
POST /api/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/call/ HTTP/1.1
Host: dashboard.tutum.co
Accept: application/json

Executes the trigger. For SCALEUP triggers, the number of containers to scale up can be passed at the end of the trigger call url, for example /api/v1/service/61a29874-9134-48f9-b460-f37d4bec4826/trigger/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/call/3/.

Endpoint Type

Available in Tutum’s REST API

HTTP Request

POST /api/v1/service/(uuid)/trigger/(trigger_uuid)/call/

Path Parameters

Parameter Description
uuid The UUID of the associated service
trigger_uuid The UUID of the trigger to call

Tutum Events

Tutum Event

Example

{
    "type": "action",
    "action": "update",
    "parents": [
        "/api/v1/container/0b0e3538-88df-4f07-9aed-3a3cc4175076/"
    ],
    "resource_uri": "/api/v1/action/49f0efe8-a704-4a10-b02f-f96344fabadd/",
    "state": "Success"
}

Tutum events are generated every time any of the following objects is created or changes state:

Attributes

Attribute Description
type Type of object that was created or updated. For possible values check the events types table below.
action Type of action that was executed on the object. Posible values: create, update or delete
parents List of resource URIs (REST API) of the parents of the object, according to the “Parent-child hierarchy” table below
resource_uri Resource URI (REST API) of the object that was created or updated. You can do a GET operation on this URL to fetch its details
state The current state of the object

Event types

Type Description
stack Whenever a Stack is created or updated
service Whenever a Service is created or updated
container Whenever a Container is created or updated
nodecluster Whenever a Node Cluster is created or updated
node Whenever a Node is created or updated
action Whenever a Action is created or updated
error Sent when an error occurs on the websocket connection or as part of the authentication process

Parent-child hierarchy

Object type Parent types
Stack (None)
Service Stack
Container Service, Stack, Node, Node Cluster
Node Cluster (None)
Node Node Cluster
Action (object to which the action applies to)

Listen to new Tutum Events

import tutum

def process_event(event):
    print event

events = tutum.TutumEvents()
events.on_message(process_event)
events.run_forever()
import "github.com/tutumcloud/go-tutum/tutum"

c := make(chan tutum.Event)
e := make(chan error)

go tutum.TutumEvents(c, e)

for {
    select {
        case event := <-c:
            log.Println(event)
        case err := <-e:
            log.Println(err)
    }
}
GET /v1/events/ HTTP/1.1
Host: stream.tutum.co
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Connection: Upgrade
Upgrade: websocket
tutum event

Listens for new Tutum Events

Endpoint Type

Available in Tutum’s STREAM API

HTTP Request

GET /v1/events/

Query Parameters

Parameter Description
user The username to authenticate as
token The API Key to authenticate with

Errors

API response structure

{
    "error": "Descriptive error message"
}

The Tutum API uses the following error codes:

Error Code Meaning
400 Bad Request – There’s a problem in the content of your request. Retrying the same request will fail.
401 Unauthorized – Your API key is wrong or your account has been deactivated.
404 Not Found – The requested object cannot be found.
405 Method Not Allowed – The endpoint requested does not implement the method sent.
409 Conflict – The object cannot be created or updated because another object exists with the same unique fields
415 Unsupported Media Type – Make sure you are using Accept and Content-Type headers as application/json and that the data your are POST-ing or PATCH-ing is in valid JSON format.
429 Too Many Requests – You are being throttled because of too many requests in a short period of time.
500 Internal Server Error – There was a server error while processing your request. Try again later, or contact support.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
504 Gateway Timeout – Our API servers are at full capacity. Please try again later.