akuity/kargo v0.4.0

on GitHub

The Kargo team is proud to bring you v0.4.0!

⚠️  With Kargo still in its early stages, and the team still learning what works and what doesn't, this release has some small breaking changes. The notes that follow will call special attention to them.

What's New

The Project CRD

🆕  New Feature

⚠️  Breaking Change

Kargo projects are not a new concept. They've been the fundamental unit of workspace organization and tenancy since before Kargo's first release. Prior to v0.4.0, projects were implemented as mere Kubernetes namespaces having a special project label.

We have long been striving to improve th experience of bootstrapping new projects, and to that end, v0.4.0 introduces the Project CRD. This new resource type reconciles to a specially labeled Kubernetes namespace.

Why do it this way? There are some specific advantages:

• Users can be granted permissions to create Project resources without granting them the ability to directly create non-project Kubernetes namespaces.

• Additional project-level configuration can be added to a Project resource. At present, this only includes promotion policies, but will include more in future releases.

  ⚠️  Complementing this change, the PromotionPolicy resource type has been removed.

• In future releases, we intend to implement additional project-bootstrapping logic as part of Project reconciliation. This is likely to include the creation of project-scoped ServiceAccounts, Roles, and RoleBindings.

• The Project resource type will provide a convenient place to aggregate project-level statuses and statistics in future releases.

A few other notes on this change:

• Project resources own the underlying namespace. Deleting a Project will delete the namespace and everything in it. The Kargo controller also provides the inverse functionality. If you delete the namespace, the owning Project resource will be deleted.

• As a convenience to users coming from older versions, if you already have appropriately labeled "project" namespaces in your cluster, and create a Project resource with the same name, the Project will "adopt" that existing namespace unless it is, for some reason, already has other owner references.

Tag-Based Constraints on Git Repository Subscriptions

🆕  New Feature

Warehouse resources have long been able to specify strategies and tag-based constraints for the selection of container images from image repositories. Kargo v0.4.0 introduces similar, optional, constraints for for the selection of a commit from a Git repository.

Why? Just like you may not want to push every container image you build in CI into your delivery pipeline, you many not want to continuously push every single configuration change into that pipeline either. If that's the case, you can now take control by tagging your commits appropriately when you are ready to move them into the pipeline.

The following example Warehouse resource will only produce new Freight resources when it finds a new tag of the form release-\d{4}-\d{2}-\d{2} in the repository:

apiVersion: kargo.akuity.io/v1alpha1
kind: Warehouse
metadata:
  name: my-warehouse
spec:
  subscriptions:
  - git:
      repoURL: https://github.com/some/repo.git
      commitSelectionStrategy: Lexical
      allowTags: release-\d{4}-\d{2}-\d{2}

This is but one example. All the new options are documented here.

Image Selection Strategies

⚠️  Breaking Change

Prior to v0.4.0, Kargo Warehouse resources subscribing to container image repositories would specify a "tag selection strategy" in the tagSelectionStrategy field. This field name was a misnomer. Although the available strategies all employ tag-based constraints, they ultimately facilitate the selection of an image.

Beginning in v0.4.0, Warehouse resources subscribing to container image repositories specify an image selection strategy instead.

Before and after this change, the selection strategy defaults to SemVer when left unspecified. This breaking change, therefore, only affects users of the other three strategies: Digest, Lexical, and NewestBuild.

Playing Nicer with Helm

⚠️  Breaking Change

Prior to v0.4.0, Kargo Warehouses subscribed to Helm charts using registryURL and name fields. For reasons too complex to explain briefly, the registryURL field generated a lot of confusion.

Beginning in v0.4.0, Warehouse resources subscribe to Helm chart repositories using a repositoryURL field instead. For classic (HTTP/S) chart repositories the name field is required to qualify the desired chart since such repositories may contain multiple, differently named charts. For OCI repository subscriptions, a repository URL unambiguously points to a single chart, so the name field must remain empty in that case. A validating webhook will enforce these rules and prevent any mistakes.

When using promotion mechanisms that either mutate the targetRevision fields of Argo CD Application sources or ones that mutate the versions of chart dependencies in Chart.yaml files, define the rules for identifying the targets of those changes by simply matching the corresponding fields in the Application sources or chart dependencies exactly. If those values differ slightly from your Warehouse Kargo will figure it out.

Argo CD Credential Borrowing Removed

⚠️  Breaking Change

Prior to v0.4.0, Kubernetes Secret resources containing repository credentials used by Argo CD could be "borrowed" by Kargo projects if specially annotated in a manner indicating consent. This feature was conceived very early in Kargo's development and was an overreaction to the feeling of creating separate but similar credential Secrets for use by each of Argo CD and Kargo.

Any similarities between the credentials used by Argo CD and Kargo are, however, were largely superficial. Digging deeper, one quickly realizes that Argo CD always requires only read-only access to Git or chart repositories, and never requires any access to image repositories. Kargo, on the other hand, frequently requires read/write access to Git repositories and frequently does require (read-only) access to image repositories.

To keep things DRY, one might be tempted to extend permissions to Argo CD that it doesn't require, but in doing so, the principle of least privilege is violated.

To discourage this poor security practice, Kargo v0.4.0 removes the Argo CD credential borrowing feature.

Other, Smaller Changes

• UI:
  • Support for OAuth 2 refresh tokens
  • Support for editing Freight aliases (previously only possible via CLI)
• CLI:
  • apply and delete commands now support Secret resources (for credentials; previously required using kubectl)
  • approve command added for manually approving Freight (previously only possible via UI)
  • dashboard command added to open UI in system default browser
  • logout command added
• Support for Git repositories secured with self-signed certificates
• Miscellaneous bug fixes and performance improvements

New Contributors

Last, but certainly not least, Kargo would be nothing without its community, so
we'd like to take a moment to thank community members whose first contributions
to the project are included in this release:

• @paulliwog
• @Juneezee
• @lrotim
• @Tchoupinax
• @Brightside56
• @snooyen
• @mfreeman451
• @maksimstankevic
• @webstradev

Full Changelog: v0.3.2...v0.4.0