Skip to content

tkseal

Jump to bottom
liseli edited this page Sep 19, 2025 · 1 revision

Project Overview

tkseal_prototype is a Python 3.12 port of the Ruby tkseal CLI tool. TKSeal is a command-line utility for managing sealed secrets in Kubernetes environments using Grafana Tanka configuration repositories.

Original Ruby Project Analysis

The original tkseal provides these core commands:

  • tkseal diff PATH - Shows differences between plain_secrets.json and Kubernetes Opaque secrets
  • tkseal pull PATH - Extracts secrets from Kubernetes cluster to plain_secrets.json
  • tkseal seal PATH - Converts plain_secrets.json to sealed_secrets.json using kubeseal
  • tkseal ready - Checks if dependencies (kubectl, tk, kubeseal) are installed
  • tkseal version - Shows current version

Architecture Overview

CLI (Click) → SecretState → External Tools (kubectl, tk, kubeseal)
     ↓              ↓              ↓
   Diff        Secret/Secrets   TK Environment
     ↓              ↓              ↓
   Seal        JSON/YAML      Context/Namespace

Development Environment

  • Python Version: 3.12
  • Package Manager: pip with pyproject.toml (modern Python packaging)
  • CLI Framework: Click (replacing Ruby Thor)
  • Testing: pytest
  • Code Quality: ruff (linting), black (formatting), mypy (type checking)

Project Structure

tkseal_prototype/
├── pyproject.toml          # Project dependencies and build config
├── src/
│   └── tkseal/
│       ├── __init__.py
│       ├── cli.py          # Main CLI interface
│       ├── secret.py       # Secret management classes
│       ├── secret_state.py # SecretState coordination class
│       ├── tk.py          # Tanka integration
│       ├── kubectl.py     # kubectl wrapper
│       ├── kubeseal.py    # kubeseal wrapper
│       ├── seal.py        # Sealing functionality
│       ├── diff.py        # Diff functionality
│       └── version.py     # Version information
├── tests/                  # pytest test suite

Dependencies

External Tools (Required at Runtime)

Python Dependencies

  • click - CLI framework (replaces Ruby Thor)
  • pyyaml - YAML parsing (replaces Ruby yaml)
  • subprocess - External command execution (built-in)
  • pathlib - Path handling (built-in)
  • base64, json - Data processing (built-in)

Common Development Commands

# Setup development environment
python3.12 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

# Code quality
ruff check src/ tests/           # Linting
ruff format src/ tests/          # Formatting
mypy src/                        # Type checking

# Testing
pytest                           # Run all tests
pytest tests/test_cli.py         # Run specific test file
pytest -v                        # Verbose output
pytest --cov=tkseal              # Coverage report

# Build and install
pip install -e .                 # Editable install for development
python -m build                  # Build distribution packages

Implementation Guidelines

Ruby to Python Mapping

  • Thor CLI → Click CLI: Use Click's decorator pattern for commands
  • OpenStruct → SimpleNamespace or @dataclass: Use Python's structured data approaches
  • Forwardable → Property delegation: Use Python properties or explicit delegation
  • Diffy → difflib: Use Python's built-in diff functionality
  • Shell commands → subprocess: Use subprocess with proper error handling

Python 3.12 Features to Leverage

  • Type hints: Full type annotations including generics
  • Dataclasses: For structured data representation
  • Pathlib: Modern path handling
  • f-strings: String formatting
  • Context managers: Resource management
  • Exception groups: Better error handling (if needed)

Code Patterns

  • Use @dataclass for data containers (Secret, etc.)
  • Implement proper logging using Python's logging module
  • Use type hints throughout for better IDE support and runtime checking
  • Follow PEP 8 style guidelines
  • Use pathlib.Path instead of string manipulation for file paths
  • Implement proper error handling with custom exception classes

Testing Strategy

  • Port existing RSpec tests to pytest
  • Maintain test fixtures in tests/fixtures/
  • Use pytest parameterization for test variations
  • Mock external command executions for unit tests
  • Test CLI commands using Click's testing utilities

Key Files to Understand

When implementing features, refer to these Ruby files for behavior:

  • lib/tkseal/cli.rb:6-80 - Main CLI commands and flow
  • lib/tkseal/secret.rb:1-48 - Secret data structures and processing
  • lib/tkseal/seal.rb:1-38 - Sealing algorithm and SealedSecret generation
  • lib/tkseal/tk.rb:18-37 - Tanka environment parsing
  • lib/tkseal/secret_state.rb:1-23 - State coordination between files and cluster

Clone this wiki locally