Add builder.output_options configuration for buildx output parameters

[sjparkinson]

This change adds a new configration option, that allows you to pass buildx build output parameters¹.

I can see this mainly being used to configure compression.

For a bit of context, I found #1549 when trying to sort this out myself today.

Using zstd should(?) be a bit faster to deploy that the default gzip, compression level 3 is the default level. I'm using the patch from the discussion on a Ubuntu Hetzner VM with no issues. Useful when deploying locally on a slow upstream connection with a local registry.

Configuration would look like:

builder:
  arch: amd64
  output_options:
    compression: zstd
    force-compression: true

Worth noting, kamal build push already supports an --output option, so you could achieve this today as a two command deploy:

bin/kamal build push --output registry,compression=zstd
bin/kamal deploy --skip-push

Footnotes

1. https://docs.docker.com/build/exporters/image-registry/#synopsis ↩

[Copilot]

Pull request overview

This PR introduces a new builder.output configuration option to let users append Docker buildx output type parameters (e.g., compression settings) to the docker buildx build --output=... invocation used during image pushes.

Changes:

• Add builder.output to configuration and expose it via Kamal::Configuration::Builder.
• Append configured output parameters to the buildx --output flag during builder.push.
• Document the new setting and add configuration/command coverage in tests.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/configuration/builder_test.rb	Adds tests for default and configured builder.output.
test/commands/builder_test.rb	Ensures buildx push command includes appended output parameters.
lib/kamal/configuration/docs/builder.yml	Documents the new builder.output config option (and drives config validation).
lib/kamal/configuration/builder.rb	Adds output accessor to the builder configuration object.
lib/kamal/commands/builder/base.rb	Extends buildx push command to include the configured output parameters.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The PR title mentions builder.outputs, but the actual config key documented/implemented here is builder.output (singular). To avoid confusing users, align the naming across the PR title/docs/implementation (either rename the key or update the title/wording to singular).

[djmb]

I think we should go with something like:

output_options:
  compression: zstd
  compression-level: 3
  force-compression: true

And raise a configuration error if type is set as Kamal controls that itself.

[sjparkinson]

Thanks @djmb, makes sense to me and I've refactored to that with b4330e9.

[djmb]

I think we should go with something like:

output_options:
  compression: zstd
  compression-level: 3
  force-compression: true

And raise a configuration error if type is set as Kamal controls that itself.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

[sjparkinson]

Shout if this is a concern to address. Because a string value comes first in the example this works fine right now.

https://github.com/sjparkinson/kamal/blob/86bd5910034ac17fc993ac904f760bd2efe93765/lib/kamal/configuration/docs/builder.yml#L139-L142