jetpack-launcher-py

One-line launcher for Python services on the Jetset platform. Wires OpenTelemetry (traces + metrics + logs), typed configuration, structured logging, and graceful shutdown — with the same code path locally and in Kubernetes.

pip install jetpack-launcher-py

from jetpack import init_jetpack

init_jetpack()

That's it. Whatever framework you're using, whatever cloud you're on, whatever backend the platform team picked — the service code never has to know.

What it does at v0.1

• Detects runtime: local (laptop, docker) vs Kubernetes
• Loads .env.local and .env.local-{flavor} when running locally
• In k8s, reads env vars populated by ConfigMap + ExternalSecret — no filesystem reads
• Validates a typed Config (Pydantic) and fails fast on missing keys
• Builds an OpenTelemetry Resource with service.*, deployment.*, and k8s.* attributes
• Initializes Tracer / Meter / Logger providers with OTLP exporters
• Bridges stdlib logging to structured JSON + OTel Logs with trace_id / span_id auto-injection
• Registers SIGTERM + atexit handlers that flush telemetry before exit

The env model — one mental model, two backends

LOCAL                              KUBERNETES
────────────────                   ───────────────────────────
.env.local            ←─ optional   ConfigMap (literals + ${param:…})
.env.local-{flavor}   ←─ optional   ExternalSecret (${secret:…})
        │                                   │
        ▼                                   ▼
                       os.environ
                            │
                            ▼
                    Config(BaseSettings)
                            │
                            ▼
                     your service code

The service reads Config. The launcher decides where the values came from.

Detection rules

1. JETPACK_RUNTIME=local|k8s overrides everything
2. KUBERNETES_SERVICE_HOST set → k8s (set by kubelet)
3. otherwise → local

Local env files (gitignored)

• .env.local — universal local overrides (often committed if it contains only non-secret defaults; otherwise gitignored)
• .env.local-{flavor} — flavor-specific, picked by JETPACK_ENV (default dev). Always gitignored.

JETPACK_ENV=dev  python -m src.main    # loads .env.local + .env.local-dev
JETPACK_ENV=prod python -m src.main    # loads .env.local + .env.local-prod

In k8s, .env.local* files are never read — the deployment supplies env vars via envFrom: [configMapRef, secretRef] and the launcher detects k8s.

Quick start

pip install jetpack-launcher-py

# src/configs/loader.py — your service's typed config
from jetpack import JetpackConfig

class Config(JetpackConfig):
    DB_HOST: str | None = None
    DB_PORT: int | None = None
    # add more — Pydantic validates at startup

# src/main.py
from jetpack import init_jetpack, get_tracer
from src.configs import Config

handle = init_jetpack(config_class=Config)
tracer = get_tracer(__name__)

with tracer.start_as_current_span("startup"):
    ...  # your service main loop

Public API (stable)

from jetpack import (
    init_jetpack,    # the one entry point
    JetpackConfig,   # base Config class — subclass for your service
    JetpackHandle,   # what init_jetpack returns
    Runtime,         # enum: LOCAL | K8S
    RuntimeInfo,     # detection result
    get_tracer,      # opentelemetry.trace.get_tracer
    get_meter,       # opentelemetry.metrics.get_meter
)

Roadmap

• v0.2 — Flask & FastAPI adapters; resource detectors for ECS / GKE / Cloud Run
• v0.3 — Secret resolver plugin; PII redaction policy; --dry-run mode
• v0.4 — OpenFeature feature flag bootstrap
• v0.5 — HTTP client factory + JWT auth plugin
• v0.6 — AI cost / token tracking for OpenAI, Anthropic

See CHANGELOG.md for shipped releases.

Contributing

See CONTRIBUTING.md. Security reports go to security@getjetpack.cloud — see SECURITY.md.

Releasing (maintainers only)

Releases are automated via GitHub Actions and PyPI Trusted Publishing:

1. Bump version in pyproject.toml and add a ## [x.y.z] section in CHANGELOG.md describing the changes.
2. Commit and merge to main.
3. Tag and push:

   git tag v0.1.0
   git push origin v0.1.0
   

4. The release.yml workflow builds the distribution, publishes to TestPyPI for sanity-check, then publishes to PyPI and cuts a GitHub Release with auto-generated notes.

The first release requires a maintainer to configure PyPI Trusted Publishing on both pypi.org and test.pypi.org pointing at this repo / release.yml / environments pypi and testpypi.

License

Licensed under the Apache License, Version 2.0 — see LICENSE and NOTICE. All contributions are accepted under the same terms.

Copyright © 2026 Jetset.