HD — Chef Deployment Example

This directory contains a reference Chef cookbook for deploying a HD instance and its supporting services.

Note: This cookbook is an example. It is derived from the sandbox Docker Compose configuration and the docs/k8s_example Helm chart. Adapt it to your environment's secrets management, network layout, and certificate infrastructure before production use.

Directory Structure

chef_example/
├── README.md                     # This file
├── metadata.rb                   # Cookbook metadata + dependencies
├── Policyfile.rb                 # Modern Chef workflow (replaces Berkshelf)
├── attributes/
│   └── default.rb                # All configurable attributes (image tags, CIDRs, secrets placeholders)
├── recipes/
│   ├── default.rb                # Optional services dispatcher
│   ├── dms_ca.rb                 # DMS-CA
│   ├── dms_core.rb               # DMS-Core
│   ├── dms_webux.rb              # DMS-WebUX
│   ├── dms_opa_engine.rb         # DMS-OPA-Engine
│   ├── dms_traefik.rb            # DMS-internal Traefik
│   ├── otel_collector.rb         # OTEL Collector
│   ├── sentry_relay.rb           # Sentry Relay
│   ├── sc_scc.rb                 # Storage Cluster Controller
│   ├── sc_sn.rb                  # Storage Node
│   ├── hd_proxy.rb               # HD Proxy
│   ├── hd_ingester.rb            # [optional] Message bus ingester
│   ├── fe_traefik.rb             # [optional] Front-End Traefik
│   ├── hd_mcp.rb                 # [optional] HD MCP server
│   ├── hd_graphql.rb             # [optional] HD GraphQL server
│   └── hd_data_explore.rb        # [optional] Data Explorer UI
└── roles/
    ├── fermihdi_dms.rb           # Role for DMS hosts
    ├── fermihdi_scc.rb           # Role for SCC hosts
    ├── fermihdi_sn.rb            # Role for SN hosts
    ├── fermihdi_proxy.rb         # Role for proxy hosts
    └── fermihdi_optional.rb      # Role for optional service hosts

Quick Start

Install Dependencies

cd docs/chef_example
chef install   # Resolves Policyfile.lock.json

Configure Global Attributes

Edit attributes/default.rb or set attributes in a role/environment/node policy:

override['fermihdi']['image_tag']          = '2.0.3'
override['fermihdi']['dms_host']           = '192.168.10.10'  # IP of DMS host
override['fermihdi']['control_plane_cidr'] = '10.147.0.0/24'
override['fermihdi']['data_plane_cidr']    = '10.150.0.0/24'
override['fermihdi']['observability_cidr'] = '10.146.0.0/24'

Configure Storage Clusters

Set the storage_clusters attribute in a role or node policy — not in attributes/default.rb (no real tokens there):

# In a role or Chef Vault data bag:
override['fermihdi']['storage_clusters'] = [
  {
    'name'      => 'sc-1',
    'scc_host'  => 'sc1-scc-host',          # Must match Chef node name
    'sn_hosts'  => ['sc1-sn-1', 'sc1-sn-2', 'sc1-sn-3'],
    'scc_token' => chef_vault_item('fermihdi', 'sc1_scc_token')['value'],
    'sn_tokens' => [
      chef_vault_item('fermihdi', 'sc1_sn1_token')['value'],
      chef_vault_item('fermihdi', 'sc1_sn2_token')['value'],
      chef_vault_item('fermihdi', 'sc1_sn3_token')['value'],
    ]
  },
  {
    'name'      => 'sc-2',
    'scc_host'  => 'sc2-scc-host',
    'sn_hosts'  => ['sc2-sn-1', 'sc2-sn-2'],
    'scc_token' => '...',
    'sn_tokens' => ['...', '...']
  }
]

The sc_scc recipe finds its SC by matching the node's hostname/fqdn against scc_host.
The sc_sn recipe finds its SC and SN index by matching against sn_hosts.

Assign Node Roles

On your Chef server:

# DMS host
knife node run_list add dms-host-01 'role[fermihdi_dms]'

# SCC host
knife node run_list add sc1-scc-host 'role[fermihdi_scc]'

# SN hosts
knife node run_list add sc1-sn-1 'role[fermihdi_sn]'
knife node run_list add sc1-sn-2 'role[fermihdi_sn]'

# Proxy host
knife node run_list add proxy-host-01 'role[fermihdi_proxy]'

Enable Optional Services

Set attributes on the optional host's node or in its role:

override['fermihdi']['optional']['enable_ingester']        = true
override['fermihdi']['optional']['enable_fe_traefik']      = true
override['fermihdi']['optional']['enable_hd_graphql']      = true
override['fermihdi']['optional']['enable_hd_mcp']          = true
override['fermihdi']['optional']['enable_hd_data_explore'] = true

Then assign the optional role:

knife node run_list add optional-host-01 'role[fermihdi_optional]'

Run Chef Client

# On each target node:
chef-client

# Or push via Chef Infra Server:
knife ssh 'role:fermihdi_dms' 'sudo chef-client'

Service Groups

Network Port Reference

Prerequisites

• Chef Infra Client ≥ 17 on all target nodes
• chef/docker cookbook (declared in metadata.rb, resolved via Policyfile)
• Docker installed on all target nodes
• Hugepages configured on SCC and SN hosts (hugepagesz=2M hugepages=1024 in GRUB)
• Chef Vault or equivalent for secret injection