workload-profile-controller 0.1.0__tar.gz

workload_profile_controller-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caue Tragante
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

workload_profile_controller-0.1.0/PKG-INFO

@@ -0,0 +1,500 @@
+Metadata-Version: 2.4
+Name: workload-profile-controller
+Version: 0.1.0
+Summary: Safe and configurable workload profile controller
+License-Expression: MIT
+Project-URL: Repository, https://github.com/lack0fcode/workload-profile-controller
+Project-URL: Issues, https://github.com/lack0fcode/workload-profile-controller/issues
+Keywords: proxmox,virtualization,workload,profiles,infrastructure,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: python-dotenv>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.12; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# Workload Profile Controller
+
+[![CI](https://github.com/lack0fcode/workload-profile-controller/actions/workflows/ci.yml/badge.svg)](https://github.com/lack0fcode/workload-profile-controller/actions/workflows/ci.yml)
+
+A safe and configurable workload profile controller for orchestrating mutually exclusive resource states across infrastructure backends.
+
+The project was designed around a simple problem: different workloads may compete for the same infrastructure resources, making manual switching between operational configurations error-prone.
+
+Instead of manually starting and stopping resources, the controller defines **profiles** describing the desired state of the infrastructure and performs deterministic, validated transitions between them.
+
+The first supported infrastructure backend is **Proxmox VE**.
+
+---
+
+## Overview
+
+A workload profile describes which resources must be running and which must be stopped.
+
+For example:
+
+```yaml
+profiles:
+  profile1:
+    description: "Normal operation"
+    running:
+      - monitoring
+      - application
+    stopped:
+      - compute
+
+  profile2:
+    description: "Compute workload"
+    running:
+      - compute
+    stopped:
+      - monitoring
+      - application
+```
+
+The controller can then transition between these profiles:
+
+```text
+                 Workload Profile Controller
+
+                         Profile
+                            │
+                            ▼
+                         Policy
+                            │
+                            ▼
+                    Transition Plan
+                            │
+                            ▼
+                       Controller
+                            │
+                            ▼
+                     Backend API
+                            │
+                            ▼
+                       Proxmox
+```
+
+The core logic is intentionally independent of Proxmox. Proxmox is implemented as a backend, allowing other infrastructure providers to be added in the future.
+
+---
+
+## Why?
+
+Manually switching infrastructure between different workload configurations can introduce dangerous situations.
+
+For example:
+
+* starting a resource before another resource has stopped;
+* assuming that a shutdown completed when it did not;
+* starting a workload while another conflicting workload is still running;
+* recovering automatically from an unexpected partial transition;
+* losing track of the actual infrastructure state.
+
+The controller therefore treats profile transitions as **stateful and deterministic operations**.
+
+A transition only proceeds when its preconditions are satisfied.
+
+If a transition fails after infrastructure changes have started, the controller enters a locked state rather than pretending that the desired profile was reached.
+
+---
+
+## Core principles
+
+The controller is designed around several safety invariants.
+
+### Validate before mutating
+
+The controller validates the current state and resolves the target resources before performing the first state-changing operation.
+
+### Stop before start
+
+When resources conflict between profiles, resources from the previous profile are stopped and confirmed stopped before new resources are started.
+
+### Confirm every operation
+
+After requesting a resource transition, the controller verifies its resulting state.
+
+### Never force-stop
+
+The controller does not use destructive forced shutdown operations.
+
+### Fail closed
+
+If a transition cannot be completed reliably, the controller enters a locked state instead of assuming success.
+
+### Reconcile is observational
+
+Reconciliation observes the infrastructure and determines which configured profile matches the current state.
+
+It does not automatically start or stop resources.
+
+### Exact resource resolution
+
+Backends must resolve configured resource identifiers deterministically.
+
+For the Proxmox backend, resource names are matched exactly. Ambiguous names are rejected rather than resolved arbitrarily.
+
+---
+
+## Profiles
+
+Profiles are completely configurable.
+
+A profile contains:
+
+* a name;
+* an optional description;
+* resources that must be running;
+* resources that must be stopped.
+
+Every configured resource must have exactly one state in every profile.
+
+For example:
+
+```yaml
+resources:
+  monitoring:
+    description: "Monitoring workload"
+
+  compute:
+    description: "Compute workload"
+
+  application:
+    description: "Application workload"
+```
+
+Profiles then describe the desired state of those resources.
+
+This separation between **resource identity** and **infrastructure-specific identifiers** allows the same profile model to remain independent of the underlying provider.
+
+---
+
+## Supported backend
+
+### Proxmox VE
+
+The current backend supports:
+
+* QEMU virtual machines;
+* LXC containers;
+* Proxmox API authentication using API tokens;
+* TLS certificate verification;
+* configurable TLS server names;
+* resource discovery;
+* exact resource-name resolution;
+* start and stop operations;
+* asynchronous task monitoring;
+* shutdown timeouts.
+
+The core controller does not need to know whether a resource is a QEMU VM or an LXC container.
+
+That information remains inside the Proxmox backend.
+
+---
+
+## Installation
+
+Clone the repository and create a virtual environment:
+
+```bash
+git clone https://github.com/lack0fcode/workload-profile-controller.git
+cd workload-profile-controller
+
+python -m venv .venv
+```
+
+Activate the virtual environment and install the project with its development dependencies:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+The CLI is then available as:
+
+```bash
+wpc
+```
+
+Check the installation:
+
+```bash
+wpc --help
+```
+
+---
+
+## Configuration
+
+The controller uses a YAML configuration file to define resources and profiles.
+
+An example configuration is available at:
+
+```text
+config/examples/config.example.yaml
+```
+
+Backend-specific connection settings are kept separately from the profile configuration.
+
+For the Proxmox backend, credentials and connection parameters are provided through environment variables.
+
+Secrets should never be committed to the repository.
+
+See:
+
+* [CONFIGURATION.md](config/CONFIGURATION.md)
+* [SECURITY.md](SECURITY.md)
+
+for details.
+
+---
+
+## CLI
+
+The current CLI provides four main operations.
+
+### List profiles
+
+```bash
+wpc --config config.yaml profiles
+```
+
+Lists the profiles defined in the configuration.
+
+### Show status
+
+```bash
+wpc --config config.yaml status
+```
+
+Shows the current state of configured resources.
+
+### Plan a transition
+
+```bash
+wpc --config config.yaml plan profile2
+```
+
+Builds and displays the transition plan without changing infrastructure.
+
+### Perform a transition
+
+```bash
+wpc --config config.yaml transition profile2
+```
+
+Executes the transition to the selected profile.
+
+---
+
+## Safety model
+
+A simplified transition looks like this:
+
+```text
+Current Profile
+      │
+      ▼
+Validate current state
+      │
+      ▼
+Resolve target resources
+      │
+      ▼
+Build transition plan
+      │
+      ▼
+Stop conflicting resources
+      │
+      ▼
+Confirm stopped
+      │
+      ▼
+Start target resources
+      │
+      ▼
+Confirm running
+      │
+      ▼
+Validate complete target profile
+      │
+      ▼
+Transition complete
+```
+
+If an operation fails after the transition has started:
+
+```text
+Transition
+    │
+    ├── success ───────► target profile
+    │
+    └── failure ───────► LOCKED
+```
+
+The locked state prevents subsequent transitions from proceeding until the situation has been explicitly investigated.
+
+---
+
+## Architecture
+
+The project separates infrastructure-independent policy from backend-specific operations.
+
+```text
+Configuration
+      │
+      ▼
+    Policy
+      │
+      ▼
+TransitionPlan
+      │
+      ▼
+  Controller
+      │
+      ▼
+   Backend
+      │
+      ├──────── Proxmox
+      │
+      ├──────── AWS       (future)
+      │
+      └──────── GCP       (future)
+```
+
+The main components are:
+
+### Configuration
+
+Loads and validates resources and profiles.
+
+### Policy
+
+Determines what must change between two profiles and generates a deterministic transition plan.
+
+### Controller
+
+Enforces the safety rules and executes the transition through the backend interface.
+
+### Backend
+
+Provides an infrastructure-independent interface for querying, starting and stopping resources.
+
+### Proxmox backend
+
+Implements the backend interface using the Proxmox API and handles provider-specific resource discovery, resolution and asynchronous tasks.
+
+More details are available in [ARCHITECTURE.md](ARCHITECTURE.md).
+
+---
+
+## Development
+
+Install the development dependencies:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+Run Ruff:
+
+```bash
+ruff check src tests
+```
+
+The project is developed with a strong emphasis on deterministic behavior and testable state transitions.
+
+---
+
+## Project status
+
+The project is currently in active development.
+
+The Proxmox backend and core profile transition logic are functional and covered by automated tests.
+
+Current priorities include:
+
+* strengthening configuration and safety validation;
+* improving the CLI;
+* expanding integration testing;
+* adding additional backend implementations;
+* developing a WebUI for profile management and operational visibility;
+* establishing the packaging and release workflow.
+
+---
+
+## Roadmap
+
+### Core
+
+* [x] Configurable resources
+* [x] Configurable profiles
+* [x] Profile validation
+* [x] Deterministic transition plans
+* [x] Backend abstraction
+* [x] Proxmox backend
+* [x] QEMU support
+* [x] LXC support
+* [x] Resource discovery
+* [x] Exact resource resolution
+* [x] Asynchronous task monitoring
+* [x] Transition locking
+* [x] Reconciliation
+
+### CLI
+
+* [x] Profile listing
+* [x] Resource status
+* [x] Transition plan
+* [x] Profile transitions
+
+### Documentation
+
+* [x] Configuration guide
+* [x] Architecture documentation
+* [x] Security documentation
+* [x] Contribution guide
+
+### Future
+
+* [ ] WebUI
+* [ ] Additional infrastructure backends
+* [ ] Integration test environment
+* [ ] Improved transition diagnostics
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+See [LICENSE](LICENSE) for the full license text.
+
+---
+
+## Contributing
+
+Contributions, bug reports and architectural discussions are welcome.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.