{"id":44030018,"url":"https://github.com/noahwhite/alloy-sysext-build","last_synced_at":"2026-03-18T02:08:27.355Z","repository":{"id":333597667,"uuid":"1137905976","full_name":"noahwhite/alloy-sysext-build","owner":"noahwhite","description":"Build systemd-sysext images for Grafana Alloy on Flatcar Container Linux","archived":false,"fork":false,"pushed_at":"2026-03-10T00:04:23.000Z","size":121,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-10T07:35:33.458Z","etag":null,"topics":["flatcar","flatcar-linux","grafana","grafana-alloy","observability","sysext","systemd-sysext"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/noahwhite.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-20T02:01:57.000Z","updated_at":"2026-03-10T00:04:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/noahwhite/alloy-sysext-build","commit_stats":null,"previous_names":["noahwhite/alloy-sysext-build"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/noahwhite/alloy-sysext-build","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahwhite%2Falloy-sysext-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahwhite%2Falloy-sysext-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahwhite%2Falloy-sysext-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahwhite%2Falloy-sysext-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/noahwhite","download_url":"https://codeload.github.com/noahwhite/alloy-sysext-build/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noahwhite%2Falloy-sysext-build/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30642184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-18T01:41:58.583Z","status":"online","status_checked_at":"2026-03-18T02:00:07.824Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flatcar","flatcar-linux","grafana","grafana-alloy","observability","sysext","systemd-sysext"],"created_at":"2026-02-07T18:41:04.399Z","updated_at":"2026-03-18T02:08:27.329Z","avatar_url":"https://github.com/noahwhite.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Grafana Alloy systemd-sysext Build Tooling\n\nBuild tooling for creating Grafana Alloy systemd-sysext images for Flatcar Container Linux.\n\n## Purpose\n\nThis repository provides automated build tooling to package [Grafana Alloy](https://grafana.com/docs/alloy/) as a systemd-sysext image for Flatcar Container Linux. systemd-sysext allows you to extend the immutable Flatcar base system with additional binaries and services without modifying the root filesystem.\n\n## What is systemd-sysext?\n\nsystemd-sysext (system extension) images provide a way to overlay additional files onto an immutable OS like Flatcar Container Linux. When merged, the files in the sysext image appear in the host filesystem at their defined paths (e.g., `/usr/local/bin/alloy`).\n\nKey benefits:\n- **Immutability**: Extends the system without modifying the base OS\n- **Atomic operations**: Images are merged/unmerged as atomic units\n- **Version management**: Easy to swap versions by changing which image is active\n- **Persistence**: Survives OS updates\n\n## Download Pre-built Images\n\nPre-built sysext images are available at:\n```\nhttps://ghost-sysext-images.separationofconcerns.dev/alloy-{VERSION}-amd64.raw\nhttps://ghost-sysext-images.separationofconcerns.dev/alloy-{VERSION}-amd64.raw.sha256\n```\n\nExample in Butane configuration:\n```yaml\nstorage:\n  files:\n    - path: /opt/extensions/alloy/alloy-1.10.2-amd64.raw\n      mode: 0644\n      contents:\n        source: https://ghost-sysext-images.separationofconcerns.dev/alloy-1.10.2-amd64.raw\n        verification:\n          hash: sha256-feb76c5aa5408c267d59508bd39d322c20d6fce44abd686296f4d0ca87e42671\n  links:\n    - target: /opt/extensions/alloy/alloy-1.10.2-amd64.raw\n      path: /etc/extensions/alloy.raw\n      hard: false\n```\n\n## Build Requirements\n\n- Docker or Podman\n- Internet connection (to download Alloy releases)\n\nThe build container includes all necessary tools:\n- Ubuntu 22.04 base\n- `curl`, `wget`, `unzip`\n- `squashfs-tools` (for creating the image)\n- `xz-utils` (for compression)\n\n## Usage\n\n### Build the Container Image\n\n```bash\ndocker build -t alloy-sysext-builder .\n```\n\n### Run the Build\n\n```bash\nmkdir -p output\ndocker run --rm \\\n  -v \"${PWD}/output:/output\" \\\n  -v \"${PWD}/build-alloy-sysext.sh:/build/build-alloy-sysext.sh:ro\" \\\n  alloy-sysext-builder \\\n  /build/build-alloy-sysext.sh\n```\n\nThis will:\n1. Download the specified Alloy version from GitHub releases\n2. Create the systemd-sysext directory structure\n3. Install the Alloy binary\n4. Generate a systemd service unit\n5. Create extension metadata\n6. Package everything into a squashfs image\n7. Generate SHA256 checksums\n\n### Customize the Build\n\nEdit the configuration variables in `build-alloy-sysext.sh`:\n\n```bash\nVERSION=\"1.10.2\"           # Alloy version to build\nARCHITECTURE=\"amd64\"       # Target architecture\nSYSEXT_NAME=\"alloy\"        # Extension name\n```\n\n## Output Format\n\nThe build produces the following files in the `output/` directory:\n\n```\nalloy-1.10.2-amd64.raw          # Architecture-specific sysext image\nalloy-1.10.2-amd64.raw.sha256   # SHA256 checksum\nalloy-1.10.2.raw                # Compatibility version (same content)\nalloy-1.10.2.raw.sha256         # SHA256 checksum\n```\n\n### Sysext Image Contents\n\nThe sysext image contains:\n\n```\n/usr/local/bin/alloy                                    # Alloy binary\n/usr/lib/systemd/system/alloy.service                   # systemd unit\n/usr/lib/extension-release.d/extension-release.alloy    # Extension metadata\n```\n\n## Using the sysext Image on Flatcar\n\n### 1. Copy the Image to Flatcar\n\n```bash\nscp output/alloy-1.10.2-amd64.raw core@your-flatcar-host:/var/lib/extensions/\n```\n\n### 2. Merge the Extension\n\n```bash\nsystemd-sysext refresh\nsystemd-sysext list\n```\n\n### 3. Verify the Binary\n\n```bash\nwhich alloy\nalloy --version\n```\n\n### 4. Configure and Enable the Service\n\nCreate your Alloy configuration:\n\n```bash\nsudo mkdir -p /var/mnt/storage/alloy\nsudo vi /var/mnt/storage/alloy/config.alloy\n```\n\nEnable and start the service:\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable alloy.service\nsudo systemctl start alloy.service\nsudo systemctl status alloy.service\n```\n\n### 5. View Logs\n\n```bash\njournalctl -u alloy.service -f\n```\n\n## systemd-sysext Image Format\n\nThe sysext image is a squashfs filesystem compressed with xz. It must include:\n\n1. **Extension metadata** at `/usr/lib/extension-release.d/extension-release.\u003cname\u003e`:\n   ```\n   ID=_any\n   ARCHITECTURE=x86-64\n   ```\n\n   - `ID=_any` makes it compatible with any OS (not just Flatcar)\n   - `ARCHITECTURE` must match the host architecture\n\n2. **File hierarchy** under standard paths:\n   - `/usr/local/bin/` for binaries\n   - `/usr/lib/systemd/system/` for systemd units\n   - Other `/usr/` paths as needed\n\n3. **Squashfs format** with xz compression for optimal size\n\n## Service Configuration\n\nThe included systemd service (`alloy.service`) is configured with:\n\n- **Config location**: `/var/mnt/storage/alloy/config.alloy`\n- **State directory**: `/var/lib/alloy` (automatically created)\n- **Security hardening**: NoNewPrivileges, ProtectSystem, ProtectHome, PrivateTmp\n- **Automatic restart**: On failure with 10s delay\n\nYou can customize the service by editing `build-alloy-sysext.sh` before building.\n\n## Automated Builds\n\nGitHub Actions automatically builds new sysext images when:\n- A new release is created in this repository\n- The workflow is manually triggered with a version parameter\n\nBuilt images are automatically uploaded to the Cloudflare R2 bucket.\n\n## Repository Structure\n\n```\n.\n├── Dockerfile              # Container image for building sysext images\n├── build-alloy-sysext.sh   # Build script\n├── README.md               # This file\n├── LICENSE                 # MIT License\n└── .github/\n    └── workflows/\n        └── build-and-publish.yml  # CI/CD pipeline (future)\n```\n\n## Updating Alloy\n\nTo update to a new Alloy version:\n\n1. Update the `VERSION` variable in `build-alloy-sysext.sh`\n2. Rebuild the image\n3. Copy the new image to `/var/lib/extensions/` on your Flatcar host\n4. Remove the old image\n5. Run `systemd-sysext refresh`\n6. Restart the service: `sudo systemctl restart alloy.service`\n\n## Troubleshooting\n\n### Extension not merging\n\nCheck extension status:\n```bash\nsystemd-sysext status\n```\n\nVerify the image format:\n```bash\nunsquashfs -ll /var/lib/extensions/alloy-1.10.2-amd64.raw\n```\n\n### Service not starting\n\nCheck logs:\n```bash\njournalctl -u alloy.service -n 50\n```\n\nVerify binary:\n```bash\nfile /usr/local/bin/alloy\n/usr/local/bin/alloy --version\n```\n\nCheck config syntax:\n```bash\n/usr/local/bin/alloy fmt /var/mnt/storage/alloy/config.alloy\n```\n\n## References\n\n- [Grafana Alloy Documentation](https://grafana.com/docs/alloy/)\n- [systemd-sysext Documentation](https://www.freedesktop.org/software/systemd/man/systemd-sysext.html)\n- [Flatcar Container Linux Documentation](https://www.flatcar.org/docs/latest/)\n\n## Contributing\n\nContributions are welcome! Please open an issue or pull request.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoahwhite%2Falloy-sysext-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnoahwhite%2Falloy-sysext-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoahwhite%2Falloy-sysext-build/lists"}