Hegel

Deep Dive into Hegel

Hegel is the metadata service within the Tinkerbell stack. It serves instance-specific metadata to bare-metal machines during provisioning. This metadata is crucial for configuring the machine correctly and can include information such as the machine’s role, network configuration, and custom user-defined data.

Hegel Architecture Overview

Hegel is similar to metadata services provided by cloud providers like AWS (EC2 instance metadata). In a bare-metal environment, Hegel serves a similar purpose by providing metadata to machines being provisioned via Tinkerbell.

Key concepts around Hegel:

  1. Metadata: Information about the machine that is used during the provisioning process. This can include network configuration, role information, operating system details, etc.
  2. Metadata Sources: Hegel aggregates metadata from various sources, such as the Tinkerbell API, user-defined metadata, and potentially external systems.
  3. Metadata Serving: Machines query Hegel during provisioning to obtain their specific metadata, which is then used to configure the machine.

Core Components of Hegel

  • Hegel Server: The primary component that serves metadata to machines. It listens on a network interface and responds to HTTP requests for metadata.
  • Metadata API: Hegel exposes a RESTful API that allows machines to query for their metadata. The API can be queried by the machines being provisioned to get details like network settings, operating system configurations, etc.
  • Tinkerbell Integration: Hegel is tightly integrated with Tinkerbell and often retrieves metadata directly from the Tink server, making it accessible to the machines.

Hegel Metadata Flow

Here’s how Hegel works in the context of a Tinkerbell provisioning workflow:

  1. Machine Boots: A bare-metal machine boots and initializes its network interface.
  2. Hegel Query: As part of the boot process, the machine sends a request to the Hegel service, asking for its metadata.
  3. Metadata Aggregation: Hegel collects and aggregates metadata for the machine. This metadata might include details like:
  • Network configuration (IP address, gateway, DNS, etc.)
  • Machine role (e.g., control plane, worker node)
  • Operating system to install
  • Custom user data (e.g., specific configuration scripts)
  1. Metadata Response: Hegel responds with the aggregated metadata, which the machine uses to configure itself during provisioning.
  2. Configuration Execution: The machine uses the metadata provided by Hegel to execute the provisioning tasks, such as setting up networking, installing the operating system, and running custom scripts.

Working Examples with Hegel

Let’s explore a practical example of how Hegel is used during a Tinkerbell provisioning process.

1. Setting Up Hegel

Hegel is typically deployed as a part of the Tinkerbell stack, often within a Kubernetes cluster. Assuming Tinkerbell is already running, Hegel can be deployed using the following steps:

Deploy Hegel

Hegel can be deployed as a containerized service. Here’s a basic Kubernetes manifest to deploy Hegel:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hegel
  namespace: tink-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hegel
  template:
    metadata:
      labels:
        app: hegel
    spec:
      containers:
      - name: hegel
        image: quay.io/tinkerbell/hegel:latest
        ports:
        - containerPort: 50061
          name: http

This manifest deploys Hegel in the tink-system namespace and exposes it on port 50061.

Service Definition

You’ll also need a service to expose Hegel within your Kubernetes cluster:

apiVersion: v1
kind: Service
metadata:
  name: hegel
  namespace: tink-system
spec:
  selector:
    app: hegel
  ports:
  - protocol: TCP
    port: 80
    targetPort: 50061

This service makes Hegel available to the machines being provisioned.

2. Defining Metadata in Tink

Hegel retrieves metadata from various sources, including Tink. When you register hardware in Tink, you can include metadata that Hegel will serve.

Here’s an example of a hardware definition with metadata:

id: "d5eb5a20-16a7-11ec-82a8-0242ac130003"
metadata:
  facility: "on-prem"
  instance:
    device_1: "00:1e:67:1c:3e:84"
    manufacturer: "Dell"
    plan: "c3.small.x86"
    state: "provisioning"
  user_data:
    key1: "value1"
    key2: "value2"
network:
  interfaces:
    - dhcp:
        arch: "x86_64"
        mac: "00:1e:67:1c:3e:84"
  netboot:
    allow_pxe: true
    osie: {
      commit: "",
      os: "ubuntu",
    }

In this definition:

  • metadata: Provides general information about the machine, including its state and plan.
  • user_data: Custom data that can be used during the provisioning process, accessible via Hegel.

3. Querying Metadata from Hegel

When a bare-metal machine is booting, it sends an HTTP request to Hegel to retrieve its metadata. This is typically done using a simple HTTP client or command like curl.

Here’s an example of a machine querying Hegel:

curl http://hegel:50061/metadata

Hegel responds with a JSON object containing the metadata for that machine. An example response might look like this:

{
  "id": "d5eb5a20-16a7-11ec-82a8-0242ac130003",
  "metadata": {
    "facility": "on-prem",
    "instance": {
      "device_1": "00:1e:67:1c:3e:84",
      "manufacturer": "Dell",
      "plan": "c3.small.x86",
      "state": "provisioning"
    },
    "user_data": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "network": {
    "interfaces": [
      {
        "dhcp": {
          "arch": "x86_64",
          "mac": "00:1e:67:1c:3e:84"
        }
      }
    ],
    "netboot": {
      "allow_pxe": true,
      "osie": {
        "commit": "",
        "os": "ubuntu"
      }
    }
  }
}

The machine can then use this metadata to perform tasks such as:

  • Configuring network interfaces based on the network section.
  • Running custom scripts using the user_data section.
  • Adjusting its behavior based on the state (e.g., provisioning, active).

4. Using Metadata in Provisioning Scripts

During provisioning, the metadata obtained from Hegel can be used directly in scripts. For example:

#!/bin/bash
# Fetch metadata from Hegel
METADATA=$(curl -s http://hegel:50061/metadata)

# Extract values using jq or similar tools
DEVICE_ID=$(echo $METADATA | jq -r .metadata.instance.device_1)
PLAN=$(echo $METADATA | jq -r .metadata.instance.plan)
USER_KEY1=$(echo $METADATA | jq -r .metadata.user_data.key1)

# Use the metadata in the provisioning process
echo "Provisioning device $DEVICE_ID with plan $PLAN"
echo "Custom user data: $USER_KEY1"

This script retrieves metadata from Hegel, extracts specific fields using jq, and uses them to guide the provisioning process.

Advanced Hegel Use Cases

  1. Dynamic Metadata: Hegel can serve dynamic metadata that changes over time, based on the machine’s current state or external inputs. This allows for more complex provisioning logic where the machine’s behavior adapts to its environment.
  2. Custom Metadata Sources: While Hegel primarily interacts with Tink, it can also be configured to pull metadata from other sources, such as a custom API or a database. This is useful for organizations with complex infrastructure environments.
  3. Metadata-Based Conditional Logic: Provisioning workflows can use metadata to implement conditional logic. For example, machines with a specific role (e.g., “database server”) can follow a different provisioning path than other machines.

Conclusion

Hegel is a crucial component of the Tinkerbell stack, providing the metadata necessary for correctly configuring bare-metal machines during provisioning. By serving metadata from Tink and other sources, Hegel enables dynamic, flexible provisioning workflows that can be tailored to specific environments and use cases. Understanding and effectively using Hegel is key to leveraging the full power of Tinkerbell for bare-metal automation.