Sources

A source is an endpoint and its credentials. convoy has three source kinds: GitRepository, HelmRegistry and OCIRegistry. A source does not select a version. Each Release selects the version, so many Releases can use one source with different versions.

apiVersion: source.convoy.kumodo.io/v1alpha1
kind: GitRepository
metadata:
  name: podinfo
  namespace: default
spec:
  auth:
    type: none
  interval: 1m0s
  minSyncInterval: 30s
  tls:
    insecureSkipVerify: true
  url: https://github.com/stefanprodan/podinfo.git

Verification and fetch#

Two different parts of convoy connect to a source:

1. The source controller verifies the endpoint. It writes the Ready condition of the source. It does not download content.
2. The fetch coordinator downloads content when a Release needs it. The Release controller and the observer use the fetch coordinator.

Each source controller verifies its endpoint with the credentials of the source:

A source controller verifies again at each periodic informer resync. It does not use spec.interval.

How a Release fetches content#

At each reconcile, the Release controller asks the fetch coordinator for the content of spec.source:

1. The coordinator reads the source object from the namespace of the Release.
2. The coordinator searches the artifact store for the content. convoy reads only commits, chart versions and OCI tags from the store. A branch or a tag can move, so convoy fetches it again at each reconcile.
3. If the content is not in the store, the coordinator downloads it.
4. The coordinator writes the content to the artifact store, and gives it to the renderer.

The download is different for each kind:

• Git branch or tag. A shallow clone of one branch or tag, without other tags. The revision is the commit at the head.
• Git commit. A full clone, then a checkout of the commit.
• Helm chart. convoy reads index.yaml, downloads the chart archive and unpacks it.
• OCI chart. convoy pulls the chart with the Helm registry client and unpacks it. With credentials, it authenticates first.

convoy unpacks a chart so that Chart.yaml is at the root of the files. For a HelmRegistry or an OCIRegistry source, do not set spec.content.helm.path.

A fetch failure stops the reconcile before rendering:

convoy has no webhook receiver. A new commit on a branch reaches the cluster at the next reconcile of the Release. See Sync policy.

The artifact store#

The artifact store keeps fetched content in memory.

• The key is the source URL and the revision. convoy removes spaces, a trailing / and a trailing .git from the URL, and changes it to lowercase.
• The revision is the commit SHA for Git. For Helm and OCI charts, it is <chart name>-<version>.
• Two sources with the same URL share the stored content.
• The controller-manager and the observer have different stores. Each process fetches its own copy.
• A restart clears the store. The next reconcile fetches the content again.
• convoy does not remove content from the store. Memory use increases with each new revision until the process restarts.

The coordinator does not merge requests. When two Releases need the same branch at the same time, convoy clones it two times.

Source and content types#

Validation does not check that spec.content.type fits spec.source.type. These pairs work:

Other pairs fail at render time, or render objects that you do not expect. See Rendering.

In convoy v0.9.0, an OCIRegistry gives only Helm charts. An artifact without a chart layer fails with no chart layer. spec.defaultContentType of an OCIRegistry is required, but convoy does not use it to fetch or render. Pulls of other OCI artifact types are planned. Not built

Other uses of a GitRepository#

A Release can read a GitRepository in two more places. Each place has its own ref, and uses the same fetch coordinator and artifact store:

• A Helm values layer of type gitRepository. See Rendering.
• A mutation with from.kind: GitRepository. See Mutations.

All source references of a Release must be in the namespace of the Release. See Release and Credentials.