Tag Patterns

Tag patterns let you control which container image tags a customer can pull under a specific license. This is useful for limiting access to certain versions of your software based on the license tier or support agreement.

How It Works

When you create or edit a license, you can specify a tag pattern that restricts which tags the customer can pull. If no pattern is set, the customer can pull any tag from the licensed repositories.

When a customer attempts to pull an image, Breakwater checks whether the requested tag matches the license's tag pattern. If it doesn't match, the pull is denied.

Pattern Types

No Pattern (Allow All)

Leave the tag pattern field blank to allow access to all tags. This is the default behavior.

Exact Match

Enter a specific tag name to restrict access to only that tag.

Pattern Allowed Denied
latest latest v1.0, stable, anything else
stable stable latest, v2.0, anything else

Wildcards

Use * as a wildcard to match any sequence of characters. A wildcard pattern can contain only the characters a tag can (letters, digits, ., _ and -) plus *.

Pattern Allowed Denied
v1.* v1.0, v1.2.3, v1.0-alpine v2.0, latest
*-alpine v1.0-alpine, latest-alpine v1.0, v1.0-slim
v1.*-stable v1.0-stable, v1.5.2-stable v1.0-beta, v2.0-stable

Version Comparisons

Use comparison operators to allow tags based on semantic version rules. This is ideal when you want to grant access up to a certain version.

Available operators:

Operator Meaning
< Less than
<= Less than or equal
> Greater than
>= Greater than or equal
= Equal
!= Not equal
~> Pessimistic (see below)

Examples:

Pattern Allowed Denied
< 2.0 1.0, 1.9, 1.99 2.0, 2.1, 3.0
<= 2.0 1.0, 1.9, 2.0 2.1, 3.0
>= 1.5 1.5, 1.6, 2.0 1.0, 1.4
< v2.0 v1.0, v1.9 v2.0, v2.1

Breakwater checks a version comparison when you save the license and rejects one the registry couldn't use, such as a four-part version (>= 1.2.3.4).

The v prefix is automatically handled - you can use < v2.0 or < 2.0 and both will work with tags like v1.5 or 1.5.

Version Ranges

Combine multiple constraints with a comma to create a range.

Pattern Allowed Denied
>= 1.0, < 2.0 1.0, 1.5, 1.99 0.9, 2.0, 2.1
>= 2.0, < 3.0 2.0, 2.5, 2.99 1.9, 3.0

Pessimistic Operator (~>)

The ~> operator (sometimes called "twiddle-wakka") allows versions that are compatible within a release series. It's equivalent to >= X.Y, < X+1.0 for two-part versions or >= X.Y.Z, < X.Y+1.0 for three-part versions.

Pattern Equivalent To Allowed Denied
~> 1.5 >= 1.5, < 2.0 1.5, 1.6, 1.99 1.4, 2.0
~> 1.5.0 >= 1.5.0, < 1.6.0 1.5.0, 1.5.1, 1.5.99 1.4.9, 1.6.0

Semantic Versioning Note

Version comparisons use semantic versioning rules, where each numeric segment is compared independently. This means:

  • 1.9 < 1.10 (because 9 < 10)
  • 1.5 < 1.43 is false (because 5 < 43, so 1.43 > 1.5)

If you're using version numbers where the minor or patch components exceed 9, make sure your patterns account for this. For example, to allow all 1.x versions below 1.50, use < 1.50 not < 1.5.

Partial Versions

A version with missing parts in a pattern stands for the whole series, so <= 1.5 allows 1.5.9, = 1.5 allows any 1.5.x, and > 1 means 2.0 or later (not 1.5). Write all three parts (> 1.0.0) when you mean an exact version.

Pre-release Tags

Tags with a pre-release part, such as 2.0.0-rc.1 or 1.4.0-beta, only match a version comparison that names a pre-release itself. >= 1.0 does not allow 1.1.0-rc.1; >= 1.0.0-0 does. Wildcard patterns aren't affected: v2.* allows v2.0.0-rc.1.

Date-Based Versions

Date-style version numbers like 2026.01 or 2026.02.15 work correctly with version comparisons:

Pattern Allowed Denied
<= 2026.02 2026.01, 2026.02, 2026.02.15 2026.03
>= 2025.01, < 2026.01 2025.01, 2025.06, 2025.12 2024.12, 2026.01

Non-Version Tags

When using version comparison patterns, tags that don't look like version numbers (such as latest, stable, or alpine) will not match. If you need to allow both version tags and named tags, consider using a wildcard pattern instead, or create separate licenses for different access needs.

Helm Charts and Build Metadata

Version constraints work on Helm chart versions. Chart versions can carry build metadata, such as 1.2.3+build.5. Helm stores the + as _ in the registry tag (1.2.3_build.5), and Breakwater ignores build metadata when comparing, so both 1.2.3_build and 1.2.3+build match >= 1.2.0.

A side effect: for version constraint patterns, a tag such as 3.19_alpine is read as version 3.19, so >= 3.0 matches it. Wildcard patterns still match the literal tag.

Signatures, SBOMs, and Attestations

Artifacts attached to an image (signatures, SBOMs, attestations) follow the image they're attached to. They're allowed whenever the customer can pull the image, and denied when they can't, whatever their own tags look like. See Helm Charts and OCI Artifacts.

Common Use Cases

Limit to Major Version

Allow a customer to access any release within version 1:

~> 1.0

or

>= 1.0, < 2.0

Limit to Specific Minor Version

Allow only 2.3.x releases:

~> 2.3.0

Up To a Specific Version

Customer purchased support up to version 1.5:

<= 1.5

LTS or Stable Only

Restrict to tags containing "lts":

*-lts

Or exact stable releases:

stable
Last updated November 21, 2026