consumes: - application/json produces: - application/json swagger: "2.0" info: 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). title: The Giant Swarm API v4 termsOfService: https://giantswarm.io/terms/ license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 4.0.0 paths: /v4/auth-tokens/: post: description: | Creates a Auth Token for a given user. Must authenticate with email and password. tags: - auth tokens summary: Create Auth Token (Login) operationId: createAuthToken parameters: - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - x-examples: application/json: email: developer@example.com password_base64: cGFzc3dvcmQ= description: Create Auth Token Request name: body in: body required: true schema: $ref: '#/definitions/v4CreateAuthTokenRequest' responses: "200": description: Success schema: $ref: '#/definitions/v4CreateAuthTokenResponse' examples: application/json: auth_token: e5239484-2299-41df-b901-d0568db7e3f9 "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. delete: description: | Deletes the authentication token provided in the Authorization header. This effectively logs you out. tags: - auth tokens summary: Delete Auth Token (Logout) operationId: deleteAuthToken parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header responses: "200": description: Success schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: RESOURCE_DELETED message: The authentication token has been succesfully deleted. "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. /v4/clusters/: get: 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. tags: - clusters summary: Get clusters operationId: getClusters parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header responses: "200": description: Success schema: type: array items: $ref: '#/definitions/v4ClusterListItem' examples: application/json: - create_date: "2017-06-08T12:31:47.215Z" id: g8s3o name: Staging Cluster owner: acme - create_date: "2017-05-22T13:58:02.024Z" id: 3dkr6 name: Test Cluster owner: testorg "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. default: description: Error schema: $ref: '#/definitions/v4GenericResponse' post: 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. tags: - clusters summary: Create cluster operationId: addCluster parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - x-examples: application/json: name: Example cluster with 3 default worker nodes owner: myteam release_version: 1.4.2 workers: - {} - {} - {} description: New cluster definition name: body in: body required: true schema: $ref: '#/definitions/v4AddClusterRequest' responses: "201": description: Cluster created schema: $ref: '#/definitions/v4GenericResponse' headers: Location: type: string description: URI to obtain details on the new cluster using the [getCluster](#operation/getCluster) operation examples: application/json: code: RESOURCE_CREATED message: A new cluster has been created with ID 'wqtlq' "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. default: description: error schema: $ref: '#/definitions/v4GenericResponse' /v4/clusters/{cluster_id}/: get: description: | This operation allows to obtain all available details on a particular cluster. tags: - clusters summary: Get cluster details operationId: getCluster parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: Cluster ID name: cluster_id in: path required: true responses: "200": description: Cluster details schema: $ref: '#/definitions/v4ClusterDetailsResponse' examples: application/json: api_endpoint: https://api.wqtlq.example.com create_date: "2017-03-03T10:50:45.949270905Z" id: wqtlq kubernetes_version: "" kvm: port_mappings: - port: 30020 protocol: http - port: 30021 protocol: https name: Just a Standard Cluster owner: acme release_version: 2.5.16 workers: - 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: 2 storage: size_gb: 20 - 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 memory: size_gb: 8 storage: size_gb: 20 "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. "404": description: Cluster not found schema: $ref: '#/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/v4GenericResponse' delete: 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. tags: - clusters summary: Delete cluster operationId: deleteCluster parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: Cluster ID name: cluster_id in: path required: true responses: "202": description: Deleting cluster schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: RESOURCE_DELETION_STARTED message: The cluster with ID 'wqtlq' is being deleted. "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. "404": description: Cluster not found schema: $ref: '#/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/v4GenericResponse' patch: 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. tags: - clusters summary: Modify cluster operationId: modifyCluster parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - x-examples: application/merge-patch+json: name: New cluster name description: Merge-patch body name: body in: body required: true schema: $ref: '#/definitions/v4ModifyClusterRequest' - type: string description: Cluster ID name: cluster_id in: path required: true responses: "200": description: Cluster modified schema: $ref: '#/definitions/v4ClusterDetailsResponse' "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. "404": description: Cluster not found schema: $ref: '#/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/v4GenericResponse' /v4/clusters/{cluster_id}/key-pairs/: get: 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. tags: - key pairs summary: Get key pairs operationId: getKeyPairs parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: Cluster ID name: cluster_id in: path required: true responses: "200": description: Key pairs schema: $ref: '#/definitions/v4GetKeyPairsResponse' "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. default: description: error schema: $ref: '#/definitions/v4GenericResponse' post: 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: `.user.`. `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. tags: - key pairs summary: Create key pair operationId: addKeyPair parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: Cluster ID name: cluster_id in: path required: true - x-examples: application/json: certificate_organizations: system:masters description: Admin key pair lasting twelve hours ttl_hours: 12 description: | While the `ttl_hours` attribute is optional and will be set to a default value when omitted, the `description` is mandatory. name: body in: body required: true schema: $ref: '#/definitions/v4AddKeyPairRequest' responses: "200": description: Success schema: $ref: '#/definitions/v4AddKeyPairResponse' examples: application/json: certificate_authority_data: '-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----' client_certificate_data: '-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----' client_key_data: '-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----' 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": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. /v4/info/: get: 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 }, } } ``` tags: - info summary: Get information on the installation operationId: getInfo parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header responses: "200": description: Information schema: $ref: '#/definitions/v4InfoResponse' examples: application/json: general: datacenter: eu-central-1 installation_name: shire provider: aws workers: count_per_cluster: default: 3 max: 20 instance_type: default: m3.large options: - m3.medium - m3.large - m3.xlarge "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. default: description: Error schema: $ref: '#/definitions/v4GenericResponse' /v4/organizations/: get: 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. tags: - organizations summary: Get organizations operationId: getOrganizations parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header responses: "200": description: Success schema: type: array items: $ref: '#/definitions/v4OrganizationListItem' examples: application/json: - id: acme - id: giantswarm - id: testorg "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. default: description: Error schema: $ref: '#/definitions/v4GenericResponse' /v4/organizations/{organization_id}/: get: description: | This operation fetches organization details. tags: - organizations summary: Get organization details operationId: getOrganization parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: | An ID for the organization. This ID must be unique and match this regular expression: ^[a-z0-9_]{4,30}$ name: organization_id in: path required: true responses: "200": description: Organization details schema: $ref: '#/definitions/v4Organization' examples: application/json: id: acme members: - email: user1@example.com - email: user2@example.com "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. "404": description: Organization not found schema: $ref: '#/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/v4GenericResponse' put: description: | This operation allows a user to create an organization. tags: - organizations summary: Create an organization operationId: addOrganization parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: | An ID for the organization. This ID must be unique and match this regular expression: ^[a-z0-9_]{4,30}$ name: organization_id in: path required: true - x-examples: application/json: id: string members: - email: myself@example.com - email: colleague@example.com name: body in: body required: true schema: $ref: '#/definitions/v4Organization' responses: "201": description: Organization created schema: $ref: '#/definitions/v4Organization' examples: application/json: id: acme members: - email: user1@example.com - email: user2@example.com "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. "409": description: Organization already exists schema: $ref: '#/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/v4GenericResponse' delete: description: | This operation allows a user to delete an organization that they are a member of. Admin users can delete any organization. tags: - organizations summary: Delete an organization operationId: deleteOrganization parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: | An ID for the organization. This ID must be unique and match this regular expression: ^[a-z0-9_]{4,30}$ name: organization_id in: path required: true responses: "200": description: Organization deleted schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: RESOURCE_DELETED message: The organization with ID 'acme' has been deleted. "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. "404": description: Organization not found schema: $ref: '#/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/v4GenericResponse' patch: 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. tags: - organizations summary: Modify organization operationId: modifyOrganization parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: | An ID for the organization. This ID must be unique and match this regular expression: ^[a-z0-9_]{4,30}$ name: organization_id in: path required: true - x-examples: application/merge-patch+json: members: - email: myself@example.com name: body in: body required: true schema: $ref: '#/definitions/modifyOrganizationParamsBody' responses: "200": description: Organization modified schema: $ref: '#/definitions/v4Organization' "400": description: Invalid input schema: $ref: '#/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": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. "404": description: Organization not found schema: $ref: '#/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/v4GenericResponse' /v4/organizations/{organization_id}/credentials/: post: 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" } } } ``` tags: - organizations summary: Set credentials operationId: addCredentials parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: | An ID for the organization. This ID must be unique and match this regular expression: ^[a-z0-9_]{4,30}$ name: organization_id in: path required: true - x-examples: application/json: aws: roles: admin: arn:aws:iam::123456789012:role/GiantSwarmAdmin awsoperator: arn:aws:iam::123456789012:role/GiantSwarmAWSOperator provider: aws name: body in: body required: true schema: $ref: '#/definitions/v4AddCredentialsRequest' responses: "201": description: Credentials created schema: $ref: '#/definitions/v4GenericResponse' headers: Location: type: string description: URI of the new credentials resource examples: application/json: code: RESOURCE_CREATED message: A new set of credentials has been created with ID '5d9h4' "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. "409": description: Conflict schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: RESOURCE_ALREADY_EXISTS message: The organisation already has a set of credentials default: description: error schema: $ref: '#/definitions/v4GenericResponse' /v4/releases/: get: 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. tags: - releases summary: Get releases operationId: getReleases parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header responses: "200": description: Releases list schema: type: array items: $ref: '#/definitions/v4ReleaseListItem' examples: application/json: - active: false changelog: - component: kubernetes description: Security fixes - component: calico description: Security fixes components: - name: kubernetes version: 1.5.8 - name: calico version: 0.9.1 timestamp: "2017-09-21T08:14:03.37759Z" version: 1.14.9 - active: true changelog: - component: calico description: Bugfix components: - name: kubernetes version: 1.7.3 - name: calico version: 1.1.1 timestamp: "2017-11-11T12:24:56.59969Z" version: 2.8.4 "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. /v4/user/: get: description: | Returns details about the currently authenticated user tags: - users summary: Get current user operationId: getCurrentUser parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header responses: "200": description: Success schema: $ref: '#/definitions/v4UserListItem' examples: application/json: created: "2017-01-15T12:00:00Z" email: andy@example.com expiry: "2019-01-15T00:00:00Z" "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. default: description: Error schema: $ref: '#/definitions/v4GenericResponse' /v4/users/: get: description: | Returns a list of all users in the system. Currently this endpoint is only available to users with admin permissions. tags: - users summary: Get users operationId: getUsers parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header responses: "200": description: Success schema: type: array items: $ref: '#/definitions/v4UserListItem' examples: application/json: - created: "2017-01-15T12:00:00Z" email: andy@example.com expiry: "2019-01-15T00:00:00Z" - created: "2017-02-15T12:30:00Z" email: bob@example.com expiry: "2020-01-15T00:00:00Z" - created: "2017-03-15T13:00:00Z" email: charles@example.com expiry: "2021-01-15T00:00:00Z" "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. default: description: Error schema: $ref: '#/definitions/v4GenericResponse' /v4/users/{email}/: get: description: | Returns details about a specific user tags: - users summary: Get user operationId: getUser parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: The user's email address name: email in: path required: true responses: "200": description: Success schema: $ref: '#/definitions/v4UserListItem' examples: application/json: created: "2017-01-15T12:00:00Z" email: andy@example.com expiry: "2019-01-15T00:00:00Z" "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. "404": description: User not found schema: $ref: '#/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/v4GenericResponse' put: description: | Creates a users in the system. Currently this endpoint is only available to users with admin permissions. tags: - users summary: Create user operationId: createUser parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: The user's email address name: email in: path required: true - x-examples: application/json: expiry: "2020-01-01T12:00:00.000Z" password: cGFzc3dvcmQ= description: User account details name: body in: body required: true schema: $ref: '#/definitions/v4CreateUserRequest' responses: "201": description: User created schema: $ref: '#/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/v4GenericResponse' examples: application/json: code: RESOURCE_ALREADY_EXISTS message: 'The user could not be created. (invalid input: email ''bob@example.com'' already exists)' "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. default: description: Error schema: $ref: '#/definitions/v4GenericResponse' delete: description: | Deletes a users in the system. Currently this endpoint is only available to users with admin permissions. tags: - users summary: Delete user operationId: deleteUser parameters: - type: string description: As described in the [authentication](#section/Authentication) section name: Authorization in: header required: true - type: string description: | A randomly generated key that can be used to track a request throughout services of Giant Swarm. name: X-Request-ID in: header - type: string description: | Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. name: X-Giant-Swarm-Activity in: header - type: string description: | If activity has been issued by a CLI, this header can contain the command line name: X-Giant-Swarm-CmdLine in: header - type: string description: The user's email address name: email in: path required: true responses: "200": description: User deleted schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: RESOURCE_DELETED message: The user with email 'bob@example.com' has been deleted. "401": description: Permission denied schema: $ref: '#/definitions/v4GenericResponse' examples: application/json: code: PERMISSION_DENIED message: The requested resource cannot be accessed using the provided authentication details. "404": description: User not found schema: $ref: '#/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/v4GenericResponse' definitions: modifyOrganizationParamsBody: type: object properties: members: description: List of members that belong to this organization type: array items: $ref: '#/definitions/v4OrganizationMember' x-go-gen-location: operations v4AddClusterRequest: description: Request model for creating a new cluster type: object required: - owner properties: kubernetes_version: description: | Kubernetes version number (deprecated). Doesn't have any effect. This attribute is going to be removed in future API versions. type: string name: description: Cluster name type: string owner: description: Name of the organization owning the cluster type: string release_version: description: | The [release](https://docs.giantswarm.io/api/#tag/releases) version to use in the new cluster type: string workers: type: array items: $ref: '#/definitions/v4AddClusterRequestWorkersItems' v4AddClusterRequestWorkersItems: type: object properties: aws: $ref: '#/definitions/v4AddClusterRequestWorkersItemsAws' azure: $ref: '#/definitions/v4AddClusterRequestWorkersItemsAzure' cpu: $ref: '#/definitions/v4AddClusterRequestWorkersItemsCpu' labels: type: object additionalProperties: true memory: $ref: '#/definitions/v4AddClusterRequestWorkersItemsMemory' storage: $ref: '#/definitions/v4AddClusterRequestWorkersItemsStorage' x-go-gen-location: models v4AddClusterRequestWorkersItemsAws: description: | Attributes specific to nodes running on Amazon Web Services (AWS) type: object properties: instance_type: description: | EC2 instance type name. Must be the same for all worker nodes of a cluster. type: string x-go-gen-location: models v4AddClusterRequestWorkersItemsAzure: description: | Attributes specific to nodes running on Microsoft Azure type: object properties: vm_size: description: | Azure Virtual Machine size. Must be the same for all worker nodes of a cluster. type: string x-go-gen-location: models v4AddClusterRequestWorkersItemsCpu: type: object properties: cores: description: Number of CPU cores type: integer x-go-gen-location: models v4AddClusterRequestWorkersItemsMemory: type: object properties: size_gb: description: RAM size in GB. Can be an integer or float. type: number x-go-gen-location: models v4AddClusterRequestWorkersItemsStorage: type: object properties: size_gb: description: Node storage size in GB. Can be an integer or float. type: number x-go-gen-location: models v4AddCredentialsRequest: description: Request model for adding a set of credentials type: object required: - provider properties: aws: $ref: '#/definitions/v4AddCredentialsRequestAws' provider: type: string v4AddCredentialsRequestAws: description: Credentials specific to an AWS account type: object required: - roles properties: roles: $ref: '#/definitions/v4AddCredentialsRequestAwsRoles' x-go-gen-location: models v4AddCredentialsRequestAwsRoles: description: IAM roles to assume by certain entities type: object required: - awsoperator - admin properties: admin: description: ARN of the IAM role to assume by Giant Swarm support staff type: string awsoperator: description: ARN of the IAM role to assume by the software operating clusters type: string x-go-gen-location: models v4AddKeyPairRequest: type: object required: - description properties: certificate_organizations: description: | This will set the certificate subject's `organization` fields. Use a comma seperated list of values. type: string cn_prefix: description: The common name prefix of the certificate subject. This only allows characters that are usable in domain names (`a-z`, `0-9`, and `.-`, where `.-` must not occur at either the start or the end). type: string description: description: Free text information about the key pair type: string ttl_hours: description: Expiration time (from creation) in hours type: integer format: int32 v4AddKeyPairResponse: type: object properties: certificate_authority_data: description: PEM-encoded CA certificate of the cluster type: string client_certificate_data: description: PEM-encoded certificate type: string client_key_data: description: PEM-encoded RSA private key type: string create_date: description: Date/time of creation type: string description: description: Free text information about the key pair type: string id: description: Unique identifier of the key pair type: string ttl_hours: description: Expiration time (from creation) in hours type: integer v4ClusterDetailsResponse: description: Response model showing details of a cluster type: object properties: api_endpoint: description: URI of the Kubernetes API endpoint type: string create_date: description: Date/time of cluster creation type: string id: description: Unique cluster identifier type: string kubernetes_version: description: Deprecated. Will be removed in a future API version. type: string kvm: $ref: '#/definitions/v4ClusterDetailsResponseKvm' name: description: Cluster name type: string owner: description: Name of the organization owning the cluster type: string release_version: description: | The [release](https://docs.giantswarm.io/api/#tag/releases) version currently running this cluster. type: string workers: type: array items: $ref: '#/definitions/v4ClusterDetailsResponseWorkersItems' v4ClusterDetailsResponseKvm: description: Attributes specific to clusters running on KVM (on-prem) installations. type: object properties: port_mappings: description: | Reveals the ports on the host cluster that are mapped to this guest cluster's ingress and which protocol that port supports. Only shown and relevant on our on-prem KVM clusters. type: array items: $ref: '#/definitions/v4ClusterDetailsResponseKvmPortMappingsItems' x-go-gen-location: models v4ClusterDetailsResponseKvmPortMappingsItems: type: object properties: port: description: | The port on the host cluster that will forward traffic to the guest cluster type: integer protocol: description: | The protocol this port mapping is made for. type: string x-go-gen-location: models v4ClusterDetailsResponseWorkersItems: type: object properties: aws: $ref: '#/definitions/v4ClusterDetailsResponseWorkersItemsAws' azure: $ref: '#/definitions/v4ClusterDetailsResponseWorkersItemsAzure' cpu: $ref: '#/definitions/v4ClusterDetailsResponseWorkersItemsCpu' labels: type: object additionalProperties: true memory: $ref: '#/definitions/v4ClusterDetailsResponseWorkersItemsMemory' storage: $ref: '#/definitions/v4ClusterDetailsResponseWorkersItemsStorage' x-go-gen-location: models v4ClusterDetailsResponseWorkersItemsAws: description: | Attributes specific to nodes running on Amazon Web Services (AWS) type: object properties: instance_type: description: | EC2 instance type name. Must be the same for all worker nodes of a cluster. type: string x-go-gen-location: models v4ClusterDetailsResponseWorkersItemsAzure: description: | Attributes specific to nodes running on Microsoft Azure type: object properties: vm_size: description: | Azure Virtual Machine size. Must be the same for all worker nodes of a cluster. type: string x-go-gen-location: models v4ClusterDetailsResponseWorkersItemsCpu: type: object properties: cores: description: Number of CPU cores type: integer x-go-gen-location: models v4ClusterDetailsResponseWorkersItemsMemory: type: object properties: size_gb: description: RAM size in GB. Can be an integer or float. type: number x-go-gen-location: models v4ClusterDetailsResponseWorkersItemsStorage: type: object properties: size_gb: description: Node storage size in GB. Can be an integer or float. type: number x-go-gen-location: models v4ClusterListItem: type: object properties: create_date: description: Date/time of cluster creation type: string id: description: Unique cluster identifier type: string name: description: Cluster name type: string owner: description: Name of the organization owning the cluster type: string release_version: description: The semantic version number of this cluster type: string v4CreateAuthTokenRequest: type: object properties: email: description: Your email address type: string password_base64: description: Your password as a base64 encoded string type: string v4CreateAuthTokenResponse: type: object properties: auth_token: description: The newly created API token type: string v4CreateUserRequest: description: Request model for creating a new user type: object required: - password properties: expiry: description: The date and time when this account will expire type: string password: description: A Base64 encoded password type: string v4GenericResponse: type: object properties: code: description: | A machine readable [response code](https://github.com/giantswarm/api-spec/blob/master/details/RESPONSE_CODES.md) like e. g. `INVALID_CREDENTIALS` type: string message: description: A human readable message type: string v4GetKeyPairsResponse: description: Array of sparse key pair objects type: array items: $ref: '#/definitions/v4GetKeyPairsResponseItems' v4GetKeyPairsResponseItems: type: object properties: certificate_organizations: description: The certificate subject's `organization` fields. type: string common_name: description: The common name of the certificate subject. type: string create_date: description: Date/time of creation type: string description: description: Free text information about the key pair type: string id: description: Unique identifier of the key pair type: string ttl_hours: description: Expiration time (from creation) in hours type: integer x-go-gen-location: models v4InfoResponse: type: object properties: general: $ref: '#/definitions/v4InfoResponseGeneral' workers: $ref: '#/definitions/v4InfoResponseWorkers' v4InfoResponseGeneral: description: General information type: object properties: datacenter: description: Identifier of the datacenter or cloud provider region, e. g. "eu-west-1" type: string installation_name: description: Unique name of the installation type: string provider: description: The technical provider used in this installation. Either "kvm", "aws", or "azure". type: string x-go-gen-location: models v4InfoResponseWorkers: description: Information related to worker nodes type: object properties: count_per_cluster: $ref: '#/definitions/v4InfoResponseWorkersCountPerCluster' instance_type: $ref: '#/definitions/v4InfoResponseWorkersInstanceType' vm_size: $ref: '#/definitions/v4InfoResponseWorkersVmSize' x-go-gen-location: models v4InfoResponseWorkersCountPerCluster: description: Number of workers per cluster type: object properties: default: description: Default number of workers in a new cluster will have, if not specifiec otherwise type: number max: description: Maximum number of worker a cluster can have type: number x-go-gen-location: models v4InfoResponseWorkersInstanceType: description: Instance types to be used for worker nodes. Only available for AWS clusters. type: object properties: default: description: The instance type used in new cluster, if not specified type: string options: description: List of available instance types type: array items: type: string x-go-gen-location: models v4InfoResponseWorkersVmSize: description: Azure Virtual Machine size to be used for worker nodes. Only available for Azure clusters. type: object properties: default: description: The instance type used in new cluster, if not specified type: string options: description: List of available instance types type: array items: type: string x-go-gen-location: models v4ModifyClusterRequest: description: Request body for cluster modification type: object properties: name: description: Name for the cluster type: string owner: description: Name of the organization owning the cluster type: string release_version: description: Release version to use after an upgrade type: string workers: description: Worker node array type: array items: $ref: '#/definitions/v4ModifyClusterRequestWorkersItems' v4ModifyClusterRequestWorkersItems: type: object properties: aws: $ref: '#/definitions/v4ModifyClusterRequestWorkersItemsAws' azure: $ref: '#/definitions/v4ModifyClusterRequestWorkersItemsAzure' cpu: $ref: '#/definitions/v4ModifyClusterRequestWorkersItemsCpu' labels: type: object additionalProperties: true memory: $ref: '#/definitions/v4ModifyClusterRequestWorkersItemsMemory' storage: $ref: '#/definitions/v4ModifyClusterRequestWorkersItemsStorage' x-go-gen-location: models v4ModifyClusterRequestWorkersItemsAws: description: | Attributes specific to nodes running on Amazon Web Services (AWS) type: object properties: instance_type: description: | EC2 instance type name. Must be the same for all worker nodes of a cluster. type: string x-go-gen-location: models v4ModifyClusterRequestWorkersItemsAzure: description: | Attributes specific to nodes running on Microsoft Azure type: object properties: vm_size: description: | Azure Virtual Machine size. Must be the same for all worker nodes of a cluster. type: string x-go-gen-location: models v4ModifyClusterRequestWorkersItemsCpu: type: object properties: cores: description: Number of CPU cores type: integer x-go-gen-location: models v4ModifyClusterRequestWorkersItemsMemory: type: object properties: size_gb: description: RAM size in GB. Can be an integer or float. type: number x-go-gen-location: models v4ModifyClusterRequestWorkersItemsStorage: type: object properties: size_gb: description: Node storage size in GB. Can be an integer or float. type: number x-go-gen-location: models v4Organization: type: object properties: id: description: Unique name/identifier of the organization type: string members: description: List of members that belong to this organization type: array items: $ref: '#/definitions/v4OrganizationMembersItems' v4OrganizationListItem: type: object properties: id: description: Unique name/identifier of the organization type: string v4OrganizationMember: type: object properties: email: description: Email address of the user type: string v4OrganizationMembersItems: type: object properties: email: description: Email address of the user type: string x-go-gen-location: models v4ReleaseListItem: type: object required: - version - timestamp - changelog - components properties: active: description: | If true, the version is available for new clusters and cluster upgrades. Older versions become unavailable and thus have the value `false` here. type: boolean changelog: description: | Structured list of changes in this release, in comparison to the previous version, with respect to the contained components. type: array items: $ref: '#/definitions/v4ReleaseListItemChangelogItems' components: description: | List of components and their version contained in the release type: array items: $ref: '#/definitions/v4ReleaseListItemComponentsItems' timestamp: description: Date and time of the release creation type: string version: description: The semantic version number type: string v4ReleaseListItemChangelogItems: type: object properties: component: description: | If the changed item was a component, this attribute is the name of the component. type: string description: description: Human-friendly description of the change type: string x-go-gen-location: models v4ReleaseListItemComponentsItems: type: object required: - name - version properties: name: description: Name of the component type: string version: description: Version number of the component type: string x-go-gen-location: models v4UserListItem: type: object properties: created: description: The date and time that this account was created type: string email: description: Email address of the user type: string expiry: description: The date and time when this account will expire type: string securityDefinitions: AuthorizationHeaderToken: description: | Clients authenticate by passing an auth token via the `Authorization` header with a value of the format `giantswarm `. Auth tokens can be obtained using the [createAuthToken](#operation/createAuthToken) operation. type: apiKey name: Authorization in: header security: - AuthorizationHeaderToken: [] tags: - 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: auth tokens - 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: clusters - description: Information about the Giant Swarm installation name: info - 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. name: key pairs externalDocs: description: 'User guide: Accessing Pods and Services from the Outside' url: https://docs.giantswarm.io/guides/accessing-services-from-the-outside/ - description: Organizations are groups of users who own resources like clusters. name: organizations - 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: users - 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. name: releases