Reference

Cogate is configured using configuration files in your git repos with a little help from a web application.

The web application is where git repos and container registries are added to the system, billing information is configured, and the results of builds are visible.

Which images to build and how to run them is determined by configuration files that are in your git repos.

The best way to see how to set up Cogate to interact with your repos is to look at the Tutorial.

To learn the details of the configuration file syntax once you have some git repos hooked up, keep reading below!

Configuration Syntax

Cogate’s configuration files are YAML files and each file is structured as a list of configuration objects. For example, a configuration file might contain one or more image definitions along with a deployment definition. The top level structure w would look like:

- image:
  ...

- image:
  ...

- deployment:
  ...

The filename can be any of the following:

• cogate.yaml

• cogate.yml

• .cogate.yaml

• .cogate.yml

The actual image and deployment details are below.

Image

This construct tells Cogate to build an image from the source in this repository. You can build as many images as you want from one repo.

image

Here is an unecessarily verbose example of an image definition:

- image:
    registry: docker.io
    repository: example/web-server
    requires:
      - example/base-server
    context: docker
    file: Dockerfile
    tags:
      - latest

The available attributes are described below. All are optional unless otherwise indicated.

image.registry (required)

The container registry for this image (e.g., docker.io). While the world of containers often assumes docker.io is the default, Cogate does not, so you need to spell it out here.

Don’t worry – during pre-merge testing Cogate isn’t going to upload anything to the real registry. But it will upload images to a special Cogate-specific registry so that deployment test jobs can run with the images built for testing without you having to change your deployment tooling. In other words, during pre-merge testing, everything in Cogate is going to pretend that this is the actual registry.

If you use gating with Cogate, Cogate will upload the actual image to the real registry after the change merges.

image.repository (required)

The name of the image repository within the registry (e.g., username/imagename). Together, image.registry and image.repository create the full name of the image. Just like image.registry this should be the actual name of your production registry, though Cogate won’t upload any images to the real registry unless you configure gating (and then only after changes merge).

image.context
Default: .

The container build context. This defaults to the root of your git repository, but you can specify any path here. You can even set it to a path outside of your git repository.

Cogate will checkout every repo into a Golang-style path like ~/src/github.com/REPONAME. Cogate runs the container build command in that directory, and the default of . means that is also the context. If you want to include all of the git repos in your build context, you could specify ~/src as the context. If you wanted the build context to be the foo subdirectory of this git repo, then you could specify just foo as the context.

image.file
Default: Dockerfile

The name of the container build file. Since Cogate runs the build command at the root of the git repo, it should either be an absolute path starting with ~/src/ or relative to the root of this git repo.

image.buildkit
Default: false
Type: bool

Set this to true to tell Cogate to use Buildkit when performing the container build.

image.requires
Type: list

A list of Cogate container images that this image depends on. If you build your own base images and use them in other images with FROM, then list them here, even if they are in a different git repo. That will allow Cogate to ensure that any changes to this image which depend on changes to those images are sequenced correctly.

image.target

If you use multi-stage builts, specify the built target for this image here.

image.tags
Default: ['latest']
Type: list

A list of container image tags for this image. By default it is the single tag latest, but any number of tags can be listed here.

image.required-projects
Type: list

If the image needs more than just the current git repo in order to build, you can list other git repos here. Cogate must be configured via the web app to know about these git repos just like this one, but you don’t need to have any cogate.yaml config files in those repos (though you can).

Any repos listed here will also be checked out under ~/src on the builder, and if you set the image.context appropriately, they can be used in the image build.

Deployment

This construct tells Cogate to deploy one or more images using configuration found in this repo. You can have as many deployments as you want in a single repo. There are two main approaches you can take to setting up deployments in Cogate: a simple kubectl apply or an action container. If you can deploy and test your app with a single Kubernetes YAML file (or Kustomize overlay) , then you can use the kubectl apply approach and save everyone a bunch of time. If you need more than that, then, well, this is the world of containers and every problem is solved with a container. Make an action container image (that should probably be a Cogate image itself) that is designed to run inside of Kubernetes and do whatever is needed to run your application. To save you from having to write a trivial Kubernetes YAML file to run that image, Cogate has some syntactic sugar to help.

Whichever approach you take, keep in mind that you need to deploy your app and test it so that Cogate can report whether a change is good or not. An action container should both deploy and run the test and return the result as the exit code for the image command. A kubectl apply file should include a resource that Cogate can wait for in order to determine success or failure.

deployment

Here is an example of a deployment definition using the kubectl apply approach.

- deployment:
    name: deploy-app
    images:
      - docker.io/example/web-app
      - docker.io/example/message-bus
    platform: k8s-1-node
    apply:
      path: deploy.yaml
      wait:
        resource: job/deploy-and-test-app
        for: condition=complete
        timeout: 60s

And here is an example of a deployment definition using the action container approach.

- deployment:
    name: deploy-app
    images:
      - docker.io/example/web-app
      - docker.io/example/message-bus
      - docker.io/example/deploy-and-test-app
    platform: k8s-1-node
    run:
      image: docker.io/example/deploy-and-test-app
      timeout: 60s

The full syntax is described below:

deployment.name (required)

The name of the deployment. This is for your benefit as it determines the name of the job that will appear in the Cogate web application and the check that is reported to GitHub.

deployment.images (required)
Type: list

A list of Cogate images that are deployed by this job. This lets Cogate know that it should run this deployment job whenever there is a pull request opened that updates one of these images.

deployment.platform (required)

What platform to run the deployment on. Generally this describes the type of Kubernetes that will be used. You can specify a small single node Kubernetes cluster, or multi-node. The costs for each platform differ. See https://cogate.dev/settings for a list of available platforms and their current rates.

deployment.apply

If you elect the kubectl apply method of deployment, use this. This is a dictionary of attributes describing what file to apply and how to wait for the resolution.

deployment.apply.namespace

The Kubernetes namespace into which the resources should be applied.

deployment.apply.path (required)

The path of the Kubernetes YAML file (or Kustomize overlay path) to be applied.

deployment.apply.kustomize
Default: false
Type: bool

Set this to true to tell Cogate to use Kustomize instead of a plain YAML file.

deployment.apply.wait (required)

A futher dictionary of attributes describing what to wait for. These have a close approximation to the arguments to the kubectl wait command.

deployment.apply.wait.resource (required)

The Kubernetes resource we’re waiting for. This is the positional argument to kubectl wait.

deployment.apply.wait.for (required)

The condition on the resource that we’re waiting to satisfy. E.g. condition=complete. Corresponds to the --for argument to kubectl wait.

deployment.apply.wait.all
Default: false
Type: bool

Set this to true to wait for all resources of the specified types. Corresponds to the --all argument to kubectl wait.

deployment.apply.wait.all-namespaces
Default: false
Type: bool

Set this to true to wait for all resources across all namespaces. Corresponds to the --all-namespaces argument to kubectl wait.

deployment.apply.wait.namespace

The namespace to use. If you set deployment.apply.namespace you probably want to set this to match (but maybe not! you have free will!).

deployment.apply.wait.timeout
Default: 300s

How long to wait for the resource. Corresponds to the --timeout argument to kubectl wait.

deployment.run

If you elect the action container method, use this. This is a dictionary describing what to run.

deployment.run.image (required)

The image to run. Essentially, Cogate is going to create a Kubernetes batch job on the fly that runs this image. The image command should perform all the necessary actions to deploy and test your app and then return an exit code of 0 to indicate success or any other value for failure.

deployment.run.timeout
Default: 600s

How long to wait for the command to complete.