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.
| 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 |
~> |
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 |
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.43is false (because 5 < 43, so1.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.
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.00 |
2026.02.01, 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.
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