github.com/deemoprobe/k8s-first-commit@v0.0.0-20230430165612-a541f1982be3/api/kubernetes.raml (about)

     1  #%RAML 0.8
     2  baseUri: http://server/api/{version}
     3  title: Kubernetes
     4  version: v1beta1
     5  mediaType: application/json
     6  documentation:
     7   - title: Overview
     8     content: |
     9       The Kubernetes API currently manages 3 main resources: `tasks`,
    10       `replicationControllers`, and `services`. Tasks correspond to
    11       colocated groups of [Docker containers](http://docker.io) with
    12       shared volumes, as supported by [Google Cloud Platform's
    13       container-vm
    14       images](https://developers.google.com/compute/docs/containers).
    15       Singleton tasks can be created directly via the `/tasks`
    16       endpoint. Sets of tasks may created, maintained, and scaled using
    17       replicationControllers.  Services create load-balanced targets
    18       for sets of tasks.
    19  
    20   - title: Resource identifiers
    21     content: |
    22       Each resource has a string `id` and list of key-value
    23       `labels`. The `id` is generated by the system and is guaranteed
    24       to be unique in space and time across all resources.  `labels`
    25       is a map of string (key) to string (value). Each resource may
    26       have at most one label with a particular key. Individual labels
    27       are used to specify identifying metadata that can be used to
    28       define sets of resources by specifying required labels. Examples
    29       of typical task label keys include `stage`, `service`, `name`,
    30       `tier`, `partition`, and `track`, but you are free to develop
    31       your own conventions.
    32  
    33   - title: Creation semantics
    34     content: |
    35       Creation is currently not idempotent. We plan to add a
    36       modification token to each resource. A unique value for the token
    37       should be provided by the user during creation. If the user
    38       specifies a duplicate token at creation time, the system should
    39       return an error with a pointer to the exiting resource with that
    40       token. In this way a user can deterministically recover from a
    41       dropped connection during a resource creation request.
    42  
    43   - title: Update semantics
    44     content: |
    45       Custom verbs are minimized and are used only for 'edge triggered'
    46       actions such as a reboot. Resource descriptions are generally set
    47       up with `desiredState` for the user provided parameters and
    48       `currentState` for the actual system state. While consistent
    49       terminology is used across these two stanzas they do not match
    50       member for member.
    51  
    52       When a new version of a resource is PUT the `desiredState` is
    53       updated and available immediately. Over time the system will work
    54       to bring the `currentState` into line with the `desiredState`. The
    55       system will drive toward the most recent `desiredState` regardless
    56       of previous versions of that stanza. In other words, if a value
    57       is changed from 2 to 5 in one PUT and then back down to 3 in
    58       another PUT the system isn't required to 'touch base' at 5 before
    59       making 3 the `currentState`.
    60  
    61       When doing an update, we assume that the entire `desiredState`
    62       stanza is specified. If a field is omitted it is assumed that the
    63       user is looking to delete that field. It is viable for a user to
    64       GET the resource, modify what they like in the `desiredState` or
    65       labels stanzas and then PUT it back. If the `currentState` is
    66       included in the PUT it will be silently ignored.
    67  
    68       While currently unspecified, it is intended that concurrent
    69       modification should be accomplished with optimistic locking of
    70       resources. We plan to add a modification token to each resource. If
    71       this is included with the PUT operation the system will verify
    72       that there haven't been other successful mutations to the
    73       resource during a read/modify/write cycle. The correct client
    74       action at this point is to GET the resource again, apply the
    75       changes afresh and try submitting again.
    76  
    77       Note that updates currently only work for replicationControllers
    78       and services, but not for tasks. Label updates have not yet been
    79       implemented, either.
    80  
    81  /tasks:
    82    get:
    83      description: List all tasks on this cluster
    84      responses:
    85        200:
    86          body:
    87            application/json:
    88              example: !include examples/task-list.json
    89    post:
    90      description: Create a new task. currentState is ignored if present.
    91      body:
    92        json/application:
    93          schema: !include doc/task-schema.json
    94          example: !include examples/task.json
    95    
    96    /{taskId}:
    97      get:
    98        description: Get a specific task
    99        responses:
   100          200:
   101            body:
   102              application/json:
   103                example: !include examples/task.json
   104      put:
   105        description: Update a task
   106        body:
   107          json/application:
   108            schema: !include doc/task-schema.json
   109            example: !include examples/task.json
   110      delete:
   111        description: Delete a specific task
   112        responses:
   113          200:
   114            body:
   115              application/json:
   116                example: |
   117                  { 
   118                    "success": true
   119                  }
   120  
   121  /replicationControllers:
   122    get:
   123      description: List all replicationControllers on this cluster
   124      responses:
   125        200:
   126          body:
   127            application/json:
   128              example: !include examples/controller-list.json
   129    post:
   130      description: Create a new controller. currentState is ignored if present.
   131      body:
   132        json/application:
   133          schema: !include doc/controller-schema.json
   134          example: !include examples/controller.json
   135    
   136    /{controllerId}:
   137      get:
   138        description: Get a specific controller
   139        responses:
   140          200:
   141            body:
   142              application/json:
   143                example: !include examples/controller.json
   144      put:
   145        description: Update a controller
   146        body:
   147          json/application:
   148            schema: !include doc/controller-schema.json
   149            example: !include examples/controller.json
   150      delete:
   151        description: Delete a specific controller
   152        responses:
   153          200:
   154            body:
   155              application/json:
   156                example: |
   157                  { 
   158                    "success": true
   159                  }
   160  
   161  /services:
   162    get:
   163      description: List all services on this cluster
   164      responses:
   165        200:
   166          body:
   167            application/json:
   168              example: !include examples/service-list.json
   169    post:
   170      description: Create a new service
   171      body:
   172        json/application:
   173          schema: !include doc/service-schema.json
   174          example: !include examples/service.json
   175    
   176    /{serviceId}:
   177      get:
   178        description: Get a specific service
   179        responses:
   180          200:
   181            body:
   182              application/json:
   183                example: !include examples/service.json
   184      put:
   185        description: Update a service
   186        body:
   187          json/application:
   188            schema: !include doc/service-schema.json
   189            example: !include examples/service.json
   190      delete:
   191        description: Delete a specific service
   192        responses:
   193          200:
   194            body:
   195              application/json:
   196                example: |
   197                  { 
   198                    "success": true
   199                  }
   200