Neuwerk

Customize The Appliance Image At First Boot

Use cloud-init or equivalent startup metadata to supply Neuwerk YAML config, install extra packages, and add supporting files to the released appliance image.

Use this guide when you want to adapt the released Neuwerk appliance image at first boot without forking the base image build.

When To Customize

Use /etc/neuwerk/config.yaml when your change is runtime configuration: interface selection, DNS settings, default policy behavior, cloud provider hinting, integration identifiers, or dataplane/runtime tuning.

For the full supported path-by-path reference, read Runtime Configuration Reference.

Use cloud-init write_files alone when you only need to place declarative config files or small support assets on disk (for example cert material, local config fragments, or helper scripts).

Use cloud-init package installation when the image is missing a true supporting dependency (for example provider CLI tooling, diagnostics packages, or a helper binary your automation calls).

Do not casually replace Neuwerk’s packaged runtime contract. The released appliance already carries the binary/runtime coupling and launch assumptions; treat that as the baseline unless you intentionally own the full custom runtime contract.

Customize Runtime Settings

/etc/neuwerk/config.yaml is the supported first-boot runtime configuration file.

Write the same subsystem YAML that Neuwerk consumes at steady state. Keep the file explicit and complete enough for your rollout instead of generating flags or env vars on first boot.

Example via cloud-init:

#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

Install Extra Packages

If you need additional dependencies, keep package installation explicit in cloud-init:

#cloud-config
package_update: true
packages:
  - jq
  - ca-certificates
  - dnsutils
runcmd:
  - apt-get -y install --no-install-recommends ethtool
  - systemctl restart neuwerk.service

Use runcmd: when ordering matters (for example when a package must exist before a script executes).

Add Files, Certificates, Or Scripts

Use cloud-init write_files to place certificates, configuration fragments, or helper scripts without rebuilding the image:

#cloud-config
write_files:
  - path: /etc/neuwerk/certs/upstream-ca.pem
    owner: root:root
    permissions: "0644"
    content: |
      -----BEGIN CERTIFICATE-----
      <redacted>
      -----END CERTIFICATE-----
  - path: /usr/local/bin/neuwerk-post-bootstrap.sh
    owner: root:root
    permissions: "0755"
    content: |
      #!/usr/bin/env bash
      set -euo pipefail
      install -d -m 0755 /var/lib/neuwerk/custom
      touch /var/lib/neuwerk/custom/first-boot.stamp
runcmd:
  - /usr/local/bin/neuwerk-post-bootstrap.sh
  - systemctl restart neuwerk.service

Customization Boundaries

  • do add YAML config, files, and supporting packages declaratively
  • do not replace bundled DPDK/runtime libraries casually
  • do not turn managed fleets into hand-tuned pet VMs