Metadata-Version: 2.4
Name: pumpwood-deploy-auth
Version: 0.0.3
Summary: Package to assist deploy Pumpwood Auth on K8s
License: BSD-3-Clause License
License-File: LICENSE
Author: André Andrade Baceti
Author-email: a.baceti@murabei.com
Requires-Python: >=3.6
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: pumpwood-deploy
Project-URL: Homepage, https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy-auth
Description-Content-Type: text/markdown

# 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`](https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy)
for apply.

Developed by [Murabei Data Science](https://murabei.com). BSD-3-Clause.

<p align="center" width="60%">
  <img src="static_doc/sitelogo-horizontal.png" /> <br>

  <a href="https://en.wikipedia.org/wiki/Cecropia">
    Pumpwood is a native Brazilian tree
  </a> with a symbiotic relation to ants (Murabei)
</p>

---

## 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).

```mermaid
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

```bash
pip install pumpwood-deploy-auth
```

Requires `pumpwood-deploy` (declared as a dependency).

---

## Quick start

A typical auth slice inside a larger Pumpwood deploy script:

```python
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`:

```bash
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`](https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy) | Orchestrator, standard services, Postgres |
| [`pumpwood-deploy-ingress-aws`](https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy) | ALB ingress (optional) |
| [`pumpwood-deploy-datalake`](https://github.com/Murabei-OpenSource-Codes/pumpwood-deploy-datalake) | Datalake microservice (optional) |

Full platform documentation:
[Murabei Open Source — pumpwood-deploy](https://murabei-opensource-codes.github.io/pumpwood-deploy/).

---

## Development

```bash
# 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](LICENSE).

