config.j2

Overview

config.j2 is a Jinja2 template file designed to generate a YAML configuration for a proxy service. This configuration primarily sets up TLS certificates, network binding addresses, peer certificates, gossip protocol settings, and block keeper addresses. The template dynamically inserts values based on environment variables, host facts gathered by Ansible, and predefined inventory variables, allowing adaptive configuration tailored to the deployment environment.

File Functionality and Structure

The file is structured as a series of key-value pairs with some keys containing lists or nested mappings. It combines static values with dynamic content generated through Jinja2 templating logic, including conditional statements and loops.

Key Configuration Sections:

• TLS Credentials

  • my_cert: Path to the proxy's TLS certificate file.

  • my_key: Path to the proxy's private key file.

  • peer_certs: List of peer TLS certificates; currently initialized as an empty list.

• Network Binding

  • bind: IP and port where the proxy service listens, defaulting to environment variables or host facts.

  • my_addr: List of the proxy's IP addresses with ports, derived from Ansible facts.

• Subscription and Peer Addresses

  • subscribe: List initialized empty, likely for future subscription endpoints.

  • bk_addrs: Block keeper addresses, either user-defined or automatically selected from the inventory's block keepers group.

• Gossip Protocol Configuration

  • gossip: Nested mapping configuring the gossip service with listening and advertising addresses, seed nodes, and the cluster identifier.

Detailed Explanation of Template Constructs

TLS Credentials

my_cert: "/workdir/certs/proxy.ca.pem"
my_key: "/workdir/certs/proxy.key.pem"
peer_certs: []

• These specify the file system paths for the proxy's certificate and private key.

• peer_certs is initialized as an empty list, intended to hold trusted certificates for peers, supporting secure TLS connections.

Binding Address (bind)

bind: {{ PROXY_BIND_IP | default(HOST_PUBLIC_IP) }}:{{ PROXY_PORT }}

• The proxy binds to an IP and port.

• PROXY_BIND_IP environment variable or Ansible variable takes precedence.

• If PROXY_BIND_IP is not defined, it falls back to HOST_PUBLIC_IP.

• PROXY_PORT defines the port number.

Computing my_addr

my_addr:
{% if ansible_all_ipv4_addresses is defined %}
{% for ip in ansible_all_ipv4_addresses %}
- {{ ip }}:{{ PROXY_PORT }}
{% endfor %}
{% else %}
{% for iface in ansible_interfaces | default([]) %}
{% set fact = hostvars[inventory_hostname]['ansible_' ~ iface] | default({}) %}
{% if fact.ipv4 is defined and fact.ipv4.address is defined %}
- {{ fact.ipv4.address }}:{{ PROXY_PORT }}
{% endif %}
{% endfor %}
{% endif %}

• This section builds a list of IP addresses with ports that the proxy can use.

• It first attempts to use the aggregated list ansible_all_ipv4_addresses.

• If that is not defined, it iterates over each network interface (ansible_interfaces) to extract IPv4 addresses.

• For each valid IPv4 address found, it appends an entry with the port.

Subscription List

subscribe: []

• An empty list placeholder for subscription endpoints, presumably for future dynamic population.

Block Keeper Addresses (bk_addrs)

bk_addrs:
{% if PROXY_BK_ADDRS %}
{% for addr in PROXY_BK_ADDRS %}
- {{ addr }}
{% endfor %}
{% else %}
- {{ hostvars[groups['block_keepers'][0]].HOST_PUBLIC_IP }}:8600
- {{ hostvars[groups['block_keepers'][1]].HOST_PUBLIC_IP }}:8600
- {{ hostvars[groups['block_keepers'][2]].HOST_PUBLIC_IP }}:8600
{% endif %}

• If PROXY_BK_ADDRS is defined (likely a list of addresses), it is used to populate block keeper addresses.

• Otherwise, the template defaults to the first three hosts in the Ansible group block_keepers, appending port 8600 to their public IPs.

• This ensures block keeper addresses are always configured, either explicitly or from defaults.

Gossip Protocol Configuration

gossip:
  listen_addr: {{ HOST_PUBLIC_IP }}:{{ PROXY_GOSSIP_PORT }}
  advertise_addr: {{ HOST_PUBLIC_IP }}:{{ PROXY_GOSSIP_PORT }}
  seeds:
  {% for seed in SEEDS -%}
  - {{ seed }}
  {% endfor -%}
  cluster_id: {{ NETWORK_NAME }}

• Configures gossip communication parameters:

  • listen_addr and advertise_addr define the IP and port for gossip communication using host public IP and a gossip port variable.

  • seeds is a list of seed nodes used to bootstrap the gossip cluster, iterated from the SEEDS list.

  • cluster_id is an identifier for the gossip cluster, set from NETWORK_NAME.

Environment and Inventory Dependencies

• The template relies heavily on Ansible facts such as ansible_all_ipv4_addresses, ansible_interfaces, and hostvars.

• It uses custom variables like PROXY_BIND_IP, PROXY_PORT, PROXY_BK_ADDRS, SEEDS, HOST_PUBLIC_IP, NETWORK_NAME, and PROXY_GOSSIP_PORT.

• These variables must be defined in the inventory or playbooks, or passed as extra variables.

Usage Example

When rendered with proper variables and facts, the template produces a YAML configuration, for example:

my_cert: "/workdir/certs/proxy.ca.pem"
my_key: "/workdir/certs/proxy.key.pem"
peer_certs: []

bind: 192.168.1.10:8080
my_addr:
- 192.168.1.10:8080
- 10.0.0.1:8080

subscribe: []
bk_addrs:
- 192.168.1.20:8600
- 192.168.1.21:8600
- 192.168.1.22:8600

gossip:
  listen_addr: 192.168.1.10:7000
  advertise_addr: 192.168.1.10:7000
  seeds:
  - 192.168.1.20:7000
  - 192.168.1.21:7000
  cluster_id: mainnet

Interactions with Other System Components

• Ansible Inventory and Facts: The template queries Ansible's gathered facts to dynamically determine IP addresses and interface details.

• Block Keepers: The block keeper hosts are referenced by their group block_keepers to populate addresses, linking this configuration to the block keeper service.

• Gossip Network: The gossip configuration aligns this proxy node into a gossip cluster identified by NETWORK_NAME and seeded by known nodes.

• TLS Certificate Management: References to certificate files imply integration with certificate management and security components.

All these integrations ensure this configuration facilitates secure and network-aware proxy operation within a distributed system.

Mermaid Flowchart Diagram

flowchart TD
A[Start: Render Template] --> B{TLS Credentials}
B --> C[my_cert path]
B --> D[my_key path]
B --> E[peer_certs list]
A --> F{Network Binding}
F --> G[bind: IP:Port]
F --> H[my_addr List]
H --> I{If ansible_all_ipv4_addresses defined}
I -->|Yes| J[Loop IPs -> my_addr]
I -->|No| K[Loop interfaces -> my_addr]
A --> L[subscribe: Empty List]
A --> M{Block Keeper Addresses}
M --> N{If PROXY_BK_ADDRS defined}
N -->|Yes| O[Use PROXY_BK_ADDRS]
N -->|No| P[Use block_keepers group IPs]
A --> Q[Gossip Configuration]
Q --> R[listen_addr]
Q --> S[advertise_addr]
Q --> T[seeds list]
Q --> U[cluster_id]
style B fill:#f9f,stroke:#333,stroke-width:1px
style F fill:#bbf,stroke:#333,stroke-width:1px
style M fill:#bfb,stroke:#333,stroke-width:1px
style Q fill:#fbf,stroke:#333,stroke-width:1px

This flowchart summarizes the main sections and their decision points during the template rendering process.