This section provides a reference for APIs that should be implemented by this Building Block.
The same comment as in section 7 applies. We refrain from defining Meta-APIs here, but may agree to do so at a later stage. The implementations should use standard APIs that are well supported by IaC tooling.
8.1. API for Provisioning Virtual Machines
Interface for creating, managing, and deallocating virtual machines on the cloud infrastructure.
The API is a REST interface; a resource gets created by and authorized POST request to the relevant endpoint (as listed in the catalogue) including the JSON data structure describing the resource properties. The methods GETDELETE, PUT, PATCH are supported to list or retrieve details, to destroy a resource and to apply changes to an existing ressource. The normal http response codes indicate whether the request was successful. The authentication happens via a header with the authorization token or via a client cert.
Note that resource creation can be a long-running process. If the request was legal, a success code (200) is returned and a message with the resource UUID, but polling for the status of the resource would be needed to ensure it’s ready before relying on it’s readiness. Details are implementation dependent, a defensive automation apporach would always check on the state of a resource.
The interface is an imperative one – the API call requests the platform to do X. The platform attempts to do so, and if there is a failure, it will be reported. The resource creation may succeed and then later enter into a failure state. This won’t be automatically fixed either but can be seen from the state.
Orchestration services with a declarative interface that describe the wanted target state that the orchestrator then tries to create are possible.
8.2. API for Managing Storage Volumes
Endpoints for creating, attaching, resizing, and deleting storage volumes used by virtual machines and containers.
The same considerations apply as in 8.1.
8.3. API for Network Configuration
Services for setting up, modifying, and tearing down network configurations, including virtual networks, subnets, and security groups.
The same considerations as in 8.1 apply.
8.4. API for Container Orchestration
Interfaces for deploying, scaling, and managing containerized applications, supporting operations like starting, stopping, and monitoring containers.
The REST API submits hierarchical data structures (typically as YAML) that describe a wanted state, like “there should be two replicas of this pod in the cluster”. (A pod is a set of containers that belong together and are always scheduled together.) The reconciliation loop of the container orchestration software is supposed to ensure that those two replicas get started. If a node dies, it will soon take care of starting another replica to ensure we (almost) always have the desired state.
The data structures are defined by the implementation and allows for being extended via schema for custom resources.
8.5. API for IAM Management
Endpoints for managing user identities, roles, permissions, and authentication policies.
Both the virtualization layer and the container orchestration layer allow for defining users, groups, and roles locally. For allowing federated infrastructure, it is desired, however, to use federated identities and configure the users in the IAM component or the customer’s own Identity Provider.
For the federation, OpenID Connect should be supported; the protocol and data structures are described by the OpenID Connect specs from the OpenID Foundation’s relevant working group.
8.6. API for Monitoring and Logging
Services for collecting, querying, and analyzing logs and monitoring data from cloud resources and applications.
Implementation specific.
8.7. API for Status Page
Interface for retrieving the current status and health metrics of various cloud services and components, enabling real-time monitoring and transparency.
Infrastructure providers should publish the status of their services to the users, allowing them to determine whether service limitations are happening in the provider’s realm. Providers use an API to publish their status that is then displayed on a web page accessible to least all platform users.
An example API specification would look like this:
