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
            description: 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