nebula-config-kit 0.0.1__tar.gz

nebula_config_kit-0.0.1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: nebula-config-kit
+Version: 0.0.1
+Summary: Define your Nebula mesh network once, generate validated configs for every host
+Keywords: nebula,vpn,mesh-network,overlay-network,network-automation,configuration-management,infrastructure,pki
+Author: Dmitry Tatarkin
+Author-email: Dmitry Tatarkin <tatarkin@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Classifier: Environment :: Console
+Classifier: Framework :: Pydantic :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pki-kit>=0.0.2
+Requires-Dist: pydantic>=2.0
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer>=0.15 ; extra == 'cli'
+Requires-Dist: rich>=13.0 ; extra == 'cli'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/dtatarkin/nebula-config-kit
+Project-URL: Repository, https://github.com/dtatarkin/nebula-config-kit
+Project-URL: Issues, https://github.com/dtatarkin/nebula-config-kit/issues
+Project-URL: Changelog, https://github.com/dtatarkin/nebula-config-kit/releases
+Provides-Extra: cli
+Description-Content-Type: text/markdown
+
+# nebula-config-kit
+
+**Stop hand-crafting Nebula configs. Define your mesh network once, generate configs for every host.**
+
+nebula-config-kit is a Python library and CLI for managing [Nebula](https://github.com/slackhq/nebula) overlay network configurations. It takes a single declarative YAML file describing your entire network — hosts, lighthouses, relays, firewall rules — and generates validated, ready-to-deploy Nebula configs for each node.
+
+---
+
+## Why?
+
+Managing a Nebula mesh network means juggling per-host YAML files that share 90% of their content but differ in subtle, error-prone ways. nebula-config-kit solves this:
+
+- **Single source of truth** — one config file defines your entire network topology
+- **Type-safe validation** — Pydantic models catch misconfigurations before deployment (duplicate IPs, missing lighthouses, invalid rules)
+- **Automatic resolution** — lighthouse maps, relay lists, and firewall rules are computed per-host from your network definition
+- **PKI integration** — built-in certificate management via pki-kit (CA creation, host cert signing, revocation)
+- **Comment-preserving templates** — generated configs retain the original Nebula YAML comments for readability
+
+## Quick start
+
+### Install
+
+```bash
+# With CLI
+pip install nebula-config-kit[cli]
+
+# Library only
+pip install nebula-config-kit
+```
+
+### Define your network
+
+Create `nebula-network.config.yml`:
+
+```yaml
+network:
+  cidr: 10.10.0.0/16
+
+certs:
+  ca_name: "My Network CA"
+  ca_duration: 3650d
+  host_duration: 365d
+
+hosts:
+  defaults:
+    listen_port: 4242
+    tun_dev: nebula1
+  hosts:
+    lighthouse1:
+      nebula_ip: 10.10.0.1
+      public_endpoints: ["203.0.113.10"]
+    webserver:
+      nebula_ip: 10.10.0.10
+    database:
+      nebula_ip: 10.10.0.20
+
+firewall:
+  security_groups:
+    icmp:
+      port: any
+      proto: icmp
+      direction: any
+    ssh:
+      port: 22
+      proto: tcp
+      direction: in
+    https:
+      port: 443
+      proto: tcp
+      direction: in
+  firewall_default:
+    all: [icmp]
+  firewall_rules:
+    webserver:
+      all: [ssh, https]
+    database:
+      webserver: [ssh]
+```
+
+### Generate configs
+
+```bash
+# List all hosts
+nebula-config hosts list
+
+# Show resolved details for a host
+nebula-config hosts show webserver
+
+# Generate a complete Nebula config
+nebula-config config generate webserver -o webserver.yml
+```
+
+### Use as a library
+
+```python
+from pathlib import Path
+from nebula_config_kit import load_config, resolve_host, generate_host_config
+from nebula_config_kit.types import HostName
+
+config = load_config(path=Path("nebula-network.config.yml"))
+host = resolve_host(name=HostName("webserver"), config=config)
+```
+
+## Features
+
+### Host resolution
+
+Hosts inherit from `defaults` and can override any setting. Lighthouses are auto-detected from hosts with `public_endpoints`. Relays are identified by the `am_relay` flag. Each host gets a resolved config with the correct static host map, lighthouse list, and relay list — excluding itself.
+
+### Security groups & firewall
+
+Define reusable security groups, assign them to hosts or host groups, and nebula-config-kit resolves the full inbound/outbound firewall ruleset per host. Default rules apply to all hosts unless overridden.
+
+### PKI management
+
+Integrated certificate lifecycle:
+
+- CA key and certificate generation
+- Host certificate signing with correct Nebula IP and groups
+- Certificate revocation
+- Validity tracking and renewal hints
+- SOPS-encrypted key storage support
+
+### CLI output formats
+
+```bash
+# Table (default), JSON, or YAML
+nebula-config hosts list --output json
+nebula-config hosts show database --output yaml
+```
+
+### Custom templates
+
+Override the built-in Nebula config template to include your own settings:
+
+```bash
+nebula-config config generate webserver --template my-template.yml
+```
+
+## Configuration
+
+| Environment Variable              | Default                     | Description                                |
+| --------------------------------- | --------------------------- | ------------------------------------------ |
+| `NEBULA_NETWORK_CONFIG`           | `nebula-network.config.yml` | Path to network config file                |
+| `NEBULA_CONFIG_KIT_PKI_PATH`      | `.`                         | Root directory for PKI stores              |
+| `NEBULA_CONFIG_KIT_PKI_NAME`      | `default`                   | PKI instance name                          |
+| `NEBULA_CONFIG_KIT_SOPS_ARGS`     | —                           | Extra SOPS arguments for encrypted keys    |
+| `NEBULA_CONFIG_KIT_OUTPUT_FORMAT` | `table`                     | CLI output format: `table`, `json`, `yaml` |
+
+## Development
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# Install dependencies
+uv sync --all-extras
+
+# Run tests
+just test
+
+# Lint + type check
+just lint
+
+# All checks
+just check
+```
+
+## License
+
+See [LICENSE](LICENSE) for details.

nebula_config_kit-0.0.1/README.md

@@ -0,0 +1,170 @@
+# nebula-config-kit
+
+**Stop hand-crafting Nebula configs. Define your mesh network once, generate configs for every host.**
+
+nebula-config-kit is a Python library and CLI for managing [Nebula](https://github.com/slackhq/nebula) overlay network configurations. It takes a single declarative YAML file describing your entire network — hosts, lighthouses, relays, firewall rules — and generates validated, ready-to-deploy Nebula configs for each node.
+
+---
+
+## Why?
+
+Managing a Nebula mesh network means juggling per-host YAML files that share 90% of their content but differ in subtle, error-prone ways. nebula-config-kit solves this:
+
+- **Single source of truth** — one config file defines your entire network topology
+- **Type-safe validation** — Pydantic models catch misconfigurations before deployment (duplicate IPs, missing lighthouses, invalid rules)
+- **Automatic resolution** — lighthouse maps, relay lists, and firewall rules are computed per-host from your network definition
+- **PKI integration** — built-in certificate management via pki-kit (CA creation, host cert signing, revocation)
+- **Comment-preserving templates** — generated configs retain the original Nebula YAML comments for readability
+
+## Quick start
+
+### Install
+
+```bash
+# With CLI
+pip install nebula-config-kit[cli]
+
+# Library only
+pip install nebula-config-kit
+```
+
+### Define your network
+
+Create `nebula-network.config.yml`:
+
+```yaml
+network:
+  cidr: 10.10.0.0/16
+
+certs:
+  ca_name: "My Network CA"
+  ca_duration: 3650d
+  host_duration: 365d
+
+hosts:
+  defaults:
+    listen_port: 4242
+    tun_dev: nebula1
+  hosts:
+    lighthouse1:
+      nebula_ip: 10.10.0.1
+      public_endpoints: ["203.0.113.10"]
+    webserver:
+      nebula_ip: 10.10.0.10
+    database:
+      nebula_ip: 10.10.0.20
+
+firewall:
+  security_groups:
+    icmp:
+      port: any
+      proto: icmp
+      direction: any
+    ssh:
+      port: 22
+      proto: tcp
+      direction: in
+    https:
+      port: 443
+      proto: tcp
+      direction: in
+  firewall_default:
+    all: [icmp]
+  firewall_rules:
+    webserver:
+      all: [ssh, https]
+    database:
+      webserver: [ssh]
+```
+
+### Generate configs
+
+```bash
+# List all hosts
+nebula-config hosts list
+
+# Show resolved details for a host
+nebula-config hosts show webserver
+
+# Generate a complete Nebula config
+nebula-config config generate webserver -o webserver.yml
+```
+
+### Use as a library
+
+```python
+from pathlib import Path
+from nebula_config_kit import load_config, resolve_host, generate_host_config
+from nebula_config_kit.types import HostName
+
+config = load_config(path=Path("nebula-network.config.yml"))
+host = resolve_host(name=HostName("webserver"), config=config)
+```
+
+## Features
+
+### Host resolution
+
+Hosts inherit from `defaults` and can override any setting. Lighthouses are auto-detected from hosts with `public_endpoints`. Relays are identified by the `am_relay` flag. Each host gets a resolved config with the correct static host map, lighthouse list, and relay list — excluding itself.
+
+### Security groups & firewall
+
+Define reusable security groups, assign them to hosts or host groups, and nebula-config-kit resolves the full inbound/outbound firewall ruleset per host. Default rules apply to all hosts unless overridden.
+
+### PKI management
+
+Integrated certificate lifecycle:
+
+- CA key and certificate generation
+- Host certificate signing with correct Nebula IP and groups
+- Certificate revocation
+- Validity tracking and renewal hints
+- SOPS-encrypted key storage support
+
+### CLI output formats
+
+```bash
+# Table (default), JSON, or YAML
+nebula-config hosts list --output json
+nebula-config hosts show database --output yaml
+```
+
+### Custom templates
+
+Override the built-in Nebula config template to include your own settings:
+
+```bash
+nebula-config config generate webserver --template my-template.yml
+```
+
+## Configuration
+
+| Environment Variable              | Default                     | Description                                |
+| --------------------------------- | --------------------------- | ------------------------------------------ |
+| `NEBULA_NETWORK_CONFIG`           | `nebula-network.config.yml` | Path to network config file                |
+| `NEBULA_CONFIG_KIT_PKI_PATH`      | `.`                         | Root directory for PKI stores              |
+| `NEBULA_CONFIG_KIT_PKI_NAME`      | `default`                   | PKI instance name                          |
+| `NEBULA_CONFIG_KIT_SOPS_ARGS`     | —                           | Extra SOPS arguments for encrypted keys    |
+| `NEBULA_CONFIG_KIT_OUTPUT_FORMAT` | `table`                     | CLI output format: `table`, `json`, `yaml` |
+
+## Development
+
+Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# Install dependencies
+uv sync --all-extras
+
+# Run tests
+just test
+
+# Lint + type check
+just lint
+
+# All checks
+just check
+```
+
+## License
+
+See [LICENSE](LICENSE) for details.

nebula_config_kit-0.0.1/pyproject.toml

@@ -0,0 +1,116 @@
+[project]
+name = "nebula-config-kit"
+version = "0.0.1"
+description = "Define your Nebula mesh network once, generate validated configs for every host"
+readme = "README.md"
+authors = [
+    { name = "Dmitry Tatarkin", email = "tatarkin@gmail.com" }
+]
+license = "MIT"
+requires-python = ">=3.12"
+keywords = [
+    "nebula",
+    "vpn",
+    "mesh-network",
+    "overlay-network",
+    "network-automation",
+    "configuration-management",
+    "infrastructure",
+    "pki",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: System Administrators",
+    "Intended Audience :: Developers",
+    "Topic :: System :: Networking",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Security",
+    "Typing :: Typed",
+    "Environment :: Console",
+    "Framework :: Pydantic :: 2",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "pki-kit>=0.0.2",
+    "pydantic>=2.0",
+    "ruamel-yaml>=0.18",
+]
+
+[project.urls]
+Homepage = "https://github.com/dtatarkin/nebula-config-kit"
+Repository = "https://github.com/dtatarkin/nebula-config-kit"
+Issues = "https://github.com/dtatarkin/nebula-config-kit/issues"
+Changelog = "https://github.com/dtatarkin/nebula-config-kit/releases"
+
+[tool.uv.sources]
+#pki-kit = { path = "lib/pki-kit", editable = true }
+
+[project.optional-dependencies]
+cli = ["typer>=0.15", "rich>=13.0"]
+
+[project.scripts]
+nebula-config = "nebula_config_kit.cli:main"
+[dependency-groups]
+dev = [
+    "codespell",
+    "mypy",
+    "pre-commit",
+    "pytest",
+    "python-dotenv[cli]",
+    "ruff",
+    "ty>=0.0.24",
+]
+
+[tool.uv.build-backend]
+module-name = "nebula_config_kit"
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "I", "N", "UP", "B", "A", "C4", "DTZ", "T20", "SIM", "TCH", "RUF", "PT", "S", "ANN"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["ANN", "S101"]
+"src/nebula_config_kit/cli/**/*.py" = ["T20", "TCH"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["nebula_config_kit"]
+
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-base-classes = ["pydantic.BaseModel"]
+
+[tool.mypy]
+strict = true
+plugins = ["pydantic.mypy"]
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_decorators = false
+
+[[tool.mypy.overrides]]
+module = "nebula_config_kit.cli.*"
+disallow_untyped_decorators = false
+
+[[tool.mypy.overrides]]
+module = "ruamel.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ty.rules]
+unused-type-ignore-comment = "ignore"
+unresolved-import = "ignore"
+
+[tool.codespell]
+skip = ".git,uv.lock,dist"

nebula_config_kit-0.0.1/src/nebula_config_kit/__init__.py

@@ -0,0 +1,72 @@
+"""nebula-config-kit — Nebula overlay network configuration management."""
+
+from ipaddress import IPv4Address, IPv4Network
+
+from nebula_config_kit.config_gen import render_host_config
+from nebula_config_kit.config_loader import DEFAULT_NEBULA_NETWORK_CONFIG_FILENAME, load_config
+from nebula_config_kit.exceptions import (
+    ConfigFileError,
+    ConfigRenderError,
+    DuplicateIPError,
+    HostNotFoundError,
+    LighthouseConfigError,
+    NebulaConfigError,
+)
+from nebula_config_kit.firewall import resolve_firewall_rules
+from nebula_config_kit.hosts import (
+    extract_lighthouses,
+    resolve_host_overrides,
+    resolve_lighthouses_for_host,
+    resolve_relays_for_host,
+)
+from nebula_config_kit.models import (
+    CertsConfig,
+    FirewallConfig,
+    HostConfig,
+    HostDefaults,
+    HostsConfig,
+    LighthouseInfo,
+    NebulaNetworkConfig,
+    NetworkConfig,
+    SecurityGroup,
+)
+from nebula_config_kit.network import get_prefix_length, make_sign_ip
+from nebula_config_kit.orchestration import ResolvedHost, generate_host_config, resolve_host
+from nebula_config_kit.types import Direction, FirewallRule, HostName, Protocol
+
+__all__ = [
+    "DEFAULT_NEBULA_NETWORK_CONFIG_FILENAME",
+    "CertsConfig",
+    "ConfigFileError",
+    "ConfigRenderError",
+    "Direction",
+    "DuplicateIPError",
+    "FirewallConfig",
+    "FirewallRule",
+    "HostConfig",
+    "HostDefaults",
+    "HostName",
+    "HostNotFoundError",
+    "HostsConfig",
+    "IPv4Address",
+    "IPv4Network",
+    "LighthouseConfigError",
+    "LighthouseInfo",
+    "NebulaConfigError",
+    "NebulaNetworkConfig",
+    "NetworkConfig",
+    "Protocol",
+    "ResolvedHost",
+    "SecurityGroup",
+    "extract_lighthouses",
+    "generate_host_config",
+    "get_prefix_length",
+    "load_config",
+    "make_sign_ip",
+    "render_host_config",
+    "resolve_firewall_rules",
+    "resolve_host",
+    "resolve_host_overrides",
+    "resolve_lighthouses_for_host",
+    "resolve_relays_for_host",
+]

nebula_config_kit-0.0.1/src/nebula_config_kit/cli/__init__.py

@@ -0,0 +1,82 @@
+"""nebula-config CLI — optional command-line interface."""
+
+from typing import Annotated
+
+import typer
+
+from nebula_config_kit.cli._context import CliContext, OutputFormat
+from nebula_config_kit.config_loader import DEFAULT_NEBULA_NETWORK_CONFIG_FILENAME
+from nebula_config_kit.exceptions import NebulaConfigError
+
+app = typer.Typer(
+    name="nebula-config",
+    help="Nebula overlay network configuration management.",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        from importlib.metadata import version
+
+        print(f"nebula-config {version('nebula-config-kit')}")
+        raise typer.Exit
+
+
+@app.callback()
+def main_callback(
+    ctx: typer.Context,
+    config: Annotated[
+        str,
+        typer.Option(envvar="NEBULA_NETWORK_CONFIG", help="Path to network config file."),
+    ] = DEFAULT_NEBULA_NETWORK_CONFIG_FILENAME,
+    pki_base_path: Annotated[
+        str,
+        typer.Option(envvar="NEBULA_CONFIG_KIT_PKI_PATH", help="Root directory for pki-kit stores."),
+    ] = ".",
+    pki_name: Annotated[
+        str,
+        typer.Option(envvar="NEBULA_CONFIG_KIT_PKI_NAME", help="PKI instance name."),
+    ] = "default",
+    sops_args: Annotated[
+        str | None,
+        typer.Option(envvar="NEBULA_CONFIG_KIT_SOPS_ARGS", help="Extra SOPS arguments (space-separated)."),
+    ] = None,
+    output_format: Annotated[
+        OutputFormat,
+        typer.Option("--output-format", "-f", envvar="NEBULA_CONFIG_KIT_OUTPUT_FORMAT", help="Output format."),
+    ] = OutputFormat.TABLE,
+    _version: Annotated[
+        bool | None,
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version and exit."),
+    ] = None,
+) -> None:
+    """Nebula overlay network configuration management."""
+    from pathlib import Path
+
+    ctx.obj = CliContext(
+        config_path=Path(config),
+        pki_base_path=Path(pki_base_path),
+        pki_name=pki_name,
+        sops_args=tuple(sops_args.split()) if sops_args else (),
+        output_format=output_format,
+    )
+
+
+# Register subcommand groups (import after app is defined to avoid circular imports)
+from nebula_config_kit.cli._config import config_app  # noqa: E402
+from nebula_config_kit.cli._hosts import hosts_app  # noqa: E402
+
+app.add_typer(config_app)
+app.add_typer(hosts_app)
+
+
+def main() -> None:
+    """Entry point for the nebula-config CLI."""
+    try:
+        app()
+    except NebulaConfigError as exc:
+        from rich.console import Console
+
+        Console(stderr=True).print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(code=1) from None

nebula_config_kit-0.0.1/src/nebula_config_kit/cli/_config.py

@@ -0,0 +1,52 @@
+"""Config generation CLI subcommands."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from nebula_config_kit.cli._context import CliContext
+
+config_app = typer.Typer(name="config", help="Configuration generation.", no_args_is_help=True)
+
+
+def _get_ctx(ctx: typer.Context) -> CliContext:
+    result: CliContext = ctx.obj
+    return result
+
+
+@config_app.command("generate")
+def generate(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Host name to generate config for.")],
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="Path to write the generated config file.")
+    ] = None,
+    template: Annotated[Path | None, typer.Option(help="Custom Nebula config template.")] = None,
+) -> None:
+    """Generate Nebula configuration for a host."""
+    from nebula_config_kit.cli._context import nebula_pki_session
+    from nebula_config_kit.config_loader import load_config
+    from nebula_config_kit.exceptions import ConfigFileError
+    from nebula_config_kit.orchestration import generate_host_config
+    from nebula_config_kit.types import HostName
+
+    cli_ctx = _get_ctx(ctx=ctx)
+    config = load_config(cli_ctx.config_path)
+    if config is None:
+        raise ConfigFileError(message="Configuration file not found.")
+
+    with nebula_pki_session(cli_ctx) as pki:
+        config_yaml = generate_host_config(
+            HostName(name),
+            config=config,
+            pki=pki,
+            template_path=template,
+        )
+
+    if output is not None:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(config_yaml)
+        print(f"Config written to {output}")
+    else:
+        print(config_yaml, end="")