+
+

Kubernetes API documentation version v1beta1

+

http://server/api/v1beta1

+ + +

Overview

+

The Kubernetes API currently manages 3 main resources: tasks, +replicationControllers, and services. Tasks correspond to +colocated groups of Docker containers with +shared volumes, as supported by Google Cloud Platform's +container-vm +images. +Singleton tasks can be created directly via the /tasks +endpoint. Sets of tasks may created, maintained, and scaled using +replicationControllers. Services create load-balanced targets +for sets of tasks.

+ + +

Resource identifiers

+

Each resource has a string id and list of key-value +labels. The id is generated by the system and is guaranteed +to be unique in space and time across all resources. labels +is a map of string (key) to string (value). Each resource may +have at most one label with a particular key. Individual labels +are used to specify identifying metadata that can be used to +define sets of resources by specifying required labels. Examples +of typical task label keys include stage, service, name, +tier, partition, and track, but you are free to develop +your own conventions.

+ + +

Creation semantics

+

Creation is currently not idempotent. We plan to add a +modification token to each resource. A unique value for the token +should be provided by the user during creation. If the user +specifies a duplicate token at creation time, the system should +return an error with a pointer to the exiting resource with that +token. In this way a user can deterministically recover from a +dropped connection during a resource creation request.

+ + +

Update semantics

+

Custom verbs are minimized and are used only for 'edge triggered' +actions such as a reboot. Resource descriptions are generally set +up with desiredState for the user provided parameters and +currentState for the actual system state. While consistent +terminology is used across these two stanzas they do not match +member for member.

+

When a new version of a resource is PUT the desiredState is +updated and available immediately. Over time the system will work +to bring the currentState into line with the desiredState. The +system will drive toward the most recent desiredState regardless +of previous versions of that stanza. In other words, if a value +is changed from 2 to 5 in one PUT and then back down to 3 in +another PUT the system isn't required to 'touch base' at 5 before +making 3 the currentState.

+

When doing an update, we assume that the entire desiredState +stanza is specified. If a field is omitted it is assumed that the +user is looking to delete that field. It is viable for a user to +GET the resource, modify what they like in the desiredState or +labels stanzas and then PUT it back. If the currentState is +included in the PUT it will be silently ignored.

+

While currently unspecified, it is intended that concurrent +modification should be accomplished with optimistic locking of +resources. We plan to add a modification token to each resource. If +this is included with the PUT operation the system will verify +that there haven't been other successful mutations to the +resource during a read/modify/write cycle. The correct client +action at this point is to GET the resource again, apply the +changes afresh and try submitting again.

+

Note that updates currently only work for replicationControllers +and services, but not for tasks. Label updates have not yet been +implemented, either.

+ + +
+ + +
+
+

/tasks

+
+ +
+ + +
+
+
+

+ +

+
+
+
+
+ + + get + List all tasks on this cluster + + + + post + Create a new task. currentState is ignored if present. + + +
+
+
+ + +
+
+
+
+ + +
+
+

List all tasks on this cluster

+
+ + + + + +
+
+ + + + + +
+ + +
+ +

HTTP status code 200

+ + + + + +

Body

+ +

Type: application/json

+ + + Example: + 
{
+    "items": [
+        {
+            "id": "my-task-1",
+            "labels": {
+                "name": "testRun",
+                "replicationController": "testRun"
+            },
+            "desiredState": {
+              "manifest": {
+                "containers": [{
+                  "image": "dockerfile/nginx",
+                  "ports": [{
+                    "hostPort": 8080,
+                    "containerPort": 80
+                  }]
+                }
+              }
+            },
+            "currentState": {
+                "host": "host-1"
+            }
+        },
+        {
+            "id": "my-task-2",
+            "labels": {
+                "name": "testRun",
+                "replicationController": "testRun"
+            },
+            "desiredState": {
+              "manifest": {
+                "containers": [{
+                  "image": "dockerfile/nginx",
+                  "ports": [{
+                    "hostPort": 8080,
+                    "containerPort": 80
+                  }]
+                }
+              }
+            },
+            "currentState": {
+                "host": "host-2"
+            }
+        }
+    ]
+}
+ + + + +
+ +
+
+
+
+
+ +
+
+
+
+ + +
+
+

Create a new task. currentState is ignored if present.

+
+ + + + + +
+
+ + + + + +

Body

+ +

Type: json/application

+ + + Schema: + 
{
+  "$schema": "http://json-schema.org/draft-03/schema",
+  "type": "object",
+  "required": false,
+  "description": "Task resource. A task corresponds to a colocated group of [Docker containers](http://docker.io).",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "required": false
+    },
+    "creationTimestamp": {
+      "type": "string",
+      "required": false
+    },
+    "selfLink": {
+      "type": "string",
+      "required": false
+    },
+    "desiredState": {
+      "type": "object",
+      "required": false,
+      "description": "The desired configuration of the task",
+      "properties": {
+        "manifest": {
+          "type": "object",
+          "required": false,
+          "description": "Manifest describing group of [Docker containers](http://docker.io); compatible with format used by [Google Cloud Platform's container-vm images](https://developers.google.com/compute/docs/containers)"
+        },
+        "status": {
+          "type": "string",
+          "required": false,
+          "description": ""
+        },
+        "host": {
+          "type": "string",
+          "required": false,
+          "description": ""
+        },
+        "hostIP": {
+          "type": "string",
+          "required": false,
+          "description": ""
+        },
+        "info": {
+          "type": "object",
+          "required": false,
+          "description": ""
+        }
+      }
+    },
+    "currentState": {
+      "type": "object",
+      "required": false,
+      "description": "The current configuration and status of the task. Fields in common with desiredState have the same meaning.",
+      "properties": {
+        "manifest": {
+          "type": "object",
+          "required": false
+        },
+        "status": {
+          "type": "string",
+          "required": false
+        },
+        "host": {
+          "type": "string",
+          "required": false
+        },
+        "hostIP": {
+          "type": "string",
+          "required": false
+        },
+        "info": {
+          "type": "object",
+          "required": false
+        }
+      }
+    },
+    "labels": {
+      "type": "object",
+      "required": false
+    }
+  }
+}
+
+ + + Example: + 
{
+  "id": "php",
+  "desiredState": {
+    "manifest": {
+      "containers": [{
+        "image": "dockerfile/nginx",
+        "ports": [{
+          "containerPort": 80,
+          "hostPort": 8080
+        }]
+      }]
+    }
+  },
+  "labels": {
+    "name": "foo"
+  }
+}
+    
+
+ + + +
+ + +
+
+
+
+
+ +
+ + +
+
+

+ +

+
+
+
+
+ + + get + Get a specific task + + + + put + Update a task + + + + delete + Delete a specific task + + +
+
+
+ + +
+
+
+
+ + +
+
+

Get a specific task

+
+ + + + + +
+
+ +

URI Parameters

+
    + +
  • taskId: string
    • + +
+ + + + + +
+ + +
+ +

HTTP status code 200

+ + + + + +

Body

+ +

Type: application/json

+ + + Example: + 
{
+  "id": "php",
+  "desiredState": {
+    "manifest": {
+      "containers": [{
+        "image": "dockerfile/nginx",
+        "ports": [{
+          "containerPort": 80,
+          "hostPort": 8080
+        }]
+      }]
+    }
+  },
+  "labels": {
+    "name": "foo"
+  }
+}
+    
+
+ + + + +
+ +
+
+
+
+
+ +
+
+
+
+ + +
+
+

Update a task

+
+ + + + + +
+
+ +

URI Parameters

+
    + +
  • taskId: string
    • + +
+ + + + + +

Body

+ +

Type: json/application

+ + + Schema: + 
{
+  "$schema": "http://json-schema.org/draft-03/schema",
+  "type": "object",
+  "required": false,
+  "description": "Task resource. A task corresponds to a colocated group of [Docker containers](http://docker.io).",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "required": false
+    },
+    "creationTimestamp": {
+      "type": "string",
+      "required": false
+    },
+    "selfLink": {
+      "type": "string",
+      "required": false
+    },
+    "desiredState": {
+      "type": "object",
+      "required": false,
+      "description": "The desired configuration of the task",
+      "properties": {
+        "manifest": {
+          "type": "object",
+          "required": false,
+          "description": "Manifest describing group of [Docker containers](http://docker.io); compatible with format used by [Google Cloud Platform's container-vm images](https://developers.google.com/compute/docs/containers)"
+        },
+        "status": {
+          "type": "string",
+          "required": false,
+          "description": ""
+        },
+        "host": {
+          "type": "string",
+          "required": false,
+          "description": ""
+        },
+        "hostIP": {
+          "type": "string",
+          "required": false,
+          "description": ""
+        },
+        "info": {
+          "type": "object",
+          "required": false,
+          "description": ""
+        }
+      }
+    },
+    "currentState": {
+      "type": "object",
+      "required": false,
+      "description": "The current configuration and status of the task. Fields in common with desiredState have the same meaning.",
+      "properties": {
+        "manifest": {
+          "type": "object",
+          "required": false
+        },
+        "status": {
+          "type": "string",
+          "required": false
+        },
+        "host": {
+          "type": "string",
+          "required": false
+        },
+        "hostIP": {
+          "type": "string",
+          "required": false
+        },
+        "info": {
+          "type": "object",
+          "required": false
+        }
+      }
+    },
+    "labels": {
+      "type": "object",
+      "required": false
+    }
+  }
+}
+
+ + + Example: + 
{
+  "id": "php",
+  "desiredState": {
+    "manifest": {
+      "containers": [{
+        "image": "dockerfile/nginx",
+        "ports": [{
+          "containerPort": 80,
+          "hostPort": 8080
+        }]
+      }]
+    }
+  },
+  "labels": {
+    "name": "foo"
+  }
+}
+    
+
+ + + +
+ + +
+
+
+
+
+ +
+
+
+
+ + +
+
+

Delete a specific task

+
+ + + + + +
+
+ +

URI Parameters

+
    + +
  • taskId: string
    • + +
+ + + + + +
+ + +
+ +

HTTP status code 200

+ + + + + +

Body

+ +

Type: application/json

+ + + Example: + 
{ 
+  "success": true
+}
+
+ + + + +
+ +
+
+
+
+
+ +
+ + + + + +
+
+
+ +
+
+

/replicationControllers

+
+ +
+ + +
+
+
+

+ +

+
+
+
+
+ + + get + List all replicationControllers on this cluster + + + + post + Create a new controller. currentState is ignored if present. + + +
+
+
+ + +
+
+
+
+ + +
+
+

List all replicationControllers on this cluster

+
+ + + + + +
+
+ + + + + +
+ + +
+ +

HTTP status code 200

+ + + + + +

Body

+ +

Type: application/json

+ + + Example: + 
{
+    "items": [
+        {
+            "id": "testRun",
+            "desiredState": {
+                "replicas": 2,
+                "replicasInSet": {
+                    "name": "testRun"
+                },
+                "taskTemplate": {
+                    "desiredState": {
+                        "image": "dockerfile/nginx",
+                        "networkPorts": [
+                            {
+                                "hostPort": 8080,
+                                "containerPort": 80
+                            }
+                        ]
+                    },
+                    "labels": {
+                        "name": "testRun"
+                    }
+                }
+            },
+            "labels": {
+                "name": "testRun"
+            }
+        }
+    ]
+}
+ + + + +
+ +
+
+
+
+
+ +
+
+
+
+ + +
+
+

Create a new controller. currentState is ignored if present.

+
+ + + + + +
+
+ + + + + +

Body

+ +

Type: json/application

+ + + Schema: + 
{
+  "$schema": "http://json-schema.org/draft-03/schema",
+  "type": "object",
+  "required": false,
+  "description": "A replicationController resource. A replicationController helps to create and manage a set of tasks. It acts as a factory to create new tasks based on a template. It ensures that there are a specific number of tasks running. If fewer tasks are running than `replicas` then the needed tasks are generated using `taskTemplate`. If more tasks are running than `replicas`, then excess tasks are deleted.",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "required": false
+    },
+    "creationTimestamp": {
+      "type": "string",
+      "required": false
+    },
+    "selfLink": {
+      "type": "string",
+      "required": false
+    },
+    "desiredState": {
+      "type": "object",
+      "required": false,
+      "description": "The desired configuration of the replicationController",
+      "properties": {
+        "replicas": {
+          "type": "number",
+          "required": false,
+          "description": "Number of tasks desired in the set"
+        },
+        "replicasInSet": {
+          "type": "object",
+          "required": false,
+          "description": "Required labels used to identify tasks in the set"
+        },
+        "taskTemplate": {
+          "type": "object",
+          "required": false,
+          "description": "Template from which to create new tasks, as necessary. Identical to task schema."
+        }
+      }
+    },
+    "labels": {
+      "type": "object",
+      "required": false
+    }
+  }
+}
+
+ + + Example: + 
  {
+    "id": "nginxController",
+    "desiredState": {
+      "replicas": 2,
+      "replicasInSet": {"name": "nginx"},
+      "taskTemplate": {
+        "desiredState": {
+           "manifest": {
+             "containers": [{
+               "image": "dockerfile/nginx",
+               "ports": [{"containerPort": 80, "hostPort": 8080}]
+             }]
+           }
+         },
+         "labels": {"name": "nginx"}
+        }},
+    "labels": {"name": "nginx"}
+  }
+
+ + + +
+ + +
+
+
+
+
+ +
+ + +
+
+

+ +

+
+
+
+
+ + + get + Get a specific controller + + + + put + Update a controller + + + + delete + Delete a specific controller + + +
+
+
+ + +
+
+
+
+ + +
+
+

Get a specific controller

+
+ + + + + +
+
+ +

URI Parameters

+
    + +
  • controllerId: string
    • + +
+ + + + + +
+ + +
+ +

HTTP status code 200

+ + + + + +

Body

+ +

Type: application/json

+ + + Example: + 
  {
+    "id": "nginxController",
+    "desiredState": {
+      "replicas": 2,
+      "replicasInSet": {"name": "nginx"},
+      "taskTemplate": {
+        "desiredState": {
+           "manifest": {
+             "containers": [{
+               "image": "dockerfile/nginx",
+               "ports": [{"containerPort": 80, "hostPort": 8080}]
+             }]
+           }
+         },
+         "labels": {"name": "nginx"}
+        }},
+    "labels": {"name": "nginx"}
+  }
+
+ + + + +
+ +
+
+
+
+
+ +
+
+
+
+ + +
+
+

Update a controller

+
+ + + + + +
+
+ +

URI Parameters

+
    + +
  • controllerId: string
    • + +
+ + + + + +

Body

+ +

Type: json/application

+ + + Schema: + 
{
+  "$schema": "http://json-schema.org/draft-03/schema",
+  "type": "object",
+  "required": false,
+  "description": "A replicationController resource. A replicationController helps to create and manage a set of tasks. It acts as a factory to create new tasks based on a template. It ensures that there are a specific number of tasks running. If fewer tasks are running than `replicas` then the needed tasks are generated using `taskTemplate`. If more tasks are running than `replicas`, then excess tasks are deleted.",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "required": false
+    },
+    "creationTimestamp": {
+      "type": "string",
+      "required": false
+    },
+    "selfLink": {
+      "type": "string",
+      "required": false
+    },
+    "desiredState": {
+      "type": "object",
+      "required": false,
+      "description": "The desired configuration of the replicationController",
+      "properties": {
+        "replicas": {
+          "type": "number",
+          "required": false,
+          "description": "Number of tasks desired in the set"
+        },
+        "replicasInSet": {
+          "type": "object",
+          "required": false,
+          "description": "Required labels used to identify tasks in the set"
+        },
+        "taskTemplate": {
+          "type": "object",
+          "required": false,
+          "description": "Template from which to create new tasks, as necessary. Identical to task schema."
+        }
+      }
+    },
+    "labels": {
+      "type": "object",
+      "required": false
+    }
+  }
+}
+
+ + + Example: + 
  {
+    "id": "nginxController",
+    "desiredState": {
+      "replicas": 2,
+      "replicasInSet": {"name": "nginx"},
+      "taskTemplate": {
+        "desiredState": {
+           "manifest": {
+             "containers": [{
+               "image": "dockerfile/nginx",
+               "ports": [{"containerPort": 80, "hostPort": 8080}]
+             }]
+           }
+         },
+         "labels": {"name": "nginx"}
+        }},
+    "labels": {"name": "nginx"}
+  }
+
+ + + +
+ + +
+
+
+
+
+ +
+
+
+
+ + +
+
+

Delete a specific controller

+
+ + + + + +
+
+ +

URI Parameters

+
    + +
  • controllerId: string
    • + +
+ + + + + +
+ + +
+ +

HTTP status code 200

+ + + + + +

Body

+ +

Type: application/json

+ + + Example: + 
{ 
+  "success": true
+}
+
+ + + + +
+ +
+
+
+
+
+ +
+ + + + + +
+
+
+ +
+
+

/services

+
+ +
+ + +
+
+
+

+ +

+
+
+
+
+ + + get + List all services on this cluster + + + + post + Create a new service + + +
+
+
+ + +
+
+
+
+ + +
+
+

List all services on this cluster

+
+ + + + + +
+
+ + + + + +
+ + +
+ +

HTTP status code 200

+ + + + + +

Body

+ +

Type: application/json

+ + + Example: + 
{
+    "items": [
+        {
+            "id": "example1",
+            "port": 8000,
+            "labels": {
+                "name": "nginx"
+            }
+        },
+        {
+            "id": "example2",
+            "port": 8080,
+            "labels": {
+                "env": "prod",
+                "name": "jetty"
+            }
+        }
+    ]
+}
+
+ + + + +
+ +
+
+
+
+
+ +
+
+
+
+ + +
+
+

Create a new service

+
+ + + + + +
+
+ + + + + +

Body

+ +

Type: json/application

+ + + Schema: + 
{
+  "$schema": "http://json-schema.org/draft-03/schema",
+  "type": "object",
+  "required": false,
+  "description": "A service resource.",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "required": false
+    },
+    "creationTimestamp": {
+      "type": "string",
+      "required": false
+    },
+    "selfLink": {
+      "type": "string",
+      "required": false
+    },
+    "name": {
+      "type": "string",
+      "required": false
+    },
+    "port": {
+      "type": "number",
+      "required": false
+    },
+    "labels": {
+      "type": "object",
+      "required": false
+    }
+  }
+}
+
+ + + Example: + 
{
+  "id": "example2",
+  "port": 8000,
+  "labels": {
+     "name": "nginx"
+  }
+}
+
+ + + +
+ + +
+
+
+
+
+ +
+ + +
+
+

+ +

+
+
+
+
+ + + get + Get a specific service + + + + put + Update a service + + + + delete + Delete a specific service + + +
+
+
+ + +
+
+
+
+ + +
+
+

Get a specific service

+
+ + + + + +
+
+ +

URI Parameters

+
    + +
  • serviceId: string
    • + +
+ + + + + +
+ + +
+ +

HTTP status code 200

+ + + + + +

Body

+ +

Type: application/json

+ + + Example: + 
{
+  "id": "example2",
+  "port": 8000,
+  "labels": {
+     "name": "nginx"
+  }
+}
+
+ + + + +
+ +
+
+
+
+
+ +
+
+
+
+ + +
+
+

Update a service

+
+ + + + + +
+
+ +

URI Parameters

+
    + +
  • serviceId: string
    • + +
+ + + + + +

Body

+ +

Type: json/application

+ + + Schema: + 
{
+  "$schema": "http://json-schema.org/draft-03/schema",
+  "type": "object",
+  "required": false,
+  "description": "A service resource.",
+  "properties": {
+    "kind": {
+      "type": "string",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "required": false
+    },
+    "creationTimestamp": {
+      "type": "string",
+      "required": false
+    },
+    "selfLink": {
+      "type": "string",
+      "required": false
+    },
+    "name": {
+      "type": "string",
+      "required": false
+    },
+    "port": {
+      "type": "number",
+      "required": false
+    },
+    "labels": {
+      "type": "object",
+      "required": false
+    }
+  }
+}
+
+ + + Example: + 
{
+  "id": "example2",
+  "port": 8000,
+  "labels": {
+     "name": "nginx"
+  }
+}
+
+ + + +
+ + +
+
+
+
+
+ +
+
+
+
+ + +
+
+

Delete a specific service

+
+ + + + + +
+
+ +

URI Parameters

+
    + +
  • serviceId: string
    • + +
+ + + + + +
+ + +
+ +

HTTP status code 200

+ + + + + +

Body

+ +

Type: application/json

+ + + Example: + 
{ 
+  "success": true
+}
+
+ + + + +
+ +
+
+
+
+
+ +
+ + + + + +
+
+
+ +