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 1311