proxy-deployment.yaml

Overview

This file is an Ansible playbook designed to automate the deployment and management of a proxy service environment. It primarily focuses on preparing necessary directories, managing proxy certificates and keys, configuring the proxy service with Docker Compose, and handling log rotation. The playbook supports both scenarios where proxy certificates are generated as part of the deployment and where pre-existing certificates are used.

Key features include:

Ensuring required directories exist with proper permissions.
Copying signing keys conditionally.
Verifying presence of proxy certificates and keys.
Backing up existing certificates and keys during regeneration.
Managing proxy Docker Compose lifecycle (pull, down, up, restart).
Waiting for certificate files to become available.
Cleaning up sensitive signing keys securely after use.
Configuring log rotation for proxy logs.

This playbook is intended to be run in an environment where variables such as PROXY_DIR, PROXY_CERTS_DIR, PROXY_SIGNING_KEYS, GENERATE_CERT, and CLEANUP_BK_KEYS are defined externally.

Tasks and Their Functional Details

1. Ensure Proxy Directories Exist

Module: ansible.builtin.file
Purpose: Creates the directories required for proxy operation with full read-write-execute permissions for user, group, and others.
Parameters:
- path: Directory paths obtained from PROXY_DIR and PROXY_CERTS_DIR.
- state: Directory (ensures directory exists).
- mode: u=rwx,g=rwx,o=rwx (permissions).
Iterates Over: List of proxy directory variables.
Usage: Prepares environment for proxy file storage.

2. Gather Network Interface Facts

Module: ansible.builtin.setup
Purpose: Gathers detailed network-related facts about the target host.
Parameters:
- gather_subset: Only gather network facts.
Usage: Provides network information for potential downstream tasks or conditional logic.

3. Copy Block Keeper Keys to Proxy

Module: ansible.builtin.copy
Purpose: Copies signing keys used by the Block Keeper to the proxy certificates directory.
Parameters:
- dest: Proxy certificates directory.
- src: Source path for each signing key.
Loop: Over PROXY_SIGNING_KEYS.
Condition: Runs only if GENERATE_CERT is true.
Error Handling: Uses mandatory filter to fail if keys are undefined.
Usage: Prepares signing keys required for certificate generation.

4. Check That Proxy Certificate and Key Exist

Module: ansible.builtin.stat
Purpose: Verifies existence of proxy.ca.pem and proxy.key.pem certificate files.
Parameters:
- path: Full path to certificate/key files.
Condition: Runs only if GENERATE_CERT is false.
Behavior: Fails the play if files do not exist.
Registers: Results in proxy_ca_exists and proxy_key_exists.
Usage: Ensures necessary certificates are present when not generating new ones.

5. Generate Configuration Files Using Templates

Module: ansible.builtin.template
Purpose: Renders configuration files from Jinja2 templates located in templates/.
Files Rendered:
- compose.yaml (Docker Compose configuration).
- config.yaml (Proxy service configuration).
- logrotate.sh (Log rotation script).
Permissions: 0644 for compose, 0655 for config, 0755 for logrotate.
Registers: logrotate task status to detect changes.
Usage: Configures proxy runtime environment.

6. Manage Docker Compose Lifecycle

Modules: ansible.builtin.shell
Commands:
- docker compose pull: Pulls latest images.
- docker compose down -v: Stops and removes volumes (only when regenerating certs).
- docker compose up -d: Starts services in detached mode.
- docker compose restart logrotate: Restarts logrotate container if configuration changed.
Working Directory: PROXY_DIR.
Usage: Controls proxy container lifecycle for deployment and updates.

7. Backup Existing Proxy Certificates and Keys

Modules: ansible.builtin.stat and ansible.builtin.command
Purpose: Before generating new certificates, backs up existing proxy.ca.pem and proxy.key.pem by renaming them with .old extension.
Condition: Runs only when regenerating certificates (GENERATE_CERT).
Registers: Backup existence status.
Usage: Protects existing certificates for rollback or recovery.

8. Wait for Proxy Certificate and Key Availability

Module: ansible.builtin.wait_for
Purpose: Waits up to 300 seconds for newly generated proxy certificate and key files to appear.
Parameters:
- path: Proxy certificate/key paths.
- timeout: 300 seconds.
Condition: Runs only when generating certificates.
Usage: Synchronizes playbook progression with certificate availability.

9. Remove Old Backup Certificates and Keys

Module: ansible.builtin.file
Purpose: Deletes .old backup files after new certificates are confirmed.
Condition: Runs only when generating certificates.
Usage: Cleans up to avoid accumulation of old backups.

10. Securely Shred and Remove Block Keeper Keys After Deployment

Modules: ansible.builtin.command and ansible.builtin.file
Purpose: Uses shred command to securely erase signing keys before deleting them.
Condition: Runs only if both CLEANUP_BK_KEYS and GENERATE_CERT are true.
Loop: Over PROXY_SIGNING_KEYS.
Ignore Errors: Yes, to continue even if shredding fails.
Usage: Security best practice for key material disposal post-deployment.

Variables Used

Variable Name	Purpose	Expected Type
PROXY_DIR	Directory path where proxy files and configs are stored	String (path)
PROXY_CERTS_DIR	Directory path for proxy certificates and keys	String (path)
PROXY_SIGNING_KEYS	List of signing key file paths for Block Keeper	List of strings (paths)
`GENERATE_CERT`	Flag indicating whether to generate new certificates	Boolean
`CLEANUP_BK_KEYS`	Flag indicating whether to shred and remove signing keys after deployment	Boolean

Interaction with Other Parts of the System

Docker Compose: This playbook relies on Docker Compose to manage proxy-related containers. The compose.yaml generated here defines container services.
Templates Directory: Uses Jinja2 templates (compose.j2, config.j2, logrotate.j2) to generate configuration files dynamically based on environment variables.
Block Keeper Keys: Interacts with an external key management system by copying and then optionally shredding its signing keys.
Certificate Generation Process: Coordinates with external certificate generation logic by waiting for certificate files to be created.
Log Rotation: Integrates log rotation management by deploying a logrotate script and restarting the corresponding service container if configuration changes.

These interactions ensure that the proxy deployment is fully automated, consistent, and secure within the broader infrastructure management workflow.

Implementation Details and Algorithms

Conditional Execution: Many tasks use when clauses to adapt behavior based on whether new certificates need to be generated.
Backup and Cleanup Strategy: Implements a backup-then-overwrite approach for certificate files, adding robustness to certificate renewal.
Secure Key Disposal: Uses the shred command to overwrite key files before deletion, enhancing security.
Wait Mechanism: The use of wait_for ensures that subsequent tasks relying on certificates only proceed after the files become available, preventing race conditions.
Permission Management: Explicitly sets directory and file modes to ensure necessary access rights for proxy service operation.

Visual Diagram: Workflow of proxy-deployment.yaml

flowchart TD
A[Start Deployment] --> B[Ensure Proxy Dirs Exist]
B --> C[Gather Network Facts]
C --> D{GENERATE_CERT?}
D -- Yes --> E[Copy Block Keeper Keys]
D -- No --> F[Check Proxy Cert & Key]
E --> G[Backup Existing Certs & Keys]
G --> H[Generate Configs from Templates]
F --> H
H --> I[Docker Compose Pull]
I --> J{GENERATE_CERT?}
J -- Yes --> K[Docker Compose Down]
J -- No --> L[Skip Down]
K --> M[Docker Compose Up]
L --> M
M --> N[Restart Logrotate if Changed]
N --> O{GENERATE_CERT?}
O -- Yes --> P[Wait for Cert & Key Availability]
P --> Q[Remove Backup Certs & Keys]
Q --> R{CLEANUP_BK_KEYS?}
O -- No --> R
R -- Yes --> S[Securely Shred Block Keeper Keys]
R -- No --> T[Skip Key Cleanup]
S --> U[Remove Block Keeper Keys]
T --> U
U --> V[End Deployment]

This flowchart represents the conditional logic and sequential flow of tasks in the playbook, highlighting key decision points related to certificate generation and cleanup operations.