Materia v0.5 has been released! This release was mostly focused on back-end improvements and other infrastructure changes that should help make 0.6.0 be a bit more featureful.

Nevertheless, here’s an overview of some of the more important changes. You can also skip directly to the changelog.

This post also has an associated little walk-through I wrote: How to write a Materia Component

Planner re-work and new settings

Much of this release was focusing on improving the planner which, as you may have guessed, is the big block of code that takes the current state of the host and repository as inputs and figures out the plan it needs to take to get the host reconciled with the desired state. Naturally, the planner is probably the oldest and most complicated chunk of code in the codebase. Unfortunately it was so complex it was making it complicated to add fun new features like dynamic timeouts so I refactored and separated out a bunch of the functions into less complex units. The user-facing changes from this should be minimal.

On my continued journey to clean up Materia’s configuration, I also separated out config options that directly affect plan generation into their own table. The following settings were migrated to the new planner section, with the old locations to be deprecated in 0.6:

cleanup -> planner.cleanup_quadlets
cleanup_volumes -> planner.cleanup_volumes
migrate_volumes -> planner.migrate_volumes
backup_volumes -> planner.backup_volumes

On a related note, the old cleanup function used to also purge components after they failed to install. I don’t think anyone ever used this feature but if you did it’s now under executor.cleanup_components.

Service definitions can use Quadlets

It felt silly to make users have to figure out what service name a Quadlet will translate to, so now Materia can use direct Quadlet resource names in the [[Services]] array.

Dynamic timeouts

Materia now automatically adjusts the timeout it uses for systemctl actions to account for whether the service is dependant on another object. This was specifically added to account for situations like .container Quadlets using Image=otherimage.build: since building a Container can take a while, the default 30s timeout was far too little but adjusting the overall timeout felt off since you’d still want other services to fail in a normal amount of time. Now Materia will A) automatically add some extra time to the timeout free of charge when it detects this situation, B) allow you to manually specify timeouts for individual Services and C) combine Service timeouts when required.

For example: if hello.container relies on hello.build, you can define the following Services for them in the manifest:

[[Services]]
Service = "hello.container"

[[Services]]
Service = "hello.build"
Stopped = true
Timeout = 100

Materia will add hello.build’s 100s timeout to any service actions applied to hello.container.

As part of this, you can also specify Stopped in your [[Services]] entries to tell Materia not to start a service automatically, as used in the .build unit above.

Ensuring Volumes and Networks

While testing dynamic timeouts I noticed something annoying about how .volume Quadlets worked: Since Podman creates those as one-shot units, running them again won’t actually do anything if they’re been run once. This is especially annoying when you do something like remove a Volume quadlet in one update, delete the Podman volume, and re-add it in another since systemd will just see the still active volumename-volume.service and not do anything.

This annoyed me so much that Materia now checks for this scenario and plans an Ensure action to account for it; if it detects a .volume/.network/.image resource being updated and doesn’t see an equivalent Podman resource for it, it will ensure it exists.

Changelog

- refactor: planner has been heavily refactored
- feat: Quadlet resources (.container,.pod,etc) can be used as services in Component services configurations
- feat: Containers that rely on Build or Image quadlets will use dynamic timeouts:
- feat: New `planner` and `executor` config sections, deprecating the old `cleanup`,`cleanup_volumes`,`migrate_volumes`,`backup_volumes` config option locations
- feat: ensure volumes and networks exist when unit already started; this fixes situations like installing,removing, and reinstalling a volume.
- feat/bugfix: materia will no longer attempt to cleanup quadlets that are still in use by other containers