Skip to content

README.md

Latest commit

 

History

History
167 lines (117 loc) · 5.28 KB

README.md

File metadata and controls

167 lines (117 loc) · 5.28 KB
Raw

AWS Hypervisor Scripts

This directory contains scripts for managing EC2 instances used as hypervisors for OpenShift development.

Configuration

Environment Setup

Copy the instance.env.template file to instance.env and set all variables to valid values for your user.

cp instance.env.template instance.env
# Edit instance.env with your specific values

Automated RHSM Registration (Hands-off Deployment)

For a completely automated deployment without manual intervention, you can configure Red Hat Subscription Manager (RHSM) activation key variables in your instance.env file:

# Uncomment and set these variables for automated RHSM registration
export RHSM_ACTIVATION_KEY="your-activation-key-here"
export RHSM_ORG="your-org-id-here"

To obtain your activation key and organization ID, refer to Red Hat documentation: https://access.redhat.com/solutions/3341191

When these variables are properly configured, the system will automatically register with RHSM during initialization, eliminating the need for manual registration steps.

Verifying Environment

To verify your environment is setup properly, source the instance.env and ensure it doesn't throw errors:

source ./instance.env

Scripts

Instance Lifecycle Scripts

create.sh

Creates a new EC2 instance using CloudFormation. Reads configuration from instance.env.

./scripts/create.sh

init.sh

Initializes a deployed instance by uploading necessary files and running initial setup.

./scripts/init.sh

start.sh

Starts a stopped EC2 instance and performs necessary post-startup checks.

./scripts/start.sh

stop.sh

Stops a running EC2 instance with interactive cluster management options. The script will:

  • Detect if OpenShift clusters are running
  • Offer options for graceful cluster shutdown or cleanup
  • Safely stop the instance based on user selection
./scripts/stop.sh

destroy.sh

Completely destroys the EC2 instance and all associated CloudFormation resources.

./scripts/destroy.sh

Utility Scripts

ssh.sh

Establishes SSH connection to the EC2 instance using the configured key and user.

./scripts/ssh.sh

print_instance_data.sh

Displays current instance information including IP addresses, instance ID, and connection details.

./scripts/print_instance_data.sh

inventory.sh

Updates the ../openshift-clusters/inventory.ini file with the current instance IP address.

./scripts/inventory.sh

Instance Configuration Script

configure.sh

This script is deployed to the EC2 instance during initialization and should be run after first login to complete the setup.

Location on instance: ~/configure.sh

Interactive Configuration: If RHSM variables are not configured, you will be asked to:

  • Set a password for pitadmin (cockpit access)
  • Register the system using your RHSM login for dnf access to various repositories

Automated Configuration: If you have configured the RHSM activation key variables in your instance.env file, the system registration will be handled automatically, requiring only the pitadmin password configuration.

# Run on the EC2 instance after first login
[ec2-user@ip-x-x-x-x ~]$ ./configure.sh

Graviton (aarch64) Instances

This toolbox supports AWS Graviton bare metal instances (c7g.metal, m7g.metal, r7g.metal) as hypervisors. Graviton instances are ~40% cheaper than equivalent x86_64 instances (e.g., c7g.metal at $2.32/hr vs c5n.metal at $3.89/hr).

Configuration

In your instance.env, set:

export RHEL_HOST_ARCHITECTURE=aarch64
export EC2_INSTANCE_TYPE="c7g.metal"  # or m7g.metal, r7g.metal

AMI auto-detection works for both architectures — the aarch64 → arm64 mapping is handled automatically.

Metal3 Image Overrides

Upstream Metal3 images (quay.io/metal3-io/{ironic,vbmc,sushy-tools}) are x86_64-only. On aarch64 hypervisors, you must override them with arm64 builds in your dev-scripts config (e.g., config_fencing.sh):

if [ "$(uname -m)" = "aarch64" ]; then
    export IRONIC_IMAGE=quay.io/rh-edge-enablement/ironic:2026-06
    export VBMC_IMAGE=quay.io/rh-edge-enablement/vbmc:2026-06
    export SUSHY_TOOLS_IMAGE=quay.io/rh-edge-enablement/sushy-tools:2026-06
fi

See config_fencing_example.sh for a complete example. To rebuild these images, use helpers/build-metal3-arm64.sh (see helpers/README.md).

Known Limitations

  • IPv6 IPI is not supported on aarch64 — nodes enter inspecting but never PXE-boot the IPA ramdisk. Use IP_STACK=v4.
  • CI release auto-discovery does not work — you must set OPENSHIFT_RELEASE_IMAGE explicitly to an aarch64 payload (e.g., quay.io/openshift-release-dev/ocp-release:4.22.0-aarch64).

Script Dependencies

All scripts expect:

  • Properly configured instance.env file
  • AWS CLI configured with appropriate credentials
  • SSH key file accessible at the path specified in instance.env

Data Storage

Instance metadata is stored in the instance-data/ directory:

  • aws-instance-id: EC2 instance ID
  • private_address: Instance private IP
  • public_address: Instance public IP
  • ssh_user: SSH username for the instance
  • Additional CloudFormation and configuration data