ibk

Image Builder Packer plugin

HashiCorp Packer plugin for image-builder-cli and bootc-image-builder. Builds are happening on a remote linux machine over SSH.

Preparing the environment

All building is done remotely over SSH connection, you need to create an instance or VM with a user dedicated to image building and sudo permission to start podman (or docker) without password or root account.

adduser -m builder

Either setup a password

passwd builder

or preferably deploy a public SSH key (execute from machine with packer)

ssh-copy-id builder@host

Make sure the container runtime can be executed without password.

cat <<EOF >/etc/sudoers.d/builder
builder ALL=(ALL) NOPASSWD: /usr/bin/podman, /usr/bin/docker
EOF

Finally, install podman or docker:

dnf -y install podman

Cross-architecture building is currently not supported so make sure the builder host architecture is correct.

Install packer

Install packer on your machine not on the builder instance/VM, for example on Fedora:

sudo dnf install -y dnf-plugins-core
sudo dnf config-manager addrepo --from-repofile=https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
sudo dnf -y install packer

On MacOS:

brew tap hashicorp/tap
brew install hashicorp/tap/packer

Building using image-builder-cli

Create a packer template named template.pkr.hcl:

packer {
  required_plugins {
    image-builder = {
      source = "github.com/lzap/image-builder"
      version = ">= 0.0.2"
    }
  }
}

source "image-builder" "example" {
    build_host {
        hostname = "buildhost.example.com"
        username = "builder"
    }

    distro = "centos-9"

    blueprint = <<BLUEPRINT
[[customizations.user]]
name = "user"
password = "changeme"
groups = ["wheel"]
BLUEPRINT

    image_type = "minimal-raw"
}

build {
    sources = [ "source.image-builder.example" ]
}

See osbuild blueprint reference for more info about blueprint format.

Perform the build via:

  packer init template.pkr.hcl
  packer build template.pkr.hcl

The image builder plugin will print last several lines from the image builder output as an artifact. To see more detailed output:

  PACKER_LOG=1 packer build template.pkr.hcl

Config mapping

For more info: https://github.com/osbuild/image-builder-cli

• build_host.hostname - IP or hostname with optional SSH port (required)
• build_host.username - either root or username with sudo permissions (required)
• build_host.password - SSH password when SSH keys are not available
• distro - maps to --distro
• blueprint - maps to --blueprint
• image_type - maps to image type argument

If there is an option missing, file an issue for us.

Building using bootc-image-builder

Create a packer template named template.pkr.hcl:

packer {
  required_plugins {
    image-builder = {
      source = "github.com/lzap/image-builder"
      version = ">= 0.0.2"
    }
  }
}

source "image-builder" "example" {
    build_host {
        hostname = "buildhost.example.com"
        username = "builder"
    }

    container_repository = "quay.io/centos-bootc/centos-bootc:stream9"

    blueprint = <<BLUEPRINT
[[customizations.user]]
name = "user"
password = "changeme"
groups = ["wheel"]
BLUEPRINT

    image_type = "raw"
}

build {
    sources = [ "source.image-builder.example" ]
}

See osbuild blueprint reference for more info about blueprint format.

Perform the build via:

  packer init template.pkr.hcl
  packer build template.pkr.hcl

The image builder plugin will print last several lines from the image builder output as an artifact. To see more detailed output:

  PACKER_LOG=1 packer build template.pkr.hcl

Config mapping

For more info: https://github.com/osbuild/bootc-image-builder

• build_host.hostname - IP or hostname with optional SSH port (required)
• build_host.username - either root or username with sudo permissions (required)
• build_host.password - SSH password when SSH keys are not available
• container_repository - maps to container repository argument
• blueprint - maps to --blueprint
• image_type - maps to --type
• rootfs - maps to --rootfs
• aws_upload.ami_name - maps to AMI cloud uploader configuration
• aws_upload.s3_bucket - maps to AMI cloud uploader configuration
• aws_upload.region - maps to AMI cloud uploader configuration
• aws_upload.access_key_id - maps to AMI cloud uploader configuration
• aws_upload.secret_access_key - maps to AMI cloud uploader configuration

If there is an option missing, file an issue for us.

Dry run

If you want to perform, for any reason, a dry run where the main build command is echoed to the console rather than executed, just set IMAGE_BUILDER_DRY_RUN=1 environment variable when executing packer. Good for demos or testing the integration.

Building without Packer

To test this library directly without packer, do:

go run github.com/lzap/packer-plugin-image-builder/cmd/ibpacker/ -help

Use options to initiate a build:

Usage of ibpacker:
  -arch string
        architecture (default "x86_64")
  -blueprint string
        path to blueprint file
  -distro string
        distribution name (fedora, centos, rhel, ...) (default "fedora")
  -dry-run
        dry run
  -hostname string
        SSH hostname or IP with optional port (e.g. example.com:22)
  -type string
        image type (minimal-raw, qcow2, ...) (default "minimal-raw")
  -username string
        SSH username

For example:

git clone github.com/lzap/packer-plugin-image-builder
go run ./cmd/ibpacker/ \
    -hostname example.com \
    -username builder \
    -distro centos-9 \
    -type minimal-raw \
    -blueprint ./cmd/ibpacker/blueprint_example.toml

Testing

To run unit and integration test against mock SSH server running on localhost:

make test

Do not invoke tests directly via go test command because some tests require packer binary to be present in the ./build directory and will be skipped if it is not present.

Keys in internal/sshtest/keys.go are just dummy (test only) keys, you may receive false positives from security scanners about leaked keys when cloning the repo.

LICENSE

Apache Version 2.0