# 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):**
    ```bash
    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.
    ```bash
    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`.
    ```bash
    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.
    ```bash
    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`.
    ```bash
    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:
        ```bash
        # 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:
        ```bash
        # 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:
    ```bash
    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`):

```bash
# 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:

```bash
# 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:

```bash
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](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. 