| swagger: "2.0" |
| info: |
| title: The Giant Swarm API v4 |
| description: | |
| This is the documentation for the Giant Swarm API starting at version `v4`. |
| |
| For an introduction to Giant Swarm, refer to the [documentation site](https://docs.giantswarm.io/). |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| 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. |
| |
| ## Source |
| |
| The source of this documentation is available on [GitHub](https://github.com/giantswarm/api-spec). |
| |
| termsOfService: https://giantswarm.io/terms/ |
| version: 4.0.0 |
| license: |
| name: Apache 2.0 |
| url: http://www.apache.org/licenses/LICENSE-2.0.html |
| consumes: |
| - application/json |
| produces: |
| - application/json |
| tags: |
| - name: auth tokens |
| description: | |
| 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). |
| - name: clusters |
| description: | |
| 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. |
| |
| The API currently provides operations to create and delete clusters, as well as list all available clusters and get details on specific clusters. |
| - name: info |
| description: Information about the Giant Swarm installation |
| - name: key pairs |
| 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. |
| externalDocs: |
| url: https://docs.giantswarm.io/guides/accessing-services-from-the-outside/ |
| description: "User guide: Accessing Pods and Services from the Outside" |
| - name: organizations |
| description: Organizations are groups of users who own resources like clusters. |
| - name: users |
| 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. |
| - name: releases |
| description: | |
| A release is a software bundle that constitutes a cluster. |
| |
| Releases are identified by their |
| [semantic version number](http://semver.org/) in the `MAJOR.MINOR.PATCH` |
| format. |
| |
| A release provides _components_, like for example Kubernetes. For each |
| release the contained components are listed. Changes in components are |
| detailed in the _changelog_ of a release. |
| securityDefinitions: |
| AuthorizationHeaderToken: |
| description: | |
| Clients authenticate by passing an auth token via the `Authorization` |
| header with a value of the format `giantswarm <token>`. Auth tokens can be |
| obtained using the [createAuthToken](#operation/createAuthToken) |
| operation. |
| type: apiKey |
| name: Authorization |
| in: header |
| |
| security: |
| - AuthorizationHeaderToken: [] |
| |
| paths: |
| /v4/info/: |
| get: |
| operationId: getInfo |
| tags: |
| - info |
| summary: Get information on the installation |
| description: | |
| Returns a set of details on the installation. The output varies based |
| on the provider used in the installation. |
| |
| This information is useful for example when creating new cluster, to |
| prevent creating clusters with more worker nodes than possible. |
| |
| ### Example for an AWS-based installation |
| |
| ```json |
| { |
| "general": { |
| "installation_name": "shire", |
| "provider": "aws", |
| "datacenter": "eu-central-1" |
| }, |
| "workers": { |
| "count_per_cluster": { |
| "max": 20, |
| "default": 3 |
| }, |
| "instance_type": { |
| "options": [ |
| "m3.medium", "m3.large", "m3.xlarge" |
| ], |
| "default": "m3.large" |
| } |
| } |
| } |
| ``` |
| |
| ### Example for a KVM-based installation |
| |
| ```json |
| { |
| "general": { |
| "installation_name": "isengard", |
| "provider": "kvm", |
| "datacenter": "string" |
| }, |
| "workers": { |
| "count_per_cluster": { |
| "max": 8, |
| "default": 3 |
| }, |
| } |
| } |
| ``` |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| responses: |
| "200": |
| description: Information |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4InfoResponse" |
| examples: |
| application/json: |
| { |
| "general": { |
| "installation_name": "shire", |
| "provider": "aws", |
| "datacenter": "eu-central-1" |
| }, |
| "workers": { |
| "count_per_cluster": { |
| "max": 20, |
| "default": 3 |
| }, |
| "instance_type": { |
| "options": [ |
| "m3.medium", "m3.large", "m3.xlarge" |
| ], |
| "default": "m3.large" |
| } |
| } |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| /v4/auth-tokens/: |
| post: |
| operationId: createAuthToken |
| tags: |
| - auth tokens |
| summary: Create Auth Token (Login) |
| description: | |
| Creates a Auth Token for a given user. Must authenticate with email and password. |
| parameters: |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - name: body |
| in: body |
| required: true |
| description: Create Auth Token Request |
| schema: |
| $ref: 'definitions.yaml#/definitions/V4CreateAuthTokenRequest' |
| x-examples: |
| application/json: |
| { |
| "email": "developer@example.com", |
| "password_base64": "cGFzc3dvcmQ=" |
| } |
| responses: |
| "200": |
| description: Success |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4CreateAuthTokenResponse" |
| examples: |
| application/json: |
| { |
| "auth_token": "e5239484-2299-41df-b901-d0568db7e3f9" |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| |
| delete: |
| operationId: deleteAuthToken |
| tags: |
| - auth tokens |
| summary: Delete Auth Token (Logout) |
| description: | |
| Deletes the authentication token provided in the Authorization header. This effectively logs you out. |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| responses: |
| "200": |
| description: Success |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_DELETED", |
| "message": "The authentication token has been succesfully deleted." |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| |
| /v4/users/: |
| get: |
| operationId: getUsers |
| tags: |
| - users |
| summary: Get users |
| description: | |
| Returns a list of all users in the system. Currently this endpoint is only available to users with admin permissions. |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| responses: |
| "200": |
| description: Success |
| schema: |
| type: array |
| items: |
| $ref: "./definitions.yaml#/definitions/V4UserListItem" |
| examples: |
| application/json: |
| [ |
| {"email": "andy@example.com", "created": "2017-01-15T12:00:00Z", "expiry": "2019-01-15T00:00:00Z"}, |
| {"email": "bob@example.com", "created": "2017-02-15T12:30:00Z", "expiry": "2020-01-15T00:00:00Z"}, |
| {"email": "charles@example.com", "created": "2017-03-15T13:00:00Z", "expiry": "2021-01-15T00:00:00Z"} |
| ] |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| /v4/user/: |
| get: |
| operationId: getCurrentUser |
| tags: |
| - users |
| summary: Get current user |
| description: | |
| Returns details about the currently authenticated user |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| responses: |
| "200": |
| description: Success |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4UserListItem" |
| examples: |
| application/json: |
| {"email": "andy@example.com", "created": "2017-01-15T12:00:00Z", "expiry": "2019-01-15T00:00:00Z"} |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| /v4/users/{email}/: |
| get: |
| operationId: getUser |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter" |
| tags: |
| - users |
| summary: Get user |
| description: | |
| Returns details about a specific user |
| responses: |
| "200": |
| description: Success |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4UserListItem" |
| examples: |
| application/json: |
| {"email": "andy@example.com", "created": "2017-01-15T12:00:00Z", "expiry": "2019-01-15T00:00:00Z"} |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| "404": |
| description: User not found |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_NOT_FOUND", |
| "message": "The user could not be found. (not found: user with email 'bob@example.com' could not be found)" |
| } |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| put: |
| operationId: createUser |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter" |
| - name: body |
| in: body |
| required: true |
| description: User account details |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4CreateUserRequest" |
| x-examples: |
| application/json: |
| { |
| "password": "cGFzc3dvcmQ=", |
| "expiry": "2020-01-01T12:00:00.000Z" |
| } |
| tags: |
| - users |
| summary: Create user |
| description: | |
| Creates a users in the system. Currently this endpoint is only available to users with admin permissions. |
| responses: |
| "201": |
| description: User created |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_CREATED", |
| "message": "The user with email 'bob@example.com' has been created." |
| } |
| "400": |
| description: User already exists |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_ALREADY_EXISTS", |
| "message": "The user could not be created. (invalid input: email 'bob@example.com' already exists)" |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| delete: |
| operationId: deleteUser |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter" |
| tags: |
| - users |
| summary: Delete user |
| description: | |
| Deletes a users in the system. Currently this endpoint is only available |
| to users with admin permissions. |
| responses: |
| "200": |
| description: User deleted |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_DELETED", |
| "message": "The user with email 'bob@example.com' has been deleted." |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| "404": |
| description: User not found |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_NOT_FOUND", |
| "message": "The user could not be deleted. (not found: user with email 'bob@example.com' could not be found)" |
| } |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| /v4/clusters/: |
| get: |
| operationId: getClusters |
| tags: |
| - clusters |
| summary: Get clusters |
| description: | |
| This operation fetches a list of clusters. |
| |
| The result depends on the permissions of the user. |
| A normal user will get all the clusters the user has access |
| to, via organization membership. |
| A user with admin permission will receive a list of all existing |
| clusters. |
| |
| The result array items are sparse representations of the cluster objects. |
| To fetch more details on a cluster, use the [getCluster](#operation/getCluster) |
| operation. |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| responses: |
| "200": |
| description: Success |
| schema: |
| type: array |
| items: |
| $ref: "./definitions.yaml#/definitions/V4ClusterListItem" |
| examples: |
| application/json: |
| [ |
| { |
| "id": "g8s3o", |
| "create_date": "2017-06-08T12:31:47.215Z", |
| "name": "Staging Cluster", |
| "owner": "acme" |
| }, |
| { |
| "id": "3dkr6", |
| "create_date": "2017-05-22T13:58:02.024Z", |
| "name": "Test Cluster", |
| "owner": "testorg" |
| } |
| ] |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| post: |
| operationId: addCluster |
| tags: |
| - clusters |
| summary: Create cluster |
| description: | |
| This operation is used to create a new Kubernetes cluster for an |
| organization. The desired configuration can be specified using the |
| __cluster definition format__ (see |
| [external documentation](https://github.com/giantswarm/api-spec/blob/master/details/CLUSTER_DEFINITION.md) |
| for details). |
| |
| The cluster definition format allows to set a number of optional |
| configuration details, like memory size and number of CPU cores. |
| However, one attribute is __mandatory__ upon creation: The `owner` |
| attribute must carry the name of the organization the cluster will |
| belong to. Note that the acting user must be a member of that |
| organization in order to create a cluster. |
| |
| It is *recommended* to also specify the `name` attribute to give the |
| cluster a friendly name, like e. g. "Development Cluster". |
| |
| Additional definition attributes can be used. Where attributes are |
| omitted, default configuration values will be applied. For example, if |
| no `release_version` is specified, the most recent version is used. |
| |
| The `workers` attribute, if present, must contain an array of node |
| definition objects. The number of objects given determines the number |
| of workers created. |
| |
| For example, requesting three worker nodes with default configuration |
| can be achieved by submitting an array of three empty objects: |
| |
| ```"workers": [{}, {}, {}]``` |
| |
| For clusters on AWS, note that all worker nodes must use the same instance type. |
| |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - name: body |
| in: body |
| required: true |
| description: New cluster definition |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4AddClusterRequest" |
| x-examples: |
| application/json: |
| { |
| "owner": "myteam", |
| "release_version": "1.4.2", |
| "name": "Example cluster with 3 default worker nodes", |
| "workers": [{}, {}, {}] |
| } |
| responses: |
| "201": |
| description: Cluster created |
| headers: |
| Location: |
| type: string |
| description: URI to obtain details on the new cluster using the [getCluster](#operation/getCluster) operation |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_CREATED", |
| "message": "A new cluster has been created with ID 'wqtlq'" |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| default: |
| description: error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| /v4/clusters/{cluster_id}/: |
| get: |
| operationId: getCluster |
| tags: |
| - clusters |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter" |
| summary: Get cluster details |
| description: | |
| This operation allows to obtain all available details on a particular cluster. |
| responses: |
| "200": |
| description: Cluster details |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4ClusterDetailsResponse" |
| examples: |
| application/json: |
| { |
| "id": "wqtlq", |
| "create_date": "2017-03-03T10:50:45.949270905Z", |
| "api_endpoint": "https://api.wqtlq.example.com", |
| "name": "Just a Standard Cluster", |
| "release_version": "2.5.16", |
| "kubernetes_version": "", |
| "owner": "acme", |
| "workers": [ |
| { |
| "memory": {"size_gb": 2.0}, |
| "storage": {"size_gb": 20.0}, |
| "cpu": {"cores": 4}, |
| "labels": { |
| "beta.kubernetes.io/arch": "amd64", |
| "beta.kubernetes.io/os": "linux", |
| "ip": "10.3.11.2", |
| "kubernetes.io/hostname": "worker-1.x882ofna.k8s.gigantic.io", |
| "nodetype": "hicpu" |
| } |
| }, |
| { |
| "memory": {"size_gb": 8.0}, |
| "storage": {"size_gb": 20.0}, |
| "cpu": {"cores": 2}, |
| "labels": { |
| "beta.kubernetes.io/arch": "amd64", |
| "beta.kubernetes.io/os": "linux", |
| "ip": "10.3.62.2", |
| "kubernetes.io/hostname": "worker-2.x882ofna.k8s.gigantic.io", |
| "nodetype": "hiram" |
| } |
| } |
| ], |
| "kvm": { |
| "port_mappings": [ |
| { |
| "port": 30020, |
| "protocol": "http" |
| }, |
| { |
| "port": 30021, |
| "protocol": "https" |
| }, |
| ] |
| } |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| "404": |
| description: Cluster not found |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_NOT_FOUND", |
| "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." |
| } |
| default: |
| description: error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| patch: |
| operationId: modifyCluster |
| tags: |
| - clusters |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - name: body |
| in: body |
| required: true |
| description: Merge-patch body |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4ModifyClusterRequest" |
| x-examples: |
| application/merge-patch+json: |
| { |
| "name": "New cluster name" |
| } |
| - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter" |
| summary: Modify cluster |
| description: | |
| This operation allows to modify an existing cluster. |
| |
| A cluster modification is performed by submitting a `PATCH` request |
| to the cluster resource (as described in the |
| [addCluster](#operation/addCluster) and [getCluster](#operation/getCluster)) |
| in form of a [JSON Patch Merge |
| (RFC 7386)](https://tools.ietf.org/html/rfc7386). This means, only the |
| attributes to be modified have to be contained in the request body. |
| |
| The following attributes can be modified: |
| |
| - `name`: Rename the cluster to something more fitting. |
| |
| - `owner`: Changing the owner organization name means to change cluster |
| ownership from one organization to another. The user performing the |
| request has to be a member of both organizations. |
| |
| - `release_version`: By changing this attribute you can upgrade a |
| cluster to a newer |
| [release](https://docs.giantswarm.io/api/#tag/releases). |
| |
| - `workers`: By modifying the array of workers, nodes can be added to |
| increase the cluster's capacity. See details below. |
| |
| ### Adding and Removing Worker Nodes (Scaling) |
| |
| Adding worker nodes to a cluster or removing worker nodes from a cluster |
| works by submitting the `workers` attribute, which contains a (sparse) |
| array of worker node defintions. |
| |
| _Sparse_ here means that all configuration details are optional. In the |
| case that worker nodes are added to a cluster, wherever a configuration |
| detail is missing, defaults will be applied. See |
| [Creating a cluster](#operation/addCluster) for details. |
| |
| When modifying the cluster resource, you describe the desired state. |
| For scaling, this means that the worker node array submitted must |
| contain as many elements as the cluster should have worker nodes. |
| If your cluster currently has five nodes and you submit a workers |
| array with four elements, this means that one worker node will be removed. |
| If your submitted workers array has six elements, this means one will |
| be added. |
| |
| As an example, this request body could be used to scale a cluster to |
| three worker nodes: |
| |
| ```json |
| { |
| "workers": [{}, {}, {}] |
| } |
| ``` |
| |
| If the scaled cluster had four worker nodes before, one would be removed. |
| If it had two worker nodes before, one with default settings would be |
| added. |
| |
| ### Limitations |
| |
| - As of now, existing worker nodes cannot be modified. |
| - When removing nodes (scaling down), it is not possible to determine |
| which nodes will be removed. |
| - On AWS based clusters, all worker nodes must use the same EC2 instance |
| type (`instance_type` node attribute). By not setting an `instance_type` |
| when submitting a PATCH request, you ensure that the right instance type |
| is used automatically. |
| |
| responses: |
| "200": |
| description: Cluster modified |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4ClusterDetailsResponse" |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| "404": |
| description: Cluster not found |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_NOT_FOUND", |
| "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." |
| } |
| default: |
| description: error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| delete: |
| operationId: deleteCluster |
| tags: |
| - clusters |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter" |
| summary: Delete cluster |
| description: | |
| This operation allows to delete a cluster. |
| |
| __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. |
| |
| The response is sent as soon as the request is validated. |
| 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. |
| responses: |
| "202": |
| description: Deleting cluster |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_DELETION_STARTED", |
| "message": "The cluster with ID 'wqtlq' is being deleted." |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| "404": |
| description: Cluster not found |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_NOT_FOUND", |
| "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." |
| } |
| default: |
| description: error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| /v4/clusters/{cluster_id}/key-pairs/: |
| get: |
| operationId: getKeyPairs |
| tags: |
| - key pairs |
| summary: Get key pairs |
| description: | |
| Returns a list of information on all key pairs of a cluster as an array. |
| |
| 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. |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter" |
| responses: |
| "200": |
| description: Key pairs |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GetKeyPairsResponse" |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| default: |
| description: error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| post: |
| operationId: addKeyPair |
| tags: |
| - key pairs |
| summary: Create key pair |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter" |
| - name: body |
| in: body |
| required: true |
| description: | |
| While the `ttl_hours` attribute is optional and will be set to a default value when omitted, the `description` is mandatory. |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4AddKeyPairRequest" |
| x-examples: |
| application/json: |
| { |
| "description": "Admin key pair lasting twelve hours", |
| "ttl_hours": 12, |
| "certificate_organizations": "system:masters" |
| } |
| description: | |
| This operation allows to create a new key pair for accessing a specific cluster. |
| |
| 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. |
| |
| 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. |
| |
| ### Customizing the certificate's subject for K8s RBAC |
| |
| It is possible to set the Common Name and Organization fields of the generated certificate's subject. |
| |
| - `cn_prefix`: The certificate's common name uses this format: `<cn_prefix>.user.<clusterdomain>`. |
| |
| `clusterdomain` is specific to your cluster and is not editable. |
| |
| The `cn_prefix` however is editable. When left blank it will default |
| to the email address of the Giant Swarm user that is performing the |
| create key pair request. |
| |
| The common name is used as the username for requests to the Kubernetes API. This allows you |
| to set up role-based access controls. |
| |
| |
| - `certificate_organizations`: This will set the certificate's `organization` fields. Use a comma separated list of values. |
| The Kubernetes API will use these values as group memberships. |
| |
| __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. |
| responses: |
| "200": |
| description: Success |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4AddKeyPairResponse" |
| examples: |
| application/json: |
| { |
| "certificate_authority_data": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----", |
| "client_key_data": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----", |
| "client_certificate_data": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----", |
| "create_date": "2016-06-01T12:00:00.000Z", |
| "description": "Key pair description", |
| "id": "02:cc:da:f9:fb:ce:c3:e5:e1:f6:27:d8:43:48:0d:37:4a:ee:b9:67", |
| "ttl_hours": 8640 |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| |
| /v4/organizations/: |
| get: |
| operationId: getOrganizations |
| tags: |
| - organizations |
| summary: Get organizations |
| description: | |
| This operation allows to fetch a list of organizations the user is a |
| member of. In the case of an admin user, the result includes all |
| existing organizations. |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| responses: |
| "200": |
| description: Success |
| schema: |
| type: array |
| items: |
| $ref: "./definitions.yaml#/definitions/V4OrganizationListItem" |
| examples: |
| application/json: |
| [ |
| {"id": "acme"}, |
| {"id": "giantswarm"}, |
| {"id": "testorg"} |
| ] |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| /v4/organizations/{organization_id}/: |
| get: |
| operationId: getOrganization |
| tags: |
| - organizations |
| summary: Get organization details |
| description: | |
| This operation fetches organization details. |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter" |
| responses: |
| "200": |
| description: Organization details |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4Organization" |
| examples: |
| application/json: |
| { |
| "id": "acme", |
| "members": [ |
| {"email": "user1@example.com"}, |
| {"email": "user2@example.com"} |
| ] |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| "404": |
| description: Organization not found |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_NOT_FOUND", |
| "message": "The organization could not be found. (not found: the organization with id 'acme' could not be found)" |
| } |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| put: |
| operationId: addOrganization |
| tags: |
| - organizations |
| summary: Create an organization |
| description: | |
| This operation allows a user to create an organization. |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter" |
| - name: body |
| in: body |
| required: true |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4Organization" |
| x-examples: |
| application/json: |
| { |
| "id": "string", |
| "members": [ |
| {"email": "myself@example.com"}, |
| {"email": "colleague@example.com"} |
| ] |
| } |
| responses: |
| "201": |
| description: Organization created |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4Organization" |
| examples: |
| application/json: |
| { |
| "id": "acme", |
| "members": [ |
| {"email": "user1@example.com"}, |
| {"email": "user2@example.com"} |
| ] |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| "409": |
| description: Organization already exists |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_ALREADY_EXISTS", |
| "message": "The organization could not be created. (org already exists)" |
| } |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| patch: |
| operationId: modifyOrganization |
| tags: |
| - organizations |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter" |
| - name: body |
| in: body |
| required: true |
| schema: |
| type: object |
| properties: |
| members: |
| type: array |
| description: List of members that belong to this organization |
| items: |
| $ref: "./definitions.yaml#/definitions/V4OrganizationMember" |
| x-examples: |
| application/merge-patch+json: |
| { |
| "members": [{"email": "myself@example.com"}] |
| } |
| |
| summary: Modify organization |
| description: | |
| This operation allows you to modify an existing organization. You must be |
| a member of the organization or an admin in order to use this endpoint. |
| |
| The following attributes can be modified: |
| |
| - `members`: By modifying the array of members, members can be added to or removed from the organization |
| |
| The request body must conform with the [JSON Patch Merge (RFC 7386)](https://tools.ietf.org/html/rfc7386) standard. |
| Requests have to be sent with the `Content-Type: application/merge-patch+json` header. |
| |
| The full request must be valid before it will be executed, currently this |
| means every member you attempt to add to the organization must actually |
| exist in the system. If any member you attempt to add is invalid, the entire |
| patch operation will fail, no members will be added or removed, and an error message |
| will explain which members in your request are invalid. |
| responses: |
| "200": |
| description: Organization modified |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4Organization" |
| "400": |
| description: Invalid input |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "INVALID_INPUT", |
| "message": "The organization could not be modified. (invalid input: user 'invalid-email' does not exist or is invalid)" |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| "404": |
| description: Organization not found |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_NOT_FOUND", |
| "message": "The organization could not be modified. (not found: the organization with id 'acme' could not be found)" |
| } |
| default: |
| description: error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| delete: |
| operationId: deleteOrganization |
| tags: |
| - organizations |
| summary: Delete an organization |
| description: | |
| This operation allows a user to delete an organization that they are a member of. |
| Admin users can delete any organization. |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter" |
| responses: |
| "200": |
| description: Organization deleted |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_DELETED", |
| "message": "The organization with ID 'acme' has been deleted." |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| "404": |
| description: Organization not found |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_NOT_FOUND", |
| "message": "The organization could not be deleted. (not found: the organization with id 'acme' could not be found)" |
| } |
| default: |
| description: Error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| /v4/organizations/{organization_id}/credentials/: |
| post: |
| operationId: addCredentials |
| tags: |
| - organizations |
| summary: Set credentials |
| description: | |
| Add a set of credentials to the organization allowing the creation and |
| operation of clusters within a cloud provider account/subscription. |
| |
| The actual type of these credentials depends on the cloud provider the |
| installation is running on. Currently, only AWS is supported, with |
| support for Azure being planned for the near future. |
| |
| Credentials in an organization are immutable. Each organization can only |
| have one set of credentials. |
| |
| Once credentials have been set for an organization, they are used for |
| every new cluster that will be created for the organization. |
| |
| ### Example request body for AWS |
| |
| ```json |
| { |
| "provider": "aws", |
| "aws": { |
| "roles": { |
| "admin": "arn:aws:iam::123456789012:role/GiantSwarmAdmin", |
| "awsoperator": "arn:aws:iam::123456789012:role/GiantSwarmAWSOperator" |
| } |
| } |
| } |
| ``` |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter" |
| - name: body |
| in: body |
| required: true |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4AddCredentialsRequest" |
| x-examples: |
| application/json: |
| { |
| "provider": "aws", |
| "aws": { |
| "roles": { |
| "admin": "arn:aws:iam::123456789012:role/GiantSwarmAdmin", |
| "awsoperator": "arn:aws:iam::123456789012:role/GiantSwarmAWSOperator" |
| } |
| } |
| } |
| responses: |
| "201": |
| description: Credentials created |
| headers: |
| Location: |
| type: string |
| description: URI of the new credentials resource |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_CREATED", |
| "message": "A new set of credentials has been created with ID '5d9h4'" |
| } |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| "409": |
| description: Conflict |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| examples: |
| application/json: |
| { |
| "code": "RESOURCE_ALREADY_EXISTS", |
| "message": "The organisation already has a set of credentials" |
| } |
| default: |
| description: error |
| schema: |
| $ref: "./definitions.yaml#/definitions/V4GenericResponse" |
| |
| /v4/releases/: |
| get: |
| operationId: getReleases |
| tags: |
| - releases |
| summary: Get releases |
| description: | |
| Lists all releases available for new clusters or for upgrading existing |
| clusters. Might also serve as an archive to obtain details on older |
| releases. |
| parameters: |
| - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader' |
| - $ref: './parameters.yaml#/parameters/XRequestIDHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader' |
| - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader' |
| responses: |
| "200": |
| description: Releases list |
| schema: |
| type: array |
| items: |
| $ref: "./definitions.yaml#/definitions/V4ReleaseListItem" |
| examples: |
| application/json: |
| [ |
| { |
| "version": "1.14.9", |
| "timestamp": "2017-09-21T08:14:03.37759Z", |
| "changelog": [ |
| { |
| "component": "kubernetes", |
| "description": "Security fixes" |
| }, |
| { |
| "component": "calico", |
| "description": "Security fixes" |
| } |
| ], |
| "components": [ |
| { |
| "name": "kubernetes", |
| "version": "1.5.8" |
| }, |
| { |
| "name": "calico", |
| "version": "0.9.1" |
| } |
| ], |
| "active": false |
| }, |
| { |
| "version": "2.8.4", |
| "timestamp": "2017-11-11T12:24:56.59969Z", |
| "changelog": [ |
| { |
| "component": "calico", |
| "description": "Bugfix" |
| } |
| ], |
| "components": [ |
| { |
| "name": "kubernetes", |
| "version": "1.7.3" |
| }, |
| { |
| "name": "calico", |
| "version": "1.1.1" |
| } |
| ], |
| "active": true |
| } |
| ] |
| "401": |
| $ref: "./responses.yaml#/responses/V4Generic401Response" |
| |
