User Guide

This guide provides an overview of using Rift for infrastructure deployment and management.

Getting Started

Rift is an Ansible-based automation tool that simplifies infrastructure deployment. The main rift command provides a unified interface for all operations.

Basic Usage

rift [global-options] <command> [command-options]

To see all available commands:

rift help

To see version information:

rift version

Common Deployment Workflow

1. Generate Inventory

Start by creating an inventory file interactively:

rift generate

This command will prompt you for:

Deployment type (baremetal or cloud)
Controller node details
Worker node configurations
Network settings
Authentication parameters

2. Verify Configuration

Validate your inventory and configuration:

rift verify

This checks:

Inventory file syntax and structure
Required group definitions
Variable assignments
Deployment type compatibility

3. Preflight Checks

Prepare the target environment:

rift preflight -k ~/.ssh/id_rsa.pub

This performs:

SSH key deployment to all hosts
System requirements verification
Network connectivity checks
User access validation

4. Deploy Infrastructure

Execute the main deployment:

rift deploy

For cloud deployments:

rift deploy -t cloud

5. Verify Installation

Run post-deployment tests:

rift test

This validates:

Service availability
Configuration correctness
Network connectivity
Performance baselines

Command Categories

Core Commands

generate: Interactive inventory generation
verify: Configuration validation
preflight: Environment preparation
deploy: Infrastructure deployment
test: Installation verification

File Management Commands

dashboard: Grafana dashboard management
dye-add: Add dye signature files
dye-remove: Remove dye signature files
input-add: Add input files with atomic copying

Utility Commands

version: Show version information
help: Display help information

Configuration Options

Global Options

Most commands support these global options:

-t, --type: Deployment type: baremetal (default) or cloud
-i, --inventory: Custom inventory file path (default: inventory/inventory.ini)
-v, --verbose: Enable detailed output for debugging
-k, --key: SSH public key file (required for preflight)

Environment Variables

Customize behavior with environment variables:

# File management user
export RIFT_USER=myuser

# Input file directories
export INPUT_SOURCE_DIR=/custom/source
export INPUT_TARGET_DIR=/custom/target

# File ownership and permissions
export INPUT_OWNER_UID=1000
export INPUT_OWNER_GID=1000
export INPUT_PERMISSIONS=755

Deployment Types

Bare Metal Deployment

For physical servers or VMs with direct access:

rift generate  # Select 'baremetal' when prompted
rift verify
rift preflight -k ~/.ssh/id_rsa.pub
rift deploy

Cloud Deployment

For cloud platforms with specific networking requirements:

rift generate  # Select 'cloud' when prompted
rift verify -t cloud
rift preflight -k ~/.ssh/id_rsa.pub -t cloud
rift deploy -t cloud

File Management

Dashboard Management

Manage Grafana dashboards on the controller node:

# Add a dashboard
rift dashboard add -d monitoring-dashboard.json

# List existing dashboards
rift dashboard list

# Validate before importing
rift dashboard validate -d new-dashboard.json

# Custom Grafana settings
rift dashboard add -d dashboard.json -u http://grafana.example.com:3000 --user admin --password secret

Dye File Processing

Manage dye signature files:

# Add dye files from source directory
rift dye-add --verbose

# List current dye files
rift dye-remove --list

# Remove specific dye file
rift dye-remove malware.dye

# Remove all dye files (with confirmation)
rift dye-remove --all

Input File Processing

Handle input files with atomic operations:

# Add input files atomically
rift input-add --verbose

This command:

Processes all files in the source directory
Uses atomic copying to prevent race conditions
Preserves source files
Sets proper ownership and permissions

Advanced Usage

Custom Inventory Files

Use custom inventory locations:

rift verify -i /path/to/custom/inventory.ini
rift deploy -i /path/to/custom/inventory.ini

Verbose Debugging

Enable detailed output for troubleshooting:

rift deploy -v
rift test -v
rift dashboard add -d dashboard.json -v

Multiple Environments

Manage different environments with separate inventories:

# Development environment
rift deploy -i inventory/dev.ini -v

# Staging environment
rift deploy -i inventory/staging.ini

# Production environment
rift deploy -i inventory/prod.ini

Automation and Scripting

Batch Operations

Automate common workflows:

#!/bin/bash
# deployment-script.sh

echo "Starting deployment..."
rift verify || exit 1
rift preflight -k ~/.ssh/id_rsa.pub || exit 1
rift deploy -v || exit 1
rift test || exit 1

echo "Adding monitoring dashboards..."
for dashboard in dashboards/*.json; do
    rift dashboard add -d "$dashboard"
done

echo "Deployment complete!"

Cron Integration

Automated file processing can be set up with cron jobs. See the respective file management documentation for details:

Dashboard Management: Dashboard Management with Rift
Dye File Management: Dye File Management
Input File Management: Input File Management

Troubleshooting

Common Issues

“Command not found” errors

Ensure the rift script is executable:

chmod +x tools/rift

Permission denied during file operations

File management commands require sudo access. Configure passwordless sudo:

# Add to /etc/sudoers
myuser ALL=(ALL) NOPASSWD: ALL

SSH connection failures

Ensure SSH keys are properly deployed:

rift preflight -k ~/.ssh/id_rsa.pub -v

Inventory validation errors

Check your inventory file syntax:

rift verify -v

Grafana dashboard import failures

Verify Grafana connectivity:

rift dashboard list

Debug Mode

Use verbose mode for detailed debugging:

rift <command> -v

Log Files

Check log files for detailed error information:

Dashboard operations: /var/log/rift/dashboard-<uid>.log
Dye processing: /var/log/dye-processing.log
Input processing: /var/log/input-processing.log

Getting Help

For command-specific help:

rift help
rift dashboard --help
rift dye-remove --help

Best Practices

Always verify before deploying
```
rift verify
```
Use version control for inventory files

Keep your inventory and configuration files in version control.
Test in staging first

Deploy to a staging environment before production:
```
rift deploy -i inventory/staging.ini
```
Monitor deployments

Use verbose mode and check logs:
```
rift deploy -v
```

Validate dashboards before importing

rift dashboard validate -d new-dashboard.json

Use atomic file operations

The input-add command uses atomic operations to prevent race conditions.
Regular testing

Run verification tests after deployments:
```
rift test
```

Security Considerations

SSH Key Management
- Use strong SSH keys
- Rotate keys regularly
- Limit key access to necessary users
Sudo Access
- Configure passwordless sudo only for required commands
- Use specific command restrictions when possible
File Permissions
- Ensure proper ownership and permissions on sensitive files
- Use the built-in permission management in file commands
Network Security
- Ensure proper firewall rules
- Use encrypted connections
- Validate network connectivity during preflight

Next Steps

See Command Reference for detailed command documentation
Check Dashboard Management with Rift for Grafana integration
Review VM Management for VM-specific operations
Read troubleshooting for common issues and solutions