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, 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, environment variables, UNS metadata, storage backend, 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 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.
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

    uns:
      location: building-a
      workcenter: scheduler

    environment:
     - ENV=production

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

    routing:
      expose: true
      port: 8000
      hostname: dashboard

    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.
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.OpenFactoryAppSchema(**data)[source]#

Bases: AttachUNSMixin, BaseModel

OpenFactory Application Schema.

deploy: Deploy | None#

environment: List[str] | None#

image: str#

model_config = {'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

networks: List[str] | None#

routing: Routing | None#

storage: 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]#

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_name, app_uuid, base_domain)[source]#

Generate canonical and optional alias hostnames for the application.

The canonical hostname is always generated and guarantees uniqueness by combining the normalized application name with a short UUID suffix.

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_name (str) – Name of the application (key in config).
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.