Promotion Made Easy with Kargo: Kargo for Beginners

Hop on the Akuity Platform and try out Kargo, now available for general access! Kargo is a multistage GitOps promotion tool and application lifecycle orchestration platform for Kubernetes.

Kargo:

• Empowers developers to promote their applications to multiple environments safely and efficiently while providing visibility for development teams.

• Builds upon GitOps principles and integrates with existing technologies such as Argo CD to streamline and automate the progressive rollout of changes across each stage in an application’s lifecycle.

• Provides a single pane of glass to easily view your application’s entire journey and stages, from production to live deployment.

• Aims to provide an intuitive and flexible layer “above” existing GitOps tooling.

You can describe the relationships between various application instances deployed to different environments and the steps taken to progress changes from one application instance’s source of truth (a manifest) to the next. Kargo makes promoting releases between GitOps environments safer and straightforward. Promoting applications is prone to human error, so why not let Kargo do the heavy lifting? 

For those new to Kargo and/or interested in getting into Kargo, this is the guide for you. This guide breaks down concepts utilized by Kargo, de-mystifies Kargo’s key concepts, and explains some of the features Kargo has to offer.

What Does ‘GitOps’ Mean?

Kargo, like Argo CD, is rooted in GitOps. As the name suggests, GitOps combines the words “Git” and “Operations.” Git is a version control system that tracks different versions of files. Git takes a snapshot of what your files look like at that moment and stores away a reference to the snapshot. This makes it easier to do rollbacks, which is when a system or application is reverted back to an earlier version. 

The OpenGitOps project has established four fundamental principles that define GitOps:

• Declarative: "A system managed by GitOps must have its desired state expressed declaratively."

• Versioned and Immutable: “Desired state is stored in a way that enforces immutability, versioning and retains a complete version history.”

• Pulled Automatically: “Software agents automatically pull the desired state declarations from the source.”

• Continuously Reconciled: “Software agents continuously observe actual system state and attempt to apply the desired state.”

This guide will reference these concepts throughout, so put a pin in it.

For a more in-depth look at these principles, please check out my guide: Getting into GitOps: GitOps Made Simple.

Breaking Down the Basics

While using Kargo, you’ll see all sorts of terms thrown around, such as "freight" and "warehouse." Here’s a rundown of common terms, what they mean, and how they’re used in Kargo.

Project

A project is a collection of related Kargo resources that describe one or more delivery pipelines. It is Kargo's basic unit of organization and tenancy. 

Remember that Kargo is a GitOps tool. The first fundamental is Declarative. So, in our source of truth, we declare the specifications needed to create the ideal state. Take a look at this example project manifest:

In the kind field, we have project. Every Kargo project is represented by a cluster-scoped Kubernetes resource of type Project. This means we declare that the Kubernetes resources we use are Project resources. 

In the metadata field, we declare the name of our project, kargo-project. Kargo follows a practice in which the namespace’s name and the project's name are always kept the same. This is to ease 1:1 project to namespace mapping throughout the codebase.

Deletion of a project resource results in the deletion of the corresponding namespace. While Kargo strongly ties projects and namespaces, Kubernetes does not enforce bidirectional deletion by default. Instead, Kargo relies on conventions where the namespace deletion triggers cleanup. This may not delete project resources but everything in that namespace. All resources belonging to a given project are grouped in that namespace.

Boilerplate configuration is automatically created when a project is created. Project administrators may use projects to define policies. One of them is RBAC (Role-Based Access Control), a security method that limits access to systems, networks, and resources based on a user's role within an organization. 

Stage

Kargo breaks down promotion into stages. Stages are Kargo's most important concept. Stages can be linked together (just like a freight train!) to describe a delivery pipeline. Typically, such a pipeline may feature a "test" or "dev", stage as its starting point, with one or more "prod", or production stages at the end. 

Why Stage, and not “environment”? The term, “environment”'s definition changes depending on who you ask, as it is based on perspective. If you mention “environment” to a developer, they may think of an instance of an application. If you mention “environment” to a DevOps engineer, they may think of a certain part of the infrastructure they maintain. To avoid confusion or any misunderstandings, Kargo avoids the term “environment” and opts to use the term “stage” instead.

The most important feature of a stage is its name. The name defines the application’s purpose, rather than its location. For example, at first glance, you can tell that the “test” stage is meant for testing purposes. The “prod” stage is for production purposes, and so on.  For a more in-depth explanation, please read our blog post.

Freight

Freight is Kargo's second most important concept. A single piece of “freight" is a set of references to one or more versioned artifacts. Artifacts are resources that you update as a part of your deployment/delivery pipelines. These artifacts can be container images (from image repositories), Kubernetes manifests (from Git repositories), or Helm Charts (from Helm repositories). Think of freight like a "meta" artifact. Kargo will look for freight, which can progress from one stage to another. 

As with all Kubernetes resources, freight has a name field, which serves as its unique identifier for a resource of that type within a Kargo project (a specially labeled Kubernetes namespace). When a new freight resource is produced, it will create a representation of the artifacts referenced from its resource (such as image repositories or Git repositories) and use that to make a SHA-1 (Secure Hash Algorithm 1) hash, a kind of algorithm used to verify data authenticity. This hash is a long string of numbers that becomes the value in the name field and serves as its unique identifier. It may be difficult to remember such a long string of numbers, but luckily, Kargo provides Aliases. Aliases are automatically generated names given to the artifact formatted as <adjective> and <animal>. Isn't it much easier to remember the name “sleepy-swan” rather than f5f87aa23c9e97f43eb34t78d8ee41f5ba3766?

Warehouse

Where do you typically keep freight? A warehouse! A warehouse is a source of freight. A warehouse subscribes to a container image repository, Git repository, or Helm Chart repository. Anytime something new is discovered in any repository that a warehouse is subscribed to, the warehouse produces a new piece of freight. This ties in with the GitOps principle, Pulled Automatically. The most important field for a warehouse is the subscriptions field, since warehouses produce freight based on their subscriptions. Kargo allows users the option of filtering rules for subscriptions for convenience.

Some examples of filtering rules include:

• DiscoveryLimit is the limit on the number of image references discovered for this subscription.

• SemVerConstraint specifies constraints on what image versions can be used. If left unspecified, no constraints will exist, so the latest semantically tagged version of an image will always be used.

• ImageSelectionStrategy specifies the rules for finding the newest version of an image referenced by the RepoURL field.

Each Kargo warehouse is represented by a Kubernetes resource called “Warehouse.” 

Here is an example of a warehouse.yaml file:

Note the filtering rules in "subscriptions." Here's how we can interpret this file:

• I'm using a public image. I can find it at the link in RepoURL.

• I want to use version 1.26.0 or above of this image.

• I'll limit the number of times my image references are discovered to 5.

• I want to choose my image's newest semantic version, something like…version 1.26.1.

Promotion

A promotion is a request to move a piece of freight into a specified stage. Moving your freight, “sleepy-swan,” to the prod stage would be “promoting” sleepy-swan to production. Every Kargo promotion is represented by a Kubernetes resource of type “Promotion.” Promotion’s required fields are its freight and stage fields under spec, or specifications, which respectively identify a piece of freight and a target stage to which freight should be promoted. 

Remember that GitOp principle, Continuously Reconciled? Kargo monitors repositories (Git, Image, or Helm) for changes and will make the necessary commits for you. Kargo will verify promotions once the commits are returned to its source repository. Steps necessary for promotion are declared in “promotionTemplate”. PromotionTemplate allows custom, configurable steps for promotion specific to each stage. The steps taken for promotion in the “test” stage may differ from the “prod” stage. It’s quite flexible and allows users to mix-and-match steps for tailored promotions. Some examples of steps are:

• git clone: create a clone of a repository, often the first step of promotion.

• git clear: deletes the contents of a specific git working tree. You can use this command to take the content of a stage-specific branch and replace it with content from another branch.

• copy: Copies files from a directory from one specific location to another.

Check out our reference guide on Promotion Steps for more examples, such as kustomize-set-imageor helm-update-image.

Understanding Continuous Delivery (CD) and Continuous Integration (CI)

Kargo uses Continuous Delivery(CD) and Continuous Integration(CI) practices. The primary goal of Continuous Delivery is to make deploying software painless, low-risk, and able to be performed at any time, on demand. Continuous Delivery is an extension of Continuous Integration. As the name implies, Continuous Integration is when code is continuously integrated/merged into the main branch of a source code’s repository. Continuous integration uses automated testing and builds to ensure the new code changes doesn’t break the existing, functional build.

Continuous Delivery is considered generally safe, using patterns such as blue-green deployments. A blue-green deployment is a software release strategy where two identical environments are created to run different versions of the same application. Typically, only one environment is live (blue), but the other (green) is idle. If something goes wrong with blue, then green takes blue's place. Think of it like an understudy or a backup plan. Once green takes blue's place, a brand new green environment is created. 

Remember, an aspect of GitOps is that the ideal state is stored in a way that enforces immutability, meaning it is immune to any changes made after it has been saved, like a screenshot. This screenshot is versioned and kept in a complete version history for convenience. Thus, being Versioned and Immutable, one of the fundamentals of GitOps mentioned before.

Introducing: Continuous Promotion

Continuous Delivery(CD) and Continuous Integration(CI) can only do so much, but alas, there are areas that still need improvement. Despite using GitOps best practices, organizations still struggled with issues such as:

• Relying on snowflake scripts running in CI workflows to move releases and configurations from one stage to the next.

• Losing track of what version is running and which is safe for deployment.

• Lack of a single control plane to view your environment or deploy targets.

• Lack of guardrails for developers and insights to better allow developers to perform self-service promotion.

A new set of practices was formed to fill these gaps, aptly called Continuous Promotion.

Continuous Promotion promotes code changes through various stages of development based on predefined criteria and automated checks. Sound familiar? That’s right! Kargo is a Continuous Promotion orchestration layer that complements Argo CD for Kubernetes. Kargo uses Continuous Promotion, which aims to tackle all the abovementioned issues. For example, with Kargo, you no longer have to rely on snowflake scripts run in CI workflows to promote releases and configurations. Kargo makes it easier to track what version is running and where. Kargo enables developers to know which deployments are safe to deploy and can easily rollback to the last working build if needed. Thus allowing for quick recovery in case of build failures. 

Another of Kargo’s safety features is verification. Before freight is promoted, it must be verified. You can manually verify each piece of freight if needed. Once freight is verified, it is ready for approval to be promoted. These are just a few built-in processes and guardrails that ensure safe transitions from one stage to the next.

How Does Kargo Work?

First, you have to make your declarations. You must create a manifest that maps out the specifications needed to create the “desired” state. You’ll need a manifest for the project, stages, and warehouse resources.

Once everything is declared and dandy, Kargo gets to work. Kargo creates everything according to the manifests: the stages, the warehouse which pulls freight from its subscriptions, and enacts any policies for promotion if specified or policies declared in the project manifest. Thus creating your very own flexible promotion pipeline. You can see your pipeline in action on the Akuity Platform! 

You can press the blue target buttons on each stage to promote freight into a stage. You can use the UI to create stages and warehouses or even regenerate the stage colors if you’re unsatisfied with the colors. On the top right, you have a row of tabs to access credentials, analysis templates, events that may have occurred, and your organization roles. Everything you could ever need is at your fingertips.

Transparency on the Akuity Platform

The Akuity Platform’s UI is straightforward, making it easy to navigate. You can monitor everything related to your Kargo instance on the Akuity Platform. You can check DevOps Research and Assessment (DORA) metrics, access the audit logs where you can keep track of changes and errors, and manage Kargo agents, which gives basic information about your instances such as status, namespace, Kargo version, and the manifest. 

Try It Out Today for Free!

The Akuity Platform provides all the tools to improve developer experience with deployment, promotion, and cluster monitoring. Sign up for a 30-day free trial for the Akuity Platform for access to Argo CD, Kargo, and KubeVision. 

• Eager to hop on Kargo and give it a try? Try out our Kargo Quickstart(OSS) or Kargo Quickstart (SaaS)

• Want to learn even more about Kargo? Read Kargo's documentation here.

• If you'd like to learn more about the amazing features Akuity Platform has to offer, you can schedule a technical demo with our team.

• If you have any questions, check out our community Discord.