controlplane.yaml

openapi: 3.0.3
info:
    title: Unikraft Cloud Control Plane API
    description: This specification describes the Unikraft Cloud Control Plane API, which provides mechanisms to interact with globally provided Unikraft Cloud system.
    contact:
        name: Unikraft Support
        url: https://unikraft.com/contact
        email: support@unikraft.com
    version: v1.0.0
servers:
    - url: https://controlplane.unikraft.cloud
      description: Official Unikraft Cloud Control Plane API
paths:
    /v1/auth:
        get:
            tags:
                - Auth
            summary: Get Authorization Status
            description: Get authorization details for a token.
            operationId: GetAuthorization
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GetAuthorizationResponse'
            x-package: controlplane
    /v1/auth/check:
        post:
            tags:
                - Auth
            summary: Check Authorization of Sign-In Request
            description: |-
                Check the authorization status of a request.  The responses are streamed
                back to the client, indicating whether the signin request is authorized or
                not.
            operationId: CheckAuthorization
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CheckAuthorizationRequest'
                required: true
            responses:
                default:
                    description: default
                    content:
                        text/event-stream:
                            schema:
                                $ref: '#/components/schemas/CheckAuthorizationResponse'
            x-package: controlplane
    /v1/auth/signin:
        post:
            tags:
                - Auth
            summary: Request Sign-In
            description: |-
                Initiate the sign-in process and return an authorization URL.  The user
                should be redirected to this URL to complete the sign-in.
            operationId: RequestSignin
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/RequestSigninRequest'
                required: true
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RequestSigninResponse'
            x-package: controlplane
    /v1/images:
        get:
            tags:
                - Images
            summary: List Images
            description: ListImages lists all images for the authenticated user.
            operationId: ListImages
            parameters:
                - name: details
                  in: query
                  description: Whether to include image tag details.
                  schema:
                    type: boolean
                - name: namespace
                  in: query
                  description: Optional namespaces to filter images by.
                  schema:
                    type: array
                    items:
                        type: string
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListImagesResponse'
            x-package: controlplane
    /v1/metros:
        get:
            tags:
                - Metros
            summary: Get Metros
            description: ListMetros lists all available metros.
            operationId: ListMetros
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListMetroResponse'
            x-package: controlplane
    /v1/nodes:
        get:
            tags:
                - NodeService
            summary: List Node Nodes
            description: |-
                Get one or more nodes.

                Returns nodes matching the specified filters. If no filters are
                provided, all nodes are returned.
            operationId: ListNodes
            parameters:
                - name: cloudprovider
                  in: query
                  description: Optional filter by cloud provider.
                  schema:
                    $ref: '#/components/schemas/CloudProvider'
                - name: state
                  in: query
                  description: Optional filter by state.
                  schema:
                    $ref: '#/components/schemas/NodeState'
                - name: metro
                  in: query
                  description: Optional filter by metro.
                  schema:
                    type: string
                - name: region
                  in: query
                  description: Optional filter by region.
                  schema:
                    type: string
                - name: limit
                  in: query
                  description: Maximum number of results to return.
                  schema:
                    type: integer
                    format: uint32
                - name: offset
                  in: query
                  description: Offset for pagination.
                  schema:
                    type: integer
                    format: uint32
            requestBody:
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                $ref: '#/components/schemas/NameOrUUID'
                required: true
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListNodesResponse'
            x-package: controlplane
        post:
            tags:
                - NodeService
            summary: Create Node Node
            description: |-
                Create a new node.

                Creates a new compute node on the specified cloud provider. The node
                will go through provisioning (PROVISIONING state) and configuration
                (CONFIGURING state) before becoming ready (READY state) for use.
            operationId: ProvisionNode
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ProvisionNodeRequest'
                required: true
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ProvisionNodeResponse'
            x-package: controlplane
        delete:
            tags:
                - NodeService
            summary: Delete Node Nodes
            description: |-
                Delete one or more nodes.

                Batch deletion of nodes by their identifiers.
            operationId: DestroyNode
            parameters:
                - name: force
                  in: query
                  description: Force deletion even if nodes are in use.
                  schema:
                    type: boolean
            requestBody:
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                $ref: '#/components/schemas/NameOrUUID'
                required: true
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DestroyNodeResponse'
            x-package: controlplane
        patch:
            tags:
                - NodeService
            summary: Update Node Nodes
            description: |-
                Update one or more nodes.

                Batch update of mutable properties for multiple nodes.
            operationId: UpdateNodes
            requestBody:
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                $ref: '#/components/schemas/NameOrUUID'
                required: true
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UpdateNodesResponse'
            x-package: controlplane
    /v1/nodes/activate:
        post:
            tags:
                - NodeActivationService
            description: |-
                Activates a new node, or renews an existing node's license. For first-time
                activation, a secret must be provided. For renewal, the CSR self-signature
                is used as proof of key possession and the secret is omitted.
            operationId: NodeActivate
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/NodeActivateRequest'
                required: true
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NodeActivateResponse'
            x-package: controlplane
    /v1/nodes/heartbeat:
        post:
            tags:
                - NodeActivationService
            description: Sends a heartbeat from a node to report its platform status.
            operationId: NodeHeartbeat
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/NodeHeartbeatRequest'
                required: true
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NodeHeartbeatResponse'
            x-package: controlplane
    /v1/nodes/provider/{cloudprovider}/regions:
        get:
            tags:
                - NodeService
            summary: List Regions
            description: |-
                List available regions for a provider.

                Returns the regions available for provisioning on the specified cloud
                provider, including availability zone information.
            operationId: ListRegions
            parameters:
                - name: cloudprovider
                  in: path
                  description: The cloud provider to list regions for.
                  required: true
                  schema:
                    $ref: '#/components/schemas/CloudProvider'
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListRegionsResponse'
            x-package: controlplane
    /v1/nodes/provider/{cloudprovider}/types:
        get:
            tags:
                - NodeService
            summary: List Machine Types
            description: |-
                List available machine types for a provider.

                Returns the machine types (instance types) available for provisioning
                on the specified cloud provider.
            operationId: ListMachineTypes
            parameters:
                - name: cloudprovider
                  in: path
                  description: The cloud provider to list machine types for.
                  required: true
                  schema:
                    $ref: '#/components/schemas/CloudProvider'
                - name: region
                  in: query
                  description: Optional region filter. Some providers have region-specific availability.
                  schema:
                    type: string
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListMachineTypesResponse'
            x-package: controlplane
    /v1/nodes/wait:
        get:
            tags:
                - NodeService
            summary: Wait for Node Nodes States
            description: Wait for multiple nodes to reach specific states.
            operationId: WaitNodes
            parameters:
                - name: states
                  in: query
                  description: The desired state(s) to wait for.
                  schema:
                    type: array
                    items:
                        $ref: '#/components/schemas/NodeState'
                - name: timeout_ms
                  in: query
                  description: Timeout in milliseconds. Use -1 for infinite wait.
                  schema:
                    type: integer
                    format: int64
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WaitNodesResponse'
            x-package: controlplane
    /v1/nodes/{uuid}:
        get:
            tags:
                - NodeService
            summary: Get Node Node by UUID
            description: Get a single node by its UUID.
            operationId: GetNodeByUUID
            parameters:
                - name: uuid
                  in: path
                  description: The UUID of the node to retrieve.
                  required: true
                  schema:
                    example: 123e4567-e89b-12d3-a456-426614174000
                    type: string
                    format: uuid
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListNodesResponse'
            x-package: controlplane
        delete:
            tags:
                - NodeService
            summary: Delete Node Node by UUID
            description: |-
                Destroy (delete) a node by its UUID.

                Deprovisions and deletes the node. The node will transition to
                DEPROVISIONING state and then be removed. If the node has a delete lock,
                this operation will fail unless the lock is first removed.
            operationId: DestroyNodeByUUID
            parameters:
                - name: uuid
                  in: path
                  description: The UUID of the node to delete.
                  required: true
                  schema:
                    example: 123e4567-e89b-12d3-a456-426614174000
                    type: string
                    format: uuid
                - name: force
                  in: query
                  description: Force deletion even if the node is in use.
                  schema:
                    type: boolean
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DestroyNodeResponse'
            x-package: controlplane
        patch:
            tags:
                - NodeService
            summary: Update Node Node by UUID
            description: |-
                Update a node by its UUID.

                Updates mutable properties of a node such as tags, delete lock,
                or SSH keys.
            operationId: UpdateNodeByUUID
            parameters:
                - name: uuid
                  in: path
                  description: The UUID of the node to update.
                  required: true
                  schema:
                    example: 123e4567-e89b-12d3-a456-426614174000
                    type: string
                    format: uuid
            requestBody:
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                $ref: '#/components/schemas/UpdateNodePayload'
                required: true
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UpdateNodesResponse'
            x-package: controlplane
    /v1/nodes/{uuid}/wait:
        get:
            tags:
                - NodeService
            summary: Wait for Node Node State by UUID
            description: |-
                Wait for a node to reach a specific state.

                Blocks until the specified node reaches one of the desired states
                or the timeout is reached.
            operationId: WaitNodeByUUID
            parameters:
                - name: uuid
                  in: path
                  description: The UUID of the node to wait for.
                  required: true
                  schema:
                    example: 123e4567-e89b-12d3-a456-426614174000
                    type: string
                    format: uuid
                - name: states
                  in: query
                  description: |-
                    The desired state(s) to wait for. The request completes when any of
                    these states is reached.
                  schema:
                    type: array
                    items:
                        $ref: '#/components/schemas/NodeState'
                - name: timeout_ms
                  in: query
                  description: Timeout in milliseconds. Use -1 for infinite wait.
                  schema:
                    type: integer
                    format: int64
            responses:
                default:
                    description: default
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WaitNodesResponse'
            x-package: controlplane
components:
    schemas:
        AWSConfig:
            required:
                - dedicated_host
                - region
                - machine_type
            type: object
            properties:
                vpc_id:
                    example: vpc-0123456789abcdef0
                    type: string
                    description: |-
                        The VPC ID where the instance will be launched. If not specified, the
                        default VPC for the region will be used.
                subnet_id:
                    example: subnet-0123456789abcdef0
                    type: string
                    description: |-
                        The subnet ID where the instance will be launched. If not specified,
                        a subnet will be selected from the VPC.
                security_group_ids:
                    example: ["sg-0123456789abcdef0"]
                    type: array
                    items:
                        type: string
                    description: |-
                        Security group IDs to attach to the instance. If not specified, the
                        default security group for the VPC will be used.
                iam_instance_profile:
                    example: arn:aws:iam::123456789012:instance-profile/MyProfile
                    type: string
                    description: The IAM instance profile ARN or name to attach to the instance.
                root_volume:
                    allOf:
                        - $ref: '#/components/schemas/AWSEBSConfig'
                    description: |-
                        Root EBS volume configuration. If not specified, provider defaults
                        will be used.
                additional_volumes:
                    type: array
                    items:
                        $ref: '#/components/schemas/AWSEBSConfig'
                    description: Additional EBS volumes to attach to the instance.
                dedicated_host:
                    type: boolean
                    description: |-
                        Whether to use a dedicated host. Dedicated hosts provide visibility and
                        control over how instances are placed on physical servers.
                placement_group:
                    example: my-cluster-placement-group
                    type: string
                    description: |-
                        Placement group name for the instance. Placement groups influence how
                        instances are placed on underlying hardware.
                region:
                    example: us-east-1
                    type: string
                    description: The AWS region where the machine is located.
                machine_type:
                    example: c8i.large
                    type: string
                    description: |-
                        The AWS machine type. This determines the compute resources
                        (CPU, memory, etc.) available on the machine. The valid values depend
                        on the chosen provider.
            description: AWSConfig contains AWS-specific configuration for node provisioning.
            x-package: controlplane
        AWSEBSConfig:
            required:
                - size_gib
                - volume_type
                - encrypted
                - delete_on_termination
            type: object
            properties:
                device_name:
                    example: /dev/xvdf
                    type: string
                    description: |-
                        The device name (e.g., "/dev/sda1", "/dev/xvdf"). Required for
                        additional volumes.
                size_gib:
                    example: 100
                    type: integer
                    description: Size of the volume in GiB.
                    format: uint32
                volume_type:
                    example: gp3
                    type: string
                    description: The volume type (gp3, gp2, io1, io2, st1, sc1, standard).
                iops:
                    example: 3000
                    type: integer
                    description: The number of IOPS. Only valid for io1, io2, and gp3 volumes.
                    format: uint32
                throughput_mibps:
                    example: 125
                    type: integer
                    description: The throughput in MiB/s. Only valid for gp3 volumes.
                    format: uint32
                encrypted:
                    type: boolean
                    description: Whether the volume should be encrypted.
                kms_key_id:
                    example: arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
                    type: string
                    description: |-
                        The KMS key ID for encryption. If encrypted is true and this is not
                        specified, the default EBS encryption key will be used.
                delete_on_termination:
                    type: boolean
                    description: Whether to delete the volume when the instance is terminated.
            description: AWSEBSConfig defines the configuration for an AWS EBS volume.
            x-package: controlplane
        CheckAuthorizationRequest:
            required:
                - request_id
            type: object
            properties:
                request_id:
                    type: string
                    description: |-
                        The request ID is a unique identifier for the request.  This is used to
                        track the request in the system and should be provided by the client.
            description: The request message for checking authorization given a request ID.
            x-package: controlplane
        CheckAuthorizationResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/CheckAuthorizationResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 56
                    type: integer
                    description: |-
                        The operation time in microseconds.  This is the time it took to process
                        the request and generate the response.
                    format: uint64
            description: The response message for checking authorization.
            x-package: controlplane
        CheckAuthorizationResponseData:
            required:
                - token
                - organization_name
                - organization_display_name
                - registry
            type: object
            properties:
                token:
                    type: string
                    description: The authorization token which can be used to authenticate requests.
                organization_name:
                    type: string
                    description: The organization name the token is associated with.
                organization_display_name:
                    type: string
                    description: The display name of the organization the token is associated with.
                registry:
                    type: string
                    description: The global image registry.
            x-package: controlplane
        CloudProvider:
            enum:
                - "manual"
                - "aws"
            type: string
            description: |-
                CloudProvider identifies the cloud infrastructure provider where nodes are
                provisioned.
            format: enum
            x-package: controlplane
        CloudProviderConfig:
            type: object
            allOf:
                - oneOf:
                    - title: aws
                      type: object
                      properties:
                        aws:
                            allOf:
                                - $ref: '#/components/schemas/AWSConfig'
                            description: AWS-specific configuration.
            description: |-
                CloudProviderConfig contains provider-specific configuration for node
                provisioning.  Use this for advanced customization beyond the common
                machine_type and region fields.
            x-package: controlplane
        DestroyNodeResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/DestroyNodeResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 2341
                    type: integer
                    description: The operation time in microseconds.
                    format: uint64
            description: Response message for deleting nodes.
            x-package: controlplane
        DestroyNodeResponseData:
            type: object
            properties:
                nodes:
                    type: array
                    items:
                        $ref: '#/components/schemas/Node'
                    description: The deleted nodes (with their final state before deletion).
            x-package: controlplane
        GetAuthorizationResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/GetAuthorizationResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 56
                    type: integer
                    description: |-
                        The operation time in microseconds.  This is the time it took to process
                        the request and generate the response.
                    format: uint64
            description: The response message for getting authorization details.
            x-package: controlplane
        GetAuthorizationResponseData:
            required:
                - organization_name
                - organization_display_name
                - registry
            type: object
            properties:
                organization_name:
                    type: string
                    description: The organization name the token is associated with.
                organization_display_name:
                    type: string
                    description: The display name of the organization the token is associated with.
                registry:
                    type: string
                    description: The global image registry.
            x-package: controlplane
        Image:
            required:
                - name
            type: object
            properties:
                name:
                    example: namespace/image1
                    type: string
                    description: The canonical name of the image.
                tags:
                    example: [{name: latest, digest: 'sha256:1111111111111111111111111111111111111111111111111111111111111111'}]
                    type: array
                    items:
                        $ref: '#/components/schemas/ImageTag'
                    description: The list of tags for the image.  Only populated when details are requested.
            x-package: controlplane
        ImageTag:
            required:
                - name
                - digest
                - size
                - push_time
            type: object
            properties:
                name:
                    example: latest
                    type: string
                    description: The tag name.
                digest:
                    example: sha256:1111111111111111111111111111111111111111111111111111111111111111
                    type: string
                    description: The digest for the tag.
                size:
                    example: 12345678
                    type: integer
                    description: The size of the image in bytes.
                    format: uint64
                push_time:
                    example: 2024-01-02T15:04:05Z
                    type: string
                    description: The push time of the image.
                    format: date-time
            x-package: controlplane
        ListImagesResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/ListImagesResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 87
                    type: integer
                    description: |-
                        The operation time in microseconds.  This is the time it took to process
                        the request and generate the response.
                    format: uint64
            x-package: controlplane
        ListImagesResponseData:
            type: object
            properties:
                images:
                    type: array
                    items:
                        $ref: '#/components/schemas/Image'
                    description: The list of images.
            x-package: controlplane
        ListMachineTypesResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/ListMachineTypesResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 123
                    type: integer
                    description: The operation time in microseconds.
                    format: uint64
            description: Response message for listing machine types.
            x-package: controlplane
        ListMachineTypesResponseData:
            type: object
            properties:
                machine_types:
                    type: array
                    items:
                        $ref: '#/components/schemas/MachineType'
                    description: The list of available machine types.
            x-package: controlplane
        ListMetroResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/ListMetroResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 87
                    type: integer
                    description: |-
                        The operation time in microseconds.  This is the time it took to process
                        the request and generate the response.
                    format: uint64
            x-package: controlplane
        ListMetroResponseData:
            type: object
            properties:
                metros:
                    type: array
                    items:
                        $ref: '#/components/schemas/Metro'
                    description: The list of metros.
            x-package: controlplane
        ListNodesResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/ListNodesResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 234
                    type: integer
                    description: The operation time in microseconds.
                    format: uint64
            description: Response message for getting nodes.
            x-package: controlplane
        ListNodesResponseData:
            required:
                - total_count
            type: object
            properties:
                nodes:
                    type: array
                    items:
                        $ref: '#/components/schemas/Node'
                    description: The list of nodes matching the request.
                total_count:
                    example: 42
                    type: integer
                    description: Total count of nodes matching the filters (for pagination).
                    format: uint32
            x-package: controlplane
        ListRegionsResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/ListRegionsResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 89
                    type: integer
                    description: The operation time in microseconds.
                    format: uint64
            description: Response message for listing regions.
            x-package: controlplane
        ListRegionsResponseData:
            type: object
            properties:
                regions:
                    type: array
                    items:
                        $ref: '#/components/schemas/Region'
                    description: The list of available regions.
            x-package: controlplane
        MachineType:
            required:
                - name
                - vcpus
                - memory_mib
                - nested_virtualization
            type: object
            properties:
                name:
                    example: m5.xlarge
                    type: string
                    description: The machine type identifier (e.g., "m5.xlarge", "n2-standard-4").
                description:
                    example: General purpose, 4 vCPUs, 16 GiB memory
                    type: string
                    description: Human-readable description.
                vcpus:
                    example: 4
                    type: integer
                    description: Number of vCPUs.
                    format: uint32
                memory_mib:
                    example: 16384
                    type: integer
                    description: Memory in MiB.
                    format: uint64
                category:
                    example: general-purpose
                    type: string
                    description: |-
                        Machine category (e.g., "general-purpose", "compute-optimized",
                        "memory-optimized").
                available_regions:
                    type: array
                    items:
                        type: string
                    description: Regions where this machine type is available.
                nested_virtualization:
                    type: boolean
                    description: Whether this machine type supports nested virtualization.
            description: Information about an available machine type.
            x-package: controlplane
        Metro:
            required:
                - uuid
                - endpoint
                - name
                - iata_code
                - country
            type: object
            properties:
                uuid:
                    example: c1d2e3f4-5678-90ab-cdef-1234567890ab
                    type: string
                    description: The UUID of the metro.
                    format: uuid
                endpoint:
                    example: https://api.metro1.unikraft.cloud/v1
                    type: string
                    description: The API endpoint for the metro.
                    format: uri
                name:
                    example: metro1
                    type: string
                    description: The name of the metro.
                iata_code:
                    example: FRA
                    type: string
                    description: The IATA code of the metro.
                country:
                    example: de
                    type: string
                    description: The country where the metro is located.
            x-package: controlplane
        MutableNodeOperation:
            enum:
                - "set"
                - "add"
                - "del"
            type: string
            description: The operations available on a node's mutable properties.
            format: enum
            x-package: controlplane
        MutableNodeProperty:
            enum:
                - "tags"
                - "delete_lock"
                - "ssh_keys"
            type: string
            description: The mutable properties of a node which can be updated.
            format: enum
            x-package: controlplane
        NameOrUUID:
            type: object
            allOf:
                - type: object
                  properties:
                    metro:
                        example: fra
                        type: string
                        description: |-
                            (Only applies when using global control plane).
                            The metro of the resource.
                - oneOf:
                    - title: uuid
                      required:
                        - uuid
                      type: object
                      properties:
                        uuid:
                            example: 123e4567-e89b-12d3-a456-426614174000
                            type: string
                            description: Mutually exclusive with name.
                            format: uuid
                    - title: name
                      required:
                        - name
                      type: object
                      properties:
                        name:
                            example: funky-town-g756b5d
                            type: string
                            description: Mutually exclusive with UUID.
            description: An identifier for a resource.  Either a name or a UUID.
            x-package: common
        Node:
            required:
                - uuid
                - name
                - created_at
                - state
                - region
                - machine_type
                - vcpus
                - memory_mib
                - uptime_seconds
                - delete_lock
            type: object
            properties:
                uuid:
                    type: string
                    description: |-
                        The UUID of the machine.

                        This is a unique identifier for the machine that is generated when the
                        machine is created. The UUID is used to reference the machine in API calls and
                        can be used to identify the machine in all API calls that require a machine
                        identifier.
                    format: uuid
                name:
                    example: machine-fra-aws-001
                    type: string
                    description: |-
                        The name of the machine.

                        This is a human-readable name that can be used to identify the machine.
                        The name must be unique within the context of your account. The name can
                        also be used to identify the machine in API calls.
                created_at:
                    example: 2024-01-15T10:30:00Z
                    type: string
                    description: The time the machine was created.
                    format: date-time
                updated_at:
                    example: 2024-01-15T12:45:00Z
                    type: string
                    description: The time the machine was last updated.
                    format: date-time
                state:
                    allOf:
                        - $ref: '#/components/schemas/NodeState'
                    description: The current state of the machine.
                state_message:
                    example: Provisioning in progress, waiting for instance to become available
                    type: string
                    description: |-
                        An optional message providing additional information about the current
                        state, particularly useful for error states.
                cloudprovider:
                    allOf:
                        - $ref: '#/components/schemas/CloudProvider'
                    description: The cloud provider where this machine is provisioned.
                region:
                    example: us-east-1
                    type: string
                    description: |-
                        The provider's region where the machine is located (e.g., "us-east-1" for
                        AWS, "us-central1" for GCP, "westeurope" for Azure).
                machine_type:
                    example: m5.xlarge
                    type: string
                    description: |-
                        The machine type as defined by the provider (e.g., "m5.xlarge" for AWS,
                        "n2-standard-4" for GCP, "Standard_D4s_v3" for Azure).

                        This determines the compute resources (CPU, memory, etc.) available on
                        the machine. The valid values depend on the chosen provider.
                vcpus:
                    example: 4
                    type: integer
                    description: The number of vCPUs available on this machine.
                    format: uint32
                memory_mib:
                    example: 16384
                    type: integer
                    description: The amount of memory in MiB available on this machine.
                    format: uint64
                ssh_keys:
                    type: array
                    items:
                        $ref: '#/components/schemas/SSHKey'
                    description: The SSH keys configured for access to this machine.
                public_ipv4:
                    example: 203.0.113.50
                    type: string
                    description: The public IPv4 address of the machine, if assigned.
                    format: ipv4
                public_ipv6:
                    example: 2001:db8::1
                    type: string
                    description: The public IPv6 address of the machine, if assigned.
                    format: ipv6
                private_ipv4:
                    example: 10.0.1.50
                    type: string
                    description: The private IPv4 address of the machine within the provider's network.
                    format: ipv4
                metro:
                    example: fra
                    type: string
                    description: The Unikraft Cloud metro this machine is associated with.
                provider_instance_id:
                    example: i-0123456789abcdef0
                    type: string
                    description: The provider-specific instance ID or resource identifier.
                provider_config:
                    allOf:
                        - $ref: '#/components/schemas/CloudProviderConfig'
                    description: Provider-specific configuration that was used to provision this node.
                tags:
                    example: {"environment": "production", "team": "platform"}
                    type: object
                    additionalProperties:
                        type: string
                    description: User-defined tags for organizing and filtering nodes.
                ready_at:
                    example: 2024-01-15T10:35:00Z
                    type: string
                    description: The time when the machine became ready (entered READY state).
                    format: date-time
                uptime_seconds:
                    example: 86400
                    type: integer
                    description: The total uptime of the machine in seconds since it became ready.
                    format: uint64
                delete_lock:
                    type: boolean
                    description: |-
                        Whether the machine is protected from deletion. When true, delete operations
                        will fail until this is set to false.
            description: |-
                Node represents a physical or virtual compute node provisioned on a
                cloud provider for use as part of the Unikraft Cloud infrastructure.

                Node nodes are the underlying compute resources where Unikraft Cloud
                instances run.  They are provisioned on-demand across multiple cloud
                providers and managed through a unified API.
            x-package: controlplane
        NodeActivateRequest:
            required:
                - csr
            type: object
            allOf:
                - type: object
                  properties:
                    csr:
                        example: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KLi4uCi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQ==
                        type: string
                        description: |-
                            The certificate signing request (CSR) for the license which is base64
                            encoded.
                - oneOf:
                    - title: secret
                      type: object
                      properties:
                        secret:
                            type: string
                            description: |-
                                An opaque secret for first-time activation. On renewal (where the node's
                                public key is already known), this field is omitted and the CSR
                                self-signature is used as proof of key possession.
                    - title: serial
                      type: object
                      properties:
                        serial:
                            type: string
                            description: The serial number of the last issued certificate.
            description: The request message for certificate activation.
            x-package: controlplane
        NodeActivateResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: / An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/NodeActivateResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 234
                    type: integer
                    description: The operation time in microseconds.
                    format: uint64
            description: The response message for certificate activation.
            x-package: controlplane
        NodeActivateResponseData:
            required:
                - license
            type: object
            properties:
                license:
                    type: string
                    description: The issued license certificate in base64 URL encoded PEM format.
            x-package: controlplane
        NodeHeartbeatRequest:
            required:
                - machine_id
                - platform_status
            type: object
            properties:
                machine_id:
                    type: string
                    description: The unique machine identifier of the node sending the heartbeat.
                platform_status:
                    allOf:
                        - $ref: '#/components/schemas/PlatformStatus'
                    description: The current platform status of the node.
            description: The request message for a node heartbeat.
            x-package: controlplane
        NodeHeartbeatResponse:
            required:
                - status
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
            description: The response message for a node heartbeat.
            x-package: controlplane
        NodeState:
            enum:
                - "unspecified"
                - "pending"
                - "provisioning"
                - "configuring"
                - "ready"
                - "deprovisioning"
                - "deprovisioned"
                - "error"
                - "maintenance"
            type: string
            description: |-
                NodeState defines the provisioning lifecycle state of a machine which will
                run the Unikraft Cloud Platform.
            format: enum
            x-package: controlplane
        PlatformStatus:
            enum:
                - "healthy"
                - "degraded"
                - "unavailable"
            type: string
            format: enum
            x-package: controlplane
        ProvisionNodeRequest:
            required:
                - region
                - machine_type
                - ssh_keys
            type: object
            properties:
                name:
                    example: node-fra-aws-001
                    type: string
                    description: |-
                        Optional name for the node. If not provided, a name will be
                        auto-generated.
                cloudprovider:
                    allOf:
                        - $ref: '#/components/schemas/CloudProvider'
                    description: The cloud provider where the machine should be provisioned.
                region:
                    example: us-east-1
                    type: string
                    description: The provider region where the machine should be provisioned.
                machine_type:
                    example: m5.xlarge
                    type: string
                    description: The machine type to provision. This is provider-specific.
                ssh_keys:
                    type: array
                    items:
                        $ref: '#/components/schemas/SSHKey'
                    description: SSH keys for accessing the node. At least one key is required.
                tags:
                    example: {"environment": "production"}
                    type: object
                    additionalProperties:
                        type: string
                    description: Optional user-defined tags.
                cloudprovider_config:
                    allOf:
                        - $ref: '#/components/schemas/CloudProviderConfig'
                    description: Optional provider-specific configuration for advanced customization.
                metro:
                    example: fra
                    type: string
                    description: The Unikraft Cloud metro to associate this machine with.
                platform_config:
                    example: {"vm-user-min-memory": "2048"}
                    type: object
                    additionalProperties:
                        type: string
                    description: |-
                        Optional user overrides for platform configuration. Keys should be
                        kebab-case (e.g., "vm-user-min-memory").
                image_pulls:
                    example: ["ghcr.io/myapp:latest", "quay.io/image:v1"]
                    type: array
                    items:
                        type: string
                    description: Optional image references to pre-pull on the provisioned machine.
                net_count:
                    example: 1000
                    type: integer
                    description: Optional network count override. If not specified, defaults to 1000.
                    format: uint32
            description: Request message for creating a new node.
            x-package: controlplane
        ProvisionNodeResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/ProvisionNodeResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 1523
                    type: integer
                    description: The operation time in microseconds.
                    format: uint64
            description: Response message for creating a node.
            x-package: controlplane
        ProvisionNodeResponseData:
            required:
                - node
            type: object
            properties:
                node:
                    allOf:
                        - $ref: '#/components/schemas/Node'
                    description: The created node.
            x-package: controlplane
        Region:
            required:
                - name
                - iata
            type: object
            properties:
                name:
                    example: us-east-1
                    type: string
                    description: The region identifier (e.g., "us-east-1", "us-central1").
                iata:
                    example: SFO
                    type: string
                    description: The IATA code for the region.
            description: Information about an available region.
            x-package: controlplane
        RequestSigninRequest:
            required:
                - hostname
            type: object
            properties:
                hostname:
                    example: my-machine.local
                    type: string
                    description: |-
                        The hostname is the name of the machine making the request.  This is
                        mandatory as it consitutes a unique identifier for the machine.
                os:
                    example: linux
                    type: string
                    description: The operating system of the machine making the request.
                os_version:
                    example: 5.10.0-17-amd64
                    type: string
                    description: |-
                        The version of the operating system of the machine making the request, if
                        available.

                        For Android, it's like "10", "11", "12", etc.  For iOS and macOS it's like
                        "15.6.1" or "12.4.0".  For Windows it's like "10.0.19044.1889". For FreeBSD
                        it's like "12.3-STABLE".  For Linux, this is simply the kernel version on
                        Linux, like "5.10.0-17-amd64".
                container:
                    example: false
                    type: boolean
                    description: A best-effort whether the client is running in a container.
                distro:
                    example: ubuntu
                    type: string
                    description: The OS distribution, if known.  E.g. "debian", "ubuntu", "nixos", ...
                distro_version:
                    example: 20.04
                    type: string
                    description: The OS distribution version if known.  E.g. "20.04", ...
                distro_codename:
                    example: jammy
                    type: string
                    description: TThe OS distribution codename if known.  E.g. "jammy", "bullseye", ...
                cli_version:
                    example: 1.0.0
                    type: string
                    description: |-
                        The CLI version is the version of the Unikraft CLI that is making the
                        request.
                goarch:
                    example: amd64
                    type: string
                    description: If available, the GOARCH value (of the built binary).
                goos:
                    example: linux
                    type: string
                    description: If available, the GOOS value (of the built binary)
                go_version:
                    example: 1.16.0
                    type: string
                    description: if available, the Go version binary was built with.
            description: The request message for a sign-in request.
            x-package: controlplane
        RequestSigninResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/RequestSigninResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 87
                    type: integer
                    description: |-
                        The operation time in microseconds.  This is the time it took to process
                        the request and generate the response.
                    format: uint64
            description: The response message for a sign-in request.
            x-package: controlplane
        RequestSigninResponseData:
            required:
                - authorization_url
                - request_id
            type: object
            properties:
                authorization_url:
                    type: string
                    description: The full URL which can be used to remotely confirm the signin.
                request_id:
                    type: string
                    description: |-
                        A unique identifier for the request.  This can be used to track the
                        request in the system.
            x-package: controlplane
        ResponseError:
            required:
                - status
            type: object
            properties:
                status:
                    example: 401
                    type: integer
                    description: The HTTP status code of the error.
                    format: uint64
            description: The error response message for an API request.
            x-package: common
        ResponseStatus:
            enum:
                - "success"
                - "error"
            type: string
            description: The response status of an API request.
            format: enum
            x-package: common
        SSHKey:
            required:
                - name
                - public_key
            type: object
            properties:
                name:
                    example: admin-key
                    type: string
                    description: A name or label for this SSH key.
                public_key:
                    example: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl user@host
                    type: string
                    description: |-
                        The SSH public key in OpenSSH format (e.g., "ssh-rsa AAAA... user@host"
                        or "ssh-ed25519 AAAA... user@host").
            description: SSHKey represents an SSH public key for authentication.
            x-package: controlplane
        UpdateNodePayload:
            required:
                - property
                - operation
            type: object
            properties:
                property:
                    allOf:
                        - $ref: '#/components/schemas/MutableNodeProperty'
                    description: The property to update.
                operation:
                    allOf:
                        - $ref: '#/components/schemas/MutableNodeOperation'
                    description: The operation to perform on the property.
                value:
                    type: string
                    description: |-
                        The value for the update operation. The type depends on the property:
                        - TAGS: google.protobuf.Struct with key-value pairs
                        - DELETE_LOCK: google.protobuf.Value with boolean
                        - SSH_KEYS: google.protobuf.ListValue with SSHKey objects
                    format: bytes
            description: UpdateNodePayload contains the changes to apply to a node.
            x-package: controlplane
        UpdateNodesResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/UpdateNodesResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 456
                    type: integer
                    description: The operation time in microseconds.
                    format: uint64
            description: Response message for updating nodes.
            x-package: controlplane
        UpdateNodesResponseData:
            type: object
            properties:
                nodes:
                    type: array
                    items:
                        $ref: '#/components/schemas/Node'
                    description: The updated nodes.
            x-package: controlplane
        WaitNodesResponse:
            required:
                - status
                - op_time_us
            type: object
            properties:
                status:
                    allOf:
                        - $ref: '#/components/schemas/ResponseStatus'
                    description: The status of the response.
                message:
                    type: string
                    description: An optional message providing additional information about the response.
                data:
                    allOf:
                        - $ref: '#/components/schemas/WaitNodesResponseData'
                    description: The response data for this request.
                errors:
                    type: array
                    items:
                        $ref: '#/components/schemas/ResponseError'
                    description: A list of errors which may have occurred during the request.
                op_time_us:
                    example: 180234
                    type: integer
                    description: The operation time in microseconds.
                    format: uint64
            description: Response message for wait operations.
            x-package: controlplane
        WaitNodesResponseData:
            type: object
            properties:
                nodes:
                    type: array
                    items:
                        $ref: '#/components/schemas/Node'
                    description: The nodes after reaching the desired state.
            x-package: controlplane
    securitySchemes:
        bearerToken:
            type: http
            scheme: bearer
tags:
    - name: Auth
      description: Authenticate with Unikraft Cloud.
    - name: Images
    - name: Metros
    - name: NodeActivationService
      description: |-
        NodeActivationService provides APIs for activating and renewing node
        licenses.
    - name: NodeService
      description: |-
        NodeService service provides APIs for provisioning and managing compute nodes
        across multiple cloud providers for use in Unikraft Cloud.