Placement Controller

Rudimentary Placement Controller for Decentralized Control Plane

• Installation
• Package
• Docker
• Helm chart
• Release
• GitHub Actions
• Act

• Collaboration guidelines

Table of Contents

• Placement Controller
  • Table of Contents
  • Prerequisites
    • Development
    • Deployment
  • Development
  • Docker
  • Manual build and deployment on minikube
  • Package
  • Helm chart
  • Release
  • Helm Chart Versioning
  • GitHub Actions
  • Act
  • Collaboration guidelines

Prerequisites

Development

• Python 3.13 - The project requires Python 3.13 or higher
• uv - Fast Python package installer and resolver
• docker
• Helm
• minikube
• Act

Deployment

• Github Actions - repository use Github Actions to automate the build, test, release and deployment processes. For your convinience we recommend to fill necessary secrets in the repository settings.

Development

1. Install uv if you don't have it:

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

2. Install dependencies:

uv sync --locked --all-extras --dev

3. Install pre-commit hooks:

uv run pre-commit install

4. Launch the project:

uv run python -m placement_controller.main --config ./etc/config.yaml

5. Running tests:

uv run pytest

6. Running style checks:

uv run mypy ./src
uv run isort ./src --check --diff
uv run flake8 ./src
uv run black ./src --check --diff

Docker

Build a Docker image and run a container:

docker build . -t <image_name>:<image_tag>
docker run <image_name>:<image_tag>

Upload the Docker image to the repository:

docker login -u <username>
docker push <image_name>:<image_tag>

Manual build and deployment on minikube

1. Install minikube.
2. Start minikube:

minikube start

3. Build a docker image:

docker build . -t <image_name>:<image_tag>

4. Upload the docker image to minikube:

minikube image load <image_name>:<image_tag>

5. Deploy the service:

helm upgrade --install <app_name> ./charts/app --set image.repository=<image_name> --set image.tag=latest --version 0.1.0

Package

To build and publish a package on pypi.org, execute the following commands:

# Build the package
uv build

# Publish to PyPI (requires PyPI token to be set)
uv publish --token <pypi_token>

pypi_token - API token for authentication on PyPI.

Helm chart

Authenticate your Helm client in the container registry:

helm registry login <container_registry> -u <username>

Create a Helm chart:

helm package charts/<chart_name>

Push the Helm chart to container registry:

helm push <helm_chart_package> <container_registry>

Deploy the Helm chart:

helm repo add <repo_name> <repo_url>
helm repo update <repo_name>
helm upgrade --install <release_name> <repo_name>/<chart_name>

Release

To create a release, add a tag in GIT with the format a.a.a, where 'a' is an integer.

git tag 0.1.0
git push origin 0.1.0

The release version for branches, pull requests, and other tags will be generated based on the last tag of the form a.a.a.

Helm Chart Versioning

The Helm chart version changed automatically when a new release is created. The version of the Helm chart is equal to the version of the release.

GitHub Actions

GitHub Actions triggers testing, builds, and application publishing for each release.

The process of building and publishing differs for web services and libraries.

Service

The default build and publish process is configured for a web application (.github\workflows\service.yaml). During this process, a Docker image is built, a Helm chart is created, an openapi.yaml is generated, and the web service is deployed to a Kubernetes cluster.

Act

Act allows you to run your GitHub Actions locally (e.g., for developing tests)

Usage example:

act push -j deploy --secret-file my.secrets

Collaboration guidelines

HIRO uses and requires from its partners GitFlow with Forks