Skip to content

Rego source policy additional UX #3567

Closed

Description

@tonistiigi

This issue is to discuss UX changes for #3539 for additional control and helpers.

Build

build and bake automatically load a default policy file based on the Dockerfile path(if one exists):

Dockerfile        → Dockerfile.rego
foo.Dockerfile    → foo.Dockerfile.rego

When building from a remote context, these files are also loaded from a remote context, like the Dockerfile.

Users may override or extend this behavior using:

--policy [csv] [--policy [csv]]...

Available options

filename=<path>

Add a policy file. Can be combined with reset.

reset=<bool>

If set, the currently loaded policy (eg. the default based on Dockerfile) is ignored and the policy set is replaced.
After reset=true, only explicitly provided filename= entries are used.

disabled=<bool>

Disable policy evaluation entirely. Using this together with other policy flags is an error.

strict=<bool>

Require policy enforcement.
If true, builds fail when running against a BuildKit that does not support policies.
Policy file load or compile errors always fail regardless of this setting.
Initially, this will default to false but may change somewhere in the future where BuildKit instances without policy support become a rarity.

log-level=<level>

Set policy logging verbosity (e.g., debug).


Optional / Under Consideration

ignore=<expr>

Example:

--policy ignore=image.repo=alpine

Potential mechanism for skipping specific sources when generating the policy input.
Not sure if we need smth. like this.


Policy Subcommand

These commands help writing policies and ensuring that they continue to work correctly after code changes.

buildx policy print-schema

Print the JSON schema describing the policy input object.

buildx policy test <path>

Execute a _test.rego file with fixed inputs, similar to opa test.
Inputs are not fetched via BuildKit, but part of the test already.

buildx policy eval --filename=<name> [--print] [source]

Evaluate the specified policy against the input for source.

  • These are the same source values as can be specified in --build-context.
    The source is resolved in BuildKit and then checked against the policy definition.

  • If --print is set, the policy isn’t evaluated; the input object is printed instead.
    Useful for exploring and validating values that policies are written against or for capturing input definitions for tests.

  • If source is not specified, the command expects an input object JSON on stdin.

@crazy-max @dvdksn @AkihiroSuda @colinhemmings

Activity

  1. crazy-max commented on Dec 17, 2025

    @crazy-max
    Member

    build and bake automatically load a default policy file based on the Dockerfile path(if one exists):

    Dockerfile        → Dockerfile.rego
    foo.Dockerfile    → foo.Dockerfile.rego
    

    When building from a remote context, these files are also loaded from a remote context, like the Dockerfile.

    I like it, this is a predictable convention and will "just work" for most users. The strict "next to Dockerfile only" behavior is simpler and probably best.

    For bake I wonder if we could have something similar to dockerfile-inline like:

    target "default" {
    	dockerfile-inline = <<EOT
    FROM alpine:latest
    RUN echo hello
    EOT
    	policy-inline = <<EOT
    package docker
    default allow := false
    allow if input.local
    allow if {
        input.image.hasProvenance
    }
    decision := {"allow": allow}
    EOT
    }

    Btw could we also have the bake equivalent like docker-bake.rego that would be applied to all targets? If a target already has a policy then it would be merged.

    filename=<path>

    Add a policy file. Can be combined with reset.

    A bit verbose, I think file would be better to be consistent with build or bake commands UX with --file?

    reset=<bool>

    If set, the currently loaded policy (eg. the default based on Dockerfile) is ignored and the policy set is replaced. After reset=true, only explicitly provided filename= entries are used.

    I'm not sure about this attribute. Could we have instead an operator to append or override similar to --set with bake?:

    # append foo.repo (or add if no default found)
    --policy filename+=foo.rego
    # override with foo.rego (or add if no default found)
    --policy filename=foo.rego
    # override with foo.rego and append bar.rego
    --policy filename=foo.rego filename+=bar.rego
    

    strict=<bool>

    Require policy enforcement. If true, builds fail when running against a BuildKit that does not support policies. Policy file load or compile errors always fail regardless of this setting. Initially, this will default to false but may change somewhere in the future where BuildKit instances without policy support become a rarity.

    Not directly related but I see a use case where orgs would want to enforce policies globally. I guess this would be some configuration on daemon side?

    ignore=<expr>

    Example:

    --policy ignore=image.repo=alpine
    

    Potential mechanism for skipping specific sources when generating the policy input. Not sure if we need smth. like this.

    Looks reasonable to leave this out for first iteration and revisit once there is a real-world demand. The expression syntax at the CLI level can be a bit tricky.

    Policy Subcommand

    I like the mirroring of OPA tooling, which will be familiar to policy authors, specially for testing: https://www.openpolicyagent.org/docs/policy-testing

  2. tonistiigi commented on Dec 17, 2025

    @tonistiigi
    MemberAuthor

    Btw could we also have the bake equivalent like docker-bake.rego that would be applied to all targets? If a target already has a policy then it would be merged.

    Policies associated with Dockerfile are loaded automatically in bake, and there should be a key to match build --policy. If want to use same policy across Dockerfiles then that can be done with normal bake target sharing.

    A bit verbose, I think file would be better to be consistent with build or bake commands UX with --file?

    👍

    I'm not sure about this attribute. Could we have instead an operator to append or override similar to --set with bake?:

    That would only reset the filename though. While reset resets everything.

  3. crazy-max commented on Jan 5, 2026

    @crazy-max
    Member

    That would only reset the filename though. While reset resets everything.

    When you say "resets everything" you mean filenames and default rego attached to Dockerfile? If so I think my suggestion still works:

    # set foo.rego (override default one if available)
    --policy filename=foo.rego
    
  4. tonistiigi commented on Jan 6, 2026

    @tonistiigi
    MemberAuthor

    @crazy-max Without the reset, --policy filename would mean that an additional policy is added, where both need to pass.

  5. added this to the v0.31.0 milestone on Jan 8, 2026
  6. crazy-max commented on Jan 15, 2026

    @crazy-max
    Member

    Tested Buildx 0.31.0-rc1, we could improve the progress output, specially for multiplatform builds:

    $ docker buildx build --platform linux/amd64,linux/arm64 -f 10-xx-external.Dockerfile .
    ...
    #1 loading policies 10-xx-external.Dockerfile.rego
    #1 0.481 checking policy for source local://context
    #1 0.490 policy decision for source local://context: ALLOW []
    #1 0.564 [linux/amd64] checking policy for source docker-image://docker.io/tonistiigi/xx:1.8.0@sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #1 0.564 checking policy for source docker-image://docker.io/library/alpine:latest@sha256:865b95f46d98cf867a156fe4a135ad3fe50d2056aa3f25ed31662dff6da4eb62
    #1 0.564 checking policy for source docker-image://docker.io/tonistiigi/xx:1.8.0@sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #1 0.565 checking policy for source docker-image://docker.io/library/alpine:latest@sha256:865b95f46d98cf867a156fe4a135ad3fe50d2056aa3f25ed31662dff6da4eb62
    #1 0.573 hack/utils.rego:4: compare sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6 add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #1 0.573 hack/utils.rego:4: compare sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6 add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #1 0.574 10-xx-external.Dockerfile.rego:12: alpine false
    #1 0.574 policy decision for source docker-image://docker.io/library/alpine:latest@sha256:865b95f46d98cf867a156fe4a135ad3fe50d2056aa3f25ed31662dff6da4eb62: ALLOW []
    #1 0.574 10-xx-external.Dockerfile.rego:12: alpine false
    #1 0.574 policy decision for source docker-image://docker.io/library/alpine:latest@sha256:865b95f46d98cf867a156fe4a135ad3fe50d2056aa3f25ed31662dff6da4eb62: ALLOW []
    #1 0.574 10-xx-external.Dockerfile.rego:12: tonistiigi/xx true
    #1 0.574 hack/utils.rego:4: compare sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6 add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #1 0.574 policy decision for source docker-image://docker.io/tonistiigi/xx:1.8.0@sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6: ALLOW []
    #1 0.574 10-xx-external.Dockerfile.rego:12: tonistiigi/xx true
    #1 0.574 hack/utils.rego:4: compare sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6 add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #1 0.574 policy decision for source docker-image://docker.io/tonistiigi/xx:1.8.0@sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6: ALLOW []
    #1 ...
    

    Maybe prefixing with [os/arch] and group by platform?:

    $ docker buildx build --platform linux/amd64,linux/arm64 -f 10-xx-external.Dockerfile .
    ...
    #1 [linux/amd64] loading policies 10-xx-external.Dockerfile.rego
    #1 1.328 checking policy for source local://context
    #1 1.336 policy decision for source local://context: ALLOW []
    #1 1.409 checking policy for source docker-image://docker.io/library/alpine:latest@sha256:865b95f46d98cf867a156fe4a135ad3fe50d2056aa3f25ed31662dff6da4eb62
    #1 1.409 checking policy for source docker-image://docker.io/tonistiigi/xx:1.8.0@sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #1 1.417 hack/utils.rego:4: compare sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6 add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #1 1.418 10-xx-external.Dockerfile.rego:12: tonistiigi/xx true
    #1 1.418 hack/utils.rego:4: compare sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6 add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #1 1.418 policy decision for source docker-image://docker.io/tonistiigi/xx:1.8.0@sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6: ALLOW []
    #1 1.418 10-xx-external.Dockerfile.rego:12: alpine false
    #1 1.419 policy decision for source docker-image://docker.io/library/alpine:latest@sha256:865b95f46d98cf867a156fe4a135ad3fe50d2056aa3f25ed31662dff6da4eb62: ALLOW []
    #1 DONE 1.7s
    #1 ...
    #2 [linux/arm64] loading policies 10-xx-external.Dockerfile.rego
    #2 1.328 checking policy for source local://context
    #2 1.336 policy decision for source local://context: ALLOW []
    #2 1.409 checking policy for source docker-image://docker.io/library/alpine:latest@sha256:865b95f46d98cf867a156fe4a135ad3fe50d2056aa3f25ed31662dff6da4eb62
    #2 1.409 checking policy for source docker-image://docker.io/tonistiigi/xx:1.8.0@sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #2 1.417 hack/utils.rego:4: compare sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6 add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #2 1.418 10-xx-external.Dockerfile.rego:12: tonistiigi/xx true
    #2 1.418 hack/utils.rego:4: compare sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6 add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6
    #2 1.418 policy decision for source docker-image://docker.io/tonistiigi/xx:1.8.0@sha256:add602d55daca18914838a78221f6bbe4284114b452c86a48f96d59aeb00f5c6: ALLOW []
    #2 1.418 10-xx-external.Dockerfile.rego:12: alpine false
    #2 1.419 policy decision for source docker-image://docker.io/library/alpine:latest@sha256:865b95f46d98cf867a156fe4a135ad3fe50d2056aa3f25ed31662dff6da4eb62: ALLOW []
    #2 DONE 1.7s
    #2 ...
    
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions