DOCSEARCHbyAlgolia
Submit Docs

Kargo Documentation

repository·main·Indexed 25 days ago

https://github.com/akuity/kargo

Kargo is a GitOps-based tool for managing and automating the promotion of software artifacts through multiple lifecycle stages. This documentation provides detailed configuration guides for installing Kargo via Helm, including API server settings, OIDC authentication, RBAC rules, data plane integration with Argo CD, and system resource management.

Tokens
215.8K
Snippets
441
Records
980
Agent score
85%

What's inside Kargo

  1. Overview of `jfrog-evidence` promotion step

    main

    The jfrog-evidence promotion step integrates with JFrog Artifactory's evidence management to enable secure attestation and verification of promotion workflows. It allows you to track artifact provenance, test results, and compliance status using cryptographically signed evidence.

    Supported Operations:

    • Create Evidence: Generate evidence with digital signatures.
    • Process Evidence: Query and verify existing evidence.
    • Delete Evidence: Clean up evidence when it is no longer needed.

    Availability Note: This step is only available in Kargo on the Akuity Platform, versions v1.7 and above.

  3. Understand Promotion Templates in Kargo

    main
    Promotion Templates define the workflow for transitioning Freight into a Stage. They consist of a sequence of discrete, composable steps that orchestrate the promotion process. When Freight is promoted to a Stage, Kargo uses the associated Promotion Template to create a Promotion object, which then executes the defined steps (e.g., cloning a Git repository or managing pull request lifecycles).

  4. Understand AnalysisRun Lifecycle and Implicit Argo CD Verification

    main

    AnalysisRun

    An AnalysisRun is a resource representing a single execution of an AnalysisTemplate for a specific Freight + Stage pair. It tracks the lifecycle (Running, Successful, Failed) and records measurements. You can view these in the Kargo UI under the Verifications tab of a Stage.

    Implicit Argo CD Verification

    If a Stage references Argo CD Applications but does not define an explicit verification process, Kargo will implicitly delay verification until the Argo CD Application reaches a Healthy state. This prevents tests from running while a deployment is still in progress.

  6. Understand Kargo's built-in roles

    main

    Kargo abstracts ServiceAccount, Role, and RoleBinding into a single "Kargo role". When a new Project is created, the following roles are pre-defined in the project namespace:

    1. default: The standard Kubernetes default ServiceAccount. It is not Kargo-managed and cannot be modified via UI/CLI.
    2. kargo-admin: Provides permissions to manage all aspects of the project. Kargo-managed.
    3. kargo-promoter: Provides permissions to promote Stages and create Promotions, but cannot modify core pipeline resources like Stages or Warehouses. Kargo-managed.
    4. kargo-viewer: Provides read-only access to view all project resources. Kargo-managed.

  7. Understand Kargo Resource Namespace Terminology

    main

    Kargo v1.9.0 introduces new terminology for managing resources to clarify access levels:

    • Shared resources namespace (replaces "global credentials namespace(s)"): Stores resources (like repository credentials) accessible by all Projects.
    • System resources namespace (replaces "cluster secrets namespace"): Stores namespaced resources referenced by cluster-scoped configuration (ClusterConfig). This is a private property of the operator and not for sharing.

    Default Namespaces:

    • kargo-shared-resources
    • kargo-system-resources

    These are overridable at install/upgrade time.

  8. Understand the Warehouse resource type

    main

    A Kargo Warehouse resource manages subscriptions to one or more artifact sources. These sources include:

    • Container image repositories
    • Git repositories
    • Helm chart repositories

    When a Warehouse detects a new revision in any of its subscribed artifact sources, it automatically creates a Freight resource. This Freight resource represents a specific collection of artifact revisions that can be promoted across different Kargo Stage resources as a single, atomic unit.

  9. Understand Kargo Core Concepts

    main
    Kargo is a continuous promotion platform designed to orchestrate the movement of code and configuration through application lifecycles using GitOps principles. Unlike GitOps agents (e.g., Argo CD) which focus on making the actual state of a cluster reflect a desired state, Kargo focuses on the promotion process: how changes are propagated from one stage of the lifecycle to the next.

  10. Understand Kargo's Data Model

    main

    Kargo's data is entirely represented as Kubernetes Custom Resource Definitions (CRDs). All state and configuration are stored as Kubernetes resources within the Kargo control plane. Key CRDs include:

    • Project
    • Warehouse
    • Stage
    • Freight
    • Promotion

    Because Kargo uses standard Kubernetes resources, you can interact with Kargo data using kubectl in addition to the Kargo CLI and UI.

  11. Advantages of using Project resources over Namespaces

    main

    Using the Project resource instead of creating Namespace resources directly provides several benefits:

    • Automatic Labeling: Ensures the required Kargo project label is correctly applied to the Namespace.
    • Granular RBAC: Allows users to be granted permission to create Kargo projects (and thus namespaces) without granting broad permissions to create any arbitrary Namespace.
    • Automated Boilerplate: Automatically creates project-level configuration, such as RBAC resources and ServiceAccount resources, upon creation.