How openshift/assisted-service works
Main Components
• Assisted Service Core: This is the heart of the system. It offers both a REST API (with swagger-generated code under the “restapi” directory) and the operator mode via CRDs and related controllers (see “config/crd” and “deploy/operator”).
• Business Logic and Domain Modules: Under “internal” you see modules for cluster management, host management, state machines (under “cmd/graphstatemachine”), networking, DNS, ISO/image generation (internal/ignition, pkg/generator), migrations, validations, and more.
• Client Libraries: The “client” folder contains autogenerated and hand-written clients for different API endpoints (installer, events, managed domains, manifests, operators, etc.). These clients are used by both the UI (in a separate repository) and possibly CLI tools.
• API Layer & Webhooks: The “pkg/webhooks” subdirectories (for agentinstall and hiveextension) indicate dynamic admission control/webhook functionality used when running as an operator or within a Kubernetes environment.
• External Integrations: The project relies on several external components:
– Database (PostgreSQL in deploy/postgres)
– Object storage (S3/MinIO in deploy/s3)
– Monitoring components such as Prometheus and Grafana (deploy/monitoring)
– Possibly external identity providers (see “pkg/auth”).
• Auxiliary Tools: Under “cmd” there are various executables like the agent-based installer, operator, and web admission entry points; and under “tools” scripts for deployments, migrations, and debugging.
Relationships and Data Flows
• Client (UI/CLI) initiates cluster creation by calling the Assisted Service via its REST API.
• The Service processes the request using internal packages for cluster and host management. It uses state machines (see “cmd/graphstatemachine”) to handle state transitions during discovery and installation.
• Once a cluster is defined, the service triggers the ISO generation (via components in “internal/ignition” and “pkg/generator”), caches installation binaries (in “internal/installercache”), and uploads images to S3.
• Concurrently, agent processes (running on booted hosts) use the API (and the webhook endpoints) to report inventory, connectivity, and validation details.
• The system writes state to a PostgreSQL database (“deploy/postgres” files) and may use additional persistent storage.
• Monitoring and logging components (see “deploy/monitoring” and “pkg/log”) are used for observability.
• The entire service can be deployed either as containers on a local host (refer to “deploy/podman”) or on Kubernetes/OpenShift clusters using provided manifests.
Important Architectural Patterns and Design Principles
• Layered Architecture: Separation between API (REST/Operator), business logic (internal packages), and infrastructure (database, storage, deployment manifests).
• State Machines: The use of state machines for processing cluster and host transitions (as shown by the “cmd/graphstatemachine” components) is central.
• Modularization and Code Generation: A separation between generated code (API definitions, swagger, CRDs) and hand-written business logic.
• Deployment Flexibility: The project supports multiple deployment targets (k8s, OpenShift, local containers) via specific manifests under “deploy” and build scripts in Makefile and CI scripts.