k4s 0.0.1a1

Infrastructure installer for Kubernetes and data platforms

k4s CLI Tool

A CLI tool for managing installations and Kubernetes operations.

Project Structure

• src/k4s: Main package code.
• k4s.yml: Optional configuration file for component operations (install/certs).
• tests/: Tests.

Development Setup

1. Clone the repository (if you haven't already):

   git clone <repository_url>
   cd k4s
   

2. Create and activate a virtual environment: It's highly recommended to use a virtual environment to manage project dependencies.

   python3 -m venv .venv
   source .venv/bin/activate
   

   (On Windows, use .venv\Scripts\activate)

3. Install dependencies: Install the required Python packages, including development tools like pytest.

   python3 -m pip install -r requirements.txt
   

4. Install the CLI in editable mode: This allows you to run the k4s (and k4) command from your terminal and have your code changes immediately reflected without reinstalling.

   python3 -m pip install -e .
   

   After this step, you should be able to run k4s --help or k4 --help from your terminal (while the virtual environment is active).

5. Running Tests: Tests are located in the tests/ directory and can be run using pytest.

   python3 -m pytest
   

   (Ensure you are in the project root directory where pytest.ini is located).

   • Running Specific Tests: You can run tests in a specific file, or even a specific test function:

     # Run all tests in a specific file
     python3 -m pytest tests/core/test_downloader.py
     
     # Run a specific test function within a file
     python3 -m pytest tests/core/test_downloader.py::test_download_file_success_with_specific_filename
     
     # Run tests containing a specific keyword in their name
     python3 -m pytest -k "downloader"
     

   • Viewing Print Statements and Live Logs During Tests: By default, pytest captures output. To see print() statements or live logging from your tests:

     # Show standard output (print statements) and disable output capturing
     python3 -m pytest -s
     
     # Show logs at a specific level (e.g., INFO or DEBUG)
     python3 -m pytest --log-cli-level=INFO
     python3 -m pytest --log-cli-level=DEBUG
     
     # Combine them to see print statements and detailed logs for a specific test file
     python3 -m pytest -s --log-cli-level=DEBUG tests/core/test_downloader.py
     

Usage

Once installed in editable mode (or as a package), you can use k4s or its alias k4.

• Some commands (e.g. install, certs) use a k4s.yml configuration file. You can specify a path using the global --config option:

  k4s --config path/to/your/custom_k4s.yml install <component_name>
  # or using the alias
  k4 --config path/to/your/custom_k4s.yml install <component_name>
  

• Commands like context and cluster do not require k4s.yml.

Verbosity

• -q/--quiet: only final results and errors
• default: concise step output
• -v: adds explanations (with optional typing effect)
• -vv: debug output (more details)

Typing effect can be toggled with --typing/--no-typing.

Contexts (SSH targets)

Create and manage connection contexts (stored under ~/.k4s/contexts.yml):

# interactive wizard
k4s init

# or explicit flags
k4s context add prod -h 10.0.0.10 -u root -i ~/.ssh/id_rsa --current

# list / switch / test
k4s context list
k4s context use prod
k4s context test

Kubernetes clusters (RKE2)

Create an RKE2 cluster using node contexts:

# preflight only (recommended)
k4s cluster preflight \
  --control-plane cp1 \
  --worker w1

# plan only
k4s cluster create --name lab --type rke2 \
  --control-plane cp1 \
  --worker w1 \
  --cni canal \
  --dry-run

# apply (installs rke2 on the nodes)
k4s cluster create --name lab --type rke2 \
  --control-plane cp1 \
  --worker w1 \
  --cni canal

Fetch kubeconfig from the control-plane:

k4s cluster kubeconfig --name lab --control-plane cp1

Supported platforms (current)

This project is early and currently targets Linux servers with systemd.

• Kubernetes (RKE2):
  • Required: Linux + systemd, SSH access, curl, root or sudo -n
  • Tested: Ubuntu/Debian-family hosts (best-effort for other systemd distros)
• Local machine (running k4s):
  • macOS/Linux supported for running the CLI (requires Python 3.12+)

Use k4s cluster preflight to see what each node reports (OS, kernel, systemd, curl, sudo).

Components (install/certs)

Example installing a component (requires k4s.yml present or --config is used): bash k4s install my_component_1 k4 install my_component_2

Certificate Management

k4s provides certificate operations using the k4s certs command group.

• k4s certs apply: Applies the uploaded certificates, setting paths, permissions, and running notification handlers (e.g., reloading a service).
• k4s certs apply: Applies a certificate configuration using the selected issuer defined in k4s.yml.

This functionality can be controlled declaratively via a certificates section in your k4s.yml or imperatively using command-line flags.

Publishing to PyPI

See docs/pypi-publish.md for build and upload steps.

TODO

• Add detailed usage instructions for each command.
• Describe configuration options in k4s.yml in more detail.