HD — Ansible Deployment Example

This directory contains a reference Ansible deployment for a HD instance and its supporting services.

Note: These playbooks are examples. They are derived from the sandbox Docker Compose configuration and the docs/k8s_example Helm chart. Adapt them to your environment's secrets management, network layout, and certificate infrastructure before production use.

Directory Structure

ansible_example/
├── README.md                            # This file
├── site.yml                             # Master playbook (imports all groups)
├── inventory/
│   ├── hosts.yml                        # Host groups — set your target hosts here
│   └── group_vars/
│       ├── all.yml                      # Global vars (registry, CIDRs, OTEL URL)
│       ├── dms.yml                      # DMS group vars + secret placeholders
│       ├── sc.yml                       # Storage Cluster topology (storage_clusters list)
│       └── optional.yml                 # Optional service toggles & vars
├── playbooks/
│   ├── dms.yml                          # DMS services play
│   ├── sc.yml                           # Storage Cluster play (SCCs + SNs)
│   ├── edge.yml                         # Edge play (HD Proxy)
│   └── optional.yml                     # Optional services play
└── roles/
    ├── fermihdi_common/                 # Common: dirs, Docker install
    ├── dms_ca/                          # DMS-CA (certificate authority)
    ├── dms_core/                        # DMS-Core (management engine)
    ├── dms_webux/                       # DMS-WebUX (Astro.build web UI)
    ├── dms_opa_engine/                  # DMS-OPA-Engine (policy engine)
    ├── dms_traefik/                     # DMS-internal Traefik proxy
    ├── otel_collector/                  # OpenTelemetry Collector
    ├── sentry_relay/                    # Sentry Relay (error aggregation)
    ├── sc_scc/                          # Storage Cluster Controller
    ├── sc_sn/                           # Storage Node
    ├── hd_proxy/                        # HD Proxy (query gateway)
    ├── hd_ingester/                     # [optional] Message bus ingester
    ├── fe_traefik/                      # [optional] Front-End Traefik
    ├── hd_graphql/                      # [optional] HD GraphQL server
    ├── hd_mcp/                          # [optional] HD MCP server
    └── hd_data_explore/                 # [optional] Data Explorer UI

Quick Start

1. Configure your inventory

Edit inventory/hosts.yml and set the ansible_host of each service group to your actual server IPs/hostnames.

2. Configure global variables

Edit inventory/group_vars/all.yml:

• Set fermihdi_image_tag to your release tag
• Set fermihdi_control_plane_cidr, fermihdi_data_plane_cidr, fermihdi_observability_cidr to match your host network layout

3. Configure Storage Clusters

Edit inventory/group_vars/sc.yml — this is where you define how many Storage Clusters you want and how many SNs each one has:

storage_clusters:
  - name: "sc-1"
    scc_host: "sc1-scc-host"       # Must match inventory hostname
    sn_hosts:
      - "sc1-sn-host-01"           # Must match inventory hostnames
      - "sc1-sn-host-02"
      - "sc1-sn-host-03"
    scc_token: "..."               # Inject via ansible-vault
    sn_tokens: ["...", "...", "..."]

  - name: "sc-2"
    scc_host: "sc2-scc-host"
    sn_hosts:
      - "sc2-sn-host-01"
    scc_token: "..."
    sn_tokens: ["..."]

The playbook automatically derives node names as <name>-scc and <name>-sn-<N>.

4. Inject secrets

Never commit real secrets. Use ansible-vault to encrypt group_vars/dms.yml:

ansible-vault encrypt inventory/group_vars/dms.yml

Or use the Vault lookup plugin:

dms_ca_bundle_pem: "{{ lookup('hashi_vault', 'secret=fermihdi/dms:ca_bundle_pem') }}"

5. Enable optional services

Edit inventory/group_vars/optional.yml and set any of the enable_* flags to true:

enable_ingester: true
enable_fe_traefik: true
enable_hd_graphql: true
enable_hd_mcp: true
enable_hd_data_explore: true

6. Run the deployment

# Full deployment
ansible-playbook -i inventory/hosts.yml site.yml --ask-vault-pass

# Deploy only DMS services
ansible-playbook -i inventory/hosts.yml playbooks/dms.yml

# Deploy only Storage Clusters
ansible-playbook -i inventory/hosts.yml playbooks/sc.yml

# Deploy only optional services
ansible-playbook -i inventory/hosts.yml playbooks/optional.yml

Service Groups

Network Port Reference

Prerequisites

• Ansible ≥ 2.14 with community.docker collection installed:

  ansible-galaxy collection install community.docker
  

• Docker installed on all target hosts (roles will attempt to install it if absent)
• Hugepages configured on SCC and SN hosts (2Mi hugepages required):

  # /etc/default/grub — add to GRUB_CMDLINE_LINUX:
  # hugepagesz=2M hugepages=1024
  

• SSH access to all target hosts with sudo privileges

DMS-CA Isolation

The DMS-CA must only be reachable from DMS-Core. In this example the DMS-CA runs on the same host as DMS-Core (fermihdi_dms group). Use your firewall (iptables, nftables, security groups) to restrict port 6989 inbound to DMS-Core's IP only.