Skip to content

scripts-reference.md

Latest commit

 

History

History
543 lines (350 loc) · 12.2 KB

scripts-reference.md

File metadata and controls

543 lines (350 loc) · 12.2 KB
Raw

Scripts Reference

Complete reference for all automation scripts in Charon. All scripts are located in the scripts/ directory and are called by Terraform during deployment.

Table of Contents

cert-manager Scripts

create_cloudflare_secret.py

Creates Kubernetes secret for Cloudflare API token used by cert-manager DNS-01 challenge.

Usage:

python scripts/cert-manager/create_cloudflare_secret.py

Environment Variables:

  • CLOUDFLARE_API_TOKEN - Cloudflare API token with DNS edit permissions

Called By: Terraform during cert-manager setup

wait_for_cert_manager.py

Waits for cert-manager pods to be ready before proceeding with certificate creation.

Usage:

python scripts/cert-manager/wait_for_cert_manager.py --namespace cert-manager

Parameters:

  • --namespace - cert-manager namespace (default: cert-manager)
  • --timeout - Maximum wait time in seconds (default: 300)

Called By: Terraform after cert-manager deployment

wait_for_wildcard_cert.py

Waits for wildcard certificate to be provisioned and ready.

Usage:

python scripts/cert-manager/wait_for_wildcard_cert.py \
  --namespace dev \
  --cert-name wildcard-example-com-tls

Parameters:

  • --namespace - Namespace containing the certificate
  • --cert-name - Name of the certificate resource
  • --timeout - Maximum wait time in seconds (default: 600)

Called By: Terraform after certificate resource creation

DNS Management Scripts

update_service_dns.py

Updates Cloudflare DNS A records for services with automatic stale record cleanup.

Key Features:

  • Resilient fallback to node IPs if pod VPN IP not available
  • Automatic cleanup of stale DNS records from old/offline pods
  • Multi-record detection and management
  • Batch service updates

Usage:

# Update single service
python scripts/dns/update_service_dns.py \
  --zone-id ZONE_ID \
  --namespace dev \
  --services '[{"name":"grafana","hostname":"grafana","record_name":"grafana","enabled":true}]'

# Initial VPN DNS setup
python scripts/dns/update_service_dns.py \
  --zone-id ZONE_ID \
  --namespace dev \
  --initial-vpn-dns

Parameters:

  • --zone-id - Cloudflare Zone ID
  • --api-token - Cloudflare API token (or use CLOUDFLARE_API_TOKEN env var)
  • --namespace - Kubernetes namespace
  • --services - JSON array of service configurations
  • --initial-vpn-dns - Create initial VPN DNS records with node IPs
  • --dry-run - Test without making changes

Service JSON Format:

{
  "name": "service-name",
  "hostname": "service-hostname",
  "record_name": "dns-record-name",
  "enabled": true
}

Called By: Terraform post-deployment per-service DNS updates

Self-Healing Behavior:

  • Detects multiple A records for same hostname
  • Keeps record matching current pod IP
  • Deletes stale records from old/offline pods
  • Creates new record if none match current IP

prune_dns_records.py

Zone-wide cleanup that removes ALL DNS A records not matching current online Headscale nodes.

Usage:

python scripts/dns/prune_dns_records.py \
  --zone-id ZONE_ID \
  --namespace dev \
  --grace-period 300

Parameters:

  • --zone-id - Cloudflare Zone ID
  • --api-token - Cloudflare API token
  • --namespace - Kubernetes namespace with Headscale
  • --grace-period - Seconds to wait before deleting (default: 300)
  • --dry-run - Test without making changes

Called By: Manual maintenance or scheduled jobs

Warning: More aggressive than update_service_dns.py - removes ANY A record not matching current Headscale nodes. Use with caution.

delete_a_record.py

Manually delete specific DNS A records.

Usage:

python scripts/dns/delete_a_record.py \
  --zone-id ZONE_ID \
  --record-id RECORD_ID

Parameters:

  • --zone-id - Cloudflare Zone ID
  • --record-id - Cloudflare DNS record ID to delete
  • --api-token - Cloudflare API token

Called By: Manual cleanup operations

FreeIPA Scripts

init_freeipa.py

Initializes FreeIPA server with domain, realm, and admin password.

Usage:

python scripts/freeipa/init_freeipa.py

Environment Variables:

  • FREEIPA_ADMIN_PASSWORD - Admin password for FreeIPA
  • FREEIPA_DOMAIN - FreeIPA domain (e.g., dev.svc.cluster.local)
  • FREEIPA_REALM - Kerberos realm (e.g., DEV.SVC.CLUSTER.LOCAL)

Called By: Terraform after FreeIPA pod starts

configure_freeipa.py

Configures FreeIPA settings, groups, and policies.

Usage:

python scripts/freeipa/configure_freeipa.py --namespace dev

Parameters:

  • --namespace - Kubernetes namespace with FreeIPA pod

Environment Variables:

  • FREEIPA_ADMIN_PASSWORD - Admin password

Called By: Terraform after FreeIPA initialization

Configuration Applied:

  • Creates user groups
  • Sets password policies
  • Configures LDAP settings
  • Sets up authentication policies

create_users.py

Creates FreeIPA users from JSON configuration file with automatic 1-year password expiration.

Usage:

python scripts/freeipa/create_users.py \
  --namespace dev \
  --users-file scripts/freeipa/freeipa_users.json

Parameters:

  • --namespace - Kubernetes namespace
  • --users-file - Path to users JSON file

Environment Variables:

  • FREEIPA_ADMIN_PASSWORD - Admin password

Users JSON Format:

[
  {
    "username": "user1",
    "first_name": "First",
    "last_name": "Last",
    "email": "user1@example.com",
    "password": "initial-password",
    "groups": ["admins"]
  }
]

Called By: Terraform after FreeIPA configuration

Features:

  • Automatically sets password expiration to 1 year from creation
  • Prevents immediate password expiration issues
  • Adds users to specified groups

Headscale Scripts

wait_for_headscale.py

Waits for Headscale pod to be ready and API to be accessible.

Usage:

python scripts/headscale/wait_for_headscale.py --namespace dev

Parameters:

  • --namespace - Kubernetes namespace
  • --timeout - Maximum wait time in seconds (default: 300)

Called By: Terraform after Headscale deployment

get_headscale_api_key.py

Generates or retrieves Headscale API key and stores in Kubernetes secret.

Usage:

python scripts/headscale/get_headscale_api_key.py --namespace dev

Parameters:

  • --namespace - Kubernetes namespace

Called By: Terraform after Headscale is ready

Creates:

  • Kubernetes secret headscale-api-key with API key

create_headscale_user_and_key.py

Creates Headscale user and generates pre-auth key for service enrollment.

Usage:

python scripts/headscale/create_headscale_user_and_key.py \
  --namespace dev \
  --user default \
  --expiration 90d

Parameters:

  • --namespace - Kubernetes namespace
  • --user - Headscale user name
  • --expiration - Key expiration (e.g., 90d, 1y)
  • --reusable - Make key reusable (flag)

Called By: Terraform when creating service-specific auth keys

Output: Pre-auth key for Tailscale enrollment

cleanup_headscale_nodes.py

Removes offline Headscale nodes to prevent IP accumulation and stale DNS records.

Usage:

python scripts/headscale/cleanup_headscale_nodes.py \
  --namespace dev \
  --offline-threshold 3600

Parameters:

  • --namespace - Kubernetes namespace
  • --offline-threshold - Seconds offline before deletion (default: 3600)

Called By: Terraform post-deployment cleanup (centralized)

What It Does:

  • Lists all Headscale nodes
  • Identifies nodes offline longer than threshold
  • Deletes offline nodes to free VPN IPs
  • Prevents DNS records for non-existent pods

Tailscale Scripts

get_tailscale_key.py

Generates Tailscale auth key for service VPN enrollment.

Usage:

python scripts/tailscale/get_tailscale_key.py \
  --namespace dev \
  --service-name grafana

Parameters:

  • --namespace - Kubernetes namespace
  • --service-name - Service name for key
  • --expiration - Key expiration (default: 90d)

Called By: Terraform when deploying services with Tailscale sidecars

Creates:

  • Kubernetes secret {service}-tailscale-auth with auth key

Redmine Scripts

backup_restore_db.py

Backup and restore Redmine PostgreSQL database.

Usage:

# Backup database
python scripts/redmine/backup_restore_db.py backup

# Restore from backup
python scripts/redmine/backup_restore_db.py restore --file redmine_backup_20241110_143000.sql

Commands:

  • backup - Create timestamped SQL backup file
  • restore - Restore database from SQL file

Parameters:

  • --file - Backup file path (restore only)
  • --output-dir - Backup directory (default: ./backups)

Environment Variables:

  • REDMINE_DB_HOST - PostgreSQL host
  • REDMINE_DB_PORT - PostgreSQL port
  • REDMINE_DB_NAME - Database name
  • REDMINE_DB_USER - Database user
  • REDMINE_DB_PASSWORD - Database password

Called By: Manual operations or scheduled backup jobs

Features:

  • Secure .pgpass file for authentication
  • Timestamped backup files
  • Automatic cleanup of temporary files

test_connection.py

Tests Redmine database connection.

Usage:

python scripts/redmine/test_connection.py

Environment Variables:

  • REDMINE_DB_HOST
  • REDMINE_DB_PORT
  • REDMINE_DB_NAME
  • REDMINE_DB_USER
  • REDMINE_DB_PASSWORD

Called By: Manual testing or troubleshooting

mirror_docs.py

Mirrors documentation to Redmine wiki pages.

Usage:

python scripts/redmine/mirror_docs.py \
  --redmine-url https://redmine.example.com \
  --api-key YOUR_API_KEY

Parameters:

  • --redmine-url - Redmine instance URL
  • --api-key - Redmine API key
  • --docs-dir - Documentation directory (default: ./docs)

Called By: Manual documentation sync operations

Common Patterns

Error Handling

All scripts follow these patterns:

  • Exit code 0 on success
  • Exit code 1 on failure
  • Descriptive error messages to stderr
  • JSON output for structured data

Kubernetes Integration

Scripts use kubectl for Kubernetes operations:

  • Namespace-aware operations
  • Pod status checking
  • Secret management
  • ConfigMap updates

Dry Run Mode

Many scripts support --dry-run flag:

  • Shows what would be done without making changes
  • Useful for testing and validation
  • Safe for experimentation

Related Documentation

Navigation: Documentation Index | Home