Wala shell

Advanced PHP File Manager

Server IP: 127.0.0.1 | PHP Version: 8.3.30 | Domains Hosted: 54

Name	Size	Last Modified	Actions
📁 ..	-	2025-05-25 12:27
📄 definitions.yaml definitions: # Generic response model V4GenericResponse: type: object properties: message: type: string description: A human readable message code: type: string description: \| A machine readable [response code](https://github.com/giantswarm/api-spec/blob/master/details/RESPONSE_CODES.md) like e. g. `INVALID_CREDENTIALS` # Info resposne V4InfoResponse: type: object properties: general: description: General information type: object properties: installation_name: description: Unique name of the installation type: string provider: description: The technical provider used in this installation. Either "kvm", "aws", or "azure". type: string datacenter: description: Identifier of the datacenter or cloud provider region, e. g. "eu-west-1" type: string workers: description: Information related to worker nodes type: object properties: count_per_cluster: description: Number of workers per cluster type: object properties: max: description: Maximum number of worker a cluster can have type: number default: description: Default number of workers in a new cluster will have, if not specifiec otherwise type: number instance_type: description: Instance types to be used for worker nodes. Only available for AWS clusters. type: object properties: options: description: List of available instance types type: array items: type: string default: description: The instance type used in new cluster, if not specified type: string vm_size: description: Azure Virtual Machine size to be used for worker nodes. Only available for Azure clusters. type: object properties: options: description: List of available instance types type: array items: type: string default: description: The instance type used in new cluster, if not specified type: string # Request to create a new cluster V4AddClusterRequest: type: object required: - owner description: Request model for creating a new cluster properties: owner: type: string description: Name of the organization owning the cluster name: type: string description: Cluster name release_version: type: string description: \| The [release](https://docs.giantswarm.io/api/#tag/releases) version to use in the new cluster kubernetes_version: type: string description: \| Kubernetes version number (deprecated). Doesn't have any effect. This attribute is going to be removed in future API versions. workers: type: array items: $ref: '#/definitions/V4NodeDefinition' V4ModifyClusterRequest: type: object required: [] description: Request body for cluster modification properties: name: type: string description: Name for the cluster owner: type: string description: Name of the organization owning the cluster release_version: type: string description: Release version to use after an upgrade workers: type: array description: Worker node array items: $ref: '#/definitions/V4NodeDefinition' # Details on existing cluster V4ClusterDetailsResponse: type: object description: Response model showing details of a cluster properties: id: type: string description: Unique cluster identifier api_endpoint: type: string description: URI of the Kubernetes API endpoint create_date: type: string description: Date/time of cluster creation owner: type: string description: Name of the organization owning the cluster name: type: string description: Cluster name release_version: type: string description: \| The [release](https://docs.giantswarm.io/api/#tag/releases) version currently running this cluster. kubernetes_version: type: string description: Deprecated. Will be removed in a future API version. workers: type: array items: $ref: '#/definitions/V4NodeDefinition' kvm: type: object description: Attributes specific to clusters running on KVM (on-prem) installations. properties: port_mappings: type: array description: \| Reveals the ports on the host cluster that are mapped to this guest cluster's ingress and which protocol that port supports. Only shown and relevant on our on-prem KVM clusters. items: type: object properties: port: description: \| The port on the host cluster that will forward traffic to the guest cluster type: integer protocol: description: \| The protocol this port mapping is made for. type: string # Definition of a cluster node V4NodeDefinition: type: object properties: aws: type: object description: \| Attributes specific to nodes running on Amazon Web Services (AWS) properties: instance_type: type: string description: \| EC2 instance type name. Must be the same for all worker nodes of a cluster. azure: type: object description: \| Attributes specific to nodes running on Microsoft Azure properties: vm_size: type: string description: \| Azure Virtual Machine size. Must be the same for all worker nodes of a cluster. memory: type: object properties: size_gb: type: number description: RAM size in GB. Can be an integer or float. storage: type: object properties: size_gb: type: number description: Node storage size in GB. Can be an integer or float. cpu: type: object properties: cores: type: integer description: Number of CPU cores labels: type: object additionalProperties: true # List of key pairs V4GetKeyPairsResponse: type: array description: Array of sparse key pair objects items: type: object properties: id: type: string description: Unique identifier of the key pair description: type: string description: Free text information about the key pair ttl_hours: type: integer description: Expiration time (from creation) in hours create_date: type: string description: Date/time of creation common_name: type: string description: The common name of the certificate subject. certificate_organizations: type: string description: The certificate subject's `organization` fields. # Add key pair request V4AddKeyPairRequest: type: object required: - description properties: description: type: string description: Free text information about the key pair ttl_hours: type: integer format: int32 description: Expiration time (from creation) in hours cn_prefix: type: string description: The common name prefix of the certificate subject. This only allows characters that are usable in domain names (`a-z`, `0-9`, and `.-`, where `.-` must not occur at either the start or the end). certificate_organizations: type: string description: \| This will set the certificate subject's `organization` fields. Use a comma seperated list of values. V4AddKeyPairResponse: type: object properties: id: type: string description: Unique identifier of the key pair description: type: string description: Free text information about the key pair ttl_hours: type: integer description: Expiration time (from creation) in hours create_date: type: string description: Date/time of creation certificate_authority_data: type: string description: PEM-encoded CA certificate of the cluster client_key_data: type: string description: PEM-encoded RSA private key client_certificate_data: type: string description: PEM-encoded certificate # cluster metrics V4GetClusterMetricsResponse: description: Response for the getClusterMetrics operation type: object properties: workers: description: Group of metrics regarding workers type: array items: $ref: '#/definitions/V4NodeMetrics' V4NodeMetrics: type: object properties: id: description: String identifying the node type: string metrics: description: Container object for all metrics available for the node type: object properties: container_count: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number pod_count: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number cpu_used: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number ram_free: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number ram_available: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number ram_cached: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number ram_buffers: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number ram_mapped: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number node_storage_used: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number network_rx: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number network_tx: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number resource_cpu_requests: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number resource_cpu_limits: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number resource_ram_requests: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number resource_ram_limits: type: object properties: timestamp: description: Time when the given value has been recorded type: string value: description: The value for the metric. Can be an integer or float. type: number # a complete organization object V4Organization: type: object properties: id: type: string description: Unique name/identifier of the organization members: type: array description: List of members that belong to this organization items: $ref: '#/definitions/V4OrganizationMember' # An organization as returned by getOrganizations as an array item V4OrganizationListItem: type: object properties: id: type: string description: Unique name/identifier of the organization # A user that belongs to an organization V4OrganizationMember: type: object properties: email: type: string description: Email address of the user # One of the users in the array as returned by getUsers V4UserListItem: type: object properties: email: type: string description: Email address of the user created: type: string description: The date and time that this account was created expiry: type: string description: The date and time when this account will expire # A cluster array item, as return by getClusters V4ClusterListItem: type: object properties: id: type: string description: Unique cluster identifier create_date: type: string description: Date/time of cluster creation name: type: string description: Cluster name owner: type: string description: Name of the organization owning the cluster release_version: type: string description: The semantic version number of this cluster # A cluster array item, as return by getClusters V4ReleaseListItem: type: object required: ["version", "timestamp", "changelog", "components"] properties: version: type: string description: The semantic version number timestamp: type: string description: Date and time of the release creation active: type: boolean description: \| If true, the version is available for new clusters and cluster upgrades. Older versions become unavailable and thus have the value `false` here. changelog: description: \| Structured list of changes in this release, in comparison to the previous version, with respect to the contained components. type: array items: type: object properties: component: type: string description: \| If the changed item was a component, this attribute is the name of the component. description: type: string description: Human-friendly description of the change components: description: \| List of components and their version contained in the release type: array items: type: object required: ["name", "version"] properties: name: type: string description: Name of the component version: type: string description: Version number of the component V4CreateUserRequest: type: object required: - password description: Request model for creating a new user properties: password: type: string description: A Base64 encoded password expiry: type: string description: The date and time when this account will expire V4AddCredentialsRequest: type: object required: - provider description: Request model for adding a set of credentials properties: provider: type: string aws: type: object description: Credentials specific to an AWS account required: - roles properties: roles: type: object descriptions: IAM roles to assume by certain entities required: - awsoperator - admin properties: admin: type: string description: ARN of the IAM role to assume by Giant Swarm support staff awsoperator: type: string description: ARN of the IAM role to assume by the software operating clusters # A request for an auth token V4CreateAuthTokenRequest: type: object properties: email: type: string description: Your email address password_base64: type: string description: Your password as a base64 encoded string # A response to a successful auth token request V4CreateAuthTokenResponse: type: object properties: auth_token: type: string description: The newly created API token	19.37 KB	2025-05-25 12:27
📄 fixture-1621.yaml 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"} "201": # Fake response added with expanded content of 200, to run test assertion, e.g. 200 <=> 201 description: Success schema: type: object properties: email: type: string description: Email address of the user created: type: string description: The date and time that this account was created expiry: type: string description: The date and time when this account will expire "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"	51.73 KB	2025-05-25 12:27
📄 parameters.yaml parameters: RequiredGiantSwarmAuthorizationHeader: name: Authorization type: string in: header required: true description: As described in the [authentication](#section/Authentication) section ClusterIdPathParameter: name: cluster_id in: path required: true type: string description: Cluster ID UserEmailPathParameter: name: email in: path required: true type: string description: The user's email address OrganizationIdPathParameter: name: organization_id in: path required: true type: string description: \| An ID for the organization. This ID must be unique and match this regular expression: ^[a-z0-9_]{4,30}$ XRequestIDHeader: name: X-Request-ID in: header type: string required: false description: \| A randomly generated key that can be used to track a request throughout services of Giant Swarm. XGiantSwarmActivityHeader: name: X-Giant-Swarm-Activity in: header type: string required: false description: \| Name of an activity to track, like "list-clusters". This allows to analyze several API requests sent in context and gives an idea on the purpose. XGiantSwarmCmdLineHeader: name: X-Giant-Swarm-CmdLine in: header type: string required: false description: \| If activity has been issued by a CLI, this header can contain the command line	1.44 KB	2025-05-25 12:27
📄 responses.yaml responses: V4Generic401Response: description: Permission denied schema: $ref: "./definitions.yaml#/definitions/V4GenericResponse" examples: application/json: { "code": "PERMISSION_DENIED", "message": "The requested resource cannot be accessed using the provided authentication details." }	353 B	2025-05-25 12:27

Terminal