compose.j2

Overview

compose.j2 is a Jinja2 template file that defines a Docker Compose service configuration for two related services: proxy and logrotate. The file dynamically generates configuration values based on provided template variables, allowing flexible deployment setups. It primarily sets up the environment, volumes, and runtime commands for these services, managing a proxy server process with logging and certificate handling, alongside a log rotation service.

Services and Their Configurations

proxy Service

This service runs a proxy server container with the following key features:

• Image: Uses the Docker image specified by the PROXY_IMAGE template variable.

• Environment Variables: Configures logging and OpenTelemetry (OTEL) metrics parameters dynamically.

• Network Mode: Uses host networking (network_mode: host) for direct access to host network interfaces.

• Entrypoint: Overridden to an empty list, allowing full customization of the container start command.

• Command: Executes a shell command that checks for the existence of proxy certificates and generates them if missing, then launches the proxy server with logs redirected to a mounted log directory.

• Volumes: Mounts configuration, certificates, and logs directories from host paths provided by template variables.

Environment Variables Details

• RUST_LOG: Sets the Rust logging level for the proxy from PROXY_LOG_LEVEL.

• OTEL_RESOURCE_ATTRIBUTES: Constructs a composite resource attribute string for OTEL, incorporating proxy node identifiers and hostnames.

• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT and OTEL_EXPORTER_OTLP_METRICS_PROTOCOL: Optionally set OTEL metrics export endpoint and protocol if OTEL_COLLECTOR is defined.

• OTEL_SERVICE_NAME: Uses a default or configured service name for OTEL telemetry.

• Additional environment variables can be injected via an included template extra/proxy-env.j2.

Certificate Generation Command

The command block executed inside the container performs:

• Check if /workdir/certs/proxy.ca.pem exists.

• If missing, runs gen_certs with options:

  • -f for force overwrite,

  • -n proxy to name the certificate,

  • -s "localhost" for the subject,

  • Dynamically adds signing keys passed from PROXY_SIGNING_KEYS, mapping filenames as --ed-key-path /workdir/certs/{keyfile},

  • Outputs certificates to /workdir/certs.

• Starts the proxy process, redirecting logs to /logsdir/proxy.log.

Volumes Mounted

• Configuration file: {PROXY_DIR}/config.yaml → /workdir/config.yaml

• Certificates directory: {PROXY_CERTS_DIR} → /workdir/certs

• Logs directory: {PROXY_LOGS} → /logsdir

logrotate Service

This service manages log rotation for the proxy logs:

• Image: Uses the Docker image specified by LOGROTATE_IMAGE.

• Restart Policy: Set to restart unless stopped.

• Environment: Sets a cron schedule (58 * * * *) to run log rotation near the end of every hour.

• Volumes:

  • Mounts the proxy logs directory at /logsdir.

  • Mounts a local logrotate.sh script for execution.

• Command: Runs the logrotate shell script.

• Init: Enabled to ensure proper process reaping inside the container.

Implementation Details and Algorithms

• Dynamic OTEL Configuration: The template constructs OTEL resource attributes by combining various environment variables and defaults. The use of Jinja2 filters and conditional logic enables flexible naming and identification of proxy instances within a network namespace.

• Certificate Management: Before launching the proxy, the service ensures necessary TLS certificates exist, generating them if not. This automates secure communications setup without manual intervention.

• Log Management: The inclusion of a separate logrotate container designed to run on a cron schedule helps maintain log file sizes and prevents disk space exhaustion.

Interactions with Other System Components

• The proxy service depends on certificates and configuration files provided externally via mounted volumes, implying integration with the broader configuration management or secrets infrastructure.

• The dynamic environment variables for telemetry indicate integration with an OpenTelemetry collector service, enabling distributed tracing and metrics aggregation for observability.

• The logrotate service interacts with the proxy service by accessing its log files and managing their lifecycle to ensure system stability.

• The included template extra/proxy-env.j2 (optional) allows injection of further environment customization, potentially integrating with other parts of the deployment pipeline or configuration sources.

Usage Examples

Assuming the following variables are defined in the rendering context:

PROXY_IMAGE: "myproxy:latest"
PROXY_LOG_LEVEL: "info"
PROXY_ID: "node-01"
NODE_GROUP_ID: "groupA"
NETWORK_NAME: "prodnet"
OTEL_MY_HOST_NAME: "host01"
OTEL_COLLECTOR: "otel-collector:4317"
PROXY_SIGNING_KEYS:
  - key1.pem
  - key2.pem
PROXY_DIR: "/etc/proxy"
PROXY_CERTS_DIR: "/etc/proxy/certs"
PROXY_LOGS: "/var/log/proxy"
LOGROTATE_IMAGE: "logrotate:latest"
TEST_NAME: "proxytest"
COMMIT_HASH: "abc123"

Rendering compose.j2 with these variables will produce a Docker Compose configuration where:

• The proxy service includes OTEL attributes like proxy=groupA-node-01, service.namespace=prodnet_proxy, and host name host01.

• Certificates will be generated with keys key1.pem and key2.pem if missing.

• The logrotate service manages the proxy logs according to the specified cron schedule.

Visual Diagram

flowchart TD
A[compose.j2] --> B[proxy Service]
A --> C[logrotate Service]
B --> D[Environment Variables]
B --> E[Volumes]
B --> F[Certificate Generation Command]
B --> G[Proxy Process]
E --> E1[config.yaml]
E --> E2[certs Directory]
E --> E3[logs Directory]
C --> H["Environment Variables (CRON_SCHEDULE)"]
C --> I[Volumes]
C --> J[Logrotate Script Execution]
I --> I1[logs Directory]
I --> I2[logrotate.sh Script]

This flowchart summarizes the structure of the compose.j2 file, showing the two main services and their key components such as environment variables, volumes, and commands executed.