github.com/thetreep/go-swagger@v0.0.0-20240223100711-35af64f14f01/fixtures/bugs/1621/fixture-1621.yaml (about)

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