Skip to content

feat: add stash service role - #14

Merged
ikhalilatteib merged 1 commit into
masterfrom
feat/stash-service-role
Nov 20, 2026
Merged

ikhalilatteib merged 1 commit into
masterfrom
feat/stash-service-role

Conversation

@ikhalilatteib

Copy link
Copy Markdown
Collaborator

What

New service role stash: installs the Stash backup agent (plusclouds/backup.agent) on a Linux VM and registers the machine to one of the customer's S3 buckets.

Also replaces the placeholder in agents/backup-agent/README.md, adds the role to the README table, and regenerates manifest.json and checksums.sha256.

Why

Today a customer has to log in to the machine, install Stash and paste a registration token by hand. With this role they pick "stash" and a bucket in the existing service-role picker and the machine does the rest at boot.

How the role works

It is included on every boot, so every step is safe to repeat.

  1. On anything other than x86_64 it prints a message and does nothing (Stash publishes one Linux build, for amd64).
  2. Downloads stash.linux for the release pinned in the role to /usr/local/bin/stash, verified against the SHA-256 pinned next to the version. An existing file that already matches is left alone; a download that does not match is never put in place. Pinned: Stash 3.2.4.
  3. If the machine has no /etc/plusclouds/stash.yaml and the platform supplied a token, runs stash register. Registration writes the config and installs and starts the stash systemd unit itself.
  4. On an already registered machine it only upgrades the binary when the pinned release changes (and restarts the service).

Any failure ends in a rescue that prints which task failed. The boot playbook always continues.

Config keys

Key Set by In defaults.yml
bucket customer yes
registration_token platform no
register_endpoint platform no

The platform resolves bucket inside the customer's own account and only then adds a one-time, short-lived token to this machine's metadata. The two platform keys are left out of defaults.yml on purpose, so they do not show in the panel picker.

Secrets

  • The token is passed through the STASH_REGISTER_TOKEN environment variable, not the command line (needs Stash 3.2.4, which added this).
  • stash register prints the agent API key and the S3 secret on success, so that task and the one reading the role config are no_log.
  • The S3 secret never travels through the metadata.

Unlike the other roles that download release binaries (prometheus, node_exporter, minio), this one verifies a checksum.

Testing

Run in an amd64 container with a playbook shaped like the one IAAS renders:

Scenario Result
Real release, no bucket Downloaded, checksum verified, installed; stash version v3.2.4
Same again 0 changes
Wrong checksum / download fails Nothing installed, rescue message, playbook continues
Bucket set, no token from the platform Installed, not registered, clear message
Token that the endpoint rejects Registration fails, no config written, playbook continues, token absent from the output
Config already present Registration skipped

ansible-lint passes on the role and on the full file set CI checks. manifest.json regenerates identically and checksums.sha256 verifies.

Not tested: a successful registration against the platform, a machine with real systemd, AlmaLinux with SELinux enforcing, and a real VM boot from a config ISO.

Not in this PR

The role does nothing beyond installing Stash until the platform supplies the token. That part (an extension point in IAAS, filled in by leo4) is separate work, as is pointing TOOLKIT_VERSION at a release that contains this role. Windows is not covered.

🤖 Generated with Claude Code

Installs the Stash backup agent from its release binary and registers the
machine to one of the customer's S3 buckets.

- The release and its SHA-256 are pinned together in the role (Stash 3.2.4);
  a download that does not match is never put in place.
- Registration only runs while the machine has no Stash config, with a
  one-time token the platform adds to the role config. The token is passed
  through the environment and the result is never logged.
- A failure in the role never fails the boot playbook.

Replaces the placeholder in agents/backup-agent/README.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@ikhalilatteib
ikhalilatteib merged commit d37f86e into master Nov 20, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant