OpenFactoryCluster#

OpenFactory Cluster Manager.

This module provides the OpenFactoryCluster class, which manages the lifecycle of an OpenFactory Docker Swarm cluster, including manager and worker nodes.

Core responsibilities:

  • Validate the current host as a Swarm manager and part of a Docker Swarm cluster

  • Provision manager and worker nodes from YAML configuration files

  • Add labels to nodes for identification and role assignment

  • Remove worker nodes from the cluster safely

  • Map node IPs to Docker Swarm node IDs for orchestration

  • Notify users of operational outcomes, warnings, and failures

Key integrations:

  • Docker API for managing Swarm nodes and containers

  • SSH access to remote nodes for initial provisioning

  • OpenFactory YAML infrastructure schemas for configuration

  • User notifications to report success, warnings, and errors

Usage Example:
from openfactory import OpenFactoryCluster

cluster = OpenFactoryCluster()

# Provision managers and workers from config file
cluster.create_infrastack_from_config_file("infra.yaml")

# Remove workers safely
cluster.remove_infrastack_from_config_file("infra.yaml")
Error handling:

  • Raises OFAException if the local host is not part of a Swarm or is not a manager

  • Catches Docker API errors and SSH connection issues during node creation

  • Skips already provisioned nodes without interrupting the orchestration

Important

User requires Docker access on all nodes of the OpenFactory cluster and ssh access to all nodes using the config.OPENFACTORY_USER.

class openfactory.openfactory_cluster.OpenFactoryCluster[source]#

Bases: object

OpenFactory Cluster Manager.

Allows to manage the OpenFactory cluster.

Important

User requires Docker access on all nodes of the OpenFactory cluster and ssh access to all nodes using the config.OPENFACTORY_USER.

__init__()[source]#

Initialize the OpenFactoryCluster instance.

Performs a check to ensure the current Docker host is part of a Swarm and is a Swarm Manager. This is required for cluster management operations.

Raises:

OFAException – If the Docker host is not part of a Swarm, is not a manager, or if the Swarm status cannot be verified.

add_label(node_name, node_details)[source]#

Adds labels to a Docker node based on its IP address.

Looks for a node in the Docker Swarm cluster whose IP address matches the given node_details. If found, it updates the node’s labels by adding a ‘name’ label and merging any additional labels specified in node_details.

Return type:

None

Parameters:

  • node_name (str) – The name to assign as a label to the Docker node.

  • node_details (Dict) – Dictionary with required ‘ip’ and optional ‘labels’ keys.

Example

self.add_label("node-3", {"ip": "10.0.0.5", "labels": {"plant": "Plant-A", "role": "stream-apps"}})
create_infrastack_from_config_file(stack_config_file)[source]#

Spins up an infrastructure stack based on the provided configuration file.

Reads a YAML configuration file that defines the infrastructure, including manager and worker nodes, and provisions them using Docker Swarm.

Return type:

None

Parameters:

stack_config_file (str) – Path to the YAML configuration file describing the infrastructure stack.

create_managers(managers)[source]#

Creates Docker Swarm manager nodes from a given configuration.

For each manager node in the input dictionary, connects via SSH, checks swarm membership, joins as a manager if needed, applies labels, and reports success or failure.

Return type:

None

Parameters:

managers (Dict) – Dictionary with manager names as keys and values as dicts with required ‘ip’ and optional ‘labels’.

Example

managers = {
    "manager1": {"ip": "10.0.0.10", "labels": {"role": "primary"}},
    "manager2": {"ip": "10.0.0.11"}
}
self.create_managers(managers)
create_workers(workers)[source]#

Creates Docker Swarm worker nodes from a given configuration.

Connects via SSH to each worker node, checks swarm membership, joins if needed, and applies labels.

Return type:

None

Parameters:

workers (Dict) – Dictionary with worker names as keys and values as dicts with required ‘ip’ and optional ‘labels’.

Example

workers = {
    "worker1": {"ip": "10.0.0.20", "labels": {"role": "compute"}},
    "worker2": {"ip": "10.0.0.21"}
}
self.create_workers(workers)
remove_infrastack_from_config_file(stack_config_file)[source]#

Tears down an infrastructure stack based on a configuration file.

This function reads a YAML file describing the infrastructure stack, identifies existing nodes in the Docker Swarm cluster by their IPs, and removes the worker nodes accordingly.

Return type:

None

Parameters:

stack_config_file (str) – Path to the YAML configuration file describing the infrastructure stack.

remove_workers(workers, node_ip_map)[source]#

Removes worker nodes from the Docker Swarm cluster.

Drains each worker node, connects remotely to remove it from the Swarm, and removes the node from the cluster manager.

Return type:

None

Parameters:

  • workers (Dict) – Dictionary with worker names as keys and values containing node details with required ‘ip’.

  • node_ip_map (Dict) – Mapping from node IP addresses to Docker node IDs.

Example

workers = {
    "worker1": {"ip": "10.0.0.20"},
    "worker2": {"ip": "10.0.0.21"}
}
node_ip_map = {
    "10.0.0.20": "node_id_123",
    "10.0.0.21": "node_id_456"
}
self.remove_workers(workers, node_ip_map)