Metadata-Version: 2.4
Name: in-cluster-checks
Version: 0.1.4
Summary: Generic framework for running health validation rules on OpenShift cluster nodes
Author-email: Shoshana Prizend <sprizend@redhat.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/sprizend-rh/in-cluster-checks
Project-URL: Repository, https://github.com/sprizend-rh/in-cluster-checks
Project-URL: Issues, https://github.com/sprizend-rh/in-cluster-checks/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openshift-client>=1.0.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: black>=24.1.1; extra == "dev"
Requires-Dist: flake8>=7.0.0; extra == "dev"
Requires-Dist: isort>=5.13.2; extra == "dev"
Dynamic: license-file

# In-Cluster Checks

[![CI](https://github.com/sprizend-rh/in-cluster-checks/workflows/CI/badge.svg)](https://github.com/sprizend-rh/in-cluster-checks/actions)
[![codecov](https://codecov.io/gh/sprizend-rh/in-cluster-checks/branch/main/graph/badge.svg)](https://codecov.io/gh/sprizend-rh/in-cluster-checks)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

A generic framework for running health validation rules directly on OpenShift cluster nodes using `oc debug`.

## Overview

This framework provides infrastructure for:
- Running validation rules on cluster nodes via `oc debug`
- Parallel execution of rules across multiple nodes
- Secret filtering and output formatting
- Prerequisite checking and domain orchestration
- Insights-compatible JSON output

Originally developed as part of Red Hat's Pendrive project, this framework has been extracted as open-source to benefit the broader OpenShift community.

## Features

- **Generic validation framework**: Base classes for creating custom health check rules
- **OpenShift integration**: Direct node access via `oc debug` with persistent connections
- **Domain organization**: Group related rules into domains (hardware, network, linux, storage)
- **Parallel execution**: Run rules concurrently across multiple nodes
- **Secret filtering**: Automatic redaction of sensitive data from outputs
- **Extensible**: Easy to add new rules and domains

## Installation

```bash
pip install in-cluster-checks
```

## Quick Start

First, ensure you're logged into your OpenShift cluster:

```bash
oc login https://api.your-cluster.com:6443
```

Then run the checks:

```bash
# Run all checks (output saved to ./cluster-checks.json)
in-cluster-checks --output ./cluster-checks.json

# Run with debug logging
in-cluster-checks --log-level DEBUG

# Debug a specific rule (disables secret filtering)
in-cluster-checks --debug-rule "check_disk_usage"

# List available domains
in-cluster-checks --list-domains

# List all available rules
in-cluster-checks --list-rules
```

## Programmatic Usage

You can also use the framework programmatically in your Python code:

```python
from in_cluster_checks.runner import InClusterCheckRunner
from pathlib import Path

# Create runner with default configuration
runner = InClusterCheckRunner()

# Or customize configuration
runner = InClusterCheckRunner(
    max_workers=75,           # Maximum concurrent workers (default: 50)
    debug_rule_flag=False,    # Enable debug mode (default: False)
    debug_rule_name="",       # Specific rule to debug (default: "")
)

# Run checks and save results
output_path = Path("./results/cluster-checks.json")
runner.run(output_path=output_path)
```

### Configuration Options

- **max_workers** (int, default: 50): Maximum number of concurrent workers for parallel execution
- **debug_rule_flag** (bool, default: False): Enable debug mode with verbose output
- **debug_rule_name** (str, default: ""): Name of specific rule to run in debug mode

**Note:** When debug mode is enabled:
- Only the specified rule runs
- Secret filtering is automatically disabled
- JSON output is disabled (real-time console output only)
- Detailed command execution logs are printed

## Architecture

### Core Components

- **Rule**: Base class for validation rules
- **RuleDomain**: Orchestrator for groups of related rules
- **Operator**: Command execution abstraction
- **NodeExecutor**: Execute commands on cluster nodes via `oc debug`
- **LoggerInterface**: Pluggable logging abstraction

### Built-in Domains

- **Hardware**: Disk usage, memory, CPU, temperature validation
- **Network**: OVS, DNS, bonding checks
- **Linux**: Systemd, SELinux, clock synchronization
- **Storage**: Storage validation rules
- **Hardware/Firmware Details**: Informational collectors for hardware inventory

## Creating Custom Rules

```python
from in_cluster_checks.core.rule import Rule
from in_cluster_checks.core.rule_result import RuleResult
from in_cluster_checks.utils.enums import Status, Objectives

class MyCustomRule(Rule):
    """Example custom validation rule."""

    objective_hosts = [Objectives.ALL_NODES]

    def set_document(self):
        self.unique_name = "my_custom_rule"
        self.title = "My Custom Validation Rule"

    def run_rule(self):
        # Run validation logic
        return_code, stdout, stderr = self.run_cmd("my-command")

        if return_code == 0:
            return RuleResult.passed("Validation passed")
        else:
            return RuleResult.failed(f"Validation failed: {stderr}")
```

## Requirements

- Python 3.9+
- OpenShift CLI (`oc`) installed and configured
- Access to OpenShift cluster

## Development

```bash
# Clone repository
git clone https://github.com/sprizend-rh/in-cluster-checks.git
cd in-cluster-checks

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run pre-commit checks
pre-commit run --all-files
```

## License

GNU General Public License v3.0 or later

See [LICENSE](LICENSE) for full text.

## Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

## Related Projects

- **Pendrive**: Red Hat's on-premise Insights validation tool (internal)
- **OpenShift**: Container orchestration platform

## Acknowledgments

This framework was extracted from Red Hat's Pendrive project. The core validation infrastructure is generic and contains no confidential logic, making it suitable for open-source release to benefit the wider OpenShift community.
