Purpose, Not Location - Why Kargo Uses the Term 'Stage'

Kargo is a next-generation continuous delivery and application lifecycle orchestration platform for Kubernetes. It builds upon GitOps principles and integrates with existing technologies, like Argo CD, to streamline and automate the progressive rollout of changes across environments.

When you hear the term “environment”, what you envision will depend significantly on your perspective. The term “environment” is widely used, especially in software development and cloud infrastructure. If someone is telling you that “The production environment is down!” a software engineer would likely envision their application's “production” instance. In contrast, an infrastructure engineer would picture the Kubernetes cluster or the servers.

Why Kargo Uses 'Stage', and Not 'Environment'

At Akuity, we've heard consistently from GitOps practitioners -- they want a sensible and mostly automated means of progressing changes through a series of environments. In this context, we understand "environments" to be a shorthand for the sources of truth for various application instances that each exist for a specific purpose and may possess different qualities of service.

We've also noticed that those less familiar with GitOps are less likely to be aware of this shorthand and are apt to interpret "environment" in more literal terms. "Test" or "production" may be thought of as locations -- particular clusters, VPCs, or failure domains, for instance, each hosting many applications.

To eliminate confusion, Kargo avoids the term "environment" altogether in favor of something more precise: "stage". The critical feature of a stage is that its name (e.g. "test", "prod") denotes an application instance's purpose and not its location.

What is a Stage Anyway?

In Kargo, the Stage resource defines the subscriptions and promotion mechanisms for an instance of an application.

The spec.subscriptions field describes the sources from which a Stage obtains artifacts. Artifacts include any combination of manifests from a Git repository, Docker images from an image repository, and Helm charts from a chart repository. Alternatively, instead of subscribing directly to repositories, a Stage may subscribe to another "upstream" Stage.

The spec.promotionMechanisms field describes how to move freight into the Stage. There are two general methods of accomplishing this: committing changes to a GitOps repository or making changes to an Argo CD Application resource. (Often, the only change is to force a sync and refresh of the Application.) These two approaches are, in many cases, used in conjunction with one another. The Kargo controller applies Git-based promotion mechanisms first, then Argo CD-based promotion mechanisms.

For each Stage, the Kargo controller will periodically check all subscriptions for the latest available materials. A single set of materials is known as a freight (or piece of freight). If a piece of freight is new, it is pushed onto the freight line and becomes available.

Conclusion

Kargo's goal is to provide an intuitive and flexible layer "above" existing GitOps tooling, wherein you can describe the relationships between various application instances deployed to different environments and procedures for progressing changes from one application instance's source of truth to the next. If you want to try this out for yourself, check out our Quickstart guide! Join the Akuity Community Discord for any questions you may have.