OpenFactory Applications Schemas#

This module defines Pydantic models and utility functions to parse, validate, and enrich application configuration files in OpenFactory. Application definitions include Docker image info, environment variables, optional UNS metadata, storage backends, Prometheus metrics endpoints, and container networks.

This module is used by OpenFactory deployment tools and runtime components to ensure application configurations are consistent, valid, and semantically enriched.

Key Components#

  • OpenFactoryAppSchema: Defines a single application including its UUID, Docker image, image pull policy, environment variables, UNS metadata, named storage backend, Prometheus metrics endpoint and container networks.

  • OpenFactoryAppsConfig: Validates a dictionary of application entries and ensures correct schema structure.

  • get_apps_from_config_file(): Loads, validates, and enriches applications from a YAML file with UNS metadata.

Features#

  • Supports UNS (Unified Namespace) enrichment through the AttachUNSMixin.

  • Restricts configuration fields with extra=”forbid” to ensure strict schema conformance.

  • Supports configurable image pull policies:

    • missing: Pull the image only if it is not available locally.

    • always: Always pull the image before deployment.

  • Supports multiple named storage backends, including:

    • LocalBackend: Bind-mount a local host directory into containers (for development).

    • NFSBackend: Mount an NFS share into containers with configurable mount options.

  • Supports connecting containers to multiple Docker networks.

  • Supports application exposure via Traefik using host-based routing. Routing configuration allows defining an internal port and optional hostname. Canonical and optional alias hostnames are generated automatically.

  • Supports Prometheus metrics endpoint configuration. Applications may expose metrics on a configurable port and path.

  • Provides utilities to load application configs from YAML with user-friendly error handling and notifications.

  • Ensures validated and enriched applications are returned as plain dictionaries.

Usage#

Use get_apps_from_config_file() to load and validate an application configuration YAML file, with automatic UNS enrichment.

YAML Example

apps:
  scheduler:
    uuid: "app-scheduler"
    image: ghcr.io/openfactoryio/scheduler:v1.0.0
    image_pull_policy: missing
    runtime_uid: 1234
    runtime_gid: 5678

    uns:
      location: building-a
      workcenter: scheduler

    environment:
     - ENV=production

    storage:
      data:
        type: nfs
        server: deskfab.openfactory.com
        remote_path: /nfs/deskfab
        mount_point: /mnt
        mount_options:
          - ro
      cache:
        type: local
        local_path: ./cache
        mount_point: /cache

    routing:
      expose: true
      port: 8000
      hostname: dashboard

    metrics:
      port: 4000
      path: /metrics

    networks:
      - factory-net
      - monitoring-net

    deploy:
      replicas: 2

      resources:
        reservations:
          cpus: 0.5
          memory: "512Mi"
        limits:
          cpus: 1.0
          memory: "1Gi"

      placement:
          constraints:
          - node.labels.zone == building-a

Note

  • Networks: All network names must exist in Docker before deployment.

  • UNS metadata: Must match the UNSSchema used in the environment for semantic consistency.

  • Storage backends: Will be extended in future to support more types.

  • Routing: Hostnames are normalized and validated to comply with DNS constraints.

  • Metrics: Applications may optionally expose Prometheus metrics using the metrics section. Metrics endpoints are automatically registered with OpenFactory for monitoring during deployment.

  • Use the apps_dict property to access validated apps in runtime code.

See also

The runtime class of OpenFactory Apps is openfactory.apps.ofaapp.OpenFactoryApp.

class openfactory.schemas.apps.Metrics(**data)[source]#

Bases: BaseModel

Prometheus metrics endpoint exposed by an application.

This schema defines where Prometheus metrics can be retrieved from a running application.

YAML example

metrics:
    port: 4000
    path: /metrics
model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

path: str#
port: int#
class openfactory.schemas.apps.OpenFactoryAppSchema(**data)[source]#

Bases: AttachUNSMixin, BaseModel

OpenFactory Application Schema.

Defines a deployable OpenFactory application including container image information, runtime settings, storage backends, routing configuration, Prometheus metrics exposure, network attachments, and deployment constraints.

deploy: Deploy | None#
environment: List[str] | None#
image: str#
image_pull_policy: Literal['missing', 'always']#
metrics: Metrics | None#
model_config = {'extra': 'forbid', 'validate_assignment': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

networks: List[str] | None#
routing: Routing | None#
runtime_gid: int | None#
runtime_uid: int | None#
storage: Dict[str, Annotated[NFSBackendConfig | LocalBackendConfig, FieldInfo(annotation=NoneType, required=True, description='Discriminator field to select the correct storage backend schema', discriminator='type')]] | None#
uns: Dict[str, Any] | None#
uuid: str#
classmethod validate_networks(v)[source]#
validate_runtime_user()[source]#
classmethod validate_storage_names(v)[source]#
class openfactory.schemas.apps.OpenFactoryAppsConfig(**data)[source]#

Bases: BaseModel

Schema for OpenFactory application configurations loaded from YAML files.

This schema validates the structure of application configuration data.

Usage example

apps_config = OpenFactoryAppsConfig(apps=yaml_data['apps'])
# or
apps_config = OpenFactoryAppsConfig(**yaml_data)
Parameters:

apps (dict) – Dictionary containing application configurations.

Raises:

pydantic.ValidationError – If the input data does not conform to the expected schema.

apps: Dict[str, OpenFactoryAppSchema]#
property apps_dict#

Dictionary with all configured OpenFactory applications.

model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class openfactory.schemas.apps.Routing(**data)[source]#

Bases: BaseModel

Routing configuration for exposing an OpenFactory application via Traefik.

This schema defines whether an application should be exposed externally, which internal port should be used, and optionally a desired hostname.

During enrichment, canonical and optional alias hostnames are generated based on the application name, UUID, and base domain.

Raises:

RoutingError – If generated hostname labels exceed DNS limits.

YAML example

routing:
    expose: true
    port: 8000
    hostname: dashboard
alias_hostname: str | None#
build_hostnames(app_uuid, base_domain)[source]#

Generate canonical and optional alias hostnames for the application.

The canonical hostname is always generated using the App UUID.

The alias hostname is optional and derived from the user-provided hostname field if present.

All hostnames are normalized to be DNS-compliant: - lowercase - invalid characters replaced - maximum label length enforced (63 characters)

Return type:

None

Parameters:

  • app_uuid (str) – Unique identifier of the application.

  • base_domain (str) – Base domain used for hostname generation.

Raises:

RoutingError – If generated hostname labels exceed DNS limits.

canonical_hostname: str | None#
expose: bool#
hostname: str | None#
model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

port: int | None#
exception openfactory.schemas.apps.RoutingError[source]#

Bases: ValueError

Raised when routing configuration is invalid.

openfactory.schemas.apps.get_apps_from_config_file(apps_yaml_config_file, uns_schema)[source]#

Load, validate, and enrich OpenFactory application configurations from a YAML file using UNS metadata.

This function reads a YAML file containing OpenFactory application definitions, validates its content using the OpenFactoryAppsConfig Pydantic model, and augments each validated application entry with Unified Namespace (UNS) metadata derived from the provided schema.

Return type:

Optional[Dict[str, OpenFactoryAppSchema]]

Parameters:

  • apps_yaml_config_file (str) – Path to the YAML file defining application configurations.

  • uns_schema (UNSSchema) – Schema instance used to extract and validate UNS metadata for each application.

Returns:

Optional[Dict[str, OpenFactoryAppSchema]] – A dictionary of validated and enriched application configurations, or None if validation fails.

Note

In case of validation errors, user notifications will be triggered and None will be returned.

openfactory.schemas.apps.normalize_name(value)[source]#

Normalize a string to be DNS-compatible.

This function transforms an arbitrary string into a valid DNS label by: - converting to lowercase - replacing underscores with hyphens - replacing invalid characters with hyphens - collapsing consecutive hyphens - stripping leading and trailing hyphens

Return type:

str

Parameters:

value (str) – Input string to normalize.

Returns:

str – Normalized string suitable for use in DNS labels.

Note

This function does not enforce DNS length constraints (e.g. 63 characters per label). Length validation must be handled by the caller.