Automated Deployment

Configure automated server deployment with preboot configurations and PXE boot

Ralph’s deployment module enables automated server provisioning using preboot configurations for Kickstart, Preseed, cloud-init, and iPXE.

Overview

The deployment system provides:

• Automated OS installation - Deploy Linux distributions automatically
• Multiple boot methods - Kickstart, Preseed, cloud-init, iPXE
• Template variables - Dynamic configuration based on asset data
• PXE network boot - Boot from network for hands-off deployment
• Deployment tracking - Monitor deployment status and history

Preboot Configuration

Preboot configurations are templates that define how servers should be deployed.

Supported Configuration Types

Kickstart

• RedHat, CentOS, Fedora deployments
• Anaconda-based installations

Preseed

• Debian and Ubuntu deployments
• Debian-installer based systems

Meta-data and User-data

• Ubuntu 20.04+ using cloud-init/casper
• Cloud-style configuration

iPXE

• Network boot configuration
• Custom boot menus
• Chainloading options

Creating Preboot Configurations

1. Navigate to Preboot Configurations

   Go to Deployment → Preboot configuration (/deployment/prebootconfiguration/)

2. Add Configuration

   Click Add preboot configuration

3. Configure Basic Settings

   Fill in:

   • Name - Reference name for this configuration
   • Type - Select kickstart, preseed, meta-data, user-data, iPXE, or script
   • Description - Optional documentation
4. Write Configuration Template

   Enter your configuration in the Configuration field.

   Use template variables (see below) for dynamic values.

5. Save

   Click Save to create the configuration.

Template Variables

Ralph provides variables that are replaced with actual values during deployment.

Available Variables

Wrap variables in {{ }} to use them:

Asset Information

• {{ hostname }} - Full hostname (e.g., ralph123.dc1.mydc.net)
• {{ dc }} - Data center name (e.g., data-center1)
• {{ domain }} - Domain name (e.g., dc1.mydc.net)

Configuration Management

• {{ configuration_class_name }} - Configuration class (e.g., www)
• {{ configuration_module }} - Configuration module (e.g., ralph)
• {{ configuration_path }} - Full path (e.g., ralph/www)

Service Information

• {{ service_env }} - Service environment (e.g., Backup systems - prod)
• {{ service_uid }} - Service unique ID (e.g., sc-123)

Deployment URLs

• {{ deployment_id }} - Unique deployment ID
• {{ kernel }} - URL to kernel image
• {{ initrd }} - URL to initrd image
• {{ kickstart }} - URL to kickstart file
• {{ preseed }} - URL to preseed file
• {{ script }} - URL to custom script
• {{ meta_data }} - URL to cloud-init meta-data
• {{ user_data }} - URL to cloud-init user-data
• {{ done_url }} - URL to mark deployment complete
• {{ deployment_base }} - Base URL for deployment
• {{ ralph_instance }} - Ralph instance URL

Example: Kickstart Template

lang en_US
langsupport en_US
keyboard us

# Set hostname from Ralph
network --hostname={{ hostname }}

# Download post-install script
%post
curl {{ script }} | bash

# Register with configuration management
echo "{{ configuration_path }}" > /etc/puppet/manifest.txt

# Mark deployment as complete
curl -X POST {{ done_url }}
%end

Example: Cloud-Init User-Data

#cloud-config
hostname: {{ hostname }}
fqdn: {{ hostname }}

packages:
  - puppet-agent
  - vim

runcmd:
  - puppet config set server puppet.{{ domain }}
  - puppet config set environment {{ service_env }}
  - systemctl enable puppet
  - systemctl start puppet
  - curl -X POST {{ done_url }}

Example: iPXE Configuration

#!ipxe

kernel {{ kernel }} hostname={{ hostname }} ks={{ kickstart }}
initrd {{ initrd }}
boot

Ralph Instance URL

By default, URLs use http://127.0.0.1:8000. Configure this in settings:

RALPH_INSTANCE = 'https://ralph.example.com'

All deployment URLs will use this base URL.

Deployment Workflow

1. Prepare Asset

   Create or select the data center asset to deploy.

   Ensure it has:

   • Hostname (or will be auto-generated)
   • Service environment
   • Configuration path (if using config management)
2. Configure PXE Boot

   Set up your DHCP/PXE server to:

   • Boot from network
   • Load iPXE or initial bootloader
   • Point to Ralph’s deployment endpoint
3. Initiate Deployment

   Trigger deployment in Ralph or boot the server from network.

   Ralph generates a unique deployment ID and serves configuration files.

4. Monitor Progress

   The deployment process:

   • Downloads kernel and initrd
   • Loads kickstart/preseed configuration
   • Installs operating system
   • Runs post-installation scripts
   • Calls done_url when complete
5. Verify Completion

   Check deployment status in Ralph.

   The asset should be marked as successfully deployed.

Integration Examples

Puppet Integration

# In kickstart %post section
%post
# Install Puppet
yum install -y puppet-agent

# Configure from Ralph variables
puppet config set server puppet.{{ domain }}
puppet config set environment production
puppet config set certname {{ hostname }}

# Set configuration path
echo "{{ configuration_path }}" > /etc/puppet/role.txt

# Enable and start
systemctl enable puppet
systemctl start puppet
%end

Ansible Integration

# Post-installation script
#!/bin/bash

# Install Ansible requirements
apt-get update
apt-get install -y python3 python3-pip
pip3 install ansible

# Fetch playbook from Ralph
curl {{ ralph_instance }}/api/deployment/{{ deployment_id }}/playbook/ > /tmp/setup.yml

# Run playbook
ansible-playbook /tmp/setup.yml \
  --extra-vars "hostname={{ hostname }}" \
  --extra-vars "service={{ service_env }}"

# Report completion
curl -X POST {{ done_url }}

Custom Scripts

Serve custom scripts via the {{ script }} URL:

# In kickstart or preseed
%post
curl {{ script }} -o /tmp/custom-setup.sh
bash /tmp/custom-setup.sh
%end

The script can use Ralph’s API to fetch additional configuration.

Advanced Configuration

Multiple Configurations

Create different preboot configurations for:

• Different OS distributions (CentOS vs Ubuntu)
• Different environments (production vs development)
• Different server roles (web server vs database)

Select the appropriate configuration during deployment.

Dynamic Kernel Parameters

iPXE configurations can pass dynamic parameters:

kernel {{ kernel }} \
  hostname={{ hostname }} \
  ks={{ kickstart }} \
  service={{ service_uid }} \
  dc={{ dc }} \
  console=ttyS0,115200

Deployment Completion Hook

Always call {{ done_url }} at the end of deployment:

# Last step in post-install
curl -X POST {{ done_url }}

This marks the deployment as complete in Ralph.

Tips and Best Practices

Test Templates: Test preboot configurations on non-production systems before deploying to production.

Version Control: Store preboot configurations in git for change tracking and rollback capability.

Error Logging: Include logging in post-installation scripts to troubleshoot failed deployments.

Security: Use HTTPS for Ralph instance URL to protect credentials in configuration files.

Always call {{ done_url }} at the end of deployment. Otherwise, Ralph won’t know the deployment completed.

Troubleshooting

Variables not replaced

• Ensure you’re using the correct syntax: {{ variable_name }}
• Check that the variable exists in the available variables list
• Verify the asset has the required data (hostname, service env, etc.)

Deployment hangs

• Check network connectivity to Ralph instance
• Verify RALPH_INSTANCE setting is correct and accessible
• Check firewall rules allow access to deployment URLs
• Review logs on the deploying server

Configuration not found

• Ensure preboot configuration is saved and active
• Verify you selected the correct configuration type
• Check URL paths are correct

Related Documentation

• DCIM - Managing deployed assets
• Custom Fields - Configuration variables
• External: Kickstart documentation
• External: Debian Preseed
• External: Cloud-init documentation