Exoscale cluster API

openapi: 3.2.0
info:
  version: 2.0.0
  termsOfService: https://exoscale.com/terms
  contact:
    email: support@exoscale.com
    name: Exoscale Support
    url: https://portal.exoscale.com/tickets
  title: Exoscale ai-api-key Cluster API
  description: Infrastructure automation API, allowing programmatic access to all Exoscale products and services.
servers:
- url: https://api-{zone}.exoscale.com/v2
  variables:
    zone:
      default: ch-gva-2
      enum:
      - ch-gva-2
      - ch-dk-2
      - de-fra-1
      - de-muc-1
      - at-vie-1
      - at-vie-2
      - bg-sof-1
      - hr-zag-1
tags:
- description: Clusters are managed Kubernetes control planes.
  parent: sks
  externalDocs:
    description: Read more
    url: https://community.exoscale.com/documentation/sks/
  name: cluster
  x-display-name: Cluster
  x-weight: 310
  x-icon: exo-sks
paths:
  /sks-cluster-kubeconfig/{id}:
    post:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  kubeconfig:
                    type: string
      description: This operation returns a Kubeconfig file encoded in base64.
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Generate a new Kubeconfig file for a SKS cluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sks-kubeconfig-request'
      operationId: generate-sks-cluster-kubeconfig
  /sks-cluster/{id}/authority/{authority}/cert:
    get:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  cacert:
                    type: string
      description: This operation returns the certificate for the given SKS cluster authority encoded in base64.
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      - in: path
        required: true
        name: authority
        schema:
          type: string
          enum:
          - control-plane
          - aggregation
          - kubelet
      summary: Get the certificate for a SKS cluster authority
      operationId: get-sks-cluster-authority-cert
  /sks-cluster-deprecated-resources/{id}:
    get:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/sks-cluster-deprecated-resource'
      description: This operation returns the deprecated resources for a given cluster
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Resources that are scheduled to be removed in future kubernetes releases
      operationId: list-sks-cluster-deprecated-resources
  /sks-cluster/{id}/upgrade-service-level:
    put:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/operation'
      description: ''
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Upgrade a SKS cluster to pro
      operationId: upgrade-sks-cluster-service-level
  /sks-cluster/{id}/rotate-csi-credentials:
    put:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/operation'
      description: ''
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Rotate Exoscale CSI credentials
      operationId: rotate-sks-csi-credentials
  /sks-cluster:
    post:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/operation'
      description: ''
      parameters: []
      summary: Create an SKS cluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type:
                  - string
                  - 'null'
                  maxLength: 255
                  description: Cluster description
                labels:
                  $ref: '#/components/schemas/sks-cluster-labels'
                  description: Cluster Labels
                cni:
                  type: string
                  enum:
                  - calico
                  - cilium
                  description: Cluster CNI
                auto-upgrade:
                  type: boolean
                  description: Enable auto upgrade of the control plane to the latest patch version available
                networking:
                  $ref: '#/components/schemas/networking'
                  description: Cluster networking configuration
                oidc:
                  $ref: '#/components/schemas/sks-oidc'
                  description: Cluster OpenID configmap
                name:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: Cluster name
                create-default-security-group:
                  type:
                  - boolean
                  - 'null'
                  description: Creates an ad-hoc security group based on the choice of the selected CNI
                enable-kube-proxy:
                  type: boolean
                  description: Indicates whether to deploy the Kubernetes network proxy. When unspecified, defaults to `true` unless Cilium CNI is selected
                level:
                  type: string
                  enum:
                  - starter
                  - pro
                  description: Cluster service level
                feature-gates:
                  type: array
                  items:
                    type: string
                  uniqueItems: true
                  description: A list of Kubernetes-only Alpha features to enable for API server component
                addons:
                  type: array
                  items:
                    type: string
                    enum:
                    - exoscale-cloud-controller
                    - exoscale-container-storage-interface
                    - metrics-server
                    - karpenter
                  uniqueItems: true
                  description: Cluster addons
                audit:
                  $ref: '#/components/schemas/sks-audit-create'
                  description: Kubernetes Audit Log Configuration
                version:
                  type: string
                  description: Control plane Kubernetes version
              required:
              - name
              - level
              - version
      operationId: create-sks-cluster
    get:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  sks-clusters:
                    type: array
                    items:
                      $ref: '#/components/schemas/sks-cluster'
      description: ''
      parameters: []
      summary: List SKS clusters
      operationId: list-sks-clusters
  /sks-cluster/{id}:
    delete:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/operation'
      description: ''
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Delete an SKS cluster
      operationId: delete-sks-cluster
    get:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sks-cluster'
      description: ''
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Retrieve SKS cluster details
      operationId: get-sks-cluster
    put:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/operation'
      description: ''
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Update an SKS cluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type:
                  - string
                  - 'null'
                  maxLength: 255
                  description: Cluster description
                labels:
                  $ref: '#/components/schemas/sks-cluster-labels'
                  description: Cluster labels
                auto-upgrade:
                  type: boolean
                  description: Enable auto upgrade of the control plane to the latest patch version available
                oidc:
                  $ref: '#/components/schemas/sks-oidc'
                  description: Cluster OpenID configmap
                name:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: Cluster name
                enable-operators-ca:
                  type: boolean
                  description: Add or remove the operators certificate authority (CA) from the list of trusted CAs of the api server. The default value is true
                feature-gates:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                  uniqueItems: true
                  description: A list of Kubernetes-only Alpha features to enable for API server component
                addons:
                  type: array
                  items:
                    type: string
                    enum:
                    - exoscale-cloud-controller
                    - exoscale-container-storage-interface
                    - metrics-server
                    - karpenter
                  uniqueItems: true
                  description: Cluster addons
                audit:
                  $ref: '#/components/schemas/sks-audit-update'
                  description: Kubernetes Audit Log Configuration
      operationId: update-sks-cluster
  /sks-cluster/{id}/inspection:
    get:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
      description: Helps troubleshoot common problems when deploying a kubernetes cluster. Inspections run every couple of minutes.
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Get the latest inspection result
      operationId: get-sks-cluster-inspection
  /sks-cluster/{id}/rotate-ccm-credentials:
    put:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/operation'
      description: ''
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Rotate Exoscale CCM credentials
      operationId: rotate-sks-ccm-credentials
  /sks-cluster/{id}/rotate-karpenter-credentials:
    put:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/operation'
      description: ''
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Rotate Exoscale Karpenter credentials
      operationId: rotate-sks-karpenter-credentials
  /sks-cluster/{id}/rotate-operators-ca:
    put:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/operation'
      description: ''
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Rotate operators certificate authority
      operationId: rotate-sks-operators-ca
  /sks-cluster-version:
    get:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  sks-cluster-versions:
                    type: array
                    items:
                      type: string
      description: ''
      parameters:
      - in: query
        required: false
        name: include-deprecated
        schema:
          type: string
      summary: List available versions for SKS clusters
      operationId: list-sks-cluster-versions
  /sks-cluster/{id}/upgrade:
    put:
      tags:
      - cluster
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/operation'
      description: ''
      parameters:
      - in: path
        required: true
        name: id
        schema:
          type: string
          format: uuid
      summary: Upgrade an SKS cluster
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  description: Control plane Kubernetes version
              required:
              - version
      operationId: upgrade-sks-cluster
components:
  schemas:
    networking:
      type: object
      properties:
        cluster-cidr:
          type: string
          description: "CIDR Range for Pods in cluster. This must not overlap with any IP ranges assigned to pods. Max of two, comma-separated, dual-stack CIDRs is allowed.\n              If not specified, defaults to 192.168.0.0/16."
        service-cluster-ip-range:
          type: string
          description: "CIDR range for service cluster IPs. This must not overlap with any IP ranges assigned to nodes or pods. Max of two, comma-separated, dual-stack CIDRs is allowed.\n              If not specified, defaults to 10.96.0.0/12."
        node-cidr-mask-size-ipv4:
          type: integer
          format: int64
          description: Mask size for node cidr in cluster. It must be larger than the Pod CIDR subnet mask. Defaults to 24
          exclusiveMinimum: 0
        node-cidr-mask-size-ipv6:
          type: integer
          format: int64
          description: Mask size for node cidr in cluster. It must be larger than the Pod CIDR subnet mask. Defaults to 64
          exclusiveMinimum: 0
      description: Cluster networking configuration.
    template-ref:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Template ID
      description: Template reference
    sks-audit-initial-backoff:
      type: string
      maxLength: 10
      minLength: 1
    sks-cluster-labels:
      type: object
      additionalProperties:
        type: string
    sks-nodepool:
      type: object
      properties:
        anti-affinity-groups:
          type: array
          items:
            $ref: '#/components/schemas/anti-affinity-group-ref'
          uniqueItems: true
          maxItems: 8
          description: Nodepool Anti-affinity Groups
        description:
          type: string
          maxLength: 255
          description: Nodepool description
        public-ip-assignment:
          type: string
          enum:
          - inet4
          - dual
          description: 'Nodepool public IP assignment of the Instances:


            * IPv4 (`inet4`) addressing only;

            * IPv4 and IPv6 (`dual`) addressing.'
        labels:
          $ref: '#/components/schemas/sks-nodepool-labels'
          description: Nodepool labels
        taints:
          $ref: '#/components/schemas/sks-nodepool-taints'
          description: Nodepool taints
        security-groups:
          type: array
          items:
            $ref: '#/components/schemas/security-group-ref'
          uniqueItems: true
          maxItems: 16
          description: Nodepool Security Groups
        name:
          type: string
          maxLength: 255
          minLength: 1
          description: Nodepool name
        instance-type:
          $ref: '#/components/schemas/instance-type-ref'
          description: Nodepool Instances type
        private-networks:
          type: array
          items:
            $ref: '#/components/schemas/private-network-ref'
          uniqueItems: true
          maxItems: 16
          description: Nodepool Private Networks
        template:
          $ref: '#/components/schemas/template-ref'
          readOnly: true
          description: Nodepool Instance template
        state:
          type: string
          enum:
          - renewing-token
          - creating
          - deleting
          - running
          - scaling
          - updating
          - error
          readOnly: true
          description: Nodepool state
        size:
          type: integer
          format: int64
          minimum: 0
          description: Number of instances
        kubelet-image-gc:
          $ref: '#/components/schemas/kubelet-image-gc'
          description: Kubelet image GC options
        instance-pool:
          $ref: '#/components/schemas/instance-pool-ref'
          readOnly: true
          description: Instance Pool managed by the Nodepool
        instance-prefix:
          type: string
          maxLength: 30
          minLength: 1
          description: 'The instances created by the Nodepool will be prefixed with this value (default: pool)'
        deploy-target:
          $ref: '#/components/schemas/deploy-target-ref'
          description: Instance Pool Deploy Target
        addons:
          type: array
          items:
            type: string
            enum:
            - storage-lvm
          uniqueItems: true
          description: Nodepool addons
        id:
          type: string
          format: uuid
          readOnly: true
          description: Nodepool ID
        disk-size:
          type: integer
          format: int64
          minimum: 20
          maximum: 51200
          description: Nodepool instances disk size in GiB
        version:
          type: string
          readOnly: true
          description: Nodepool version
        created-at:
          type: string
          format: date-time
          readOnly: true
          description: Nodepool creation date
      description: SKS Nodepool
    instance-type-ref:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Instance type ID
      description: Instance type reference
    private-network-ref:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Private network ID
      description: Private network reference
    sks-cluster:
      type: object
      properties:
        description:
          type: string
          maxLength: 255
          description: Cluster description
        labels:
          $ref: '#/components/schemas/sks-cluster-labels'
          description: Cluster labels
        cni:
          type: string
          enum:
          - calico
          - cilium
          description: Cluster CNI
        auto-upgrade:
          type: boolean
          description: Enable auto upgrade of the control plane to the latest patch version available
        name:
          type: string
          maxLength: 255
          minLength: 1
          description: Cluster name
        enable-operators-ca:
          type: boolean
          description: Indicates whether to add operators certificate authority (CA) as part of trusted CAs for the API server.
        default-security-group-id:
          type:
          - string
          - 'null'
          format: uuid
          readOnly: true
          description: Cluster default Security Group ID
        state:
          type: string
          enum:
          - rotating-csi-credentials
          - rotating-ccm-credentials
          - creating
          - upgrading
          - deleting
          - running
          - suspending
          - updating
          - error
          - rotating-karpenter-credentials
          - resuming
          readOnly: true
          description: Cluster state
        enable-kube-proxy:
          type: boolean
          description: Indicates whether to deploy the Kubernetes network proxy.
        nodepools:
          type: array
          items:
            $ref: '#/components/schemas/sks-nodepool'
          uniqueItems: true
          maxItems: 16
          readOnly: true
          description: Cluster Nodepools
        level:
          type: string
          enum:
          - starter
          - pro
          description: Cluster level
        feature-gates:
          type: array
          items:
            type: string
          description: A list of Kubernetes-only Alpha features to enable for API server component
        addons:
          type: array
          items:
            type: string
            enum:
            - exoscale-cloud-controller
            - exoscale-container-storage-interface
            - metrics-server
            - karpenter
          uniqueItems: true
          description: Cluster addons
        id:
          type: string
          format: uuid
          readOnly: true
          description: Cluster ID
        audit:
          $ref: '#/components/schemas/sks-audit'
          description: Kubernetes Audit
        version:
          type: string
          description: Control plane Kubernetes version
        created-at:
          type: string
          format: date-time
          readOnly: true
          description: Cluster creation date
        endpoint:
          type: string
          readOnly: true
          description: Cluster endpoint
      description: SKS Cluster
    sks-nodepool-taint:
      type: object
      properties:
        value:
          type: string
          maxLength: 255
          minLength: 1
          description: Nodepool taint value
        effect:
          type: string
          enum:
          - NoExecute
          - NoSchedule
          - PreferNoSchedule
          description: Nodepool taint effect
      required:
      - value
      - effect
      description: Nodepool taint
    sks-cluster-deprecated-resource:
      type: object
      properties:
        group:
          type: string
        version:
          type: string
        resource:
          type: string
        subresource:
          type: string
        removed-release:
          type: string
    sks-nodepool-taints:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/sks-nodepool-taint'
    sks-audit-create:
      type: object
      properties:
        endpoint:
          $ref: '#/components/schemas/sks-audit-endpoint'
          description: Target Webserver URL
        bearer-token:
          $ref: '#/components/schemas/sks-audit-bearer-token'
          description: Bearer token
        initial-backoff:
          $ref: '#/components/schemas/sks-audit-initial-backoff'
          description: Initial backoff (default '10s')
      required:
      - endpoint
      - bearer-token
      description: Kubernetes Audit parameters
    sks-audit-bearer-token:
      type: string
      maxLength: 2000
      minLength: 1
    sks-oidc:
      type: object
      properties:
        client-id:
          type: string
          maxLength: 255
          minLength: 1
          description: OpenID client ID
        issuer-url:
          type: string
          maxLength: 255
          minLength: 1
          description: OpenID provider URL
        username-claim:
          type: string
          maxLength: 255
          minLength: 1
          description: JWT claim to use as the user name
        username-prefix:
          type: string
          maxLength: 255
          minLength: 1
          description: Prefix prepended to username claims
        groups-claim:
          type: string
          maxLength: 255
          minLength: 1
          description: JWT claim to use as the user's group
        groups-prefix:
          type: string
          maxLength: 255
          minLength: 1
          description: Prefix prepended to group claims
        required-claim:
          type: object
          additionalProperties:
            type: string
          description: A key value map that describes a required claim in the ID Token
      required:
      - client-id
      - issuer-url
      description: SKS Cluster OpenID config map
    sks-audit-update:
      type: object
      properties:
        endpoint:
          $ref: '#/components/schemas/sks-audit-endpoint'
          description: Target Webserver URL
        bearer-token:
          $ref: '#/components/schemas/sks-audit-bearer-token'
          description: Bearer token
        initial-backoff:
          $ref: '#/components/schemas/sks-audit-initial-backoff'
          description: Initial backoff (default '10s')
        enabled:
          type: boolean
          description: Enable or Disable Kubernetes Audit
      description: Kubernetes Audit parameters
    kubelet-image-gc:
      type: object
      properties:
        high-threshold:
          type: integer
          format: int64
          minimum: 0
        low-threshold:
          type: integer
          format: int64
          minimum: 0
        min-age:
          type: string
      description: Kubelet image GC options
    sks-audit:
      type: object
      properties:
        endpoint:
          $ref: '#/components/schemas/sks-audit-endpoint'
          description: Target Webserver URL
        enabled:
          type: boolean
          description: Enabled
        initial-backoff:
          $ref: '#/components/schemas/sks-audit-initial-backoff'
          description: Initial Backoff (default '10s')
      description: Kubernetes Audit parameters
    deploy-target-ref:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Deploy target ID
      description: Deploy target reference
    operation:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Operation ID
        reason:
          type: string
          enum:
          - incorrect
          - unknown
          - unavailable
          - forbidden
          - busy
          - fault
          - partial
          - not-found
          - interrupted
          - unsupported
          - conflict
          readOnly: true
          description: Operation failure reason
        reference:
          type: object
          properties:
            id:
              type: string
              format: uuid
              description: Reference ID
            link:
              type: string
              readOnly: true
              description: Link to the referenced resource
            command:
              type: string
              description: Command name
          description: Related resource reference
          readOnly: true
        message:
          type: string
          readOnly: true
          description: Operation message
        state:
          type: string
          enum:
          - failure
          - pending
          - success
          - timeout
          readOnly: true
          description: Operation status
      description: Operation
    sks-kubeconfig-request:
      type: object
      properties:
        ttl:
          type: integer
          format: int64
          description: 'Validity in seconds of the Kubeconfig user certificate (default: 30 days)'
          exclusiveMinimum: 0
        user:
          type: string
          description: User name in the generated Kubeconfig. The certificate present in the Kubeconfig will also have this name set for the CN field.
        groups:
          type: array
          items:
            type: string
          description: List of roles. The certificate present in the Kubeconfig will have these roles set in the Org field.
      required:
      - user
      - groups
      description: Kubeconfig request for a SKS cluster
    security-group-ref:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Security group ID
      description: Security group reference
    anti-affinity-group-ref:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Anti-affinity group ID
      description: Anti-affinity group reference
    sks-audit-endpoint:
      type: string
      maxLength: 2000
      minLength: 1
    sks-nodepool-labels:
      type: object
      additionalProperties:
        type: string
    instance-pool-ref:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Instance Pool ID
      description: Target Instance Pool
x-topics:
- title: API Request Signature
  content: '

    In order to authenticate legitimate users, the Exoscale API requires incoming requests to be signed using valid Exoscale API account credentials with the following mechanism.


    ## Signature Mechanism


    The *message* (i.e. content) to sign contains several segments concatenated using a line return character (`\n`).


    All segments must be included and in the described order. For cases where a segment doesn''t fit the context of the request (e.g. no request body) **an empty line must be used instead**.


    * Request method and request URL (path only), separated by a space character

    * Request body

    * Request URL parameters (Query String) values, concatenated without separator. The matching parameter names have to be specified in the resulting signature header `signed-query-args=` pragma, separated by semicolons (e.g. `p1;p2;pN`).

    * Request header values, concatenated without separator (none at the moment, leave empty)

    * Request expiration date in UNIX timestamp format


    Example *message* to sign for `GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0?p1=v1&p2=v2`:


    ```

    GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0


    v1v2


    1599140767

    ```


    The two blank lines above are due to the absence of a request body and signed headers.


    Example *message* to [create a security group](https://community.exoscale.com/reference/api/compute/security-group/#create-security-group)


    ```

    POST /v2/security-group

    {"name": "my-security-group"}



    1599140767

    ```


    The two blank lines above are due to the absence of query parameters and signed headers.


    The request signature consists of the base64-encoded [HMAC](https://en.wikipedia.org/wiki/HMAC) hash of the UTF-8 encoded *message* and the Exoscale API

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/exoscale/refs/heads/main/openapi/exoscale-cluster-api-openapi.yml