pumpwood-deploy-auth

Satellite deploy package for the Pumpwood Auth microservice on Kubernetes. It generates manifests for the Django application, static assets, and auth-specific secrets — then hands them to pumpwood-deploy for apply.

Developed by Murabei Data Science. BSD-3-Clause.

Pumpwood is a native Brazilian tree with a symbiotic relation to ants (Murabei)

---

What it deploys

Manifest	Kubernetes resources
pumpwood_auth__secrets	Secret pumpwood-auth
pumpwood_auth_app__deploy	Deployment + Service pumpwood-auth-app
pumpwood_auth_admin_static__deploy	Deployment pumpwood-auth-static + Service pumpwood-auth-admin-static

Pumpwood Auth provides authorization endpoints, Django admin, Kong route registration, optional SMS MFA (Twilio), and optional SSO (OAuth2 / Microsoft Entra).

flowchart LR
    subgraph pkg [pumpwood-deploy-auth]
        A[PumpWoodAuthMicroservice]
    end
    subgraph core [pumpwood-deploy]
        B[DeployPumpWood]
    end
    subgraph cluster [Cluster]
        S[pumpwood-auth Secret]
        APP[pumpwood-auth-app]
        ST[pumpwood-auth-static]
    end
    A --> B
    B --> S
    B --> APP
    B --> ST

---

Prerequisites

This package does not stand alone. Before auth pods can start, the cluster (or your deploy script) must already provide:

Resource	Provided by
storage ConfigMap	StandardMicroservices in pumpwood-deploy
general-secrets	StandardMicroservices
rabbitmq-main-secrets	StandardMicroservices
Storage keys (GCP / Azure / AWS)	DeployPumpWood storage config
Postgres for auth	PostgresDatabase + PGBouncerDatabase

Storage bucket name and type are read from the cluster storage ConfigMap — they are not passed to PumpWoodAuthMicroservice.

---

Installation

pip install pumpwood-deploy-auth

Requires pumpwood-deploy (declared as a dependency).

---

Quick start

A typical auth slice inside a larger Pumpwood deploy script:

import os
import simplejson as json
from dotenv import load_dotenv
from pumpwood_deploy.deploy import DeployPumpWood
from pumpwood_deploy.microservices.postgres.deploy import (
    PostgresDatabase, PGBouncerDatabase)
from pumpwood_deploy_auth import PumpWoodAuthMicroservice

with open("secrets/production.json", "r") as file:
    secrets = json.loads(file.read())
load_dotenv()

deploy = DeployPumpWood(
    model_user_password=secrets["microservices--model"],
    rabbitmq_secret=secrets["rabbitmq_secret"],
    hash_salt=secrets["hash_salt"],
    storage_type="aws_s3",
    storage_deploy_args={
        "storage_bucket_name": "my-pumpwood-bucket",
        "access_key_id": secrets["aws_access_key_id"],
        "secret_access_key": secrets["aws_secret_access_key"],
    },
    k8_provider="aws",
    k8_deploy_args={
        "region": "us-east-1",
        "cluster_name": "my-cluster",
    },
    k8_namespace="pumpwood",
)

deploy.add_microservice(
    PostgresDatabase(
        db_username="pumpwood",
        db_password=secrets["postgres_password"],
        name="postgres-main",
        disk_name="postgres-disk",
        disk_size="150Gi",
    ))

deploy.add_microservice(
    PGBouncerDatabase(
        name="pgbouncer-pumpwood-auth",
        postgres_database="pumpwood_auth",
        postgres_secret="postgres-main",
        postgres_host="postgres-main",
    ))

deploy.add_microservice(
    PumpWoodAuthMicroservice(
        secret_key=secrets["django_secret_key"],
        email_host_user=secrets["email_user"],
        email_host_password=secrets["email_password"],
        app_version=os.getenv("PUMPWOOD_AUTH_APP"),
        static_version=os.getenv("PUMPWOOD_AUTH_STATIC"),
        repository="my-registry.example.com/",
        static_repository="my-registry.example.com/",
        db_host="pgbouncer-pumpwood-auth",
        db_database="pumpwood_auth",
        db_password=secrets["postgres_password"],
        microservice_password=secrets["microservice--auth"],
        app_csrf_trusted_origins='["https://app.example.com"]',
        app_replicas=1,
        app_debug="FALSE",
    ))

deploy.create_deploy_files()
deploy.deploy_microservices()

Environment variables

Container versions are usually loaded from .env:

PUMPWOOD_AUTH_APP=2.1.0
PUMPWOOD_AUTH_STATIC=1.4.0

If the rendered manifest matches what is already on the cluster, kubectl apply produces no changes — safe for rolling image updates.

---

Configuration reference

Required

Parameter	Description
secret_key	Django hash salt for password storage
email_host_user	SMTP username for Django mail
email_host_password	SMTP password
app_version	Image tag for pumpwood-auth-app
static_version	Image tag for pumpwood-auth-static

Database

Parameter	Default	Description
db_host	postgres-pumpwood-auth	Postgres host (use PgBouncer in prod)
db_port	5432	Postgres port
db_database	pumpwood	Database name
db_username	pumpwood	Database user
db_password	pumpwood	Database password
microservice_password	microservice--auth	Service user password

Application

Parameter	Default	Description
app_replicas	1	Number of app pods
app_debug	FALSE	Django debug flag
app_workers	10	Gunicorn workers
app_timeout	300	Gunicorn timeout (seconds)
app_csrf_trusted_origins	[]	JSON list of trusted admin origins
repository	GCR default	Registry for app image
static_repository	GCR default	Registry for static image

MFA (optional — Twilio SMS)

Leave Twilio fields empty to disable SMS MFA.

Parameter	Description
mfa_application_name	Name shown in SMS messages
mfa_token_expiration_interval	Token lifetime in seconds (default 60)
mfa_twilio_sender_phone_number	Twilio sender number
mfa_twilio_account_sid	Twilio account SID
mfa_twilio_auth_token	Twilio auth token

SSO (optional — OAuth2)

Leave SSO fields empty to disable single sign-on. Only microsoft-entra is implemented in the auth application today.

Parameter	Description
sso__provider	Provider identifier
sso__redirect_url	Post-login redirect URL
sso__authorization_url	OAuth2 authorization endpoint
sso__token_url	OAuth2 token endpoint
sso__client_id	OAuth2 client ID
sso__secret	OAuth2 client secret

---

Health check

The app Deployment exposes a readiness probe at:

GET /health-check/pumpwood-auth-app/  (port 5000)

Use this path for ingress health checks and load balancer targets.

---

Related packages

Package	Role
pumpwood-deploy	Orchestrator, standard services, Postgres
pumpwood-deploy-ingress-aws	ALB ingress (optional)
pumpwood-deploy-datalake	Datalake microservice (optional)

Full platform documentation: Murabei Open Source — pumpwood-deploy.

---

Development

# Install in editable mode with core deploy package
pip install -e ../pumpwood-deploy
pip install -e .

# Lint
ruff check src/

---

License

BSD-3-Clause — see LICENSE.