Neuwerk

Launch Neuwerk From The Released Cloud Image

Download the signed release artifact, convert and import it into AWS, Azure, or GCP, then configure first boot with config.yaml and cloud-init.

Use this guide to launch Neuwerk from the published cloud appliance release instead of building a custom image first.

Before importing or booting the image, plan for separate management and dataplane NICs. Neuwerk expects distinct management and dataplane interfaces, and startup can fail if only one usable NIC is present.

Download And Verify The Release

Download one release into a dedicated working directory. The minimum asset set is:

  • neuwerk-ubuntu-24.04-minimal-amd64.qcow2.zst.part-*
  • restore-qcow2.sh
  • SHA256SUMS
  • SHA256SUMS.sig
  • neuwerk-release-signing-key.asc

Example download flow from GitHub Releases (replace <release-tag> with the published tag you are deploying, for example v0.15.2):

RELEASE_TAG="<release-tag>"
BASE_URL="https://github.com/moolen/neuwerk/releases/download/${RELEASE_TAG}"

curl -fLO "${BASE_URL}/restore-qcow2.sh"
curl -fLO "${BASE_URL}/SHA256SUMS"
curl -fLO "${BASE_URL}/SHA256SUMS.sig"
curl -fLO "${BASE_URL}/neuwerk-release-signing-key.asc"

# Split image parts use numeric 3-digit suffixes (part-000, part-001, ...).
# Increase the upper bound if a release contains many parts.
for i in $(seq 0 63); do
  part="$(printf '%03d' "${i}")"
  curl -fLO "${BASE_URL}/neuwerk-ubuntu-24.04-minimal-amd64.qcow2.zst.part-${part}" || break
done

Expected Neuwerk release-signing fingerprint:

  • DC34EB84D498D1445B68CB405E6B936CF37928C3

Then verify signature and checksums:

gpg --import neuwerk-release-signing-key.asc
gpg --show-keys --with-fingerprint neuwerk-release-signing-key.asc
gpg --verify SHA256SUMS.sig SHA256SUMS
sha256sum -c SHA256SUMS

If verification passes, restore the published image:

bash ./restore-qcow2.sh

Expected output artifact:

  • neuwerk-ubuntu-24.04-minimal-amd64.qcow2

Convert And Import For Your Cloud

AWS

Convert the restored qcow2 to raw:

qemu-img convert \
  -f qcow2 \
  -O raw \
  neuwerk-ubuntu-24.04-minimal-amd64.qcow2 \
  neuwerk-ubuntu-24.04-minimal-amd64.raw

Upload and import:

aws s3 cp \
  neuwerk-ubuntu-24.04-minimal-amd64.raw \
  s3://<bucket>/neuwerk-ubuntu-24.04-minimal-amd64.raw

aws ec2 import-image \
  --description "Neuwerk ubuntu-24.04-minimal-amd64" \
  --disk-containers "Format=raw,UserBucket={S3Bucket=<bucket>,S3Key=neuwerk-ubuntu-24.04-minimal-amd64.raw}"

Poll until the AMI is ready:

aws ec2 describe-import-image-tasks --import-task-ids <import-task-id>

Azure

Convert the restored qcow2 to a fixed VHD:

qemu-img convert \
  -f qcow2 \
  -O vpc \
  -o subformat=fixed \
  neuwerk-ubuntu-24.04-minimal-amd64.qcow2 \
  neuwerk-ubuntu-24.04-minimal-amd64.vhd

Upload and import as a specialized OS disk:

az storage blob upload \
  --account-name <storage-account> \
  --container-name <container> \
  --name neuwerk-ubuntu-24.04-minimal-amd64.vhd \
  --file neuwerk-ubuntu-24.04-minimal-amd64.vhd \
  --type page

az disk create \
  --resource-group <resource-group> \
  --name neuwerk-ubuntu-24.04-minimal-amd64 \
  --source https://<storage-account>.blob.core.windows.net/<container>/neuwerk-ubuntu-24.04-minimal-amd64.vhd

az vm create \
  --resource-group <resource-group> \
  --name neuwerk-appliance \
  --attach-os-disk neuwerk-ubuntu-24.04-minimal-amd64 \
  --os-type Linux \
  --specialized

GCP

Convert the restored qcow2 to the required disk.raw:

qemu-img convert \
  -f qcow2 \
  -O raw \
  neuwerk-ubuntu-24.04-minimal-amd64.qcow2 \
  disk.raw

Package, upload, and import:

tar --format=oldgnu -Sczf \
  neuwerk-ubuntu-24.04-minimal-amd64-disk.raw.tar.gz \
  disk.raw

gcloud storage cp \
  neuwerk-ubuntu-24.04-minimal-amd64-disk.raw.tar.gz \
  gs://<bucket>/neuwerk-ubuntu-24.04-minimal-amd64-disk.raw.tar.gz

gcloud compute images create neuwerk-ubuntu-24-04-minimal-amd64 \
  --source-uri=gs://<bucket>/neuwerk-ubuntu-24.04-minimal-amd64-disk.raw.tar.gz

For manually imported images, install or validate the GCP guest environment on first boot before relying on normal Compute Engine guest integration, metadata handling, or guest-agent behavior.

Configure First Boot

The supported override file is:

  • /etc/neuwerk/config.yaml

Write the same YAML document Neuwerk consumes at steady state. Keep first boot declarative by delivering the final runtime config file directly.

At minimum, set:

  • bootstrap.management_interface
  • bootstrap.data_interface
  • bootstrap.cloud_provider
  • dns.target_ips
  • dns.upstreams
  • policy.default
  • any integration.*, dpdk.*, or tls_intercept.* settings your rollout requires

For the full supported config surface and defaults, read Runtime Configuration Reference.

If you also need supporting packages, certificates, helper scripts, or a fuller first-boot customization pattern, read Customize The Appliance Image At First Boot.

Cloud-init-friendly example:

#cloud-config
write_files:
  - path: /etc/neuwerk/config.yaml
    owner: root:root
    permissions: "0644"
    content: |
      version: 1
      bootstrap:
        management_interface: eth0
        data_interface: eth1
        cloud_provider: aws
        data_plane_mode: dpdk
      dns:
        target_ips:
          - 10.20.0.10
        upstreams:
          - 10.20.0.2:53
          - 10.20.0.3:53
      policy:
        default: deny
      integration:
        mode: aws-asg
        aws:
          region: eu-central-1
          vpc_id: vpc-0123456789abcdef0
          asg_name: neuwerk-prod-asg
runcmd:
  - systemctl restart neuwerk.service

Start And Verify Neuwerk

On first boot (or after updating config.yaml), restart the service:

sudo systemctl restart neuwerk.service
sudo journalctl -u neuwerk.service -n 200 --no-pager

Then verify service health and readiness:

curl -skf https://127.0.0.1:8443/health
curl -skf https://127.0.0.1:8443/ready

For first admin access, follow Get Admin Access after the node reports ready.

Production Next Steps

After first launch: