1swagger: "2.0"
2info:
3 title: The Giant Swarm API v4
4 description: |
5 This is the documentation for the Giant Swarm API starting at version `v4`.
6
7 For an introduction to Giant Swarm, refer to the [documentation site](https://docs.giantswarm.io/).
8
9 The Giant Swarm API attempts to behave in a __restful__ way. As a developer, you access resources using the `GET` method and, for example, delete them using the same path and the `DELETE` method.
10
11 Accessing resources via GET usually returns all information available about a resource, while collections, like for example the list of all clusters you have access to, only contain a selected few attributes of each member item.
12
13 Some requests, like for example the request to create a new cluster, don't return the resource itself. Instead, the response delivers a standard message body, showing a `code` and a `message` part. The `message` contains information for you or a client's end user. The `code` attribute contains some string (example: `RESOURCE_CREATED`) that is supposed to give you details on the state of the operation, in addition to standard HTTP status codes. This message format is also used in the case of errors. We provide a [list of all response codes](https://github.com/giantswarm/api-spec/blob/master/details/RESPONSE_CODES.md) outside this documentation.
14
15 Feedback on the API as well as this documentation is welcome via `support@giantswarm.io` or on IRC channel [#giantswarm](irc://irc.freenode.org:6667/#giantswarm) on freenode.
16
17 ## Source
18
19 The source of this documentation is available on [GitHub](https://github.com/giantswarm/api-spec).
20
21 termsOfService: https://giantswarm.io/terms/
22 version: 4.0.0
23 license:
24 name: Apache 2.0
25 url: http://www.apache.org/licenses/LICENSE-2.0.html
26consumes:
27 - application/json
28produces:
29 - application/json
30tags:
31 - name: auth tokens
32 description: |
33 Auth Tokens are your way of authenticating against this API. You can create one by passing your email and base64 encoded password to the create auth token endpoint. The auth token never expires, in case you want to invalidate it you need to delete it (logout).
34 - name: clusters
35 description: |
36 Clusters are a central resource of the Giant Swarm API. As a user or team using Giant Swarm, you set up Kubernetes clusters to run your own workloads.
37
38 The API currently provides operations to create and delete clusters, as well as list all available clusters and get details on specific clusters.
39 - name: info
40 description: Information about the Giant Swarm installation
41 - name: key pairs
42 description: A key pair is a unique combination of a X.509 certificate and a private key. Key pairs are used to access the Kubernetes API of a cluster, both using `kubectl` and any standard web browser.
43 externalDocs:
44 url: https://docs.giantswarm.io/guides/accessing-services-from-the-outside/
45 description: "User guide: Accessing Pods and Services from the Outside"
46 - name: organizations
47 description: Organizations are groups of users who own resources like clusters.
48 - name: users
49 description: A user represents a person that should have access to the Giant Swarm API. Users can belong to many groups, and are identified by email address.
50 - name: releases
51 description: |
52 A release is a software bundle that constitutes a cluster.
53
54 Releases are identified by their
55 [semantic version number](http://semver.org/) in the `MAJOR.MINOR.PATCH`
56 format.
57
58 A release provides _components_, like for example Kubernetes. For each
59 release the contained components are listed. Changes in components are
60 detailed in the _changelog_ of a release.
61securityDefinitions:
62 AuthorizationHeaderToken:
63 description: |
64 Clients authenticate by passing an auth token via the `Authorization`
65 header with a value of the format `giantswarm <token>`. Auth tokens can be
66 obtained using the [createAuthToken](#operation/createAuthToken)
67 operation.
68 type: apiKey
69 name: Authorization
70 in: header
71
72security:
73 - AuthorizationHeaderToken: []
74
75paths:
76 /v4/info/:
77 get:
78 operationId: getInfo
79 tags:
80 - info
81 summary: Get information on the installation
82 description: |
83 Returns a set of details on the installation. The output varies based
84 on the provider used in the installation.
85
86 This information is useful for example when creating new cluster, to
87 prevent creating clusters with more worker nodes than possible.
88
89 ### Example for an AWS-based installation
90
91 ```json
92 {
93 "general": {
94 "installation_name": "shire",
95 "provider": "aws",
96 "datacenter": "eu-central-1"
97 },
98 "workers": {
99 "count_per_cluster": {
100 "max": 20,
101 "default": 3
102 },
103 "instance_type": {
104 "options": [
105 "m3.medium", "m3.large", "m3.xlarge"
106 ],
107 "default": "m3.large"
108 }
109 }
110 }
111 ```
112
113 ### Example for a KVM-based installation
114
115 ```json
116 {
117 "general": {
118 "installation_name": "isengard",
119 "provider": "kvm",
120 "datacenter": "string"
121 },
122 "workers": {
123 "count_per_cluster": {
124 "max": 8,
125 "default": 3
126 },
127 }
128 }
129 ```
130 parameters:
131 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
132 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
133 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
134 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
135 responses:
136 "200":
137 description: Information
138 schema:
139 $ref: "./definitions.yaml#/definitions/V4InfoResponse"
140 examples:
141 application/json:
142 {
143 "general": {
144 "installation_name": "shire",
145 "provider": "aws",
146 "datacenter": "eu-central-1"
147 },
148 "workers": {
149 "count_per_cluster": {
150 "max": 20,
151 "default": 3
152 },
153 "instance_type": {
154 "options": [
155 "m3.medium", "m3.large", "m3.xlarge"
156 ],
157 "default": "m3.large"
158 }
159 }
160 }
161 "401":
162 $ref: "./responses.yaml#/responses/V4Generic401Response"
163 default:
164 description: Error
165 schema:
166 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
167
168 /v4/auth-tokens/:
169 post:
170 operationId: createAuthToken
171 tags:
172 - auth tokens
173 summary: Create Auth Token (Login)
174 description: |
175 Creates a Auth Token for a given user. Must authenticate with email and password.
176 parameters:
177 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
178 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
179 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
180 - name: body
181 in: body
182 required: true
183 description: Create Auth Token Request
184 schema:
185 $ref: 'definitions.yaml#/definitions/V4CreateAuthTokenRequest'
186 x-examples:
187 application/json:
188 {
189 "email": "developer@example.com",
190 "password_base64": "cGFzc3dvcmQ="
191 }
192 responses:
193 "200":
194 description: Success
195 schema:
196 $ref: "./definitions.yaml#/definitions/V4CreateAuthTokenResponse"
197 examples:
198 application/json:
199 {
200 "auth_token": "e5239484-2299-41df-b901-d0568db7e3f9"
201 }
202 "401":
203 $ref: "./responses.yaml#/responses/V4Generic401Response"
204
205 delete:
206 operationId: deleteAuthToken
207 tags:
208 - auth tokens
209 summary: Delete Auth Token (Logout)
210 description: |
211 Deletes the authentication token provided in the Authorization header. This effectively logs you out.
212 parameters:
213 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
214 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
215 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
216 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
217 responses:
218 "200":
219 description: Success
220 schema:
221 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
222 examples:
223 application/json:
224 {
225 "code": "RESOURCE_DELETED",
226 "message": "The authentication token has been succesfully deleted."
227 }
228 "401":
229 $ref: "./responses.yaml#/responses/V4Generic401Response"
230
231 /v4/users/:
232 get:
233 operationId: getUsers
234 tags:
235 - users
236 summary: Get users
237 description: |
238 Returns a list of all users in the system. Currently this endpoint is only available to users with admin permissions.
239 parameters:
240 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
241 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
242 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
243 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
244 responses:
245 "200":
246 description: Success
247 schema:
248 type: array
249 items:
250 $ref: "./definitions.yaml#/definitions/V4UserListItem"
251 examples:
252 application/json:
253 [
254 {"email": "andy@example.com", "created": "2017-01-15T12:00:00Z", "expiry": "2019-01-15T00:00:00Z"},
255 {"email": "bob@example.com", "created": "2017-02-15T12:30:00Z", "expiry": "2020-01-15T00:00:00Z"},
256 {"email": "charles@example.com", "created": "2017-03-15T13:00:00Z", "expiry": "2021-01-15T00:00:00Z"}
257 ]
258 "401":
259 $ref: "./responses.yaml#/responses/V4Generic401Response"
260 default:
261 description: Error
262 schema:
263 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
264
265 /v4/user/:
266 get:
267 operationId: getCurrentUser
268 tags:
269 - users
270 summary: Get current user
271 description: |
272 Returns details about the currently authenticated user
273 parameters:
274 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
275 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
276 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
277 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
278 responses:
279 "200":
280 description: Success
281 schema:
282 $ref: "./definitions.yaml#/definitions/V4UserListItem"
283 examples:
284 application/json:
285 {"email": "andy@example.com", "created": "2017-01-15T12:00:00Z", "expiry": "2019-01-15T00:00:00Z"}
286 "201":
287 # Fake response added with expanded content of 200, to run test assertion, e.g. 200 <=> 201
288 description: Success
289 schema:
290 type: object
291 properties:
292 email:
293 type: string
294 description: Email address of the user
295 created:
296 type: string
297 description: The date and time that this account was created
298 expiry:
299 type: string
300 description: The date and time when this account will expire
301 "401":
302 $ref: "./responses.yaml#/responses/V4Generic401Response"
303 default:
304 description: Error
305 schema:
306 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
307
308 /v4/users/{email}/:
309 get:
310 operationId: getUser
311 parameters:
312 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
313 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
314 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
315 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
316 - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter"
317 tags:
318 - users
319 summary: Get user
320 description: |
321 Returns details about a specific user
322 responses:
323 "200":
324 description: Success
325 schema:
326 $ref: "./definitions.yaml#/definitions/V4UserListItem"
327 examples:
328 application/json:
329 {"email": "andy@example.com", "created": "2017-01-15T12:00:00Z", "expiry": "2019-01-15T00:00:00Z"}
330 "401":
331 $ref: "./responses.yaml#/responses/V4Generic401Response"
332 "404":
333 description: User not found
334 schema:
335 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
336 examples:
337 application/json:
338 {
339 "code": "RESOURCE_NOT_FOUND",
340 "message": "The user could not be found. (not found: user with email 'bob@example.com' could not be found)"
341 }
342 default:
343 description: Error
344 schema:
345 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
346
347 put:
348 operationId: createUser
349 parameters:
350 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
351 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
352 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
353 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
354 - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter"
355 - name: body
356 in: body
357 required: true
358 description: User account details
359 schema:
360 $ref: "./definitions.yaml#/definitions/V4CreateUserRequest"
361 x-examples:
362 application/json:
363 {
364 "password": "cGFzc3dvcmQ=",
365 "expiry": "2020-01-01T12:00:00.000Z"
366 }
367 tags:
368 - users
369 summary: Create user
370 description: |
371 Creates a users in the system. Currently this endpoint is only available to users with admin permissions.
372 responses:
373 "201":
374 description: User created
375 schema:
376 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
377 examples:
378 application/json:
379 {
380 "code": "RESOURCE_CREATED",
381 "message": "The user with email 'bob@example.com' has been created."
382 }
383 "400":
384 description: User already exists
385 schema:
386 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
387 examples:
388 application/json:
389 {
390 "code": "RESOURCE_ALREADY_EXISTS",
391 "message": "The user could not be created. (invalid input: email 'bob@example.com' already exists)"
392 }
393 "401":
394 $ref: "./responses.yaml#/responses/V4Generic401Response"
395 default:
396 description: Error
397 schema:
398 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
399
400 delete:
401 operationId: deleteUser
402 parameters:
403 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
404 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
405 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
406 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
407 - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter"
408 tags:
409 - users
410 summary: Delete user
411 description: |
412 Deletes a users in the system. Currently this endpoint is only available
413 to users with admin permissions.
414 responses:
415 "200":
416 description: User deleted
417 schema:
418 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
419 examples:
420 application/json:
421 {
422 "code": "RESOURCE_DELETED",
423 "message": "The user with email 'bob@example.com' has been deleted."
424 }
425 "401":
426 $ref: "./responses.yaml#/responses/V4Generic401Response"
427 "404":
428 description: User not found
429 schema:
430 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
431 examples:
432 application/json:
433 {
434 "code": "RESOURCE_NOT_FOUND",
435 "message": "The user could not be deleted. (not found: user with email 'bob@example.com' could not be found)"
436 }
437 default:
438 description: Error
439 schema:
440 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
441
442 /v4/clusters/:
443 get:
444 operationId: getClusters
445 tags:
446 - clusters
447 summary: Get clusters
448 description: |
449 This operation fetches a list of clusters.
450
451 The result depends on the permissions of the user.
452 A normal user will get all the clusters the user has access
453 to, via organization membership.
454 A user with admin permission will receive a list of all existing
455 clusters.
456
457 The result array items are sparse representations of the cluster objects.
458 To fetch more details on a cluster, use the [getCluster](#operation/getCluster)
459 operation.
460 parameters:
461 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
462 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
463 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
464 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
465 responses:
466 "200":
467 description: Success
468 schema:
469 type: array
470 items:
471 $ref: "./definitions.yaml#/definitions/V4ClusterListItem"
472 examples:
473 application/json:
474 [
475 {
476 "id": "g8s3o",
477 "create_date": "2017-06-08T12:31:47.215Z",
478 "name": "Staging Cluster",
479 "owner": "acme"
480 },
481 {
482 "id": "3dkr6",
483 "create_date": "2017-05-22T13:58:02.024Z",
484 "name": "Test Cluster",
485 "owner": "testorg"
486 }
487 ]
488 "401":
489 $ref: "./responses.yaml#/responses/V4Generic401Response"
490 default:
491 description: Error
492 schema:
493 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
494 post:
495 operationId: addCluster
496 tags:
497 - clusters
498 summary: Create cluster
499 description: |
500 This operation is used to create a new Kubernetes cluster for an
501 organization. The desired configuration can be specified using the
502 __cluster definition format__ (see
503 [external documentation](https://github.com/giantswarm/api-spec/blob/master/details/CLUSTER_DEFINITION.md)
504 for details).
505
506 The cluster definition format allows to set a number of optional
507 configuration details, like memory size and number of CPU cores.
508 However, one attribute is __mandatory__ upon creation: The `owner`
509 attribute must carry the name of the organization the cluster will
510 belong to. Note that the acting user must be a member of that
511 organization in order to create a cluster.
512
513 It is *recommended* to also specify the `name` attribute to give the
514 cluster a friendly name, like e. g. "Development Cluster".
515
516 Additional definition attributes can be used. Where attributes are
517 omitted, default configuration values will be applied. For example, if
518 no `release_version` is specified, the most recent version is used.
519
520 The `workers` attribute, if present, must contain an array of node
521 definition objects. The number of objects given determines the number
522 of workers created.
523
524 For example, requesting three worker nodes with default configuration
525 can be achieved by submitting an array of three empty objects:
526
527 ```"workers": [{}, {}, {}]```
528
529 For clusters on AWS, note that all worker nodes must use the same instance type.
530
531 parameters:
532 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
533 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
534 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
535 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
536 - name: body
537 in: body
538 required: true
539 description: New cluster definition
540 schema:
541 $ref: "./definitions.yaml#/definitions/V4AddClusterRequest"
542 x-examples:
543 application/json:
544 {
545 "owner": "myteam",
546 "release_version": "1.4.2",
547 "name": "Example cluster with 3 default worker nodes",
548 "workers": [{}, {}, {}]
549 }
550 responses:
551 "201":
552 description: Cluster created
553 headers:
554 Location:
555 type: string
556 description: URI to obtain details on the new cluster using the [getCluster](#operation/getCluster) operation
557 schema:
558 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
559 examples:
560 application/json:
561 {
562 "code": "RESOURCE_CREATED",
563 "message": "A new cluster has been created with ID 'wqtlq'"
564 }
565 "401":
566 $ref: "./responses.yaml#/responses/V4Generic401Response"
567 default:
568 description: error
569 schema:
570 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
571
572 /v4/clusters/{cluster_id}/:
573 get:
574 operationId: getCluster
575 tags:
576 - clusters
577 parameters:
578 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
579 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
580 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
581 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
582 - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
583 summary: Get cluster details
584 description: |
585 This operation allows to obtain all available details on a particular cluster.
586 responses:
587 "200":
588 description: Cluster details
589 schema:
590 $ref: "./definitions.yaml#/definitions/V4ClusterDetailsResponse"
591 examples:
592 application/json:
593 {
594 "id": "wqtlq",
595 "create_date": "2017-03-03T10:50:45.949270905Z",
596 "api_endpoint": "https://api.wqtlq.example.com",
597 "name": "Just a Standard Cluster",
598 "release_version": "2.5.16",
599 "kubernetes_version": "",
600 "owner": "acme",
601 "workers": [
602 {
603 "memory": {"size_gb": 2.0},
604 "storage": {"size_gb": 20.0},
605 "cpu": {"cores": 4},
606 "labels": {
607 "beta.kubernetes.io/arch": "amd64",
608 "beta.kubernetes.io/os": "linux",
609 "ip": "10.3.11.2",
610 "kubernetes.io/hostname": "worker-1.x882ofna.k8s.gigantic.io",
611 "nodetype": "hicpu"
612 }
613 },
614 {
615 "memory": {"size_gb": 8.0},
616 "storage": {"size_gb": 20.0},
617 "cpu": {"cores": 2},
618 "labels": {
619 "beta.kubernetes.io/arch": "amd64",
620 "beta.kubernetes.io/os": "linux",
621 "ip": "10.3.62.2",
622 "kubernetes.io/hostname": "worker-2.x882ofna.k8s.gigantic.io",
623 "nodetype": "hiram"
624 }
625 }
626 ],
627 "kvm": {
628 "port_mappings": [
629 {
630 "port": 30020,
631 "protocol": "http"
632 },
633 {
634 "port": 30021,
635 "protocol": "https"
636 },
637 ]
638 }
639 }
640 "401":
641 $ref: "./responses.yaml#/responses/V4Generic401Response"
642 "404":
643 description: Cluster not found
644 schema:
645 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
646 examples:
647 application/json:
648 {
649 "code": "RESOURCE_NOT_FOUND",
650 "message": "The cluster with ID 'wqtlq' could not be found, or perhaps you do not have access to it. Please make sure the cluster ID is correct, and that you are a member of the organization that it belongs to."
651 }
652 default:
653 description: error
654 schema:
655 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
656 patch:
657 operationId: modifyCluster
658 tags:
659 - clusters
660 parameters:
661 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
662 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
663 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
664 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
665 - name: body
666 in: body
667 required: true
668 description: Merge-patch body
669 schema:
670 $ref: "./definitions.yaml#/definitions/V4ModifyClusterRequest"
671 x-examples:
672 application/merge-patch+json:
673 {
674 "name": "New cluster name"
675 }
676 - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
677 summary: Modify cluster
678 description: |
679 This operation allows to modify an existing cluster.
680
681 A cluster modification is performed by submitting a `PATCH` request
682 to the cluster resource (as described in the
683 [addCluster](#operation/addCluster) and [getCluster](#operation/getCluster))
684 in form of a [JSON Patch Merge
685 (RFC 7386)](https://tools.ietf.org/html/rfc7386). This means, only the
686 attributes to be modified have to be contained in the request body.
687
688 The following attributes can be modified:
689
690 - `name`: Rename the cluster to something more fitting.
691
692 - `owner`: Changing the owner organization name means to change cluster
693 ownership from one organization to another. The user performing the
694 request has to be a member of both organizations.
695
696 - `release_version`: By changing this attribute you can upgrade a
697 cluster to a newer
698 [release](https://docs.giantswarm.io/api/#tag/releases).
699
700 - `workers`: By modifying the array of workers, nodes can be added to
701 increase the cluster's capacity. See details below.
702
703 ### Adding and Removing Worker Nodes (Scaling)
704
705 Adding worker nodes to a cluster or removing worker nodes from a cluster
706 works by submitting the `workers` attribute, which contains a (sparse)
707 array of worker node defintions.
708
709 _Sparse_ here means that all configuration details are optional. In the
710 case that worker nodes are added to a cluster, wherever a configuration
711 detail is missing, defaults will be applied. See
712 [Creating a cluster](#operation/addCluster) for details.
713
714 When modifying the cluster resource, you describe the desired state.
715 For scaling, this means that the worker node array submitted must
716 contain as many elements as the cluster should have worker nodes.
717 If your cluster currently has five nodes and you submit a workers
718 array with four elements, this means that one worker node will be removed.
719 If your submitted workers array has six elements, this means one will
720 be added.
721
722 As an example, this request body could be used to scale a cluster to
723 three worker nodes:
724
725 ```json
726 {
727 "workers": [{}, {}, {}]
728 }
729 ```
730
731 If the scaled cluster had four worker nodes before, one would be removed.
732 If it had two worker nodes before, one with default settings would be
733 added.
734
735 ### Limitations
736
737 - As of now, existing worker nodes cannot be modified.
738 - When removing nodes (scaling down), it is not possible to determine
739 which nodes will be removed.
740 - On AWS based clusters, all worker nodes must use the same EC2 instance
741 type (`instance_type` node attribute). By not setting an `instance_type`
742 when submitting a PATCH request, you ensure that the right instance type
743 is used automatically.
744
745 responses:
746 "200":
747 description: Cluster modified
748 schema:
749 $ref: "./definitions.yaml#/definitions/V4ClusterDetailsResponse"
750 "401":
751 $ref: "./responses.yaml#/responses/V4Generic401Response"
752 "404":
753 description: Cluster not found
754 schema:
755 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
756 examples:
757 application/json:
758 {
759 "code": "RESOURCE_NOT_FOUND",
760 "message": "The cluster with ID 'wqtlq' could not be found, or perhaps you do not have access to it. Please make sure the cluster ID is correct, and that you are a member of the organization that it belongs to."
761 }
762 default:
763 description: error
764 schema:
765 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
766 delete:
767 operationId: deleteCluster
768 tags:
769 - clusters
770 parameters:
771 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
772 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
773 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
774 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
775 - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
776 summary: Delete cluster
777 description: |
778 This operation allows to delete a cluster.
779
780 __Caution:__ Deleting a cluster causes the termination of all workloads running on the cluster. Data stored on the worker nodes will be lost. There is no way to undo this operation.
781
782 The response is sent as soon as the request is validated.
783 At that point, workloads might still be running on the cluster and may be accessible for a little wile, until the cluster is actually deleted.
784 responses:
785 "202":
786 description: Deleting cluster
787 schema:
788 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
789 examples:
790 application/json:
791 {
792 "code": "RESOURCE_DELETION_STARTED",
793 "message": "The cluster with ID 'wqtlq' is being deleted."
794 }
795 "401":
796 $ref: "./responses.yaml#/responses/V4Generic401Response"
797 "404":
798 description: Cluster not found
799 schema:
800 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
801 examples:
802 application/json:
803 {
804 "code": "RESOURCE_NOT_FOUND",
805 "message": "The cluster with ID 'wqtlq' could not be found, or perhaps you do not have access to it. Please make sure the cluster ID is correct, and that you are a member of the organization that it belongs to."
806 }
807 default:
808 description: error
809 schema:
810 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
811
812 /v4/clusters/{cluster_id}/key-pairs/:
813 get:
814 operationId: getKeyPairs
815 tags:
816 - key pairs
817 summary: Get key pairs
818 description: |
819 Returns a list of information on all key pairs of a cluster as an array.
820
821 The individual array items contain metadata on the key pairs, but neither the key nor the certificate. These can only be obtained upon creation, using the [addKeypair](#operation/addKeyPair) operation.
822 parameters:
823 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
824 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
825 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
826 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
827 - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
828 responses:
829 "200":
830 description: Key pairs
831 schema:
832 $ref: "./definitions.yaml#/definitions/V4GetKeyPairsResponse"
833 "401":
834 $ref: "./responses.yaml#/responses/V4Generic401Response"
835 default:
836 description: error
837 schema:
838 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
839 post:
840 operationId: addKeyPair
841 tags:
842 - key pairs
843 summary: Create key pair
844 parameters:
845 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
846 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
847 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
848 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
849 - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
850 - name: body
851 in: body
852 required: true
853 description: |
854 While the `ttl_hours` attribute is optional and will be set to a default value when omitted, the `description` is mandatory.
855 schema:
856 $ref: "./definitions.yaml#/definitions/V4AddKeyPairRequest"
857 x-examples:
858 application/json:
859 {
860 "description": "Admin key pair lasting twelve hours",
861 "ttl_hours": 12,
862 "certificate_organizations": "system:masters"
863 }
864 description: |
865 This operation allows to create a new key pair for accessing a specific cluster.
866
867 A key pair consists of an unencrypted private RSA key and an X.509 certificate. In addition, when obtaining a key pair for a cluster, the cluster's certificate authority file (CA certificate) is delivered, which is required by TLS clients to establish trust to the cluster.
868
869 In addition to the credentials itself, a key pair has some metadata like a unique ID, a creation timestamp and a free text `description` that you can use at will, for example to note for whom a key pair has been issued.
870
871 ### Customizing the certificate's subject for K8s RBAC
872
873 It is possible to set the Common Name and Organization fields of the generated certificate's subject.
874
875 - `cn_prefix`: The certificate's common name uses this format: `<cn_prefix>.user.<clusterdomain>`.
876
877 `clusterdomain` is specific to your cluster and is not editable.
878
879 The `cn_prefix` however is editable. When left blank it will default
880 to the email address of the Giant Swarm user that is performing the
881 create key pair request.
882
883 The common name is used as the username for requests to the Kubernetes API. This allows you
884 to set up role-based access controls.
885
886
887 - `certificate_organizations`: This will set the certificate's `organization` fields. Use a comma separated list of values.
888 The Kubernetes API will use these values as group memberships.
889
890 __Note:__ The actual credentials coming with the key pair (key, certificate) can only be accessed once, as the result of the `POST` request that triggers their creation. This restriction exists to minimize the risk of credentials being leaked. If you fail to capture the credentials upon creation, you'll have to repeat the creation request.
891 responses:
892 "200":
893 description: Success
894 schema:
895 $ref: "./definitions.yaml#/definitions/V4AddKeyPairResponse"
896 examples:
897 application/json:
898 {
899 "certificate_authority_data": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
900 "client_key_data": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
901 "client_certificate_data": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
902 "create_date": "2016-06-01T12:00:00.000Z",
903 "description": "Key pair description",
904 "id": "02:cc:da:f9:fb:ce:c3:e5:e1:f6:27:d8:43:48:0d:37:4a:ee:b9:67",
905 "ttl_hours": 8640
906 }
907 "401":
908 $ref: "./responses.yaml#/responses/V4Generic401Response"
909
910 /v4/organizations/:
911 get:
912 operationId: getOrganizations
913 tags:
914 - organizations
915 summary: Get organizations
916 description: |
917 This operation allows to fetch a list of organizations the user is a
918 member of. In the case of an admin user, the result includes all
919 existing organizations.
920 parameters:
921 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
922 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
923 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
924 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
925 responses:
926 "200":
927 description: Success
928 schema:
929 type: array
930 items:
931 $ref: "./definitions.yaml#/definitions/V4OrganizationListItem"
932 examples:
933 application/json:
934 [
935 {"id": "acme"},
936 {"id": "giantswarm"},
937 {"id": "testorg"}
938 ]
939 "401":
940 $ref: "./responses.yaml#/responses/V4Generic401Response"
941 default:
942 description: Error
943 schema:
944 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
945
946 /v4/organizations/{organization_id}/:
947 get:
948 operationId: getOrganization
949 tags:
950 - organizations
951 summary: Get organization details
952 description: |
953 This operation fetches organization details.
954 parameters:
955 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
956 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
957 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
958 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
959 - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
960 responses:
961 "200":
962 description: Organization details
963 schema:
964 $ref: "./definitions.yaml#/definitions/V4Organization"
965 examples:
966 application/json:
967 {
968 "id": "acme",
969 "members": [
970 {"email": "user1@example.com"},
971 {"email": "user2@example.com"}
972 ]
973 }
974 "401":
975 $ref: "./responses.yaml#/responses/V4Generic401Response"
976 "404":
977 description: Organization not found
978 schema:
979 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
980 examples:
981 application/json:
982 {
983 "code": "RESOURCE_NOT_FOUND",
984 "message": "The organization could not be found. (not found: the organization with id 'acme' could not be found)"
985 }
986 default:
987 description: Error
988 schema:
989 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
990 put:
991 operationId: addOrganization
992 tags:
993 - organizations
994 summary: Create an organization
995 description: |
996 This operation allows a user to create an organization.
997 parameters:
998 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
999 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
1000 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
1001 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
1002 - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
1003 - name: body
1004 in: body
1005 required: true
1006 schema:
1007 $ref: "./definitions.yaml#/definitions/V4Organization"
1008 x-examples:
1009 application/json:
1010 {
1011 "id": "string",
1012 "members": [
1013 {"email": "myself@example.com"},
1014 {"email": "colleague@example.com"}
1015 ]
1016 }
1017 responses:
1018 "201":
1019 description: Organization created
1020 schema:
1021 $ref: "./definitions.yaml#/definitions/V4Organization"
1022 examples:
1023 application/json:
1024 {
1025 "id": "acme",
1026 "members": [
1027 {"email": "user1@example.com"},
1028 {"email": "user2@example.com"}
1029 ]
1030 }
1031 "401":
1032 $ref: "./responses.yaml#/responses/V4Generic401Response"
1033 "409":
1034 description: Organization already exists
1035 schema:
1036 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1037 examples:
1038 application/json:
1039 {
1040 "code": "RESOURCE_ALREADY_EXISTS",
1041 "message": "The organization could not be created. (org already exists)"
1042 }
1043 default:
1044 description: Error
1045 schema:
1046 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1047 patch:
1048 operationId: modifyOrganization
1049 tags:
1050 - organizations
1051 parameters:
1052 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
1053 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
1054 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
1055 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
1056 - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
1057 - name: body
1058 in: body
1059 required: true
1060 schema:
1061 type: object
1062 properties:
1063 members:
1064 type: array
1065 description: List of members that belong to this organization
1066 items:
1067 $ref: "./definitions.yaml#/definitions/V4OrganizationMember"
1068 x-examples:
1069 application/merge-patch+json:
1070 {
1071 "members": [{"email": "myself@example.com"}]
1072 }
1073
1074 summary: Modify organization
1075 description: |
1076 This operation allows you to modify an existing organization. You must be
1077 a member of the organization or an admin in order to use this endpoint.
1078
1079 The following attributes can be modified:
1080
1081 - `members`: By modifying the array of members, members can be added to or removed from the organization
1082
1083 The request body must conform with the [JSON Patch Merge (RFC 7386)](https://tools.ietf.org/html/rfc7386) standard.
1084 Requests have to be sent with the `Content-Type: application/merge-patch+json` header.
1085
1086 The full request must be valid before it will be executed, currently this
1087 means every member you attempt to add to the organization must actually
1088 exist in the system. If any member you attempt to add is invalid, the entire
1089 patch operation will fail, no members will be added or removed, and an error message
1090 will explain which members in your request are invalid.
1091 responses:
1092 "200":
1093 description: Organization modified
1094 schema:
1095 $ref: "./definitions.yaml#/definitions/V4Organization"
1096 "400":
1097 description: Invalid input
1098 schema:
1099 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1100 examples:
1101 application/json:
1102 {
1103 "code": "INVALID_INPUT",
1104 "message": "The organization could not be modified. (invalid input: user 'invalid-email' does not exist or is invalid)"
1105 }
1106 "401":
1107 $ref: "./responses.yaml#/responses/V4Generic401Response"
1108 "404":
1109 description: Organization not found
1110 schema:
1111 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1112 examples:
1113 application/json:
1114 {
1115 "code": "RESOURCE_NOT_FOUND",
1116 "message": "The organization could not be modified. (not found: the organization with id 'acme' could not be found)"
1117 }
1118 default:
1119 description: error
1120 schema:
1121 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1122 delete:
1123 operationId: deleteOrganization
1124 tags:
1125 - organizations
1126 summary: Delete an organization
1127 description: |
1128 This operation allows a user to delete an organization that they are a member of.
1129 Admin users can delete any organization.
1130 parameters:
1131 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
1132 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
1133 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
1134 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
1135 - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
1136 responses:
1137 "200":
1138 description: Organization deleted
1139 schema:
1140 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1141 examples:
1142 application/json:
1143 {
1144 "code": "RESOURCE_DELETED",
1145 "message": "The organization with ID 'acme' has been deleted."
1146 }
1147 "401":
1148 $ref: "./responses.yaml#/responses/V4Generic401Response"
1149 "404":
1150 description: Organization not found
1151 schema:
1152 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1153 examples:
1154 application/json:
1155 {
1156 "code": "RESOURCE_NOT_FOUND",
1157 "message": "The organization could not be deleted. (not found: the organization with id 'acme' could not be found)"
1158 }
1159 default:
1160 description: Error
1161 schema:
1162 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1163
1164 /v4/organizations/{organization_id}/credentials/:
1165 post:
1166 operationId: addCredentials
1167 tags:
1168 - organizations
1169 summary: Set credentials
1170 description: |
1171 Add a set of credentials to the organization allowing the creation and
1172 operation of clusters within a cloud provider account/subscription.
1173
1174 The actual type of these credentials depends on the cloud provider the
1175 installation is running on. Currently, only AWS is supported, with
1176 support for Azure being planned for the near future.
1177
1178 Credentials in an organization are immutable. Each organization can only
1179 have one set of credentials.
1180
1181 Once credentials have been set for an organization, they are used for
1182 every new cluster that will be created for the organization.
1183
1184 ### Example request body for AWS
1185
1186 ```json
1187 {
1188 "provider": "aws",
1189 "aws": {
1190 "roles": {
1191 "admin": "arn:aws:iam::123456789012:role/GiantSwarmAdmin",
1192 "awsoperator": "arn:aws:iam::123456789012:role/GiantSwarmAWSOperator"
1193 }
1194 }
1195 }
1196 ```
1197 parameters:
1198 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
1199 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
1200 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
1201 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
1202 - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
1203 - name: body
1204 in: body
1205 required: true
1206 schema:
1207 $ref: "./definitions.yaml#/definitions/V4AddCredentialsRequest"
1208 x-examples:
1209 application/json:
1210 {
1211 "provider": "aws",
1212 "aws": {
1213 "roles": {
1214 "admin": "arn:aws:iam::123456789012:role/GiantSwarmAdmin",
1215 "awsoperator": "arn:aws:iam::123456789012:role/GiantSwarmAWSOperator"
1216 }
1217 }
1218 }
1219 responses:
1220 "201":
1221 description: Credentials created
1222 headers:
1223 Location:
1224 type: string
1225 description: URI of the new credentials resource
1226 schema:
1227 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1228 examples:
1229 application/json:
1230 {
1231 "code": "RESOURCE_CREATED",
1232 "message": "A new set of credentials has been created with ID '5d9h4'"
1233 }
1234 "401":
1235 $ref: "./responses.yaml#/responses/V4Generic401Response"
1236 "409":
1237 description: Conflict
1238 schema:
1239 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1240 examples:
1241 application/json:
1242 {
1243 "code": "RESOURCE_ALREADY_EXISTS",
1244 "message": "The organisation already has a set of credentials"
1245 }
1246 default:
1247 description: error
1248 schema:
1249 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1250
1251 /v4/releases/:
1252 get:
1253 operationId: getReleases
1254 tags:
1255 - releases
1256 summary: Get releases
1257 description: |
1258 Lists all releases available for new clusters or for upgrading existing
1259 clusters. Might also serve as an archive to obtain details on older
1260 releases.
1261 parameters:
1262 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
1263 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
1264 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
1265 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
1266 responses:
1267 "200":
1268 description: Releases list
1269 schema:
1270 type: array
1271 items:
1272 $ref: "./definitions.yaml#/definitions/V4ReleaseListItem"
1273 examples:
1274 application/json:
1275 [
1276 {
1277 "version": "1.14.9",
1278 "timestamp": "2017-09-21T08:14:03.37759Z",
1279 "changelog": [
1280 {
1281 "component": "kubernetes",
1282 "description": "Security fixes"
1283 },
1284 {
1285 "component": "calico",
1286 "description": "Security fixes"
1287 }
1288 ],
1289 "components": [
1290 {
1291 "name": "kubernetes",
1292 "version": "1.5.8"
1293 },
1294 {
1295 "name": "calico",
1296 "version": "0.9.1"
1297 }
1298 ],
1299 "active": false
1300 },
1301 {
1302 "version": "2.8.4",
1303 "timestamp": "2017-11-11T12:24:56.59969Z",
1304 "changelog": [
1305 {
1306 "component": "calico",
1307 "description": "Bugfix"
1308 }
1309 ],
1310 "components": [
1311 {
1312 "name": "kubernetes",
1313 "version": "1.7.3"
1314 },
1315 {
1316 "name": "calico",
1317 "version": "1.1.1"
1318 }
1319 ],
1320 "active": true
1321 }
1322 ]
1323 "401":
1324 $ref: "./responses.yaml#/responses/V4Generic401Response"
1325
View as plain text