1consumes:
2- application/json
3produces:
4- application/json
5swagger: "2.0"
6info:
7 description: |
8 This is the documentation for the Giant Swarm API starting at version `v4`.
9
10 For an introduction to Giant Swarm, refer to the [documentation site](https://docs.giantswarm.io/).
11
12 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.
13
14 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.
15
16 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.
17
18 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.
19
20 ## Source
21
22 The source of this documentation is available on [GitHub](https://github.com/giantswarm/api-spec).
23 title: The Giant Swarm API v4
24 termsOfService: https://giantswarm.io/terms/
25 license:
26 name: Apache 2.0
27 url: http://www.apache.org/licenses/LICENSE-2.0.html
28 version: 4.0.0
29paths:
30 /v4/auth-tokens/:
31 post:
32 description: |
33 Creates a Auth Token for a given user. Must authenticate with email and password.
34 tags:
35 - auth tokens
36 summary: Create Auth Token (Login)
37 operationId: createAuthToken
38 parameters:
39 - type: string
40 description: |
41 A randomly generated key that can be used to track a request throughout
42 services of Giant Swarm.
43 name: X-Request-ID
44 in: header
45 - type: string
46 description: |
47 Name of an activity to track, like "list-clusters". This allows to
48 analyze several API requests sent in context and gives an idea on
49 the purpose.
50 name: X-Giant-Swarm-Activity
51 in: header
52 - type: string
53 description: |
54 If activity has been issued by a CLI, this header can contain the
55 command line
56 name: X-Giant-Swarm-CmdLine
57 in: header
58 - x-examples:
59 application/json:
60 email: developer@example.com
61 password_base64: cGFzc3dvcmQ=
62 description: Create Auth Token Request
63 name: body
64 in: body
65 required: true
66 schema:
67 $ref: '#/definitions/v4CreateAuthTokenRequest'
68 responses:
69 "200":
70 description: Success
71 schema:
72 $ref: '#/definitions/v4CreateAuthTokenResponse'
73 examples:
74 application/json:
75 auth_token: e5239484-2299-41df-b901-d0568db7e3f9
76 "401":
77 description: Permission denied
78 schema:
79 $ref: '#/definitions/v4GenericResponse'
80 examples:
81 application/json:
82 code: PERMISSION_DENIED
83 message: The requested resource cannot be accessed using the provided
84 authentication details.
85 delete:
86 description: |
87 Deletes the authentication token provided in the Authorization header. This effectively logs you out.
88 tags:
89 - auth tokens
90 summary: Delete Auth Token (Logout)
91 operationId: deleteAuthToken
92 parameters:
93 - type: string
94 description: As described in the [authentication](#section/Authentication)
95 section
96 name: Authorization
97 in: header
98 required: true
99 - type: string
100 description: |
101 A randomly generated key that can be used to track a request throughout
102 services of Giant Swarm.
103 name: X-Request-ID
104 in: header
105 - type: string
106 description: |
107 Name of an activity to track, like "list-clusters". This allows to
108 analyze several API requests sent in context and gives an idea on
109 the purpose.
110 name: X-Giant-Swarm-Activity
111 in: header
112 - type: string
113 description: |
114 If activity has been issued by a CLI, this header can contain the
115 command line
116 name: X-Giant-Swarm-CmdLine
117 in: header
118 responses:
119 "200":
120 description: Success
121 schema:
122 $ref: '#/definitions/v4GenericResponse'
123 examples:
124 application/json:
125 code: RESOURCE_DELETED
126 message: The authentication token has been succesfully deleted.
127 "401":
128 description: Permission denied
129 schema:
130 $ref: '#/definitions/v4GenericResponse'
131 examples:
132 application/json:
133 code: PERMISSION_DENIED
134 message: The requested resource cannot be accessed using the provided
135 authentication details.
136 /v4/clusters/:
137 get:
138 description: |
139 This operation fetches a list of clusters.
140
141 The result depends on the permissions of the user.
142 A normal user will get all the clusters the user has access
143 to, via organization membership.
144 A user with admin permission will receive a list of all existing
145 clusters.
146
147 The result array items are sparse representations of the cluster objects.
148 To fetch more details on a cluster, use the [getCluster](#operation/getCluster)
149 operation.
150 tags:
151 - clusters
152 summary: Get clusters
153 operationId: getClusters
154 parameters:
155 - type: string
156 description: As described in the [authentication](#section/Authentication)
157 section
158 name: Authorization
159 in: header
160 required: true
161 - type: string
162 description: |
163 A randomly generated key that can be used to track a request throughout
164 services of Giant Swarm.
165 name: X-Request-ID
166 in: header
167 - type: string
168 description: |
169 Name of an activity to track, like "list-clusters". This allows to
170 analyze several API requests sent in context and gives an idea on
171 the purpose.
172 name: X-Giant-Swarm-Activity
173 in: header
174 - type: string
175 description: |
176 If activity has been issued by a CLI, this header can contain the
177 command line
178 name: X-Giant-Swarm-CmdLine
179 in: header
180 responses:
181 "200":
182 description: Success
183 schema:
184 type: array
185 items:
186 $ref: '#/definitions/v4ClusterListItem'
187 examples:
188 application/json:
189 - create_date: "2017-06-08T12:31:47.215Z"
190 id: g8s3o
191 name: Staging Cluster
192 owner: acme
193 - create_date: "2017-05-22T13:58:02.024Z"
194 id: 3dkr6
195 name: Test Cluster
196 owner: testorg
197 "401":
198 description: Permission denied
199 schema:
200 $ref: '#/definitions/v4GenericResponse'
201 examples:
202 application/json:
203 code: PERMISSION_DENIED
204 message: The requested resource cannot be accessed using the provided
205 authentication details.
206 default:
207 description: Error
208 schema:
209 $ref: '#/definitions/v4GenericResponse'
210 post:
211 description: |
212 This operation is used to create a new Kubernetes cluster for an
213 organization. The desired configuration can be specified using the
214 __cluster definition format__ (see
215 [external documentation](https://github.com/giantswarm/api-spec/blob/master/details/CLUSTER_DEFINITION.md)
216 for details).
217
218 The cluster definition format allows to set a number of optional
219 configuration details, like memory size and number of CPU cores.
220 However, one attribute is __mandatory__ upon creation: The `owner`
221 attribute must carry the name of the organization the cluster will
222 belong to. Note that the acting user must be a member of that
223 organization in order to create a cluster.
224
225 It is *recommended* to also specify the `name` attribute to give the
226 cluster a friendly name, like e. g. "Development Cluster".
227
228 Additional definition attributes can be used. Where attributes are
229 omitted, default configuration values will be applied. For example, if
230 no `release_version` is specified, the most recent version is used.
231
232 The `workers` attribute, if present, must contain an array of node
233 definition objects. The number of objects given determines the number
234 of workers created.
235
236 For example, requesting three worker nodes with default configuration
237 can be achieved by submitting an array of three empty objects:
238
239 ```"workers": [{}, {}, {}]```
240
241 For clusters on AWS, note that all worker nodes must use the same instance type.
242 tags:
243 - clusters
244 summary: Create cluster
245 operationId: addCluster
246 parameters:
247 - type: string
248 description: As described in the [authentication](#section/Authentication)
249 section
250 name: Authorization
251 in: header
252 required: true
253 - type: string
254 description: |
255 A randomly generated key that can be used to track a request throughout
256 services of Giant Swarm.
257 name: X-Request-ID
258 in: header
259 - type: string
260 description: |
261 Name of an activity to track, like "list-clusters". This allows to
262 analyze several API requests sent in context and gives an idea on
263 the purpose.
264 name: X-Giant-Swarm-Activity
265 in: header
266 - type: string
267 description: |
268 If activity has been issued by a CLI, this header can contain the
269 command line
270 name: X-Giant-Swarm-CmdLine
271 in: header
272 - x-examples:
273 application/json:
274 name: Example cluster with 3 default worker nodes
275 owner: myteam
276 release_version: 1.4.2
277 workers:
278 - {}
279 - {}
280 - {}
281 description: New cluster definition
282 name: body
283 in: body
284 required: true
285 schema:
286 $ref: '#/definitions/v4AddClusterRequest'
287 responses:
288 "201":
289 description: Cluster created
290 schema:
291 $ref: '#/definitions/v4GenericResponse'
292 headers:
293 Location:
294 type: string
295 description: URI to obtain details on the new cluster using the [getCluster](#operation/getCluster)
296 operation
297 examples:
298 application/json:
299 code: RESOURCE_CREATED
300 message: A new cluster has been created with ID 'wqtlq'
301 "401":
302 description: Permission denied
303 schema:
304 $ref: '#/definitions/v4GenericResponse'
305 examples:
306 application/json:
307 code: PERMISSION_DENIED
308 message: The requested resource cannot be accessed using the provided
309 authentication details.
310 default:
311 description: error
312 schema:
313 $ref: '#/definitions/v4GenericResponse'
314 /v4/clusters/{cluster_id}/:
315 get:
316 description: |
317 This operation allows to obtain all available details on a particular cluster.
318 tags:
319 - clusters
320 summary: Get cluster details
321 operationId: getCluster
322 parameters:
323 - type: string
324 description: As described in the [authentication](#section/Authentication)
325 section
326 name: Authorization
327 in: header
328 required: true
329 - type: string
330 description: |
331 A randomly generated key that can be used to track a request throughout
332 services of Giant Swarm.
333 name: X-Request-ID
334 in: header
335 - type: string
336 description: |
337 Name of an activity to track, like "list-clusters". This allows to
338 analyze several API requests sent in context and gives an idea on
339 the purpose.
340 name: X-Giant-Swarm-Activity
341 in: header
342 - type: string
343 description: |
344 If activity has been issued by a CLI, this header can contain the
345 command line
346 name: X-Giant-Swarm-CmdLine
347 in: header
348 - type: string
349 description: Cluster ID
350 name: cluster_id
351 in: path
352 required: true
353 responses:
354 "200":
355 description: Cluster details
356 schema:
357 $ref: '#/definitions/v4ClusterDetailsResponse'
358 examples:
359 application/json:
360 api_endpoint: https://api.wqtlq.example.com
361 create_date: "2017-03-03T10:50:45.949270905Z"
362 id: wqtlq
363 kubernetes_version: ""
364 kvm:
365 port_mappings:
366 - port: 30020
367 protocol: http
368 - port: 30021
369 protocol: https
370 name: Just a Standard Cluster
371 owner: acme
372 release_version: 2.5.16
373 workers:
374 - cpu:
375 cores: 4
376 labels:
377 beta.kubernetes.io/arch: amd64
378 beta.kubernetes.io/os: linux
379 ip: 10.3.11.2
380 kubernetes.io/hostname: worker-1.x882ofna.k8s.gigantic.io
381 nodetype: hicpu
382 memory:
383 size_gb: 2
384 storage:
385 size_gb: 20
386 - cpu:
387 cores: 2
388 labels:
389 beta.kubernetes.io/arch: amd64
390 beta.kubernetes.io/os: linux
391 ip: 10.3.62.2
392 kubernetes.io/hostname: worker-2.x882ofna.k8s.gigantic.io
393 nodetype: hiram
394 memory:
395 size_gb: 8
396 storage:
397 size_gb: 20
398 "401":
399 description: Permission denied
400 schema:
401 $ref: '#/definitions/v4GenericResponse'
402 examples:
403 application/json:
404 code: PERMISSION_DENIED
405 message: The requested resource cannot be accessed using the provided
406 authentication details.
407 "404":
408 description: Cluster not found
409 schema:
410 $ref: '#/definitions/v4GenericResponse'
411 examples:
412 application/json:
413 code: RESOURCE_NOT_FOUND
414 message: The cluster with ID 'wqtlq' could not be found, or perhaps
415 you do not have access to it. Please make sure the cluster ID is correct,
416 and that you are a member of the organization that it belongs to.
417 default:
418 description: error
419 schema:
420 $ref: '#/definitions/v4GenericResponse'
421 delete:
422 description: |
423 This operation allows to delete a cluster.
424
425 __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.
426
427 The response is sent as soon as the request is validated.
428 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.
429 tags:
430 - clusters
431 summary: Delete cluster
432 operationId: deleteCluster
433 parameters:
434 - type: string
435 description: As described in the [authentication](#section/Authentication)
436 section
437 name: Authorization
438 in: header
439 required: true
440 - type: string
441 description: |
442 A randomly generated key that can be used to track a request throughout
443 services of Giant Swarm.
444 name: X-Request-ID
445 in: header
446 - type: string
447 description: |
448 Name of an activity to track, like "list-clusters". This allows to
449 analyze several API requests sent in context and gives an idea on
450 the purpose.
451 name: X-Giant-Swarm-Activity
452 in: header
453 - type: string
454 description: |
455 If activity has been issued by a CLI, this header can contain the
456 command line
457 name: X-Giant-Swarm-CmdLine
458 in: header
459 - type: string
460 description: Cluster ID
461 name: cluster_id
462 in: path
463 required: true
464 responses:
465 "202":
466 description: Deleting cluster
467 schema:
468 $ref: '#/definitions/v4GenericResponse'
469 examples:
470 application/json:
471 code: RESOURCE_DELETION_STARTED
472 message: The cluster with ID 'wqtlq' is being deleted.
473 "401":
474 description: Permission denied
475 schema:
476 $ref: '#/definitions/v4GenericResponse'
477 examples:
478 application/json:
479 code: PERMISSION_DENIED
480 message: The requested resource cannot be accessed using the provided
481 authentication details.
482 "404":
483 description: Cluster not found
484 schema:
485 $ref: '#/definitions/v4GenericResponse'
486 examples:
487 application/json:
488 code: RESOURCE_NOT_FOUND
489 message: The cluster with ID 'wqtlq' could not be found, or perhaps
490 you do not have access to it. Please make sure the cluster ID is correct,
491 and that you are a member of the organization that it belongs to.
492 default:
493 description: error
494 schema:
495 $ref: '#/definitions/v4GenericResponse'
496 patch:
497 description: |
498 This operation allows to modify an existing cluster.
499
500 A cluster modification is performed by submitting a `PATCH` request
501 to the cluster resource (as described in the
502 [addCluster](#operation/addCluster) and [getCluster](#operation/getCluster))
503 in form of a [JSON Patch Merge
504 (RFC 7386)](https://tools.ietf.org/html/rfc7386). This means, only the
505 attributes to be modified have to be contained in the request body.
506
507 The following attributes can be modified:
508
509 - `name`: Rename the cluster to something more fitting.
510
511 - `owner`: Changing the owner organization name means to change cluster
512 ownership from one organization to another. The user performing the
513 request has to be a member of both organizations.
514
515 - `release_version`: By changing this attribute you can upgrade a
516 cluster to a newer
517 [release](https://docs.giantswarm.io/api/#tag/releases).
518
519 - `workers`: By modifying the array of workers, nodes can be added to
520 increase the cluster's capacity. See details below.
521
522 ### Adding and Removing Worker Nodes (Scaling)
523
524 Adding worker nodes to a cluster or removing worker nodes from a cluster
525 works by submitting the `workers` attribute, which contains a (sparse)
526 array of worker node defintions.
527
528 _Sparse_ here means that all configuration details are optional. In the
529 case that worker nodes are added to a cluster, wherever a configuration
530 detail is missing, defaults will be applied. See
531 [Creating a cluster](#operation/addCluster) for details.
532
533 When modifying the cluster resource, you describe the desired state.
534 For scaling, this means that the worker node array submitted must
535 contain as many elements as the cluster should have worker nodes.
536 If your cluster currently has five nodes and you submit a workers
537 array with four elements, this means that one worker node will be removed.
538 If your submitted workers array has six elements, this means one will
539 be added.
540
541 As an example, this request body could be used to scale a cluster to
542 three worker nodes:
543
544 ```json
545 {
546 "workers": [{}, {}, {}]
547 }
548 ```
549
550 If the scaled cluster had four worker nodes before, one would be removed.
551 If it had two worker nodes before, one with default settings would be
552 added.
553
554 ### Limitations
555
556 - As of now, existing worker nodes cannot be modified.
557 - When removing nodes (scaling down), it is not possible to determine
558 which nodes will be removed.
559 - On AWS based clusters, all worker nodes must use the same EC2 instance
560 type (`instance_type` node attribute). By not setting an `instance_type`
561 when submitting a PATCH request, you ensure that the right instance type
562 is used automatically.
563 tags:
564 - clusters
565 summary: Modify cluster
566 operationId: modifyCluster
567 parameters:
568 - type: string
569 description: As described in the [authentication](#section/Authentication)
570 section
571 name: Authorization
572 in: header
573 required: true
574 - type: string
575 description: |
576 A randomly generated key that can be used to track a request throughout
577 services of Giant Swarm.
578 name: X-Request-ID
579 in: header
580 - type: string
581 description: |
582 Name of an activity to track, like "list-clusters". This allows to
583 analyze several API requests sent in context and gives an idea on
584 the purpose.
585 name: X-Giant-Swarm-Activity
586 in: header
587 - type: string
588 description: |
589 If activity has been issued by a CLI, this header can contain the
590 command line
591 name: X-Giant-Swarm-CmdLine
592 in: header
593 - x-examples:
594 application/merge-patch+json:
595 name: New cluster name
596 description: Merge-patch body
597 name: body
598 in: body
599 required: true
600 schema:
601 $ref: '#/definitions/v4ModifyClusterRequest'
602 - type: string
603 description: Cluster ID
604 name: cluster_id
605 in: path
606 required: true
607 responses:
608 "200":
609 description: Cluster modified
610 schema:
611 $ref: '#/definitions/v4ClusterDetailsResponse'
612 "401":
613 description: Permission denied
614 schema:
615 $ref: '#/definitions/v4GenericResponse'
616 examples:
617 application/json:
618 code: PERMISSION_DENIED
619 message: The requested resource cannot be accessed using the provided
620 authentication details.
621 "404":
622 description: Cluster not found
623 schema:
624 $ref: '#/definitions/v4GenericResponse'
625 examples:
626 application/json:
627 code: RESOURCE_NOT_FOUND
628 message: The cluster with ID 'wqtlq' could not be found, or perhaps
629 you do not have access to it. Please make sure the cluster ID is correct,
630 and that you are a member of the organization that it belongs to.
631 default:
632 description: error
633 schema:
634 $ref: '#/definitions/v4GenericResponse'
635 /v4/clusters/{cluster_id}/key-pairs/:
636 get:
637 description: |
638 Returns a list of information on all key pairs of a cluster as an array.
639
640 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.
641 tags:
642 - key pairs
643 summary: Get key pairs
644 operationId: getKeyPairs
645 parameters:
646 - type: string
647 description: As described in the [authentication](#section/Authentication)
648 section
649 name: Authorization
650 in: header
651 required: true
652 - type: string
653 description: |
654 A randomly generated key that can be used to track a request throughout
655 services of Giant Swarm.
656 name: X-Request-ID
657 in: header
658 - type: string
659 description: |
660 Name of an activity to track, like "list-clusters". This allows to
661 analyze several API requests sent in context and gives an idea on
662 the purpose.
663 name: X-Giant-Swarm-Activity
664 in: header
665 - type: string
666 description: |
667 If activity has been issued by a CLI, this header can contain the
668 command line
669 name: X-Giant-Swarm-CmdLine
670 in: header
671 - type: string
672 description: Cluster ID
673 name: cluster_id
674 in: path
675 required: true
676 responses:
677 "200":
678 description: Key pairs
679 schema:
680 $ref: '#/definitions/v4GetKeyPairsResponse'
681 "401":
682 description: Permission denied
683 schema:
684 $ref: '#/definitions/v4GenericResponse'
685 examples:
686 application/json:
687 code: PERMISSION_DENIED
688 message: The requested resource cannot be accessed using the provided
689 authentication details.
690 default:
691 description: error
692 schema:
693 $ref: '#/definitions/v4GenericResponse'
694 post:
695 description: |
696 This operation allows to create a new key pair for accessing a specific cluster.
697
698 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.
699
700 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.
701
702 ### Customizing the certificate's subject for K8s RBAC
703
704 It is possible to set the Common Name and Organization fields of the generated certificate's subject.
705
706 - `cn_prefix`: The certificate's common name uses this format: `<cn_prefix>.user.<clusterdomain>`.
707
708 `clusterdomain` is specific to your cluster and is not editable.
709
710 The `cn_prefix` however is editable. When left blank it will default
711 to the email address of the Giant Swarm user that is performing the
712 create key pair request.
713
714 The common name is used as the username for requests to the Kubernetes API. This allows you
715 to set up role-based access controls.
716
717
718 - `certificate_organizations`: This will set the certificate's `organization` fields. Use a comma separated list of values.
719 The Kubernetes API will use these values as group memberships.
720
721 __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.
722 tags:
723 - key pairs
724 summary: Create key pair
725 operationId: addKeyPair
726 parameters:
727 - type: string
728 description: As described in the [authentication](#section/Authentication)
729 section
730 name: Authorization
731 in: header
732 required: true
733 - type: string
734 description: |
735 A randomly generated key that can be used to track a request throughout
736 services of Giant Swarm.
737 name: X-Request-ID
738 in: header
739 - type: string
740 description: |
741 Name of an activity to track, like "list-clusters". This allows to
742 analyze several API requests sent in context and gives an idea on
743 the purpose.
744 name: X-Giant-Swarm-Activity
745 in: header
746 - type: string
747 description: |
748 If activity has been issued by a CLI, this header can contain the
749 command line
750 name: X-Giant-Swarm-CmdLine
751 in: header
752 - type: string
753 description: Cluster ID
754 name: cluster_id
755 in: path
756 required: true
757 - x-examples:
758 application/json:
759 certificate_organizations: system:masters
760 description: Admin key pair lasting twelve hours
761 ttl_hours: 12
762 description: |
763 While the `ttl_hours` attribute is optional and will be set to a default value when omitted, the `description` is mandatory.
764 name: body
765 in: body
766 required: true
767 schema:
768 $ref: '#/definitions/v4AddKeyPairRequest'
769 responses:
770 "200":
771 description: Success
772 schema:
773 $ref: '#/definitions/v4AddKeyPairResponse'
774 examples:
775 application/json:
776 certificate_authority_data: '-----BEGIN CERTIFICATE-----...-----END
777 CERTIFICATE-----'
778 client_certificate_data: '-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----'
779 client_key_data: '-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE
780 KEY-----'
781 create_date: "2016-06-01T12:00:00.000Z"
782 description: Key pair description
783 id: 02:cc:da:f9:fb:ce:c3:e5:e1:f6:27:d8:43:48:0d:37:4a:ee:b9:67
784 ttl_hours: 8640
785 "401":
786 description: Permission denied
787 schema:
788 $ref: '#/definitions/v4GenericResponse'
789 examples:
790 application/json:
791 code: PERMISSION_DENIED
792 message: The requested resource cannot be accessed using the provided
793 authentication details.
794 /v4/info/:
795 get:
796 description: |
797 Returns a set of details on the installation. The output varies based
798 on the provider used in the installation.
799
800 This information is useful for example when creating new cluster, to
801 prevent creating clusters with more worker nodes than possible.
802
803 ### Example for an AWS-based installation
804
805 ```json
806 {
807 "general": {
808 "installation_name": "shire",
809 "provider": "aws",
810 "datacenter": "eu-central-1"
811 },
812 "workers": {
813 "count_per_cluster": {
814 "max": 20,
815 "default": 3
816 },
817 "instance_type": {
818 "options": [
819 "m3.medium", "m3.large", "m3.xlarge"
820 ],
821 "default": "m3.large"
822 }
823 }
824 }
825 ```
826
827 ### Example for a KVM-based installation
828
829 ```json
830 {
831 "general": {
832 "installation_name": "isengard",
833 "provider": "kvm",
834 "datacenter": "string"
835 },
836 "workers": {
837 "count_per_cluster": {
838 "max": 8,
839 "default": 3
840 },
841 }
842 }
843 ```
844 tags:
845 - info
846 summary: Get information on the installation
847 operationId: getInfo
848 parameters:
849 - type: string
850 description: As described in the [authentication](#section/Authentication)
851 section
852 name: Authorization
853 in: header
854 required: true
855 - type: string
856 description: |
857 A randomly generated key that can be used to track a request throughout
858 services of Giant Swarm.
859 name: X-Request-ID
860 in: header
861 - type: string
862 description: |
863 Name of an activity to track, like "list-clusters". This allows to
864 analyze several API requests sent in context and gives an idea on
865 the purpose.
866 name: X-Giant-Swarm-Activity
867 in: header
868 - type: string
869 description: |
870 If activity has been issued by a CLI, this header can contain the
871 command line
872 name: X-Giant-Swarm-CmdLine
873 in: header
874 responses:
875 "200":
876 description: Information
877 schema:
878 $ref: '#/definitions/v4InfoResponse'
879 examples:
880 application/json:
881 general:
882 datacenter: eu-central-1
883 installation_name: shire
884 provider: aws
885 workers:
886 count_per_cluster:
887 default: 3
888 max: 20
889 instance_type:
890 default: m3.large
891 options:
892 - m3.medium
893 - m3.large
894 - m3.xlarge
895 "401":
896 description: Permission denied
897 schema:
898 $ref: '#/definitions/v4GenericResponse'
899 examples:
900 application/json:
901 code: PERMISSION_DENIED
902 message: The requested resource cannot be accessed using the provided
903 authentication details.
904 default:
905 description: Error
906 schema:
907 $ref: '#/definitions/v4GenericResponse'
908 /v4/organizations/:
909 get:
910 description: |
911 This operation allows to fetch a list of organizations the user is a
912 member of. In the case of an admin user, the result includes all
913 existing organizations.
914 tags:
915 - organizations
916 summary: Get organizations
917 operationId: getOrganizations
918 parameters:
919 - type: string
920 description: As described in the [authentication](#section/Authentication)
921 section
922 name: Authorization
923 in: header
924 required: true
925 - type: string
926 description: |
927 A randomly generated key that can be used to track a request throughout
928 services of Giant Swarm.
929 name: X-Request-ID
930 in: header
931 - type: string
932 description: |
933 Name of an activity to track, like "list-clusters". This allows to
934 analyze several API requests sent in context and gives an idea on
935 the purpose.
936 name: X-Giant-Swarm-Activity
937 in: header
938 - type: string
939 description: |
940 If activity has been issued by a CLI, this header can contain the
941 command line
942 name: X-Giant-Swarm-CmdLine
943 in: header
944 responses:
945 "200":
946 description: Success
947 schema:
948 type: array
949 items:
950 $ref: '#/definitions/v4OrganizationListItem'
951 examples:
952 application/json:
953 - id: acme
954 - id: giantswarm
955 - id: testorg
956 "401":
957 description: Permission denied
958 schema:
959 $ref: '#/definitions/v4GenericResponse'
960 examples:
961 application/json:
962 code: PERMISSION_DENIED
963 message: The requested resource cannot be accessed using the provided
964 authentication details.
965 default:
966 description: Error
967 schema:
968 $ref: '#/definitions/v4GenericResponse'
969 /v4/organizations/{organization_id}/:
970 get:
971 description: |
972 This operation fetches organization details.
973 tags:
974 - organizations
975 summary: Get organization details
976 operationId: getOrganization
977 parameters:
978 - type: string
979 description: As described in the [authentication](#section/Authentication)
980 section
981 name: Authorization
982 in: header
983 required: true
984 - type: string
985 description: |
986 A randomly generated key that can be used to track a request throughout
987 services of Giant Swarm.
988 name: X-Request-ID
989 in: header
990 - type: string
991 description: |
992 Name of an activity to track, like "list-clusters". This allows to
993 analyze several API requests sent in context and gives an idea on
994 the purpose.
995 name: X-Giant-Swarm-Activity
996 in: header
997 - type: string
998 description: |
999 If activity has been issued by a CLI, this header can contain the
1000 command line
1001 name: X-Giant-Swarm-CmdLine
1002 in: header
1003 - type: string
1004 description: |
1005 An ID for the organization.
1006 This ID must be unique and match this regular
1007 expression: ^[a-z0-9_]{4,30}$
1008 name: organization_id
1009 in: path
1010 required: true
1011 responses:
1012 "200":
1013 description: Organization details
1014 schema:
1015 $ref: '#/definitions/v4Organization'
1016 examples:
1017 application/json:
1018 id: acme
1019 members:
1020 - email: user1@example.com
1021 - email: user2@example.com
1022 "401":
1023 description: Permission denied
1024 schema:
1025 $ref: '#/definitions/v4GenericResponse'
1026 examples:
1027 application/json:
1028 code: PERMISSION_DENIED
1029 message: The requested resource cannot be accessed using the provided
1030 authentication details.
1031 "404":
1032 description: Organization not found
1033 schema:
1034 $ref: '#/definitions/v4GenericResponse'
1035 examples:
1036 application/json:
1037 code: RESOURCE_NOT_FOUND
1038 message: 'The organization could not be found. (not found: the organization
1039 with id ''acme'' could not be found)'
1040 default:
1041 description: Error
1042 schema:
1043 $ref: '#/definitions/v4GenericResponse'
1044 put:
1045 description: |
1046 This operation allows a user to create an organization.
1047 tags:
1048 - organizations
1049 summary: Create an organization
1050 operationId: addOrganization
1051 parameters:
1052 - type: string
1053 description: As described in the [authentication](#section/Authentication)
1054 section
1055 name: Authorization
1056 in: header
1057 required: true
1058 - type: string
1059 description: |
1060 A randomly generated key that can be used to track a request throughout
1061 services of Giant Swarm.
1062 name: X-Request-ID
1063 in: header
1064 - type: string
1065 description: |
1066 Name of an activity to track, like "list-clusters". This allows to
1067 analyze several API requests sent in context and gives an idea on
1068 the purpose.
1069 name: X-Giant-Swarm-Activity
1070 in: header
1071 - type: string
1072 description: |
1073 If activity has been issued by a CLI, this header can contain the
1074 command line
1075 name: X-Giant-Swarm-CmdLine
1076 in: header
1077 - type: string
1078 description: |
1079 An ID for the organization.
1080 This ID must be unique and match this regular
1081 expression: ^[a-z0-9_]{4,30}$
1082 name: organization_id
1083 in: path
1084 required: true
1085 - x-examples:
1086 application/json:
1087 id: string
1088 members:
1089 - email: myself@example.com
1090 - email: colleague@example.com
1091 name: body
1092 in: body
1093 required: true
1094 schema:
1095 $ref: '#/definitions/v4Organization'
1096 responses:
1097 "201":
1098 description: Organization created
1099 schema:
1100 $ref: '#/definitions/v4Organization'
1101 examples:
1102 application/json:
1103 id: acme
1104 members:
1105 - email: user1@example.com
1106 - email: user2@example.com
1107 "401":
1108 description: Permission denied
1109 schema:
1110 $ref: '#/definitions/v4GenericResponse'
1111 examples:
1112 application/json:
1113 code: PERMISSION_DENIED
1114 message: The requested resource cannot be accessed using the provided
1115 authentication details.
1116 "409":
1117 description: Organization already exists
1118 schema:
1119 $ref: '#/definitions/v4GenericResponse'
1120 examples:
1121 application/json:
1122 code: RESOURCE_ALREADY_EXISTS
1123 message: The organization could not be created. (org already exists)
1124 default:
1125 description: Error
1126 schema:
1127 $ref: '#/definitions/v4GenericResponse'
1128 delete:
1129 description: |
1130 This operation allows a user to delete an organization that they are a member of.
1131 Admin users can delete any organization.
1132 tags:
1133 - organizations
1134 summary: Delete an organization
1135 operationId: deleteOrganization
1136 parameters:
1137 - type: string
1138 description: As described in the [authentication](#section/Authentication)
1139 section
1140 name: Authorization
1141 in: header
1142 required: true
1143 - type: string
1144 description: |
1145 A randomly generated key that can be used to track a request throughout
1146 services of Giant Swarm.
1147 name: X-Request-ID
1148 in: header
1149 - type: string
1150 description: |
1151 Name of an activity to track, like "list-clusters". This allows to
1152 analyze several API requests sent in context and gives an idea on
1153 the purpose.
1154 name: X-Giant-Swarm-Activity
1155 in: header
1156 - type: string
1157 description: |
1158 If activity has been issued by a CLI, this header can contain the
1159 command line
1160 name: X-Giant-Swarm-CmdLine
1161 in: header
1162 - type: string
1163 description: |
1164 An ID for the organization.
1165 This ID must be unique and match this regular
1166 expression: ^[a-z0-9_]{4,30}$
1167 name: organization_id
1168 in: path
1169 required: true
1170 responses:
1171 "200":
1172 description: Organization deleted
1173 schema:
1174 $ref: '#/definitions/v4GenericResponse'
1175 examples:
1176 application/json:
1177 code: RESOURCE_DELETED
1178 message: The organization with ID 'acme' has been deleted.
1179 "401":
1180 description: Permission denied
1181 schema:
1182 $ref: '#/definitions/v4GenericResponse'
1183 examples:
1184 application/json:
1185 code: PERMISSION_DENIED
1186 message: The requested resource cannot be accessed using the provided
1187 authentication details.
1188 "404":
1189 description: Organization not found
1190 schema:
1191 $ref: '#/definitions/v4GenericResponse'
1192 examples:
1193 application/json:
1194 code: RESOURCE_NOT_FOUND
1195 message: 'The organization could not be deleted. (not found: the organization
1196 with id ''acme'' could not be found)'
1197 default:
1198 description: Error
1199 schema:
1200 $ref: '#/definitions/v4GenericResponse'
1201 patch:
1202 description: |
1203 This operation allows you to modify an existing organization. You must be
1204 a member of the organization or an admin in order to use this endpoint.
1205
1206 The following attributes can be modified:
1207
1208 - `members`: By modifying the array of members, members can be added to or removed from the organization
1209
1210 The request body must conform with the [JSON Patch Merge (RFC 7386)](https://tools.ietf.org/html/rfc7386) standard.
1211 Requests have to be sent with the `Content-Type: application/merge-patch+json` header.
1212
1213 The full request must be valid before it will be executed, currently this
1214 means every member you attempt to add to the organization must actually
1215 exist in the system. If any member you attempt to add is invalid, the entire
1216 patch operation will fail, no members will be added or removed, and an error message
1217 will explain which members in your request are invalid.
1218 tags:
1219 - organizations
1220 summary: Modify organization
1221 operationId: modifyOrganization
1222 parameters:
1223 - type: string
1224 description: As described in the [authentication](#section/Authentication)
1225 section
1226 name: Authorization
1227 in: header
1228 required: true
1229 - type: string
1230 description: |
1231 A randomly generated key that can be used to track a request throughout
1232 services of Giant Swarm.
1233 name: X-Request-ID
1234 in: header
1235 - type: string
1236 description: |
1237 Name of an activity to track, like "list-clusters". This allows to
1238 analyze several API requests sent in context and gives an idea on
1239 the purpose.
1240 name: X-Giant-Swarm-Activity
1241 in: header
1242 - type: string
1243 description: |
1244 If activity has been issued by a CLI, this header can contain the
1245 command line
1246 name: X-Giant-Swarm-CmdLine
1247 in: header
1248 - type: string
1249 description: |
1250 An ID for the organization.
1251 This ID must be unique and match this regular
1252 expression: ^[a-z0-9_]{4,30}$
1253 name: organization_id
1254 in: path
1255 required: true
1256 - x-examples:
1257 application/merge-patch+json:
1258 members:
1259 - email: myself@example.com
1260 name: body
1261 in: body
1262 required: true
1263 schema:
1264 $ref: '#/definitions/modifyOrganizationParamsBody'
1265 responses:
1266 "200":
1267 description: Organization modified
1268 schema:
1269 $ref: '#/definitions/v4Organization'
1270 "400":
1271 description: Invalid input
1272 schema:
1273 $ref: '#/definitions/v4GenericResponse'
1274 examples:
1275 application/json:
1276 code: INVALID_INPUT
1277 message: 'The organization could not be modified. (invalid input: user
1278 ''invalid-email'' does not exist or is invalid)'
1279 "401":
1280 description: Permission denied
1281 schema:
1282 $ref: '#/definitions/v4GenericResponse'
1283 examples:
1284 application/json:
1285 code: PERMISSION_DENIED
1286 message: The requested resource cannot be accessed using the provided
1287 authentication details.
1288 "404":
1289 description: Organization not found
1290 schema:
1291 $ref: '#/definitions/v4GenericResponse'
1292 examples:
1293 application/json:
1294 code: RESOURCE_NOT_FOUND
1295 message: 'The organization could not be modified. (not found: the organization
1296 with id ''acme'' could not be found)'
1297 default:
1298 description: error
1299 schema:
1300 $ref: '#/definitions/v4GenericResponse'
1301 /v4/organizations/{organization_id}/credentials/:
1302 post:
1303 description: |
1304 Add a set of credentials to the organization allowing the creation and
1305 operation of clusters within a cloud provider account/subscription.
1306
1307 The actual type of these credentials depends on the cloud provider the
1308 installation is running on. Currently, only AWS is supported, with
1309 support for Azure being planned for the near future.
1310
1311 Credentials in an organization are immutable. Each organization can only
1312 have one set of credentials.
1313
1314 Once credentials have been set for an organization, they are used for
1315 every new cluster that will be created for the organization.
1316
1317 ### Example request body for AWS
1318
1319 ```json
1320 {
1321 "provider": "aws",
1322 "aws": {
1323 "roles": {
1324 "admin": "arn:aws:iam::123456789012:role/GiantSwarmAdmin",
1325 "awsoperator": "arn:aws:iam::123456789012:role/GiantSwarmAWSOperator"
1326 }
1327 }
1328 }
1329 ```
1330 tags:
1331 - organizations
1332 summary: Set credentials
1333 operationId: addCredentials
1334 parameters:
1335 - type: string
1336 description: As described in the [authentication](#section/Authentication)
1337 section
1338 name: Authorization
1339 in: header
1340 required: true
1341 - type: string
1342 description: |
1343 A randomly generated key that can be used to track a request throughout
1344 services of Giant Swarm.
1345 name: X-Request-ID
1346 in: header
1347 - type: string
1348 description: |
1349 Name of an activity to track, like "list-clusters". This allows to
1350 analyze several API requests sent in context and gives an idea on
1351 the purpose.
1352 name: X-Giant-Swarm-Activity
1353 in: header
1354 - type: string
1355 description: |
1356 If activity has been issued by a CLI, this header can contain the
1357 command line
1358 name: X-Giant-Swarm-CmdLine
1359 in: header
1360 - type: string
1361 description: |
1362 An ID for the organization.
1363 This ID must be unique and match this regular
1364 expression: ^[a-z0-9_]{4,30}$
1365 name: organization_id
1366 in: path
1367 required: true
1368 - x-examples:
1369 application/json:
1370 aws:
1371 roles:
1372 admin: arn:aws:iam::123456789012:role/GiantSwarmAdmin
1373 awsoperator: arn:aws:iam::123456789012:role/GiantSwarmAWSOperator
1374 provider: aws
1375 name: body
1376 in: body
1377 required: true
1378 schema:
1379 $ref: '#/definitions/v4AddCredentialsRequest'
1380 responses:
1381 "201":
1382 description: Credentials created
1383 schema:
1384 $ref: '#/definitions/v4GenericResponse'
1385 headers:
1386 Location:
1387 type: string
1388 description: URI of the new credentials resource
1389 examples:
1390 application/json:
1391 code: RESOURCE_CREATED
1392 message: A new set of credentials has been created with ID '5d9h4'
1393 "401":
1394 description: Permission denied
1395 schema:
1396 $ref: '#/definitions/v4GenericResponse'
1397 examples:
1398 application/json:
1399 code: PERMISSION_DENIED
1400 message: The requested resource cannot be accessed using the provided
1401 authentication details.
1402 "409":
1403 description: Conflict
1404 schema:
1405 $ref: '#/definitions/v4GenericResponse'
1406 examples:
1407 application/json:
1408 code: RESOURCE_ALREADY_EXISTS
1409 message: The organisation already has a set of credentials
1410 default:
1411 description: error
1412 schema:
1413 $ref: '#/definitions/v4GenericResponse'
1414 /v4/releases/:
1415 get:
1416 description: |
1417 Lists all releases available for new clusters or for upgrading existing
1418 clusters. Might also serve as an archive to obtain details on older
1419 releases.
1420 tags:
1421 - releases
1422 summary: Get releases
1423 operationId: getReleases
1424 parameters:
1425 - type: string
1426 description: As described in the [authentication](#section/Authentication)
1427 section
1428 name: Authorization
1429 in: header
1430 required: true
1431 - type: string
1432 description: |
1433 A randomly generated key that can be used to track a request throughout
1434 services of Giant Swarm.
1435 name: X-Request-ID
1436 in: header
1437 - type: string
1438 description: |
1439 Name of an activity to track, like "list-clusters". This allows to
1440 analyze several API requests sent in context and gives an idea on
1441 the purpose.
1442 name: X-Giant-Swarm-Activity
1443 in: header
1444 - type: string
1445 description: |
1446 If activity has been issued by a CLI, this header can contain the
1447 command line
1448 name: X-Giant-Swarm-CmdLine
1449 in: header
1450 responses:
1451 "200":
1452 description: Releases list
1453 schema:
1454 type: array
1455 items:
1456 $ref: '#/definitions/v4ReleaseListItem'
1457 examples:
1458 application/json:
1459 - active: false
1460 changelog:
1461 - component: kubernetes
1462 description: Security fixes
1463 - component: calico
1464 description: Security fixes
1465 components:
1466 - name: kubernetes
1467 version: 1.5.8
1468 - name: calico
1469 version: 0.9.1
1470 timestamp: "2017-09-21T08:14:03.37759Z"
1471 version: 1.14.9
1472 - active: true
1473 changelog:
1474 - component: calico
1475 description: Bugfix
1476 components:
1477 - name: kubernetes
1478 version: 1.7.3
1479 - name: calico
1480 version: 1.1.1
1481 timestamp: "2017-11-11T12:24:56.59969Z"
1482 version: 2.8.4
1483 "401":
1484 description: Permission denied
1485 schema:
1486 $ref: '#/definitions/v4GenericResponse'
1487 examples:
1488 application/json:
1489 code: PERMISSION_DENIED
1490 message: The requested resource cannot be accessed using the provided
1491 authentication details.
1492 /v4/user/:
1493 get:
1494 description: |
1495 Returns details about the currently authenticated user
1496 tags:
1497 - users
1498 summary: Get current user
1499 operationId: getCurrentUser
1500 parameters:
1501 - type: string
1502 description: As described in the [authentication](#section/Authentication)
1503 section
1504 name: Authorization
1505 in: header
1506 required: true
1507 - type: string
1508 description: |
1509 A randomly generated key that can be used to track a request throughout
1510 services of Giant Swarm.
1511 name: X-Request-ID
1512 in: header
1513 - type: string
1514 description: |
1515 Name of an activity to track, like "list-clusters". This allows to
1516 analyze several API requests sent in context and gives an idea on
1517 the purpose.
1518 name: X-Giant-Swarm-Activity
1519 in: header
1520 - type: string
1521 description: |
1522 If activity has been issued by a CLI, this header can contain the
1523 command line
1524 name: X-Giant-Swarm-CmdLine
1525 in: header
1526 responses:
1527 "200":
1528 description: Success
1529 schema:
1530 $ref: '#/definitions/v4UserListItem'
1531 examples:
1532 application/json:
1533 created: "2017-01-15T12:00:00Z"
1534 email: andy@example.com
1535 expiry: "2019-01-15T00:00:00Z"
1536 "401":
1537 description: Permission denied
1538 schema:
1539 $ref: '#/definitions/v4GenericResponse'
1540 examples:
1541 application/json:
1542 code: PERMISSION_DENIED
1543 message: The requested resource cannot be accessed using the provided
1544 authentication details.
1545 default:
1546 description: Error
1547 schema:
1548 $ref: '#/definitions/v4GenericResponse'
1549 /v4/users/:
1550 get:
1551 description: |
1552 Returns a list of all users in the system. Currently this endpoint is only available to users with admin permissions.
1553 tags:
1554 - users
1555 summary: Get users
1556 operationId: getUsers
1557 parameters:
1558 - type: string
1559 description: As described in the [authentication](#section/Authentication)
1560 section
1561 name: Authorization
1562 in: header
1563 required: true
1564 - type: string
1565 description: |
1566 A randomly generated key that can be used to track a request throughout
1567 services of Giant Swarm.
1568 name: X-Request-ID
1569 in: header
1570 - type: string
1571 description: |
1572 Name of an activity to track, like "list-clusters". This allows to
1573 analyze several API requests sent in context and gives an idea on
1574 the purpose.
1575 name: X-Giant-Swarm-Activity
1576 in: header
1577 - type: string
1578 description: |
1579 If activity has been issued by a CLI, this header can contain the
1580 command line
1581 name: X-Giant-Swarm-CmdLine
1582 in: header
1583 responses:
1584 "200":
1585 description: Success
1586 schema:
1587 type: array
1588 items:
1589 $ref: '#/definitions/v4UserListItem'
1590 examples:
1591 application/json:
1592 - created: "2017-01-15T12:00:00Z"
1593 email: andy@example.com
1594 expiry: "2019-01-15T00:00:00Z"
1595 - created: "2017-02-15T12:30:00Z"
1596 email: bob@example.com
1597 expiry: "2020-01-15T00:00:00Z"
1598 - created: "2017-03-15T13:00:00Z"
1599 email: charles@example.com
1600 expiry: "2021-01-15T00:00:00Z"
1601 "401":
1602 description: Permission denied
1603 schema:
1604 $ref: '#/definitions/v4GenericResponse'
1605 examples:
1606 application/json:
1607 code: PERMISSION_DENIED
1608 message: The requested resource cannot be accessed using the provided
1609 authentication details.
1610 default:
1611 description: Error
1612 schema:
1613 $ref: '#/definitions/v4GenericResponse'
1614 /v4/users/{email}/:
1615 get:
1616 description: |
1617 Returns details about a specific user
1618 tags:
1619 - users
1620 summary: Get user
1621 operationId: getUser
1622 parameters:
1623 - type: string
1624 description: As described in the [authentication](#section/Authentication)
1625 section
1626 name: Authorization
1627 in: header
1628 required: true
1629 - type: string
1630 description: |
1631 A randomly generated key that can be used to track a request throughout
1632 services of Giant Swarm.
1633 name: X-Request-ID
1634 in: header
1635 - type: string
1636 description: |
1637 Name of an activity to track, like "list-clusters". This allows to
1638 analyze several API requests sent in context and gives an idea on
1639 the purpose.
1640 name: X-Giant-Swarm-Activity
1641 in: header
1642 - type: string
1643 description: |
1644 If activity has been issued by a CLI, this header can contain the
1645 command line
1646 name: X-Giant-Swarm-CmdLine
1647 in: header
1648 - type: string
1649 description: The user's email address
1650 name: email
1651 in: path
1652 required: true
1653 responses:
1654 "200":
1655 description: Success
1656 schema:
1657 $ref: '#/definitions/v4UserListItem'
1658 examples:
1659 application/json:
1660 created: "2017-01-15T12:00:00Z"
1661 email: andy@example.com
1662 expiry: "2019-01-15T00:00:00Z"
1663 "401":
1664 description: Permission denied
1665 schema:
1666 $ref: '#/definitions/v4GenericResponse'
1667 examples:
1668 application/json:
1669 code: PERMISSION_DENIED
1670 message: The requested resource cannot be accessed using the provided
1671 authentication details.
1672 "404":
1673 description: User not found
1674 schema:
1675 $ref: '#/definitions/v4GenericResponse'
1676 examples:
1677 application/json:
1678 code: RESOURCE_NOT_FOUND
1679 message: 'The user could not be found. (not found: user with email ''bob@example.com''
1680 could not be found)'
1681 default:
1682 description: Error
1683 schema:
1684 $ref: '#/definitions/v4GenericResponse'
1685 put:
1686 description: |
1687 Creates a users in the system. Currently this endpoint is only available to users with admin permissions.
1688 tags:
1689 - users
1690 summary: Create user
1691 operationId: createUser
1692 parameters:
1693 - type: string
1694 description: As described in the [authentication](#section/Authentication)
1695 section
1696 name: Authorization
1697 in: header
1698 required: true
1699 - type: string
1700 description: |
1701 A randomly generated key that can be used to track a request throughout
1702 services of Giant Swarm.
1703 name: X-Request-ID
1704 in: header
1705 - type: string
1706 description: |
1707 Name of an activity to track, like "list-clusters". This allows to
1708 analyze several API requests sent in context and gives an idea on
1709 the purpose.
1710 name: X-Giant-Swarm-Activity
1711 in: header
1712 - type: string
1713 description: |
1714 If activity has been issued by a CLI, this header can contain the
1715 command line
1716 name: X-Giant-Swarm-CmdLine
1717 in: header
1718 - type: string
1719 description: The user's email address
1720 name: email
1721 in: path
1722 required: true
1723 - x-examples:
1724 application/json:
1725 expiry: "2020-01-01T12:00:00.000Z"
1726 password: cGFzc3dvcmQ=
1727 description: User account details
1728 name: body
1729 in: body
1730 required: true
1731 schema:
1732 $ref: '#/definitions/v4CreateUserRequest'
1733 responses:
1734 "201":
1735 description: User created
1736 schema:
1737 $ref: '#/definitions/v4GenericResponse'
1738 examples:
1739 application/json:
1740 code: RESOURCE_CREATED
1741 message: The user with email 'bob@example.com' has been created.
1742 "400":
1743 description: User already exists
1744 schema:
1745 $ref: '#/definitions/v4GenericResponse'
1746 examples:
1747 application/json:
1748 code: RESOURCE_ALREADY_EXISTS
1749 message: 'The user could not be created. (invalid input: email ''bob@example.com''
1750 already exists)'
1751 "401":
1752 description: Permission denied
1753 schema:
1754 $ref: '#/definitions/v4GenericResponse'
1755 examples:
1756 application/json:
1757 code: PERMISSION_DENIED
1758 message: The requested resource cannot be accessed using the provided
1759 authentication details.
1760 default:
1761 description: Error
1762 schema:
1763 $ref: '#/definitions/v4GenericResponse'
1764 delete:
1765 description: |
1766 Deletes a users in the system. Currently this endpoint is only available
1767 to users with admin permissions.
1768 tags:
1769 - users
1770 summary: Delete user
1771 operationId: deleteUser
1772 parameters:
1773 - type: string
1774 description: As described in the [authentication](#section/Authentication)
1775 section
1776 name: Authorization
1777 in: header
1778 required: true
1779 - type: string
1780 description: |
1781 A randomly generated key that can be used to track a request throughout
1782 services of Giant Swarm.
1783 name: X-Request-ID
1784 in: header
1785 - type: string
1786 description: |
1787 Name of an activity to track, like "list-clusters". This allows to
1788 analyze several API requests sent in context and gives an idea on
1789 the purpose.
1790 name: X-Giant-Swarm-Activity
1791 in: header
1792 - type: string
1793 description: |
1794 If activity has been issued by a CLI, this header can contain the
1795 command line
1796 name: X-Giant-Swarm-CmdLine
1797 in: header
1798 - type: string
1799 description: The user's email address
1800 name: email
1801 in: path
1802 required: true
1803 responses:
1804 "200":
1805 description: User deleted
1806 schema:
1807 $ref: '#/definitions/v4GenericResponse'
1808 examples:
1809 application/json:
1810 code: RESOURCE_DELETED
1811 message: The user with email 'bob@example.com' has been deleted.
1812 "401":
1813 description: Permission denied
1814 schema:
1815 $ref: '#/definitions/v4GenericResponse'
1816 examples:
1817 application/json:
1818 code: PERMISSION_DENIED
1819 message: The requested resource cannot be accessed using the provided
1820 authentication details.
1821 "404":
1822 description: User not found
1823 schema:
1824 $ref: '#/definitions/v4GenericResponse'
1825 examples:
1826 application/json:
1827 code: RESOURCE_NOT_FOUND
1828 message: 'The user could not be deleted. (not found: user with email
1829 ''bob@example.com'' could not be found)'
1830 default:
1831 description: Error
1832 schema:
1833 $ref: '#/definitions/v4GenericResponse'
1834definitions:
1835 modifyOrganizationParamsBody:
1836 type: object
1837 properties:
1838 members:
1839 description: List of members that belong to this organization
1840 type: array
1841 items:
1842 $ref: '#/definitions/v4OrganizationMember'
1843 x-go-gen-location: operations
1844 v4AddClusterRequest:
1845 description: Request model for creating a new cluster
1846 type: object
1847 required:
1848 - owner
1849 properties:
1850 kubernetes_version:
1851 description: |
1852 Kubernetes version number (deprecated). Doesn't have any effect.
1853 This attribute is going to be removed in future API versions.
1854 type: string
1855 name:
1856 description: Cluster name
1857 type: string
1858 owner:
1859 description: Name of the organization owning the cluster
1860 type: string
1861 release_version:
1862 description: |
1863 The [release](https://docs.giantswarm.io/api/#tag/releases) version
1864 to use in the new cluster
1865 type: string
1866 workers:
1867 type: array
1868 items:
1869 $ref: '#/definitions/v4AddClusterRequestWorkersItems'
1870 v4AddClusterRequestWorkersItems:
1871 type: object
1872 properties:
1873 aws:
1874 $ref: '#/definitions/v4AddClusterRequestWorkersItemsAws'
1875 azure:
1876 $ref: '#/definitions/v4AddClusterRequestWorkersItemsAzure'
1877 cpu:
1878 $ref: '#/definitions/v4AddClusterRequestWorkersItemsCpu'
1879 labels:
1880 type: object
1881 additionalProperties: true
1882 memory:
1883 $ref: '#/definitions/v4AddClusterRequestWorkersItemsMemory'
1884 storage:
1885 $ref: '#/definitions/v4AddClusterRequestWorkersItemsStorage'
1886 x-go-gen-location: models
1887 v4AddClusterRequestWorkersItemsAws:
1888 description: |
1889 Attributes specific to nodes running on Amazon Web Services (AWS)
1890 type: object
1891 properties:
1892 instance_type:
1893 description: |
1894 EC2 instance type name. Must be the same for all worker nodes
1895 of a cluster.
1896 type: string
1897 x-go-gen-location: models
1898 v4AddClusterRequestWorkersItemsAzure:
1899 description: |
1900 Attributes specific to nodes running on Microsoft Azure
1901 type: object
1902 properties:
1903 vm_size:
1904 description: |
1905 Azure Virtual Machine size. Must be the same for all worker nodes
1906 of a cluster.
1907 type: string
1908 x-go-gen-location: models
1909 v4AddClusterRequestWorkersItemsCpu:
1910 type: object
1911 properties:
1912 cores:
1913 description: Number of CPU cores
1914 type: integer
1915 x-go-gen-location: models
1916 v4AddClusterRequestWorkersItemsMemory:
1917 type: object
1918 properties:
1919 size_gb:
1920 description: RAM size in GB. Can be an integer or float.
1921 type: number
1922 x-go-gen-location: models
1923 v4AddClusterRequestWorkersItemsStorage:
1924 type: object
1925 properties:
1926 size_gb:
1927 description: Node storage size in GB. Can be an integer or float.
1928 type: number
1929 x-go-gen-location: models
1930 v4AddCredentialsRequest:
1931 description: Request model for adding a set of credentials
1932 type: object
1933 required:
1934 - provider
1935 properties:
1936 aws:
1937 $ref: '#/definitions/v4AddCredentialsRequestAws'
1938 provider:
1939 type: string
1940 v4AddCredentialsRequestAws:
1941 description: Credentials specific to an AWS account
1942 type: object
1943 required:
1944 - roles
1945 properties:
1946 roles:
1947 $ref: '#/definitions/v4AddCredentialsRequestAwsRoles'
1948 x-go-gen-location: models
1949 v4AddCredentialsRequestAwsRoles:
1950 description: IAM roles to assume by certain entities
1951 type: object
1952 required:
1953 - awsoperator
1954 - admin
1955 properties:
1956 admin:
1957 description: ARN of the IAM role to assume by Giant Swarm support staff
1958 type: string
1959 awsoperator:
1960 description: ARN of the IAM role to assume by the software operating clusters
1961 type: string
1962 x-go-gen-location: models
1963 v4AddKeyPairRequest:
1964 type: object
1965 required:
1966 - description
1967 properties:
1968 certificate_organizations:
1969 description: |
1970 This will set the certificate subject's `organization` fields.
1971 Use a comma seperated list of values.
1972 type: string
1973 cn_prefix:
1974 description: The common name prefix of the certificate subject. This only
1975 allows characters that are usable in domain names (`a-z`, `0-9`, and `.-`,
1976 where `.-` must not occur at either the start or the end).
1977 type: string
1978 description:
1979 description: Free text information about the key pair
1980 type: string
1981 ttl_hours:
1982 description: Expiration time (from creation) in hours
1983 type: integer
1984 format: int32
1985 v4AddKeyPairResponse:
1986 type: object
1987 properties:
1988 certificate_authority_data:
1989 description: PEM-encoded CA certificate of the cluster
1990 type: string
1991 client_certificate_data:
1992 description: PEM-encoded certificate
1993 type: string
1994 client_key_data:
1995 description: PEM-encoded RSA private key
1996 type: string
1997 create_date:
1998 description: Date/time of creation
1999 type: string
2000 description:
2001 description: Free text information about the key pair
2002 type: string
2003 id:
2004 description: Unique identifier of the key pair
2005 type: string
2006 ttl_hours:
2007 description: Expiration time (from creation) in hours
2008 type: integer
2009 v4ClusterDetailsResponse:
2010 description: Response model showing details of a cluster
2011 type: object
2012 properties:
2013 api_endpoint:
2014 description: URI of the Kubernetes API endpoint
2015 type: string
2016 create_date:
2017 description: Date/time of cluster creation
2018 type: string
2019 id:
2020 description: Unique cluster identifier
2021 type: string
2022 kubernetes_version:
2023 description: Deprecated. Will be removed in a future API version.
2024 type: string
2025 kvm:
2026 $ref: '#/definitions/v4ClusterDetailsResponseKvm'
2027 name:
2028 description: Cluster name
2029 type: string
2030 owner:
2031 description: Name of the organization owning the cluster
2032 type: string
2033 release_version:
2034 description: |
2035 The [release](https://docs.giantswarm.io/api/#tag/releases) version
2036 currently running this cluster.
2037 type: string
2038 workers:
2039 type: array
2040 items:
2041 $ref: '#/definitions/v4ClusterDetailsResponseWorkersItems'
2042 v4ClusterDetailsResponseKvm:
2043 description: Attributes specific to clusters running on KVM (on-prem) installations.
2044 type: object
2045 properties:
2046 port_mappings:
2047 description: |
2048 Reveals the ports on the host cluster that are mapped to this guest cluster's ingress
2049 and which protocol that port supports. Only shown and relevant on our on-prem KVM clusters.
2050 type: array
2051 items:
2052 $ref: '#/definitions/v4ClusterDetailsResponseKvmPortMappingsItems'
2053 x-go-gen-location: models
2054 v4ClusterDetailsResponseKvmPortMappingsItems:
2055 type: object
2056 properties:
2057 port:
2058 description: |
2059 The port on the host cluster that will forward traffic to the guest cluster
2060 type: integer
2061 protocol:
2062 description: |
2063 The protocol this port mapping is made for.
2064 type: string
2065 x-go-gen-location: models
2066 v4ClusterDetailsResponseWorkersItems:
2067 type: object
2068 properties:
2069 aws:
2070 $ref: '#/definitions/v4ClusterDetailsResponseWorkersItemsAws'
2071 azure:
2072 $ref: '#/definitions/v4ClusterDetailsResponseWorkersItemsAzure'
2073 cpu:
2074 $ref: '#/definitions/v4ClusterDetailsResponseWorkersItemsCpu'
2075 labels:
2076 type: object
2077 additionalProperties: true
2078 memory:
2079 $ref: '#/definitions/v4ClusterDetailsResponseWorkersItemsMemory'
2080 storage:
2081 $ref: '#/definitions/v4ClusterDetailsResponseWorkersItemsStorage'
2082 x-go-gen-location: models
2083 v4ClusterDetailsResponseWorkersItemsAws:
2084 description: |
2085 Attributes specific to nodes running on Amazon Web Services (AWS)
2086 type: object
2087 properties:
2088 instance_type:
2089 description: |
2090 EC2 instance type name. Must be the same for all worker nodes
2091 of a cluster.
2092 type: string
2093 x-go-gen-location: models
2094 v4ClusterDetailsResponseWorkersItemsAzure:
2095 description: |
2096 Attributes specific to nodes running on Microsoft Azure
2097 type: object
2098 properties:
2099 vm_size:
2100 description: |
2101 Azure Virtual Machine size. Must be the same for all worker nodes
2102 of a cluster.
2103 type: string
2104 x-go-gen-location: models
2105 v4ClusterDetailsResponseWorkersItemsCpu:
2106 type: object
2107 properties:
2108 cores:
2109 description: Number of CPU cores
2110 type: integer
2111 x-go-gen-location: models
2112 v4ClusterDetailsResponseWorkersItemsMemory:
2113 type: object
2114 properties:
2115 size_gb:
2116 description: RAM size in GB. Can be an integer or float.
2117 type: number
2118 x-go-gen-location: models
2119 v4ClusterDetailsResponseWorkersItemsStorage:
2120 type: object
2121 properties:
2122 size_gb:
2123 description: Node storage size in GB. Can be an integer or float.
2124 type: number
2125 x-go-gen-location: models
2126 v4ClusterListItem:
2127 type: object
2128 properties:
2129 create_date:
2130 description: Date/time of cluster creation
2131 type: string
2132 id:
2133 description: Unique cluster identifier
2134 type: string
2135 name:
2136 description: Cluster name
2137 type: string
2138 owner:
2139 description: Name of the organization owning the cluster
2140 type: string
2141 release_version:
2142 description: The semantic version number of this cluster
2143 type: string
2144 v4CreateAuthTokenRequest:
2145 type: object
2146 properties:
2147 email:
2148 description: Your email address
2149 type: string
2150 password_base64:
2151 description: Your password as a base64 encoded string
2152 type: string
2153 v4CreateAuthTokenResponse:
2154 type: object
2155 properties:
2156 auth_token:
2157 description: The newly created API token
2158 type: string
2159 v4CreateUserRequest:
2160 description: Request model for creating a new user
2161 type: object
2162 required:
2163 - password
2164 properties:
2165 expiry:
2166 description: The date and time when this account will expire
2167 type: string
2168 password:
2169 description: A Base64 encoded password
2170 type: string
2171 v4GenericResponse:
2172 type: object
2173 properties:
2174 code:
2175 description: |
2176 A machine readable [response code](https://github.com/giantswarm/api-spec/blob/master/details/RESPONSE_CODES.md) like e. g. `INVALID_CREDENTIALS`
2177 type: string
2178 message:
2179 description: A human readable message
2180 type: string
2181 v4GetKeyPairsResponse:
2182 description: Array of sparse key pair objects
2183 type: array
2184 items:
2185 $ref: '#/definitions/v4GetKeyPairsResponseItems'
2186 v4GetKeyPairsResponseItems:
2187 type: object
2188 properties:
2189 certificate_organizations:
2190 description: The certificate subject's `organization` fields.
2191 type: string
2192 common_name:
2193 description: The common name of the certificate subject.
2194 type: string
2195 create_date:
2196 description: Date/time of creation
2197 type: string
2198 description:
2199 description: Free text information about the key pair
2200 type: string
2201 id:
2202 description: Unique identifier of the key pair
2203 type: string
2204 ttl_hours:
2205 description: Expiration time (from creation) in hours
2206 type: integer
2207 x-go-gen-location: models
2208 v4InfoResponse:
2209 type: object
2210 properties:
2211 general:
2212 $ref: '#/definitions/v4InfoResponseGeneral'
2213 workers:
2214 $ref: '#/definitions/v4InfoResponseWorkers'
2215 v4InfoResponseGeneral:
2216 description: General information
2217 type: object
2218 properties:
2219 datacenter:
2220 description: Identifier of the datacenter or cloud provider region, e. g.
2221 "eu-west-1"
2222 type: string
2223 installation_name:
2224 description: Unique name of the installation
2225 type: string
2226 provider:
2227 description: The technical provider used in this installation. Either "kvm",
2228 "aws", or "azure".
2229 type: string
2230 x-go-gen-location: models
2231 v4InfoResponseWorkers:
2232 description: Information related to worker nodes
2233 type: object
2234 properties:
2235 count_per_cluster:
2236 $ref: '#/definitions/v4InfoResponseWorkersCountPerCluster'
2237 instance_type:
2238 $ref: '#/definitions/v4InfoResponseWorkersInstanceType'
2239 vm_size:
2240 $ref: '#/definitions/v4InfoResponseWorkersVmSize'
2241 x-go-gen-location: models
2242 v4InfoResponseWorkersCountPerCluster:
2243 description: Number of workers per cluster
2244 type: object
2245 properties:
2246 default:
2247 description: Default number of workers in a new cluster will have, if not
2248 specifiec otherwise
2249 type: number
2250 max:
2251 description: Maximum number of worker a cluster can have
2252 type: number
2253 x-go-gen-location: models
2254 v4InfoResponseWorkersInstanceType:
2255 description: Instance types to be used for worker nodes. Only available for AWS
2256 clusters.
2257 type: object
2258 properties:
2259 default:
2260 description: The instance type used in new cluster, if not specified
2261 type: string
2262 options:
2263 description: List of available instance types
2264 type: array
2265 items:
2266 type: string
2267 x-go-gen-location: models
2268 v4InfoResponseWorkersVmSize:
2269 description: Azure Virtual Machine size to be used for worker nodes. Only available
2270 for Azure clusters.
2271 type: object
2272 properties:
2273 default:
2274 description: The instance type used in new cluster, if not specified
2275 type: string
2276 options:
2277 description: List of available instance types
2278 type: array
2279 items:
2280 type: string
2281 x-go-gen-location: models
2282 v4ModifyClusterRequest:
2283 description: Request body for cluster modification
2284 type: object
2285 properties:
2286 name:
2287 description: Name for the cluster
2288 type: string
2289 owner:
2290 description: Name of the organization owning the cluster
2291 type: string
2292 release_version:
2293 description: Release version to use after an upgrade
2294 type: string
2295 workers:
2296 description: Worker node array
2297 type: array
2298 items:
2299 $ref: '#/definitions/v4ModifyClusterRequestWorkersItems'
2300 v4ModifyClusterRequestWorkersItems:
2301 type: object
2302 properties:
2303 aws:
2304 $ref: '#/definitions/v4ModifyClusterRequestWorkersItemsAws'
2305 azure:
2306 $ref: '#/definitions/v4ModifyClusterRequestWorkersItemsAzure'
2307 cpu:
2308 $ref: '#/definitions/v4ModifyClusterRequestWorkersItemsCpu'
2309 labels:
2310 type: object
2311 additionalProperties: true
2312 memory:
2313 $ref: '#/definitions/v4ModifyClusterRequestWorkersItemsMemory'
2314 storage:
2315 $ref: '#/definitions/v4ModifyClusterRequestWorkersItemsStorage'
2316 x-go-gen-location: models
2317 v4ModifyClusterRequestWorkersItemsAws:
2318 description: |
2319 Attributes specific to nodes running on Amazon Web Services (AWS)
2320 type: object
2321 properties:
2322 instance_type:
2323 description: |
2324 EC2 instance type name. Must be the same for all worker nodes
2325 of a cluster.
2326 type: string
2327 x-go-gen-location: models
2328 v4ModifyClusterRequestWorkersItemsAzure:
2329 description: |
2330 Attributes specific to nodes running on Microsoft Azure
2331 type: object
2332 properties:
2333 vm_size:
2334 description: |
2335 Azure Virtual Machine size. Must be the same for all worker nodes
2336 of a cluster.
2337 type: string
2338 x-go-gen-location: models
2339 v4ModifyClusterRequestWorkersItemsCpu:
2340 type: object
2341 properties:
2342 cores:
2343 description: Number of CPU cores
2344 type: integer
2345 x-go-gen-location: models
2346 v4ModifyClusterRequestWorkersItemsMemory:
2347 type: object
2348 properties:
2349 size_gb:
2350 description: RAM size in GB. Can be an integer or float.
2351 type: number
2352 x-go-gen-location: models
2353 v4ModifyClusterRequestWorkersItemsStorage:
2354 type: object
2355 properties:
2356 size_gb:
2357 description: Node storage size in GB. Can be an integer or float.
2358 type: number
2359 x-go-gen-location: models
2360 v4Organization:
2361 type: object
2362 properties:
2363 id:
2364 description: Unique name/identifier of the organization
2365 type: string
2366 members:
2367 description: List of members that belong to this organization
2368 type: array
2369 items:
2370 $ref: '#/definitions/v4OrganizationMembersItems'
2371 v4OrganizationListItem:
2372 type: object
2373 properties:
2374 id:
2375 description: Unique name/identifier of the organization
2376 type: string
2377 v4OrganizationMember:
2378 type: object
2379 properties:
2380 email:
2381 description: Email address of the user
2382 type: string
2383 v4OrganizationMembersItems:
2384 type: object
2385 properties:
2386 email:
2387 description: Email address of the user
2388 type: string
2389 x-go-gen-location: models
2390 v4ReleaseListItem:
2391 type: object
2392 required:
2393 - version
2394 - timestamp
2395 - changelog
2396 - components
2397 properties:
2398 active:
2399 description: |
2400 If true, the version is available for new clusters and cluster
2401 upgrades. Older versions become unavailable and thus have the
2402 value `false` here.
2403 type: boolean
2404 changelog:
2405 description: |
2406 Structured list of changes in this release, in comparison to the
2407 previous version, with respect to the contained components.
2408 type: array
2409 items:
2410 $ref: '#/definitions/v4ReleaseListItemChangelogItems'
2411 components:
2412 description: |
2413 List of components and their version contained in the release
2414 type: array
2415 items:
2416 $ref: '#/definitions/v4ReleaseListItemComponentsItems'
2417 timestamp:
2418 description: Date and time of the release creation
2419 type: string
2420 version:
2421 description: The semantic version number
2422 type: string
2423 v4ReleaseListItemChangelogItems:
2424 type: object
2425 properties:
2426 component:
2427 description: |
2428 If the changed item was a component, this attribute is the
2429 name of the component.
2430 type: string
2431 description:
2432 description: Human-friendly description of the change
2433 type: string
2434 x-go-gen-location: models
2435 v4ReleaseListItemComponentsItems:
2436 type: object
2437 required:
2438 - name
2439 - version
2440 properties:
2441 name:
2442 description: Name of the component
2443 type: string
2444 version:
2445 description: Version number of the component
2446 type: string
2447 x-go-gen-location: models
2448 v4UserListItem:
2449 type: object
2450 properties:
2451 created:
2452 description: The date and time that this account was created
2453 type: string
2454 email:
2455 description: Email address of the user
2456 type: string
2457 expiry:
2458 description: The date and time when this account will expire
2459 type: string
2460securityDefinitions:
2461 AuthorizationHeaderToken:
2462 description: |
2463 Clients authenticate by passing an auth token via the `Authorization`
2464 header with a value of the format `giantswarm <token>`. Auth tokens can be
2465 obtained using the [createAuthToken](#operation/createAuthToken)
2466 operation.
2467 type: apiKey
2468 name: Authorization
2469 in: header
2470security:
2471- AuthorizationHeaderToken: []
2472tags:
2473- description: |
2474 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).
2475 name: auth tokens
2476- description: |
2477 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.
2478
2479 The API currently provides operations to create and delete clusters, as well as list all available clusters and get details on specific clusters.
2480 name: clusters
2481- description: Information about the Giant Swarm installation
2482 name: info
2483- description: A key pair is a unique combination of a X.509 certificate and a private
2484 key. Key pairs are used to access the Kubernetes API of a cluster, both using
2485 `kubectl` and any standard web browser.
2486 name: key pairs
2487 externalDocs:
2488 description: 'User guide: Accessing Pods and Services from the Outside'
2489 url: https://docs.giantswarm.io/guides/accessing-services-from-the-outside/
2490- description: Organizations are groups of users who own resources like clusters.
2491 name: organizations
2492- description: A user represents a person that should have access to the Giant Swarm
2493 API. Users can belong to many groups, and are identified by email address.
2494 name: users
2495- description: |
2496 A release is a software bundle that constitutes a cluster.
2497
2498 Releases are identified by their
2499 [semantic version number](http://semver.org/) in the `MAJOR.MINOR.PATCH`
2500 format.
2501
2502 A release provides _components_, like for example Kubernetes. For each
2503 release the contained components are listed. Changes in components are
2504 detailed in the _changelog_ of a release.
2505 name: releases
View as plain text