Skip to main content

​
Overview

Polystack Compute relies on image-side configuration to inject SSH keys, assign hostnames, configure network interfaces, and deliver user data at instance launch. Images that do not meet these requirements will fail to boot correctly, be unreachable over SSH, or require manual reconfiguration after launch.
Prerequisites
  • An active Polystack account with appropriate permissions
  • Access to the Polystack Dashboard or CLI configured with credentials
  • API credentials sourced (source openrc.sh)
Test compatibility using a CirrOS image first. CirrOS meets all requirements and launches in seconds, making it ideal for validating your environment before importing production images.

​
Required Components

Images missing cloud-init will not receive SSH keys at launch. The instance boots but remains inaccessible unless a password was baked into the image.

​
Cloud-Init Configuration

Cloud-init runs during the first boot of every new instance and handles:
  • SSH public key injection from the keypair selected at launch
  • Hostname assignment and /etc/hosts update
  • User-data script execution (shell scripts, Ansible, etc.)
  • Network interface configuration via DHCP

​
Install cloud-init

Install cloud-init and cloud-utils

Install on Ubuntu or Debian

Clean the cloud-init state

Remove any cached instance data before capturing the image:
Reset cloud-init state
The instance data directory /var/lib/cloud/ is cleared and ready for re-initialization.

​
SSH Access

Polystack injects the selected keypair’s public key into the instance’s authorized keys file via cloud-init. Ensure the image is configured correctly for key-based authentication.

Disable password authentication

Edit /etc/ssh/sshd_config and set:
/etc/ssh/sshd_config
This prevents brute-force attacks on instances with public IP addresses.

Remove pre-seeded SSH host keys

Host keys are regenerated on first boot by cloud-init. Remove existing keys so every instance gets unique host keys:
Remove SSH host keys

Verify cloud-init SSH module is enabled

Confirm ssh is listed in the cc_ssh cloud-init module:
Check cloud-init configuration
SSH host keys are regenerated and the instance keypair is injected on first boot.

​
Disk Partitioning

Use a single root partition

Polystack Compute resizes the root disk to the flavor’s allocated size at launch. A single root partition (/) is the simplest layout and works reliably with cloud-growpart.Avoid:
  • LVM (Logical Volume Manager) — growpart does not automatically extend LVM logical volumes
  • Separate /boot partitions unless required by the OS
  • Swap partitions — use swap files instead, which cloud-init can create dynamically
Both GPT and MBR partition tables are supported. GPT is recommended for disks over 2 TB. When using GPT, ensure a BIOS boot partition is present for GRUB compatibility with non-UEFI instances.

​
Network Configuration

Images must be configured to obtain IP addresses via DHCP. Polystack assigns instance IP addresses through its DHCP service. Static IP configuration in the image causes network conflicts and prevents proper instance addressing.

Configure DHCP on all interfaces

Ensure the primary network interface is set to DHCP. For cloud-init-managed images, cloud-init handles network configuration automatically via the metadata service.Remove any persistent interface rules that bind MAC addresses to interface names:
Remove persistent network rules (Debian/Ubuntu)

Disable network manager caching

On images using NetworkManager, clear cached connection profiles:
Remove NetworkManager connection cache

​
Console Logging

Serial console output enables troubleshooting when SSH is unavailable. Enable it by adding the serial console to the kernel command line.

Edit GRUB default configuration

Edit /etc/default/grub and add the serial console parameters:
/etc/default/grub

Regenerate GRUB configuration

Regenerate GRUB (Debian/Ubuntu)
Regenerate GRUB (RHEL-compatible)
Console output streams to both the local display and the serial port.

​
Validation

Verify your image meets all requirements before uploading to Polystack.

Pre-upload checklist

Run this checklist on the image before capturing or uploading:
  • cloud-init --version returns version 22.4 or later
  • cloud-init clean has been run to clear cached state
  • SSH host keys removed from /etc/ssh/ssh_host_*
  • PasswordAuthentication no set in sshd_config
  • Root partition uses ext4 or xfs
  • Serial console enabled in GRUB
  • Network interface configured for DHCP
  • No static IP addresses in network configuration files
  • Persistent network interface rules removed
After launching an instance from the image, verify:
Check cloud-init completed successfully
Expected output:
Expected result
Also confirm SSH key injection:
Check injected SSH keys

​
Next Steps

Get Cloud Images

Download pre-built images for Ubuntu, AlmaLinux, Rocky Linux, and more.

Modify Images

Customize existing images using virt-customize and guestfish.

Convert Formats

Convert VMDK, VHD, or RAW images to the recommended QCOW2 format.

Upload an Image

Upload a compatible image to the Polystack Image Service.