Merge pull request #3684 from Azure/feat/allow-exact-tag-match

feat: search exact tag match avoiding pagination

Author: openshift-merge-bot[bot]

tooling/image-updater/README.md

@@ -91,7 +91,7 @@ When using `--env stg` or `--env prod`, the tool operates in **promotion mode**:
 
 ## Output Format
 
-When the tool updates image digests in YAML files, it automatically adds inline comments with version tag and timestamp information:
+When the tool updates image digests in YAML files, it automatically adds inline comments with version information and timestamp:
 
 ```yaml
 defaults:
@@ -102,11 +102,28 @@ defaults:
 
 This helps track:
 
-- **Tag name**: The version or tag name (e.g., `v1.18.4`)
+- **Version**: The version information from either:
+  - Container label (if `versionLabel` is configured) - e.g., a commit hash from `org.opencontainers.image.revision`
+  - Tag name (if no version label is configured) - e.g., `v1.18.4`
 - **Timestamp**: When the image was created/published (format: `YYYY-MM-DD HH:MM`)
 
 The comments are automatically generated and updated each time the tool runs.
 
+### Version Labels
+
+By default, when using the `tag` field (e.g., `tag: "latest"`), the tool automatically extracts version information from the `org.opencontainers.image.revision` container label if present. This provides meaningful version information even when using generic tags like "latest" or "stable".
+
+You can customize the label to extract using the `versionLabel` field:
+
+```yaml
+source:
+  image: quay.io/example/image
+  tag: "latest"
+  versionLabel: "org.opencontainers.image.revision"  # Default when using 'tag'
+```
+
+When using `tagPattern`, no version label is extracted by default (uses the tag name), but you can explicitly configure one if needed.
+
 ## Configuration
 
 Define images to monitor and target files to update. Each image can optionally specify Azure Key Vault credentials for authentication.
@@ -158,6 +175,27 @@ images:
       filePath: ../../config/config.yaml
       env: dev
 
+  # Quay.io image pinned to specific version (e.g., during rollback)
+  pko-manager:
+    source:
+      image: quay.io/package-operator/package-operator-manager
+      tag: "v1.18.3"  # Pin to specific version instead of using pattern
+    targets:
+    - jsonPath: defaults.pko.imageManager.digest
+      filePath: ../../config/config.yaml
+      env: dev
+
+  # Image using generic tag with version label extraction
+  my-app:
+    source:
+      image: quay.io/example/my-app
+      tag: "latest"  # Generic tag
+      versionLabel: "org.opencontainers.image.revision"  # Extracts commit hash from label (default)
+    targets:
+    - jsonPath: defaults.myApp.image.digest
+      filePath: ../../config/config.yaml
+      env: dev
+
   # Private ACR image requiring authentication
   arohcpfrontend:
     source:
@@ -344,18 +382,57 @@ images:
 - Read access to the specified Key Vault
 - Pull secret must be stored in Key Vault in Docker config.json format (supports both base64-encoded and raw JSON)
 
-## Tag Patterns
+## Tag Selection
+
+You can specify which image tag to use in two ways:
+
+### Option 1: Specific Tag (Recommended for pinning versions)
+
+Use the `tag` field to specify an exact tag name:
+
+```yaml
+source:
+  image: quay.io/package-operator/package-operator-package
+  tag: "v1.18.3"  # Pin to specific version
+```
+
+**Use cases:**
+- Pinning to a specific version temporarily (e.g., during a rollback)
+- Testing a specific release
+- Production stability requirements
 
-Common regex patterns for filtering tags:
+**Performance benefits:**
+- **No pagination required** - fetches only the specified tag directly from the registry
+- Faster execution compared to pattern matching which requires listing all tags
 
+### Option 2: Tag Pattern (Recommended for automatic updates)
+
+Use the `tagPattern` field with a regex pattern to automatically select the latest matching tag:
+
+```yaml
+source:
+  image: quay.io/package-operator/package-operator-package
+  tagPattern: "^v\\d+\\.\\d+\\.\\d+$"  # Match any semantic version
+```
+
+**Common regex patterns:**
 - `^[a-f0-9]{7}$` - 7-character commit hashes (short)
 - `^[a-f0-9]{40}$` - 40-character commit hashes (full)
 - `^sha256-[a-f0-9]{64}$` - SHA256-prefixed single-arch images
 - `^latest$` - Only 'latest' tag
 - `^v\\d+\\.\\d+\\.\\d+$` - Semantic versions (v1.2.3)
 - `^main-.*` - Tags starting with 'main-'
 
-If no pattern is specified, uses the most recently pushed tag.
+**Use cases:**
+- Continuous updates to the latest version matching a pattern
+- Development and staging environments
+- Following a release branch
+
+### Important Notes
+
+- `tag` and `tagPattern` are **mutually exclusive** - you can only specify one
+- If neither is specified, the tool uses the most recently pushed tag
+- When using `tag`, the tool will find and use that exact tag (case-sensitive)
 
 ## Architecture Filtering
 
@@ -456,7 +533,9 @@ Use `--verbosity 2` or higher when debugging authentication issues, tag filterin
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `image` | string | Yes | - | Full image reference (registry/repository) |
-| `tagPattern` | string | No | - | Regex pattern to filter tags (uses most recent if omitted) |
+| `tag` | string | No | - | Exact tag to use (mutually exclusive with `tagPattern`) |
+| `tagPattern` | string | No | - | Regex pattern to filter tags (mutually exclusive with `tag`) |
+| `versionLabel` | string | No | `org.opencontainers.image.revision` (when using `tag`), empty (when using `tagPattern`) | Container label to extract for human-friendly version in comments and output table. Defaults to `org.opencontainers.image.revision` when using `tag` field. |
 | `architecture` | string | No | `amd64` | Target architecture for single-arch images (`amd64`, `arm64`, etc.) |
 | `multiArch` | bool | No | `false` | If `true`, fetches multi-arch manifest list digest |
 | `useAuth` | bool | No | `false` | If `true`, uses authentication (required for private registries) |
@@ -466,6 +545,8 @@ Use `--verbosity 2` or higher when debugging authentication issues, tag filterin
 
 **Notes**:
 
+- `tag` and `tagPattern` are mutually exclusive - only one can be specified
+- If neither `tag` nor `tagPattern` is specified, uses the most recently pushed tag
 - `multiArch` and `architecture` are mutually exclusive
 - `useAuth` defaults to `false` for all registries
 - For private registries, explicitly set `useAuth: true`

tooling/image-updater/config.yaml

@@ -40,7 +40,7 @@ images:
   hypershift:
     source:
       image: quay.io/redhat-services-prod/crt-redhat-acm-tenant/hypershift/hypershift-operator
-      tagPattern: "^[a-f0-9]{7}$"
+      tag: "latest"
       multiArch: true # Use multi-arch manifest
       useAuth: true
       keyVault:
@@ -64,7 +64,7 @@ images:
     source:
       image: quay.io/package-operator/package-operator-package
       # tagPattern: "^v\\d+\\.\\d+\\.\\d+$"
-      tagPattern: "v1.18.3" # Current image is failing, we needed to rollback
+      tag: "v1.18.3" # Current image is failing, we needed to rollback
     targets:
     - jsonPath: defaults.pko.imagePackage.digest
       filePath: ../../config/config.yaml
@@ -82,7 +82,7 @@ images:
     source:
       image: quay.io/package-operator/package-operator-manager
       # tagPattern: "^v\\d+\\.\\d+\\.\\d+$"
-      tagPattern: "v1.18.3" # Current image is failing, we needed to rollback
+      tag: "v1.18.3" # Current image is failing, we needed to rollback
     targets:
     - jsonPath: defaults.pko.imageManager.digest
       filePath: ../../config/config.yaml
@@ -100,7 +100,7 @@ images:
     source:
       image: quay.io/package-operator/remote-phase-manager
       # tagPattern: "^v\\d+\\.\\d+\\.\\d+$"
-      tagPattern: "v1.18.3" # Current image is failing, we needed to rollback
+      tag: "v1.18.3" # Current image is failing, we needed to rollback
     targets:
     - jsonPath: defaults.pko.remotePhaseManager.digest
       filePath: ../../config/config.yaml
@@ -118,7 +118,8 @@ images:
   clusters-service:
     source:
       image: quay.io/app-sre/aro-hcp-clusters-service
-      tagPattern: "^[a-f0-9]{7}$"
+      tag: "latest"
+      versionLabel: "vcs-ref"
       useAuth: true
       keyVault:
         url: "https://arohcpdev-global.vault.azure.net/"

tooling/image-updater/internal/clients/acr.go

@@ -29,6 +29,7 @@ import (
 type ACRClient struct {
 	client      *azcontainerregistry.Client
 	registryURL string
+	useAuth     bool
 }
 
 // NewACRClient creates a new Azure Container Registry client
@@ -37,6 +38,7 @@ type ACRClient struct {
 func NewACRClient(registryURL string, useAuth bool) (*ACRClient, error) {
 	acr := &ACRClient{
 		registryURL: registryURL,
+		useAuth:     useAuth,
 	}
 
 	var client *azcontainerregistry.Client
@@ -132,7 +134,7 @@ func (c *ACRClient) getClient() *azcontainerregistry.Client {
 	return c.client
 }
 
-func (c *ACRClient) GetArchSpecificDigest(ctx context.Context, repository string, tagPattern string, arch string, multiArch bool) (*Tag, error) {
+func (c *ACRClient) GetArchSpecificDigest(ctx context.Context, repository string, tagPattern string, arch string, multiArch bool, versionLabel string) (*Tag, error) {
 	logger, err := logr.FromContext(ctx)
 	if err != nil {
 		return nil, fmt.Errorf("logger not found in context: %w", err)
@@ -183,6 +185,7 @@ func (c *ACRClient) GetArchSpecificDigest(ctx context.Context, repository string
 		// If multiArch is requested and this is a multi-arch manifest, return it
 		if multiArch && len(manifest.RelatedArtifacts) > 0 {
 			logger.V(2).Info("found multi-arch manifest", "tag", tag.Name, "relatedArtifacts", len(manifest.RelatedArtifacts), "digest", tag.Digest)
+			tag.Version = extractVersionLabel(ctx, c.registryURL, repository, tag.Name, versionLabel, c.useAuth)
 			return &tag, nil
 		}
 
@@ -199,6 +202,7 @@ func (c *ACRClient) GetArchSpecificDigest(ctx context.Context, repository string
 		normalizedArch := NormalizeArchitecture(string(*manifest.Architecture))
 
 		if normalizedArch == arch && string(*manifest.OperatingSystem) == "linux" {
+			tag.Version = extractVersionLabel(ctx, c.registryURL, repository, tag.Name, versionLabel, c.useAuth)
 			return &tag, nil
 		}
 
@@ -210,3 +214,82 @@ func (c *ACRClient) GetArchSpecificDigest(ctx context.Context, repository string
 	}
 	return nil, fmt.Errorf("no single-arch %s/linux image found for repository %s (all tags are either multi-arch or different architecture)", arch, repository)
 }
+
+// GetDigestForTag fetches the digest for a specific tag without pagination
+func (c *ACRClient) GetDigestForTag(ctx context.Context, repository string, tagName string, arch string, multiArch bool, versionLabel string) (*Tag, error) {
+	logger, err := logr.FromContext(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("logger not found in context: %w", err)
+	}
+
+	logger.V(2).Info("fetching digest for specific tag", "registry", c.registryURL, "repository", repository, "tag", tagName)
+
+	// Check if context is cancelled before processing
+	select {
+	case <-ctx.Done():
+		return nil, fmt.Errorf("operation cancelled: %w", ctx.Err())
+	default:
+	}
+
+	client := c.getClient()
+
+	// Get tag properties to get the digest
+	tagProps, err := client.GetTagProperties(ctx, repository, tagName, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get tag properties for tag %s: %w", tagName, err)
+	}
+
+	if tagProps.Tag == nil || tagProps.Tag.Digest == nil {
+		return nil, fmt.Errorf("tag %s has no digest information", tagName)
+	}
+
+	tag := Tag{
+		Name:   tagName,
+		Digest: *tagProps.Tag.Digest,
+	}
+
+	if tagProps.Tag.CreatedOn != nil {
+		tag.LastModified = *tagProps.Tag.CreatedOn
+	}
+
+	// Get manifest properties to check architecture
+	manifestProps, err := client.GetManifestProperties(ctx, repository, tag.Digest, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to fetch manifest properties for tag %s (digest: %s): %w", tagName, tag.Digest, err)
+	}
+
+	if manifestProps.Manifest == nil {
+		return nil, fmt.Errorf("tag %s has no manifest information", tagName)
+	}
+
+	manifest := manifestProps.Manifest
+
+	// If multiArch is requested, verify this is a multi-arch manifest
+	if multiArch {
+		if len(manifest.RelatedArtifacts) == 0 {
+			return nil, fmt.Errorf("tag %s is not a multi-arch manifest", tagName)
+		}
+		logger.V(2).Info("found multi-arch manifest", "tag", tagName, "relatedArtifacts", len(manifest.RelatedArtifacts), "digest", tag.Digest)
+		return &tag, nil
+	}
+
+	// For single-arch, verify it's not a multi-arch manifest
+	if len(manifest.RelatedArtifacts) > 0 {
+		return nil, fmt.Errorf("tag %s is a multi-arch manifest, but single-arch was requested (use multiArch: true)", tagName)
+	}
+
+	if manifest.Architecture == nil || manifest.OperatingSystem == nil {
+		return nil, fmt.Errorf("tag %s is missing architecture or OS information", tagName)
+	}
+
+	normalizedArch := NormalizeArchitecture(string(*manifest.Architecture))
+
+	if normalizedArch != arch || string(*manifest.OperatingSystem) != "linux" {
+		return nil, fmt.Errorf("tag %s has architecture %s/%s, but %s/linux was requested", tagName, string(*manifest.Architecture), string(*manifest.OperatingSystem), arch)
+	}
+
+	tag.Version = extractVersionLabel(ctx, c.registryURL, repository, tagName, versionLabel, c.useAuth)
+	logger.V(2).Info("found matching image", "tag", tagName, "arch", normalizedArch, "digest", tag.Digest)
+
+	return &tag, nil
+}