</style></head><bodydata-spy=scrolldata-target=#sidebar><divclass=container><divclass=row><divclass=col-md-9role=main><divclass=page-header><h1>Kubernetes API documentation <small>version v1beta1</small></h1><p>http://server/api/v1beta1</p><h3id=Overview><ahref=#Overview>Overview</a></h3><p>The Kubernetes API currently manages 3 main resources: <code>pods</code>, <code>replicationControllers</code>, and <code>services</code>. Pods correspond to colocated groups of <ahref=http://docker.io>Docker containers</a> with shared volumes, as supported by <ahref=https://developers.google.com/compute/docs/containers>Google Cloud Platform's container-vm images</a>. Singleton pods can be created directly via the <code>/pods</code> endpoint. Sets of pods may created, maintained, and scaled using replicationControllers. Services create load-balanced targets for sets of pods.</p><h3id=Resource-identifiers><ahref=#Resource-identifiers>Resource identifiers</a></h3><p>Each resource has a string <code>id</code> and list of key-value <code>labels</code>. The <code>id</code> is generated by the system and is guaranteed to be unique in space and time across all resources. <code>labels</code> 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 pod label keys include <code>stage</code>, <code>service</code>, <code>name</code>, <code>tier</code>, <code>partition</code>, and <code>track</code>, but you are free to develop your own conventions.</p><h3id=Creation-semantics><ahref=#Creation-semantics>Creation semantics</a></h3><p>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 existing resource with that token. In this way a user can deterministically recover from a dropped connection during a resource creation request.</p><h3id=Update-semantics><ahref=#Update-semantics>Update semantics</a></h3><p>Custom verbs are minimized and are used only for 'edge triggered' actions such as a reboot. Resource descriptions are generally set up with <code>desiredState</code> for the user provided parameters and <code>currentState</code> for the actual system state. While consistent terminology is used across these two stanzas they do not match member for member.</p><p>When a new version of a resource is PUT the <code>desiredState</code> is updated and available immediately. Over time the system will work to bring the <code>currentState</code> into line with the <code>desiredState</code>. The system will drive toward the most recent <code>desiredState</code> 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 <code>currentState</code>.</p><p>When doing an update, we assume that the entire <code>desiredState</code> 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 <code>desiredState</code> or labels stanzas and then PUT it back. If the <code>currentState</code> is included in the PUT it will be silently ignored.</p><p>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.</p><p>Note
</code></pre></small></p></div></div></div></div></div></div><divclass="modal fade"tabindex=0id=_pods_post><divclass=modal-dialog><divclass=modal-content><divclass=modal-header><buttontype=buttonclass=closedata-dismiss=modalaria-hidden=true>×</button><h4class=modal-titleid=myModalLabel><spanclass="badge badge_post">post</span><spanclass=parent></span>/pods</h4></div><divclass=modal-body><divclass="alert alert-info"><p>Create a new pod. currentState is ignored if present.</p></div><ulclass="nav nav-tabs"><liclass=active><ahref=#_pods_post_requestdata-toggle=tab>Request</a></li></ul><divclass=tab-content><divclass="tab-pane active"id=_pods_post_request><h3>Body</h3><p><strong>Type: application/json</strong></p><p><small><strong>Schema</strong>:<pre><code>{
"description": "Pod resource. A pod corresponds to a co-located 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 pod",
"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 pod. Fields in common with desiredState have the same meaning.",
</code></pre></small></p></div></div></div></div></div></div></div><divclass="panel panel-white"><divclass=panel-heading><h4class=panel-title><aclass=collapseddata-toggle=collapsehref=#panel__pods__podId_><spanclass=parent>/pods</span>/{podId}</a><spanclass=methods><ahref=#data-toggle=modaldata-target=#_pods__podId__get><spanclass="badge badge_get">get</span></a><ahref=#data-toggle=modaldata-target=#_pods__podId__put><spanclass="badge badge_put">put</span></a><ahref=#data-toggle=modaldata-target=#_pods__podId__delete><spanclass="badge badge_delete">delete</span></a></span></h4></div><divid=panel__pods__podId_class="panel-collapse collapse"><divclass=panel-body><divclass=list-group><ahref=#data-toggle=modaldata-target=#_pods__podId__getclass=list-group-item><spanclass="badge badge_get">get</span><divclass=method_description><p>Get a specific pod</p></div><divclass=clearfix></div></a><ahref=#data-toggle=modaldata-target=#_pods__podId__putclass=list-group-item><spanclass="badge badge_put">put</span><divclass=method_description><p>Update a pod</p></div><divclass=clearfix></div></a><ahref=#data-toggle=modaldata-target=#_pods__podId__deleteclass=list-group-item><spanclass="badge badge_delete">delete</span><divclass=method_description><p>Delete a specific pod</p></div><divclass=clearfix></div></a></div></div></div><divclass="modal fade"tabindex=0id=_pods__podId__get><divclass=modal-dialog><divclass=modal-content><divclass=modal-header><buttontype=buttonclass=closedata-dismiss=modalaria-hidden=true>×</button><h4class=modal-titleid=myModalLabel><spanclass="badge badge_get">get</span><spanclass=parent>/pods</span>/{podId}</h4></div><divclass=modal-body><divclass="alert alert-info"><p>Get a specific pod</p></div><ulclass="nav nav-tabs"><liclass=active><ahref=#_pods__podId__get_requestdata-toggle=tab>Request</a></li><li><ahref=#_pods__podId__get_responsedata-toggle=tab>Response</a></li></ul><divclass=tab-content><divclass="tab-pane active"id=_pods__podId__get_request><h3>URI Parameters</h3><ul><li><strong>podId</strong>: <em>required (string)</em></li></ul></div><divclass=tab-paneid=_pods__podId__get_response><h2>HTTP status code <ahref=http://httpstatus.es/200target=_blank>200</a></h2><h3>Body</h3><p><strong>Type: application/json</strong></p><p><small><strong>Example</strong>:<pre><code>{
"description": "Pod resource. A pod corresponds to a co-located 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 pod",
"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 pod. Fields in common with desiredState have the same meaning.",
</code></pre></small></p></div></div></div></div></div></div><divclass="modal fade"tabindex=0id=_pods__podId__delete><divclass=modal-dialog><divclass=modal-content><divclass=modal-header><buttontype=buttonclass=closedata-dismiss=modalaria-hidden=true>×</button><h4class=modal-titleid=myModalLabel><spanclass="badge badge_delete">delete</span><spanclass=parent>/pods</span>/{podId}</h4></div><divclass=modal-body><divclass="alert alert-info"><p>Delete a specific pod</p></div><ulclass="nav nav-tabs"><liclass=active><ahref=#_pods__podId__delete_requestdata-toggle=tab>Request</a></li><li><ahref=#_pods__podId__delete_responsedata-toggle=tab>Response</a></li></ul><divclass=tab-content><divclass="tab-pane active"id=_pods__podId__delete_request><h3>URI Parameters</h3><ul><li><strong>podId</strong>: <em>required (string)</em></li></ul></div><divclass=tab-paneid=_pods__podId__delete_response><h2>HTTP status code <ahref=http://httpstatus.es/200target=_blank>200</a></h2><h3>Body</h3><p><strong>Type: application/json</strong></p><p><small><strong>Example</strong>:<pre><code>{
"success": true
}
</code></pre></small></p></div></div></div></div></div></div></div></div></div></div><divclass="panel panel-default"><divclass=panel-heading><h3id=_replicationControllersclass=panel-title>/replicationControllers</h3></div><divclass=panel-body><divclass=panel-group><divclass="panel panel-white"><divclass=panel-heading><h4class=panel-title><aclass=collapseddata-toggle=collapsehref=#panel__replicationControllers><spanclass=parent></span>/replicationControllers</a><spanclass=methods><ahref=#data-toggle=modaldata-target=#_replicationControllers_get><spanclass="badge badge_get">get</span></a><ahref=#data-toggle=modaldata-target=#_replicationControllers_post><spanclass="badge badge_post">post</span></a></span></h4></div><divid=panel__replicationControllersclass="panel-collapse collapse"><divclass=panel-body><divclass=list-group><ahref=#data-toggle=modaldata-target=#_replicationControllers_getclass=list-group-item><spanclass="badge badge_get">get</span><divclass=method_description><p>List all replicationControllers on this cluster</p></div><divclass=clearfix></div></a><ahref=#data-toggle=modaldata-target=#_replicationControllers_postclass=list-group-item><spanclass="badge badge_post">post</span><divclass=method_description><p>Create a new controller. currentState is ignored if present.</p></div><divclass=clearfix></div></a></div></div></div><divclass="modal fade"tabindex=0id=_replicationControllers_get><divclass=modal-dialog><divclass=modal-content><divclass=modal-header><buttontype=buttonclass=closedata-dismiss=modalaria-hidden=true>×</button><h4class=modal-titleid=myModalLabel><spanclass="badge badge_get">get</span><spanclass=parent></span>/replicationControllers</h4></div><divclass=modal-body><divclass="alert alert-info"><p>List all replicationControllers on this cluster</p></div><ulclass="nav nav-tabs"><liclass=active><ahref=#_replicationControllers_get_requestdata-toggle=tab>Request</a></li><li><ahref=#_replicationControllers_get_responsedata-toggle=tab>Response</a></li></ul><divclass=tab-content><divclass="tab-pane active"id=_replicationControllers_get_request></div><divclass=tab-paneid=_replicationControllers_get_response><h2>HTTP status code <ahref=http://httpstatus.es/200target=_blank>200</a></h2><h3>Body</h3><p><strong>Type: application/json</strong></p><p><small><strong>Example</strong>:<pre><code>{
</code></pre></small></p></div></div></div></div></div></div><divclass="modal fade"tabindex=0id=_replicationControllers_post><divclass=modal-dialog><divclass=modal-content><divclass=modal-header><buttontype=buttonclass=closedata-dismiss=modalaria-hidden=true>×</button><h4class=modal-titleid=myModalLabel><spanclass="badge badge_post">post</span><spanclass=parent></span>/replicationControllers</h4></div><divclass=modal-body><divclass="alert alert-info"><p>Create a new controller. currentState is ignored if present.</p></div><ulclass="nav nav-tabs"><liclass=active><ahref=#_replicationControllers_post_requestdata-toggle=tab>Request</a></li></ul><divclass=tab-content><divclass="tab-pane active"id=_replicationControllers_post_request><h3>Body</h3><p><strong>Type: application/json</strong></p><p><small><strong>Schema</strong>:<pre><code>{
"description": "A replicationController resource. A replicationController helps to create and manage a set of pods. It acts as a factory to create new pods based on a template. It ensures that there are a specific number of pods running. If fewer pods are running than `replicas` then the needed pods are generated using `podTemplate`. If more pods are running than `replicas`, then excess pods 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 pods desired in the set"
},
"replicaSelector": {
"type": "object",
"required": false,
"description": "Required labels used to identify pods in the set"
},
"podTemplate": {
"type": "object",
"required": false,
"description": "Template from which to create new pods, as necessary. Identical to pod schema."
</code></pre></small></p></div></div></div></div></div></div></div><divclass="panel panel-white"><divclass=panel-heading><h4class=panel-title><aclass=collapseddata-toggle=collapsehref=#panel__replicationControllers__controllerId_><spanclass=parent>/replicationControllers</span>/{controllerId}</a><spanclass=methods><ahref=#data-toggle=modaldata-target=#_replicationControllers__controllerId__get><spanclass="badge badge_get">get</span></a><ahref=#data-toggle=modaldata-target=#_replicationControllers__controllerId__put><spanclass="badge badge_put">put</span></a><ahref=#data-toggle=modaldata-target=#_replicationControllers__controllerId__delete><spanclass="badge badge_delete">delete</span></a></span></h4></div><divid=panel__replicationControllers__controllerId_class="panel-collapse collapse"><divclass=panel-body><divclass=list-group><ahref=#data-toggle=modaldata-target=#_replicationControllers__controllerId__getclass=list-group-item><spanclass="badge badge_get">get</span><divclass=method_description><p>Get a specific controller</p></div><divclass=clearfix></div></a><ahref=#data-toggle=modaldata-target=#_replicationControllers__controllerId__putclass=list-group-item><spanclass="badge badge_put">put</span><divclass=method_description><p>Update a controller</p></div><divclass=clearfix></div></a><ahref=#data-toggle=modaldata-target=#_replicationControllers__controllerId__deleteclass=list-group-item><spanclass="badge badge_delete">delete</span><divclass=method_description><p>Delete a specific controller</p></div><divclass=clearfix></div></a></div></div></div><divclass="modal fade"tabindex=0id=_replicationControllers__controllerId__get><divclass=modal-dialog><divclass=modal-content><divclass=modal-header><buttontype=buttonclass=closedata-dismiss=modalaria-hidden=true>×</button><h4class=modal-titleid=myModalLabel><spanclass="badge badge_get">get</span><spanclass=parent>/replicationControllers</span>/{controllerId}</h4></div><divclass=modal-body><divclass="alert alert-info"><p>Get a specific controller</p></div><ulclass="nav nav-tabs"><liclass=active><ahref=#_replicationControllers__controllerId__get_requestdata-toggle=tab>Request</a></li><li><ahref=#_replicationControllers__controllerId__get_responsedata-toggle=tab>Response</a></li></ul><divclass=tab-content><divclass="tab-pane active"id=_replicationControllers__controllerId__get_request><h3>URI Parameters</h3><ul><li><strong>controllerId</strong>: <em>required (string)</em></li></ul></div><divclass=tab-paneid=_replicationControllers__controllerId__get_response><h2>HTTP status code <ahref=http://httpstatus.es/200target=_blank>200</a></h2><h3>Body</h3><p><strong>Type: application/json</strong></p><p><small><strong>Example</strong>:<pre><code> {
"description": "A replicationController resource. A replicationController helps to create and manage a set of pods. It acts as a factory to create new pods based on a template. It ensures that there are a specific number of pods running. If fewer pods are running than `replicas` then the needed pods are generated using `podTemplate`. If more pods are running than `replicas`, then excess pods 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 pods desired in the set"
},
"replicaSelector": {
"type": "object",
"required": false,
"description": "Required labels used to identify pods in the set"
},
"podTemplate": {
"type": "object",
"required": false,
"description": "Template from which to create new pods, as necessary. Identical to pod schema."
</code></pre></small></p></div></div></div></div></div></div><divclass="modal fade"tabindex=0id=_replicationControllers__controllerId__delete><divclass=modal-dialog><divclass=modal-content><divclass=modal-header><buttontype=buttonclass=closedata-dismiss=modalaria-hidden=true>×</button><h4class=modal-titleid=myModalLabel><spanclass="badge badge_delete">delete</span><spanclass=parent>/replicationControllers</span>/{controllerId}</h4></div><divclass=modal-body><divclass="alert alert-info"><p>Delete a specific controller</p></div><ulclass="nav nav-tabs"><liclass=active><ahref=#_replicationControllers__controllerId__delete_requestdata-toggle=tab>Request</a></li><li><ahref=#_replicationControllers__controllerId__delete_responsedata-toggle=tab>Response</a></li></ul><divclass=tab-content><divclass="tab-pane active"id=_replicationControllers__controllerId__delete_request><h3>URI Parameters</h3><ul><li><strong>controllerId</strong>: <em>required (string)</em></li></ul></div><divclass=tab-paneid=_replicationControllers__controllerId__delete_response><h2>HTTP status code <ahref=http://httpstatus.es/200target=_blank>200</a></h2><h3>Body</h3><p><strong>Type: application/json</strong></p><p><small><strong>Example</strong>:<pre><code>{
"success": true
}
</code></pre></small></p></div></div></div></div></div></div></div></div></div></div><divclass="panel panel-default"><divclass=panel-heading><h3id=_servicesclass=panel-title>/services</h3></div><divclass=panel-body><divclass=panel-group><divclass="panel panel-white"><divclass=panel-heading><h4class=panel-title><aclass=collapseddata-toggle=collapsehref=#panel__services><spanclass=parent></span>/services</a><spanclass=methods><ahref=#data-toggle=modaldata-target=#_services_get><spanclass="badge badge_get">get</span></a><ahref=#data-toggle=modaldata-target=#_services_post><spanclass="badge badge_post">post</span></a></span></h4></div><divid=panel__servicesclass="panel-collapse collapse"><divclass=panel-body><divclass=list-group><ahref=#data-toggle=modaldata-target=#_services_getclass=list-group-item><spanclass="badge badge_get">get</span><divclass=method_description><p>List all services on this cluster</p></div><divclass=clearfix></div></a><ahref=#data-toggle=modaldata-target=#_services_postclass=list-group-item><spanclass="badge badge_post">post</span><divclass=method_description><p>Create a new service</p></div><divclass=clearfix></div></a></div></div></div><divclass="modal fade"tabindex=0id=_services_get><divclass=modal-dialog><divclass=modal-content><divclass=modal-header><buttontype=buttonclass=closedata-dismiss=modalaria-hidden=true>×</button><h4class=modal-titleid=myModalLabel><spanclass="badge badge_get">get</span><spanclass=parent></span>/services</h4></div><divclass=modal-body><divclass="alert alert-info"><p>List all services on this cluster</p></div><ulclass="nav nav-tabs"><liclass=active><ahref=#_services_get_requestdata-toggle=tab>Request</a></li><li><ahref=#_services_get_responsedata-toggle=tab>Response</a></li></ul><divclass=tab-content><divclass="tab-pane active"id=_services_get_request></div><divclass=tab-paneid=_services_get_response><h2>HTTP status code <ahref=http://httpstatus.es/200target=_blank>200</a></h2><h3>Body</h3><p><strong>Type: application/json</strong></p><p><small><strong>Example</strong>:<pre><code>{
</code></pre></small></p></div></div></div></div></div></div><divclass="modal fade"tabindex=0id=_services_post><divclass=modal-dialog><divclass=modal-content><divclass=modal-header><buttontype=buttonclass=closedata-dismiss=modalaria-hidden=true>×</button><h4class=modal-titleid=myModalLabel><spanclass="badge badge_post">post</span><spanclass=parent></span>/services</h4></div><divclass=modal-body><divclass="alert alert-info"><p>Create a new service</p></div><ulclass="nav nav-tabs"><liclass=active><ahref=#_services_post_requestdata-toggle=tab>Request</a></li></ul><divclass=tab-content><divclass="tab-pane active"id=_services_post_request><h3>Body</h3><p><strong>Type: application/json</strong></p><p><small><strong>Schema</strong>:<pre><code>{
</code></pre></small></p></div></div></div></div></div></div></div><divclass="panel panel-white"><divclass=panel-heading><h4class=panel-title><aclass=collapseddata-toggle=collapsehref=#panel__services__serviceId_><spanclass=parent>/services</span>/{serviceId}</a><spanclass=methods><ahref=#data-toggle=modaldata-target=#_services__serviceId__get><spanclass="badge badge_get">get</span></a><ahref=#data-toggle=modaldata-target=#_services__serviceId__put><spanclass="badge badge_put">put</span></a><ahref=#data-toggle=modaldata-target=#_services__serviceId__delete><spanclass="badge badge_delete">delete</span></a></span></h4></div><divid=panel__services__serviceId_class="panel-collapse collapse"><divclass=panel-body><divclass=list-group><ahref=#data-toggle=modaldata-target=#_services__serviceId__getclass=list-group-item><spanclass="badge badge_get">get</span><divclass=method_description><p>Get a specific service</p></div><divclass=clearfix></div></a><ahref=#data-toggle=modaldata-target=#_services__serviceId__putclass=list-group-item><spanclass="badge badge_put">put</span><divclass=method_description><p>Update a service</p></div><divclass=clearfix></div></a><ahref=#data-toggle=modaldata-target=#_services__serviceId__deleteclass=list-group-item><spanclass="badge badge_delete">delete</span><divclass=method_description><p>Delete a specific service</p></div><divclass=clearfix></div></a></div></div></div><divclass="modal fade"tabindex=0id=_services__serviceId__get><divclass=modal-dialog><divclass=modal-content><divclass=modal-header><buttontype=buttonclass=closedata-dismiss=modalaria-hidden=true>×</button><h4class=modal-titleid=myModalLabel><spanclass="badge badge_get">get</span><spanclass=parent>/services</span>/{serviceId}</h4></div><divclass=modal-body><divclass="alert alert-info"><p>Get a specific service</p></div><ulclass="nav nav-tabs"><liclass=active><ahref=#_services__serviceId__get_requestdata-toggle=tab>Request</a></li><li><ahref=#_services__serviceId__get_responsedata-toggle=tab>Response</a></li></ul><divclass=tab-content><divclass="tab-pane active"id=_services__serviceId__get_request><h3>URI Parameters</h3><ul><li><strong>serviceId</strong>: <em>required (string)</em></li></ul></div><divclass=tab-paneid=_services__serviceId__get_response><h2>HTTP status code <ahref=http://httpstatus.es/200target=_blank>200</a></h2><h3>Body</h3><p><strong>Type: application/json</strong></p><p><small><strong>Example</strong>:<pre><code>{
