Snapshots

A Konflux Snapshot represents a specific, immutable collection of container images for the Components within an Application at a particular point in time. They capture the exact versions of all relevant component artifacts that were built and intended to be used together including their Git commits. Once created, the list of Components with their images is immutable.

Snapshots are fundamental for ensuring consistency during testing and release processes. They provide a stable target for:

  • Running integration tests defined by IntegrationTestScenarios (ITS). The Integration service updates the status of the resources to reflect the testing outcomes.

  • Creating Releases using ReleasePlans to promote a specific set of component versions to different environments (like staging or production).

Example Snapshot

Example Snapshot resource contents
apiVersion: appstudio.redhat.com/v1alpha1
kind: Snapshot
metadata:
  name: snapshot-sample (1)
  namespace: ws-sample-tenant (2)
spec:
  application: application-sample (3)
  components:
    - name: component-sample (4)
      containerImage: quay.io/redhat-user-workloads/ws-sample-tenant/application-sample/component-sample@sha256:0db0a473a6abf5c15c424ab07cfbd5c40c06622fe648d4fe6a6b6abc224a0d0c (5)
      source: (6)
        git:
          url: https://github.com/sample-org/sample-repo
          revision: fa8b89274a61ef0f1c257b7a84c37aa2ec844109
1 The name of the Snapshot resource.
2 The namespace where the Snapshot exists. It should correspond to the user’s tenant namespace.
3 The Application that the Snapshot belongs to.
4 The name of the individual Component of the Application.
5 The full image pull specification for the container image. The images need to be referenced by digest.
6 The component source containing the git URL and revision that the component’s container image was built from.

Snapshot Creation

Snapshots can be generated in several ways:

  • Automatic (Push Events): This is the primary mechanism for generating snapshots intended for release pipelines.

    • When code is pushed to a branch tracked by your Components (e.g., main, release-4.19), Konflux triggers the associated build pipelines defined in the .tekton/ directory of your component repositories.

    • Once the build is complete, a Snapshot CR is automatically created. It contains references to the container image digest produced by that successful build along with the latest images for all other Components in the Application.

    • These push-event snapshots are typically labeled with pac.test.appstudio.openshift.io/event-type=push.

    • They may be used for creating a release.

  • Automatic (Pull Request Events): Snapshots are also generated for Pull Requests (PRs) to enable automated testing of proposed changes.

    • Once a pull or merge request build is complete, a Snapshot CR is automatically created. It contains references to the container image digest produced by that successful build along with the latest push images for all other Components in the Application.

    • These pull request-event snapshots are typically labeled with pac.test.appstudio.openshift.io/event-type=pull_request.

    • These snapshots might be created incrementally constructed as individual component builds finish within the PR context (i.e. group snapshots). These group snapshots are often annotated with test.appstudio.openshift.io/pr-group.

    • Pull request Snapshots are subject to more aggressive garbage collection policies (see below).

    • They are primarily intended for pre-merge testing and usually not used for formal releases.

  • Manual: You can manually create a Snapshot custom resource (CR) if needed. This allows you to define a specific combination of existing component container images (e.g., previously built images stored in quay.io) for testing or release purposes. This is useful for scenarios like promoting a specific known-good set of images to production when automatic releases are disabled.

Quotas and Garbage Collection

Understanding how Snapshots are managed and limited within Konflux is essential to avoid unexpected behavior:

Snapshot Quota

  • There is a resource quota limiting the total number of Snapshot CRs that can exist within a single tenant namespace.

  • The default quota is 1024 Snapshots (count/snapshots.appstudio.redhat.com).

This quota is not user-configurable. If you anticipate exceeding this limit due to a large number of applications or frequent builds across many supported versions, you may need to contact the Konflux administrators to request a quota increase for your namespace.

Monitor usage via kubectl get quota appstudio-crds-integration -o yaml.

Snapshot Garbage Collection (GC)

Snapshot CRs themselves consume resources. To manage this and stay within quota, Konflux implements automated garbage collection:

  • Eligibility: GC applies to Snapshots that are not referenced by an active Release CR.

  • Mechanism: GC is based on retention counts, not age. Konflux keeps a specific number of the most recent unreferenced snapshots and deletes the oldest ones beyond that limit.

    • Default retention counts:

      • ~=600 non-PR (push event) snapshots.

      • 70 PR event snapshots.

  • Exception: Snapshots annotated with test.appstudio.openshift.io/keep-snapshot=true will not be garbage collected

These retention counts are not user-configurable.

Relationship with Releases

  • When you create a Release CR from a Snapshot, that Snapshot is protected from the count-based garbage collection described above if the Release exists.

  • Release CRs have their own time-based expiration, defined by the releaseGracePeriodDays field in the associated ReleasePlan (default: 7 days). This is configurable per ReleasePlan.

  • When a Release CR expires, it is automatically deleted.

  • Once the Release is deleted, its associated Snapshot CR is no longer protected and becomes eligible for count-based garbage collection if the retention limits are exceeded.

The garbage collection of Snapshot and Release CRs does not automatically delete the underlying container images that were pushed to registries.

  • Images pushed to quay.io during PR builds typically expire automatically (default: 5 days, configurable in the pipeline with the image-expires-after parameter).

  • Images pushed to quay.io during push builds do not expire automatically but will be deleted if the corresponding Component CR is deleted (unless repository deletion is explicitly skipped).

  • Images promoted to external registries via a release pipeline are not deleted by Konflux GC.

Understanding Incomplete Snapshots

A common point of confusion occurs when a Snapshot contains fewer components than expected (e.g., only 1 out of 5 components in an Application).

  • Cause: A Snapshot accurately reflects the state of successfully completed component builds at the time it was created. If components are missing, it usually means their corresponding build pipelines either:

    1. Were not triggered correctly by the push event.

    2. Failed to complete successfully before the Snapshot was generated.

  • Troubleshooting: If you encounter incomplete push-event snapshots:

    • Verify the build PipelineRun status for all expected components associated with that push event.

    • Examine the pipeline trigger configuration, specifically the pipelinesascode.tekton.dev/on-cel-expression annotation in the .tekton/ pipeline definitions within each component’s repository. Ensure the expression correctly targets the intended branch (e.g., event.ref == refs/heads/release-4.19) and includes the necessary conditions (e.g., relevant file paths changed) to trigger builds when expected. Misconfigurations here are a common cause of components not building and thus being absent from the Snapshot.

Further Reading