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 "401":
287 $ref: "./responses.yaml#/responses/V4Generic401Response"
288 default:
289 description: Error
290 schema:
291 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
292
293 /v4/users/{email}/:
294 get:
295 operationId: getUser
296 parameters:
297 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
298 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
299 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
300 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
301 - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter"
302 tags:
303 - users
304 summary: Get user
305 description: |
306 Returns details about a specific user
307 responses:
308 "200":
309 description: Success
310 schema:
311 $ref: "./definitions.yaml#/definitions/V4UserListItem"
312 examples:
313 application/json:
314 {"email": "andy@example.com", "created": "2017-01-15T12:00:00Z", "expiry": "2019-01-15T00:00:00Z"}
315 "401":
316 $ref: "./responses.yaml#/responses/V4Generic401Response"
317 "404":
318 description: User not found
319 schema:
320 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
321 examples:
322 application/json:
323 {
324 "code": "RESOURCE_NOT_FOUND",
325 "message": "The user could not be found. (not found: user with email 'bob@example.com' could not be found)"
326 }
327 default:
328 description: Error
329 schema:
330 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
331
332 put:
333 operationId: createUser
334 parameters:
335 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
336 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
337 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
338 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
339 - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter"
340 - name: body
341 in: body
342 required: true
343 description: User account details
344 schema:
345 $ref: "./definitions.yaml#/definitions/V4CreateUserRequest"
346 x-examples:
347 application/json:
348 {
349 "password": "cGFzc3dvcmQ=",
350 "expiry": "2020-01-01T12:00:00.000Z"
351 }
352 tags:
353 - users
354 summary: Create user
355 description: |
356 Creates a users in the system. Currently this endpoint is only available to users with admin permissions.
357 responses:
358 "201":
359 description: User created
360 schema:
361 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
362 examples:
363 application/json:
364 {
365 "code": "RESOURCE_CREATED",
366 "message": "The user with email 'bob@example.com' has been created."
367 }
368 "400":
369 description: User already exists
370 schema:
371 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
372 examples:
373 application/json:
374 {
375 "code": "RESOURCE_ALREADY_EXISTS",
376 "message": "The user could not be created. (invalid input: email 'bob@example.com' already exists)"
377 }
378 "401":
379 $ref: "./responses.yaml#/responses/V4Generic401Response"
380 default:
381 description: Error
382 schema:
383 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
384
385 delete:
386 operationId: deleteUser
387 parameters:
388 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
389 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
390 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
391 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
392 - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter"
393 tags:
394 - users
395 summary: Delete user
396 description: |
397 Deletes a users in the system. Currently this endpoint is only available
398 to users with admin permissions.
399 responses:
400 "200":
401 description: User deleted
402 schema:
403 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
404 examples:
405 application/json:
406 {
407 "code": "RESOURCE_DELETED",
408 "message": "The user with email 'bob@example.com' has been deleted."
409 }
410 "401":
411 $ref: "./responses.yaml#/responses/V4Generic401Response"
412 "404":
413 description: User not found
414 schema:
415 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
416 examples:
417 application/json:
418 {
419 "code": "RESOURCE_NOT_FOUND",
420 "message": "The user could not be deleted. (not found: user with email 'bob@example.com' could not be found)"
421 }
422 default:
423 description: Error
424 schema:
425 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
426
427 /v4/clusters/:
428 get:
429 operationId: getClusters
430 tags:
431 - clusters
432 summary: Get clusters
433 description: |
434 This operation fetches a list of clusters.
435
436 The result depends on the permissions of the user.
437 A normal user will get all the clusters the user has access
438 to, via organization membership.
439 A user with admin permission will receive a list of all existing
440 clusters.
441
442 The result array items are sparse representations of the cluster objects.
443 To fetch more details on a cluster, use the [getCluster](#operation/getCluster)
444 operation.
445 parameters:
446 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
447 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
448 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
449 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
450 responses:
451 "200":
452 description: Success
453 schema:
454 type: array
455 items:
456 $ref: "./definitions.yaml#/definitions/V4ClusterListItem"
457 examples:
458 application/json:
459 [
460 {
461 "id": "g8s3o",
462 "create_date": "2017-06-08T12:31:47.215Z",
463 "name": "Staging Cluster",
464 "owner": "acme"
465 },
466 {
467 "id": "3dkr6",
468 "create_date": "2017-05-22T13:58:02.024Z",
469 "name": "Test Cluster",
470 "owner": "testorg"
471 }
472 ]
473 "401":
474 $ref: "./responses.yaml#/responses/V4Generic401Response"
475 default:
476 description: Error
477 schema:
478 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
479 post:
480 operationId: addCluster
481 tags:
482 - clusters
483 summary: Create cluster
484 description: |
485 This operation is used to create a new Kubernetes cluster for an
486 organization. The desired configuration can be specified using the
487 __cluster definition format__ (see
488 [external documentation](https://github.com/giantswarm/api-spec/blob/master/details/CLUSTER_DEFINITION.md)
489 for details).
490
491 The cluster definition format allows to set a number of optional
492 configuration details, like memory size and number of CPU cores.
493 However, one attribute is __mandatory__ upon creation: The `owner`
494 attribute must carry the name of the organization the cluster will
495 belong to. Note that the acting user must be a member of that
496 organization in order to create a cluster.
497
498 It is *recommended* to also specify the `name` attribute to give the
499 cluster a friendly name, like e. g. "Development Cluster".
500
501 Additional definition attributes can be used. Where attributes are
502 omitted, default configuration values will be applied. For example, if
503 no `release_version` is specified, the most recent version is used.
504
505 The `workers` attribute, if present, must contain an array of node
506 definition objects. The number of objects given determines the number
507 of workers created.
508
509 For example, requesting three worker nodes with default configuration
510 can be achieved by submitting an array of three empty objects:
511
512 ```"workers": [{}, {}, {}]```
513
514 For clusters on AWS, note that all worker nodes must use the same instance type.
515
516 parameters:
517 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
518 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
519 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
520 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
521 - name: body
522 in: body
523 required: true
524 description: New cluster definition
525 schema:
526 $ref: "./definitions.yaml#/definitions/V4AddClusterRequest"
527 x-examples:
528 application/json:
529 {
530 "owner": "myteam",
531 "release_version": "1.4.2",
532 "name": "Example cluster with 3 default worker nodes",
533 "workers": [{}, {}, {}]
534 }
535 responses:
536 "201":
537 description: Cluster created
538 headers:
539 Location:
540 type: string
541 description: URI to obtain details on the new cluster using the [getCluster](#operation/getCluster) operation
542 schema:
543 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
544 examples:
545 application/json:
546 {
547 "code": "RESOURCE_CREATED",
548 "message": "A new cluster has been created with ID 'wqtlq'"
549 }
550 "401":
551 $ref: "./responses.yaml#/responses/V4Generic401Response"
552 default:
553 description: error
554 schema:
555 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
556
557 /v4/clusters/{cluster_id}/:
558 get:
559 operationId: getCluster
560 tags:
561 - clusters
562 parameters:
563 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
564 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
565 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
566 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
567 - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
568 summary: Get cluster details
569 description: |
570 This operation allows to obtain all available details on a particular cluster.
571 responses:
572 "200":
573 description: Cluster details
574 schema:
575 $ref: "./definitions.yaml#/definitions/V4ClusterDetailsResponse"
576 examples:
577 application/json:
578 {
579 "id": "wqtlq",
580 "create_date": "2017-03-03T10:50:45.949270905Z",
581 "api_endpoint": "https://api.wqtlq.example.com",
582 "name": "Just a Standard Cluster",
583 "release_version": "2.5.16",
584 "kubernetes_version": "",
585 "owner": "acme",
586 "workers": [
587 {
588 "memory": {"size_gb": 2.0},
589 "storage": {"size_gb": 20.0},
590 "cpu": {"cores": 4},
591 "labels": {
592 "beta.kubernetes.io/arch": "amd64",
593 "beta.kubernetes.io/os": "linux",
594 "ip": "10.3.11.2",
595 "kubernetes.io/hostname": "worker-1.x882ofna.k8s.gigantic.io",
596 "nodetype": "hicpu"
597 }
598 },
599 {
600 "memory": {"size_gb": 8.0},
601 "storage": {"size_gb": 20.0},
602 "cpu": {"cores": 2},
603 "labels": {
604 "beta.kubernetes.io/arch": "amd64",
605 "beta.kubernetes.io/os": "linux",
606 "ip": "10.3.62.2",
607 "kubernetes.io/hostname": "worker-2.x882ofna.k8s.gigantic.io",
608 "nodetype": "hiram"
609 }
610 }
611 ],
612 "kvm": {
613 "port_mappings": [
614 {
615 "port": 30020,
616 "protocol": "http"
617 },
618 {
619 "port": 30021,
620 "protocol": "https"
621 },
622 ]
623 }
624 }
625 "401":
626 $ref: "./responses.yaml#/responses/V4Generic401Response"
627 "404":
628 description: Cluster not found
629 schema:
630 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
631 examples:
632 application/json:
633 {
634 "code": "RESOURCE_NOT_FOUND",
635 "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."
636 }
637 default:
638 description: error
639 schema:
640 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
641 patch:
642 operationId: modifyCluster
643 tags:
644 - clusters
645 parameters:
646 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
647 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
648 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
649 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
650 - name: body
651 in: body
652 required: true
653 description: Merge-patch body
654 schema:
655 $ref: "./definitions.yaml#/definitions/V4ModifyClusterRequest"
656 x-examples:
657 application/merge-patch+json:
658 {
659 "name": "New cluster name"
660 }
661 - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
662 summary: Modify cluster
663 description: |
664 This operation allows to modify an existing cluster.
665
666 A cluster modification is performed by submitting a `PATCH` request
667 to the cluster resource (as described in the
668 [addCluster](#operation/addCluster) and [getCluster](#operation/getCluster))
669 in form of a [JSON Patch Merge
670 (RFC 7386)](https://tools.ietf.org/html/rfc7386). This means, only the
671 attributes to be modified have to be contained in the request body.
672
673 The following attributes can be modified:
674
675 - `name`: Rename the cluster to something more fitting.
676
677 - `owner`: Changing the owner organization name means to change cluster
678 ownership from one organization to another. The user performing the
679 request has to be a member of both organizations.
680
681 - `release_version`: By changing this attribute you can upgrade a
682 cluster to a newer
683 [release](https://docs.giantswarm.io/api/#tag/releases).
684
685 - `workers`: By modifying the array of workers, nodes can be added to
686 increase the cluster's capacity. See details below.
687
688 ### Adding and Removing Worker Nodes (Scaling)
689
690 Adding worker nodes to a cluster or removing worker nodes from a cluster
691 works by submitting the `workers` attribute, which contains a (sparse)
692 array of worker node defintions.
693
694 _Sparse_ here means that all configuration details are optional. In the
695 case that worker nodes are added to a cluster, wherever a configuration
696 detail is missing, defaults will be applied. See
697 [Creating a cluster](#operation/addCluster) for details.
698
699 When modifying the cluster resource, you describe the desired state.
700 For scaling, this means that the worker node array submitted must
701 contain as many elements as the cluster should have worker nodes.
702 If your cluster currently has five nodes and you submit a workers
703 array with four elements, this means that one worker node will be removed.
704 If your submitted workers array has six elements, this means one will
705 be added.
706
707 As an example, this request body could be used to scale a cluster to
708 three worker nodes:
709
710 ```json
711 {
712 "workers": [{}, {}, {}]
713 }
714 ```
715
716 If the scaled cluster had four worker nodes before, one would be removed.
717 If it had two worker nodes before, one with default settings would be
718 added.
719
720 ### Limitations
721
722 - As of now, existing worker nodes cannot be modified.
723 - When removing nodes (scaling down), it is not possible to determine
724 which nodes will be removed.
725 - On AWS based clusters, all worker nodes must use the same EC2 instance
726 type (`instance_type` node attribute). By not setting an `instance_type`
727 when submitting a PATCH request, you ensure that the right instance type
728 is used automatically.
729
730 responses:
731 "200":
732 description: Cluster modified
733 schema:
734 $ref: "./definitions.yaml#/definitions/V4ClusterDetailsResponse"
735 "401":
736 $ref: "./responses.yaml#/responses/V4Generic401Response"
737 "404":
738 description: Cluster not found
739 schema:
740 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
741 examples:
742 application/json:
743 {
744 "code": "RESOURCE_NOT_FOUND",
745 "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."
746 }
747 default:
748 description: error
749 schema:
750 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
751 delete:
752 operationId: deleteCluster
753 tags:
754 - clusters
755 parameters:
756 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
757 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
758 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
759 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
760 - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
761 summary: Delete cluster
762 description: |
763 This operation allows to delete a cluster.
764
765 __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.
766
767 The response is sent as soon as the request is validated.
768 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.
769 responses:
770 "202":
771 description: Deleting cluster
772 schema:
773 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
774 examples:
775 application/json:
776 {
777 "code": "RESOURCE_DELETION_STARTED",
778 "message": "The cluster with ID 'wqtlq' is being deleted."
779 }
780 "401":
781 $ref: "./responses.yaml#/responses/V4Generic401Response"
782 "404":
783 description: Cluster not found
784 schema:
785 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
786 examples:
787 application/json:
788 {
789 "code": "RESOURCE_NOT_FOUND",
790 "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."
791 }
792 default:
793 description: error
794 schema:
795 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
796
797 /v4/clusters/{cluster_id}/key-pairs/:
798 get:
799 operationId: getKeyPairs
800 tags:
801 - key pairs
802 summary: Get key pairs
803 description: |
804 Returns a list of information on all key pairs of a cluster as an array.
805
806 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.
807 parameters:
808 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
809 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
810 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
811 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
812 - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
813 responses:
814 "200":
815 description: Key pairs
816 schema:
817 $ref: "./definitions.yaml#/definitions/V4GetKeyPairsResponse"
818 "401":
819 $ref: "./responses.yaml#/responses/V4Generic401Response"
820 default:
821 description: error
822 schema:
823 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
824 post:
825 operationId: addKeyPair
826 tags:
827 - key pairs
828 summary: Create key pair
829 parameters:
830 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
831 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
832 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
833 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
834 - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
835 - name: body
836 in: body
837 required: true
838 description: |
839 While the `ttl_hours` attribute is optional and will be set to a default value when omitted, the `description` is mandatory.
840 schema:
841 $ref: "./definitions.yaml#/definitions/V4AddKeyPairRequest"
842 x-examples:
843 application/json:
844 {
845 "description": "Admin key pair lasting twelve hours",
846 "ttl_hours": 12,
847 "certificate_organizations": "system:masters"
848 }
849 description: |
850 This operation allows to create a new key pair for accessing a specific cluster.
851
852 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.
853
854 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.
855
856 ### Customizing the certificate's subject for K8s RBAC
857
858 It is possible to set the Common Name and Organization fields of the generated certificate's subject.
859
860 - `cn_prefix`: The certificate's common name uses this format: `<cn_prefix>.user.<clusterdomain>`.
861
862 `clusterdomain` is specific to your cluster and is not editable.
863
864 The `cn_prefix` however is editable. When left blank it will default
865 to the email address of the Giant Swarm user that is performing the
866 create key pair request.
867
868 The common name is used as the username for requests to the Kubernetes API. This allows you
869 to set up role-based access controls.
870
871
872 - `certificate_organizations`: This will set the certificate's `organization` fields. Use a comma separated list of values.
873 The Kubernetes API will use these values as group memberships.
874
875 __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.
876 responses:
877 "200":
878 description: Success
879 schema:
880 $ref: "./definitions.yaml#/definitions/V4AddKeyPairResponse"
881 examples:
882 application/json:
883 {
884 "certificate_authority_data": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
885 "client_key_data": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
886 "client_certificate_data": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
887 "create_date": "2016-06-01T12:00:00.000Z",
888 "description": "Key pair description",
889 "id": "02:cc:da:f9:fb:ce:c3:e5:e1:f6:27:d8:43:48:0d:37:4a:ee:b9:67",
890 "ttl_hours": 8640
891 }
892 "401":
893 $ref: "./responses.yaml#/responses/V4Generic401Response"
894
895 /v4/organizations/:
896 get:
897 operationId: getOrganizations
898 tags:
899 - organizations
900 summary: Get organizations
901 description: |
902 This operation allows to fetch a list of organizations the user is a
903 member of. In the case of an admin user, the result includes all
904 existing organizations.
905 parameters:
906 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
907 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
908 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
909 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
910 responses:
911 "200":
912 description: Success
913 schema:
914 type: array
915 items:
916 $ref: "./definitions.yaml#/definitions/V4OrganizationListItem"
917 examples:
918 application/json:
919 [
920 {"id": "acme"},
921 {"id": "giantswarm"},
922 {"id": "testorg"}
923 ]
924 "401":
925 $ref: "./responses.yaml#/responses/V4Generic401Response"
926 default:
927 description: Error
928 schema:
929 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
930
931 /v4/organizations/{organization_id}/:
932 get:
933 operationId: getOrganization
934 tags:
935 - organizations
936 summary: Get organization details
937 description: |
938 This operation fetches organization details.
939 parameters:
940 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
941 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
942 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
943 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
944 - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
945 responses:
946 "200":
947 description: Organization details
948 schema:
949 $ref: "./definitions.yaml#/definitions/V4Organization"
950 examples:
951 application/json:
952 {
953 "id": "acme",
954 "members": [
955 {"email": "user1@example.com"},
956 {"email": "user2@example.com"}
957 ]
958 }
959 "401":
960 $ref: "./responses.yaml#/responses/V4Generic401Response"
961 "404":
962 description: Organization not found
963 schema:
964 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
965 examples:
966 application/json:
967 {
968 "code": "RESOURCE_NOT_FOUND",
969 "message": "The organization could not be found. (not found: the organization with id 'acme' could not be found)"
970 }
971 default:
972 description: Error
973 schema:
974 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
975 put:
976 operationId: addOrganization
977 tags:
978 - organizations
979 summary: Create an organization
980 description: |
981 This operation allows a user to create an organization.
982 parameters:
983 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
984 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
985 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
986 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
987 - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
988 - name: body
989 in: body
990 required: true
991 schema:
992 $ref: "./definitions.yaml#/definitions/V4Organization"
993 x-examples:
994 application/json:
995 {
996 "id": "string",
997 "members": [
998 {"email": "myself@example.com"},
999 {"email": "colleague@example.com"}
1000 ]
1001 }
1002 responses:
1003 "201":
1004 description: Organization created
1005 schema:
1006 $ref: "./definitions.yaml#/definitions/V4Organization"
1007 examples:
1008 application/json:
1009 {
1010 "id": "acme",
1011 "members": [
1012 {"email": "user1@example.com"},
1013 {"email": "user2@example.com"}
1014 ]
1015 }
1016 "401":
1017 $ref: "./responses.yaml#/responses/V4Generic401Response"
1018 "409":
1019 description: Organization already exists
1020 schema:
1021 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1022 examples:
1023 application/json:
1024 {
1025 "code": "RESOURCE_ALREADY_EXISTS",
1026 "message": "The organization could not be created. (org already exists)"
1027 }
1028 default:
1029 description: Error
1030 schema:
1031 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1032 patch:
1033 operationId: modifyOrganization
1034 tags:
1035 - organizations
1036 parameters:
1037 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
1038 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
1039 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
1040 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
1041 - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
1042 - name: body
1043 in: body
1044 required: true
1045 schema:
1046 type: object
1047 properties:
1048 members:
1049 type: array
1050 description: List of members that belong to this organization
1051 items:
1052 $ref: "./definitions.yaml#/definitions/V4OrganizationMember"
1053 x-examples:
1054 application/merge-patch+json:
1055 {
1056 "members": [{"email": "myself@example.com"}]
1057 }
1058
1059 summary: Modify organization
1060 description: |
1061 This operation allows you to modify an existing organization. You must be
1062 a member of the organization or an admin in order to use this endpoint.
1063
1064 The following attributes can be modified:
1065
1066 - `members`: By modifying the array of members, members can be added to or removed from the organization
1067
1068 The request body must conform with the [JSON Patch Merge (RFC 7386)](https://tools.ietf.org/html/rfc7386) standard.
1069 Requests have to be sent with the `Content-Type: application/merge-patch+json` header.
1070
1071 The full request must be valid before it will be executed, currently this
1072 means every member you attempt to add to the organization must actually
1073 exist in the system. If any member you attempt to add is invalid, the entire
1074 patch operation will fail, no members will be added or removed, and an error message
1075 will explain which members in your request are invalid.
1076 responses:
1077 "200":
1078 description: Organization modified
1079 schema:
1080 $ref: "./definitions.yaml#/definitions/V4Organization"
1081 "400":
1082 description: Invalid input
1083 schema:
1084 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1085 examples:
1086 application/json:
1087 {
1088 "code": "INVALID_INPUT",
1089 "message": "The organization could not be modified. (invalid input: user 'invalid-email' does not exist or is invalid)"
1090 }
1091 "401":
1092 $ref: "./responses.yaml#/responses/V4Generic401Response"
1093 "404":
1094 description: Organization not found
1095 schema:
1096 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1097 examples:
1098 application/json:
1099 {
1100 "code": "RESOURCE_NOT_FOUND",
1101 "message": "The organization could not be modified. (not found: the organization with id 'acme' could not be found)"
1102 }
1103 default:
1104 description: error
1105 schema:
1106 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1107 delete:
1108 operationId: deleteOrganization
1109 tags:
1110 - organizations
1111 summary: Delete an organization
1112 description: |
1113 This operation allows a user to delete an organization that they are a member of.
1114 Admin users can delete any organization.
1115 parameters:
1116 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
1117 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
1118 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
1119 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
1120 - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
1121 responses:
1122 "200":
1123 description: Organization deleted
1124 schema:
1125 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1126 examples:
1127 application/json:
1128 {
1129 "code": "RESOURCE_DELETED",
1130 "message": "The organization with ID 'acme' has been deleted."
1131 }
1132 "401":
1133 $ref: "./responses.yaml#/responses/V4Generic401Response"
1134 "404":
1135 description: Organization not found
1136 schema:
1137 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1138 examples:
1139 application/json:
1140 {
1141 "code": "RESOURCE_NOT_FOUND",
1142 "message": "The organization could not be deleted. (not found: the organization with id 'acme' could not be found)"
1143 }
1144 default:
1145 description: Error
1146 schema:
1147 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1148
1149 /v4/organizations/{organization_id}/credentials/:
1150 post:
1151 operationId: addCredentials
1152 tags:
1153 - organizations
1154 summary: Set credentials
1155 description: |
1156 Add a set of credentials to the organization allowing the creation and
1157 operation of clusters within a cloud provider account/subscription.
1158
1159 The actual type of these credentials depends on the cloud provider the
1160 installation is running on. Currently, only AWS is supported, with
1161 support for Azure being planned for the near future.
1162
1163 Credentials in an organization are immutable. Each organization can only
1164 have one set of credentials.
1165
1166 Once credentials have been set for an organization, they are used for
1167 every new cluster that will be created for the organization.
1168
1169 ### Example request body for AWS
1170
1171 ```json
1172 {
1173 "provider": "aws",
1174 "aws": {
1175 "roles": {
1176 "admin": "arn:aws:iam::123456789012:role/GiantSwarmAdmin",
1177 "awsoperator": "arn:aws:iam::123456789012:role/GiantSwarmAWSOperator"
1178 }
1179 }
1180 }
1181 ```
1182 parameters:
1183 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
1184 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
1185 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
1186 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
1187 - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
1188 - name: body
1189 in: body
1190 required: true
1191 schema:
1192 $ref: "./definitions.yaml#/definitions/V4AddCredentialsRequest"
1193 x-examples:
1194 application/json:
1195 {
1196 "provider": "aws",
1197 "aws": {
1198 "roles": {
1199 "admin": "arn:aws:iam::123456789012:role/GiantSwarmAdmin",
1200 "awsoperator": "arn:aws:iam::123456789012:role/GiantSwarmAWSOperator"
1201 }
1202 }
1203 }
1204 responses:
1205 "201":
1206 description: Credentials created
1207 headers:
1208 Location:
1209 type: string
1210 description: URI of the new credentials resource
1211 schema:
1212 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1213 examples:
1214 application/json:
1215 {
1216 "code": "RESOURCE_CREATED",
1217 "message": "A new set of credentials has been created with ID '5d9h4'"
1218 }
1219 "401":
1220 $ref: "./responses.yaml#/responses/V4Generic401Response"
1221 "409":
1222 description: Conflict
1223 schema:
1224 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1225 examples:
1226 application/json:
1227 {
1228 "code": "RESOURCE_ALREADY_EXISTS",
1229 "message": "The organisation already has a set of credentials"
1230 }
1231 default:
1232 description: error
1233 schema:
1234 $ref: "./definitions.yaml#/definitions/V4GenericResponse"
1235
1236 /v4/releases/:
1237 get:
1238 operationId: getReleases
1239 tags:
1240 - releases
1241 summary: Get releases
1242 description: |
1243 Lists all releases available for new clusters or for upgrading existing
1244 clusters. Might also serve as an archive to obtain details on older
1245 releases.
1246 parameters:
1247 - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
1248 - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
1249 - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
1250 - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
1251 responses:
1252 "200":
1253 description: Releases list
1254 schema:
1255 type: array
1256 items:
1257 $ref: "./definitions.yaml#/definitions/V4ReleaseListItem"
1258 examples:
1259 application/json:
1260 [
1261 {
1262 "version": "1.14.9",
1263 "timestamp": "2017-09-21T08:14:03.37759Z",
1264 "changelog": [
1265 {
1266 "component": "kubernetes",
1267 "description": "Security fixes"
1268 },
1269 {
1270 "component": "calico",
1271 "description": "Security fixes"
1272 }
1273 ],
1274 "components": [
1275 {
1276 "name": "kubernetes",
1277 "version": "1.5.8"
1278 },
1279 {
1280 "name": "calico",
1281 "version": "0.9.1"
1282 }
1283 ],
1284 "active": false
1285 },
1286 {
1287 "version": "2.8.4",
1288 "timestamp": "2017-11-11T12:24:56.59969Z",
1289 "changelog": [
1290 {
1291 "component": "calico",
1292 "description": "Bugfix"
1293 }
1294 ],
1295 "components": [
1296 {
1297 "name": "kubernetes",
1298 "version": "1.7.3"
1299 },
1300 {
1301 "name": "calico",
1302 "version": "1.1.1"
1303 }
1304 ],
1305 "active": true
1306 }
1307 ]
1308 "401":
1309 $ref: "./responses.yaml#/responses/V4Generic401Response"
1310
View as plain text