Skip to main content

Configuring Kargo Render

Kargo Render is configured using a file named kargo-render.yaml, which should be stored at the root of the default branch of your GitOps repository.

The role of kargo-render.yaml is simply to enumerate your environment branches, and for each, specify:

  • Which configuration management tools to use in rendering that environment branch -- and what the inputs to those tools are.

  • Where to place the rendered manifests within the environment branch.

  • Other policies, such as:

    • Whether to commit directly to the environment branch or open a PR instead.

    • Whether to produce a manifest per Kubernetes resource or combine all resources into a single manifest.

Basic configuration​

Before introducing example configurations, it's worth a brief digression to discuss the different perspectives teams may adopt with respect to their environments and applications.

With an application-centric perspective, a team treats their applications as "first class." Environments are simply different instances of an application. This perspective might be adopted by a team that is developing and deploying multiple, distinct, monolithic applications that can be deployed independently of one another.

With an environment-centric perspective, a team treats their environments as "first class." Applications are simply different pieces of an environment. This perspective might be adopted by a team that is employing a microsevice architecture wherein each "application" is a single component of a larger whole that should be deployed as an atomic unit.

Understanding these two perspectives is important insofar as it impacts how a team is likely to organize their GitOps repositories.

A team with an application-centric approach is likely to use a GitOps repository per application. Each Kargo Render-managed environment branch within that repository will contain environment-specific manifests for the one application. In contrast, a team with an environment-centric approach is likely to include configuration for multiple applications in a single GitOps repository. Each Kargo Render-managed environment branch within that repository will contain environment-specific manifests for multiple applications.

Ultimately, the fundamental difference between the two approaches is whether a single GitOps repository houses manifests for one application or for multiple. With the latter scenario being the (very slightly) more complex of the two, all examples that follow will involve two applications -- foo and bar. When we render manifests for an environment branch, we wish to render manifests for both apps.

Config management tool configuration​

Behind the scene Kargo Render uses Argo CD Repo Server to render manifests. More information about supported settings is available in Argo CD documentation.

For each environment branch, the configuration below specifies the location of environment-specific Kustomize overlays for each application. It also specifies where within each environment branch to store the rendered manifests for each application.

configVersion: v1alpha1
branchConfigs:
- name: env/test
  appConfigs:
    foo:
      configManagement:
        path: env/test/foo # test overlay for app "foo"
      outputPath: foo
    bar:
      configManagement:
        path: env/test/bar # test overlay for app "bar"
      outputPath: bar
- name: env/stage
  appConfigs:
    foo:
      configManagement:
        path: env/stage/foo # stage overlay for app "foo"
      outputPath: foo
    bar:
      configManagement:
        path: env/stage/bar # stage overlay for app "bar"
      outputPath: bar
- name: env/prod
  appConfigs:
    foo:
      configManagement:
        path: env/prod/foo # prod overlay for app "foo"
      outputPath: foo
    bar:
      configManagement:
        path: env/prod/bar # prod overlay for app "bar"
      outputPath: bar

Refer directly to Kustomize's documentation for more information.

Keeping things DRY​

In our introductory examples, you may notice that the configuration for each environment branch looks remarkably similar to the configuration for every other environment branch. Paths and other values for each environment were consistently a function of the environment's name. This is an obvious DRY violation.

To keep configuration more succinct, Kargo Render supports matching environment branches with applicable configuration using patterns (i.e. regular expressions). Capture groups can be used in those patterns to extract meaningful information, such as environment name, and paths that reference those capture groups will be expanded accordingly.

The following examples are equivalent to our initial examples, but are considerably more succinct:

configVersion: v1alpha1
branchConfigs:
- pattern: env/(\w+)
  appConfigs:
    foo:
      configManagement:
        path: env/${1}/foo
      outputPath: foo
    bar:
      configManagement:
        path: env/${1}/bar
      outputPath: bar

Other options​

This section covers environment branch configuration options that are not specific to any configuration management tool.

Pull requests​

For any environment branch, you can specify that Kargo Render should open pull requests for changes to that branch instead of committing those changes directly. (Committing changes directly is the default behavior.) This is an effective method of creating opportunities for manifest changes to be reviewed and before they are applied by a CD platform that is tracking the head of that environment branch.

This option can be applied as follows:

configVersion: v1alpha1
branchConfigs:
# ...
- name: env/prod
  appConfigs:
    my-app:
      configManagement:
        # omitted for brevity
  prs:
    enabled: true
info

At this time, pull requests are only supported for remote GitOps repositories hosted on GitHub, but support for most major Git hosting providers is planned.

When PRs are enabled, changes are, by default, committed to a predictably named intermediate branch. PRs are opened from that intermediate branch to the environment branch. If new changes are queued up for the environment branch and such a PR is already open, the new commits are applied to the intermediate branch, which implicitly amends the open PR. This makes a single PR a record of all pending changes to a given environment branch.

Some teams may prefer a different approach wherein every change headed for an environment branch results in a new PR. In this case, if change a results in a new PR A and that PR has not yet been merged, a subsequent change b results in a new PR B that contains the commits for both changes a and b. To catch the environment branch all the way up with both changes, B can be merged and A can be closed, unmerged. Alternatively, in this scenario, A could be merged to catch the environment branch up to change a and B can remain open for further consideration.

caution

The downside to this option is that for teams making frequent commits to the default branch of the GitOps repository, there may be many open PRs at any given moment and many of them may end up closed, unmerged. This can get rather noisy, so it's worth carefully considering whether you need this behavior.

To enable this:

configVersion: v1alpha1
branchConfigs:
# ...
- name: env/prod
  # ...
  prs:
    enabled: true
    useUniqueBranchNames: true

Combining manifests​

For any app configuration within an environment branch, you can specify that Kargo Render should combine all Kubernetes resources into a single manifest file (named all.yaml). When not enabled (the default) Kargo Render produces a separate manifest file named <resource name>-<resource type> for every Kubernetes resource. Enabling this or not is strictly a matter of preference.

To enable combining manifests, use configuration like the following:

configVersion: v1alpha1
branchConfigs:
# ...
- name: env/prod
  appConfigs:
    my-app:
      # ...
      outputPath: my-app
      combineManifests: true

Convention over configuration​

In the absence of a kargo-render.yaml file at the root of the default branch, Kargo Render will assume:

  • You are using Kustomize for configuration management.

  • Environment-specific Kustomize overlays exist within paths in the default branch that exactly match the names of the environment branches for which they are inputs. e.g. The Kustomize overlay to be rendered for any environment branch x exists within the path x/, relative to the root of the default branch.

  • Changes should be committed directly to environment branches.

  • Every Kubernetes resource will be rendered into its own manifest file and not combined into a single manifest file.

  • Rendered manifests will be stored in the app/ directory of the environment branches.

If deemed acceptable, these assumptions permit Kargo Render to be used without any configuration at all.