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