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¶

Configure your inventory¶

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

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

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>.

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') }}"

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

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¶

Group	Services	Hosts Group
DMS	DMS-CA, DMS-Core, DMS-WebUX, DMS-OPA-Engine, DMS-Traefik, OTEL Collector, Sentry Relay	`fermihdi_dms`
SC	SCC + N×SNs per Storage Cluster	`fermihdi_scc`, `fermihdi_sn`
Edge	HD Proxy	`fermihdi_edge`
Optional	hd_ingester, Front-End Traefik, hd_graphql, hd_mcp, hd_data_explore	`fermihdi_optional`

Network Port Reference¶

Port	Protocol	Plane
`6985`	TLS/mTLS	DMS Internal
`6986`	TLS/mTLS	Control Plane
`6987`	TCP	Data Plane (FHDWP)
`6988`	UDP	NORM Multicast (Auxiliary)
`6989`	TLS/mTLS	DMS-CA Plane
`8080`	HTTP	Observability

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.