Server : LiteSpeed System : Linux in-mum-web1949.main-hosting.eu 5.14.0-503.40.1.el9_5.x86_64 #1 SMP PREEMPT_DYNAMIC Mon May 5 06:06:04 EDT 2025 x86_64 User : u595547767 ( 595547767) PHP Version : 7.4.33 Disable Function : NONE Directory : /opt/go/pkg/mod/github.com/go-openapi/spec@v0.21.0/fixtures/bugs/1621/ |
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"