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
}