Service Type Definitions

This enhancement defines standardized schemas for DCM service types to enable cross-platform portability.

Summary

This ADR defines provider-agnostic schemas for DCM service types. These schemas enable Service Providers to provision four core service types — virtual machines, containers, databases, and Kubernetes clusters — across different infrastructure platforms without vendor lock-in. The key principle is portability first: schemas contain only minimal fields common across all implementations, with platform-specific configuration delegated to providerHints.

Motivation

Define a generic schema structure that ensures portability across infrastructure platforms while allowing extensibility for platform-specific optimizations without breaking compatibility.

Goals

• Define a generic schema that works for any serviceType, ensure portability, and allows extensibility without schema changes.
• Define an initial set of four primary service types applying this pattern:
  • VM
    Virtual machines with compute, storage, and OS specifications
  • Container
    Containerized workloads running on any container platform
  • Kubernetes Cluster
    Kubernetes Container Platform of any distribution (Kubernetes, OpenShift, EKS, AWS, GKE, etc.)
  • Database
    Database services with various engines (PostgreSQL, MySQL, etc.)

Non-Goals

• Allow runtime editability through API operations so administrators can create and modify templates without code changes
• Tooling to validate Service Provider compliance with catalog schemas (conformance test suites, reference implementations, automated validation frameworks)
• Migration strategies for breaking schema changes
• Provider-specific implementation details (each provider handles translation independently)
• Additional service types beyond VMs, containers, databases, and Kubernetes clusters (deferred to future phases)
• Standalone storage volumes or separately provisioned networks are not included. All storage (disk size, ephemeral allocation) and networking (interfaces, IPs, subnets, security groups) must be defined and bundled directly with the compute specification. Future iterations may decouple these services, but the current principle is monolithic definition for simplified deployment.

Proposal

Implementation Details/Notes/Constraints

All schemas use OpenAPI 3.1.0 to leverage JSON Schema features like contains for array validation.

Generic Service

All service schemas share common fields defined once in common.yaml

Schema Structure

Metadata Object

ProviderHints Object

providerHints is key to portability: providers use hints they recognize and ignore the rest. This means catalog offering using only common fields (vcpu, memory, guestOS) can be provisioned by any compatible provider. The providerHints section allows adding platform-specific optimizations: providers use hints they recognize and silently ignore the rest, so the same catalog item remains portable across platforms.

Specific services

Any serviceType can be defined by inheriting from common.yaml and adding type-specific fields. For the first milestone, DCM will support the following serviceTypes:

• Virtual Machine
  Virtual machines with CPU, memory, storage, and OS specifications
• Container
  Fields common to Kubernetes, Docker, Podman, Openshift, CRI-O, containerd
• Cluster
  Fields common to Kubernetes, OpenShift, EKS, GKE, AKS, and other distributions
• Database
  Fields common across all database types (SQL, NoSQL, search, time-series, etc.)

Virtual Machine

The following sections detail the VM schema architecture.

  flowchart TD
    SC[(Service Catalog)]
    API[Service Provider API]

    subgraph SP [Service Provider]
        direction LR
        KV[KubeVirt]
        VW[VMware]
        OS[OpenStack]
        AWS[AWS EC2]
    end

    Note_Reg

    Note_Trans@{ shape: card, label: "Each provider translates
the catalog item to its
native resource format" }

    SC --> API
    API --> SP

    Note_Reg -.- SP
    Note_Trans -.-> KV
    Note_Trans -.-> VW
    Note_Trans -.-> OS
    Note_Trans -.-> AWS

Schema

For easier review, the schema is accessible here vmspec.yaml.
Plus common fields: serviceType, schemaVersion, metadata, providerHints

VM vcpu Object

VM memory Object

VM storage Object

Disk names must be unique within the VM.

VM disk Object

VM guestOS Object

VM access Object

Containers

The following sections detail the Container schema architecture.

Schema

For easier review, the schema is accessible here containerspec.yaml.
Plus common fields: serviceType, schemaVersion, metadata, providerHints

Container image Object

Container resources Object

Container resources.cpu Object

Container resources.memory Object

Container process Object

Container env Object

Container network Object

Container port Object

Database

The following sections detail the Database schema architecture.

Schema

For easier review, the schema is accessible here databasespec.yaml.
Plus common fields: serviceType, schemaVersion, metadata, providerHints

Database resources Object

Kubernetes Cluster

The cluster schema works across all Kubernetes distributions: OpenShift, EKS, GKE, AKS, etc.

Schema

For easier review, the schema is available here: clusterspec.yaml.
Plus common fields: serviceType, schemaVersion, metadata, providerHints

Cluster nodes Object

Cluster controlPlane Object

Cluster worker Object

Upgrade / Downgrade Strategy

Schemas evolve over time as requirements change. Each catalog item carries a schemaVersion field that tells providers which translation logic to use. This allows us to introduce new schema versions while maintaining backward compatibility (this means that older catalog items continue working with their original schema, newer items use enhanced versions). During transitions, providers support multiple versions simultaneously.

Implementation History

Drawbacks

Alternatives

Comprehensive schemas with all platform features

Description: We considered including all possible fields (CPU topology, security contexts, HA configuration, etc.) in the core schema.

Why rejected: Not all fields exist on all platforms. This would force providers to handle features they don’t support, or force users to understand which fields work where. Portability would be compromised.

Virtual Machine Alternatives

Pure OVF XML Format

Description: We considered using OVF XML directly as our catalog format. This would provide perfect alignment with the standard but creates practical problems. OVF XML is verbose with complex nested structures, XML namespaces, and numeric resource type codes (3 for CPU, 4 for memory).

Pros: Perfect standard compliance, well-understood by virtualization teams

Cons: XML complexity, poor API ergonomics, includes packaging concepts irrelevant to catalog specs

TOSCA Cloud Orchestration

Description: TOSCA (Topology and Orchestration Specification for Cloud Applications) is an OASIS standard designed specifically for cloud resource orchestration. It provides a comprehensive model with node templates, capabilities, requirements, and relationship definitions. While powerful, TOSCA introduces significant complexity with its topology-based approach. For a catalog specification that describes individual resource templates, TOSCA’s relationship modeling and orchestration features are overkill.

Pros: Purpose-built for cloud, handles complex deployments

Cons: Steep learning curve, heavyweight for simple resource specs, less tooling ecosystem

Custom Schema from Scratch

Description: We could design a completely custom schema without reference to existing standards, optimizing purely for our immediate needs. This provides maximum flexibility and simplicity initially but loses the benefit of industry knowledge embedded in standards like OVF. Provider translation becomes harder because engineers must learn our invented vocabulary rather than mapping to familiar concepts they already know from OVF, OpenStack, or other systems.

Pros: Perfect fit for current needs, no standard overhead

Cons: Reinventing solved problems, harder provider adoption, no external validation

OpenStack-Style Flavors

Description: OpenStack’s approach separates compute templates (flavors) from images. Users select a flavor (m1.small, m1.medium) and an image separately. While simple, this creates a two-level hierarchy that feels unnatural for a general catalog system. It also doesn’t handle the full richness of VM configuration, storage configuration, and network interfaces. Initialization is handled separately rather than as part of a cohesive specification.

Pros: Simple flavor model, proven in OpenStack

Cons: Limited to compute specs, doesn’t handle full VM configuration, creates artificial separation

Container Alternatives

Kubernetes Pod Specification

Description: Using Kubernetes Pod/Deployment YAML directly as the catalog format would provide immediate familiarity for Kubernetes users but creates vendor lock-in.

Pros: Familiar to Kubernetes users, rich feature set, comprehensive documentation, established ecosystem

Cons: Kubernetes-specific (incompatible with Docker/Podman standalone), includes orchestration concepts unnecessary for resource specifications, ties catalog to Kubernetes API versions, prevents portability to non-Kubernetes platforms

Compose Specification

Description: The Compose Specification provides a YAML format for defining multi-container applications, now an open specification supported by Docker, Podman, and other runtimes.

Pros: Simple and approachable, widely known format, open specification, good for multi-container applications

Cons: Designed for application composition not individual resource specifications, doesn’t map cleanly to single-container catalog items, less granular than OCI for runtime configuration, focuses on orchestration rather than resource provisioning

Containerfile Build Instructions

Description: Define containers through Dockerfile/Containerfile rather than runtime specifications.

Pros: Reproducible builds, version control friendly, defines complete container image

Cons: Build-time specification not runtime specification, requires build infrastructure in catalog system, doesn’t address runtime configuration (resources, networking, security), mixes build concerns with deployment concerns

Custom Schema

Description: Design a container schema without reference to existing standards like OCI, optimizing purely for DCM’s immediate needs.

Pros: Optimized for DCM requirements, simpler for current use cases, no standard overhead

Cons: Reinventing problems OCI already solved, harder provider adoption (engineers learn new vocabulary instead of familiar OCI concepts), no external validation, loses portability benefits, incompatible with existing container tooling

Database Alternatives

Single Cloud Provider Model

Description: Using AWS RDS, Azure Database, or Google Cloud SQL specification directly as the catalog format.

Pros: Complete feature coverage, well-documented, proven in production

Cons: Vendor lock-in, cloud-specific terminology and features, doesn’t work with on-premise or Kubernetes-based databases, prevents multi-cloud portability

Kubernetes Operator CRD

Description: Using a specific Kubernetes database operator CRD (CloudNativePG, Percona) as the standard.

Pros: Kubernetes-native, rich feature set, battle-tested

Cons: Kubernetes-specific, incompatible with cloud DBaaS providers, ties catalog to specific operator versions, doesn’t support VM-based database deployments

SQL Standard Only

Description: Focus purely on SQL standards (ANSI SQL, SQL:2016) for database specifications.

Pros: Well-established standard, vendor-neutral

Cons: Only covers query language not provisioning/infrastructure, no coverage for NoSQL databases, doesn’t address compute/storage/backup configuration, mixes application concerns with infrastructure.

Custom Schema

Description: Design database schema without reference to existing patterns.

Pros: Optimized for DCM needs, simpler initially

Cons: Reinventing patterns cloud providers and operators already solved, harder adoption, no external validation, incompatible with existing tooling and knowledge

Kubernetes Cluster Alternatives

Full install-config.yaml

Description: Using OpenShift’s complete install-config.yaml format as the catalog schema.

Pros: Comprehensive coverage of all OpenShift deployment options, official Red Hat format, well-documented

Cons: Platform-specific sections create complexity, includes infrastructure credentials and bootstrapping details inappropriate for catalog specifications, ties catalog to OpenShift installer API versions, verbose for users who just want node sizing

Cluster API (CAPI) Specification

Description: Adopting Kubernetes Cluster API CRDs as the standard for all cluster provisioning.

Pros: Kubernetes community standard, cloud-agnostic, supports multiple platforms

Cons: Still maturing as a standard, OpenShift has its own established patterns, CAPI abstractions don’t always align with OpenShift’s architecture, requires CAPI operator infrastructure

Managed OpenShift Service APIs

Description: Using cloud provider managed OpenShift APIs (ROSA for AWS, ARO for Azure) as the specification format.

Pros: Native to cloud providers, optimized for managed OpenShift services

Cons: Cloud-specific, incompatible with on-premise and self-managed OpenShift deployments, each provider has different API structure, doesn’t work with standard OpenShift IPI/UPI installations, prevents portability to vSphere or bare metal

Custom Cluster Schema

Description: Design a cluster schema without reference to existing standards or patterns.

Pros: Optimized for DCM requirements, simpler for current use cases

Cons: Ignores established OpenShift configuration patterns, harder for users familiar with install-config.yaml, no validation against industry knowledge, incompatible with existing automation and tooling

Infrastructure Needed

TBD