Release

Release is the unit of delivery. It binds one source, one way to render that source, and one target cluster.

Example#

apiVersion: core.convoy.kumodo.io/v1alpha1
kind: Release
metadata:
  name: podinfo-helmreg-in-cluster
  namespace: default
spec:
  clusterRef:
    name: dev-local
  source:
    type: helmRegistry
    helmRegistry:
      name: podinfo
      namespace: default
      chart:
        name: podinfo
        version: "6.12.0"
  content:
    type: helm
    helm:
      releaseName: podinfo-from-helmreg
      releaseNamespace: default
      dependencyMode: vendored
      values:
        - type: gitRepository
          gitRepository:
            name: podinfo-values
            namespace: default
            ref:
              branch: main
            paths:
              - podinfo/values.yaml
        - type: inline
          inline:
            image:
              tag: 6.13.0
  syncPolicy:
    automatic: true
    prune:
      orphaned: false
      includeCRDs: false
      includeNamespaces: false
    interval: 1m

Object structure#

A Release has four writable parts. Only spec is under spec. The other three are top-level fields, so that each one can have its own subresource, RBAC rule and audit event.

spec.source#

spec.source tells convoy where to fetch from and which version. source.type selects one block: gitRepository, helmRegistry or ociRegistry. Each block references a source object by name, and adds the version to fetch.

• Git refs. convoy uses the first ref field that is set, in the order branch, tag, commit. Validation does not reject more than one. semver is accepted, but fetch fails with Applied=False, reason Unsupported.
• Chart versions. helmRegistry.chart.version and ociRegistry.artifact.version must match a version exactly. Version ranges do not work. A leading v is ignored for Helm repositories.
• Namespace. The referenced source must be in the namespace of the Release. An empty namespace means the namespace of the Release.
• Immutable. source.type, and the name and namespace of the referenced source, cannot change after creation. The version fields can change.

spec.content#

spec.content tells convoy how to render the fetched files. content.type is immutable.

Validation does not check that the content type fits the source type.

spec.clusterRef#

The target Cluster. It must be in the namespace of the Release. clusterRef is immutable.

spec.syncPolicy#

• automatic: true applies each new render. With automatic: false, convoy renders and reports status, but applies only after a /sync request. automatic has no default: if you do not set it, the Release uses manual mode.
• interval is the period of the periodic reconcile of this Release. The observer uses the same interval.
• prune.orphaned deletes objects that the render no longer contains. CRDs and Namespaces are not deleted unless includeCRDs or includeNamespaces is set.
• retryBackoff sets the retry delay after a transient failure.
• waveStrategy orders this Release relative to other Releases on the same Cluster.

spec.healthAssessment and spec.failurePolicy#

healthAssessment selects health rule sets by label and sets the deadline after which a failing resource is Degraded. A nil selector selects no rule set. An empty selector {} selects all rule sets.

failurePolicy.rollback sets what convoy does when a rollout fails: Never, OnReleaseFailure or OnWaveFailure. A value other than Never requires healthAssessment.deadline. Without a deadline, a rollout cannot fail, so the API rejects the Release.

spec.retentionPolicy#

keepHistory is the number of applied renders that convoy keeps in the render store. If it is not set, convoy keeps 10. 0 keeps all renders. Without a render store, there is no history.

spec.deletionPolicy#

When you delete a Release:

• keepWorkloads: false (the default) deletes the applied objects from the cluster. true keeps them.
• blockOnClusterUnreachable: true keeps the Release until the cluster is reachable again. With false, convoy deletes the Release and leaves the objects on an unreachable cluster.

mutations#

An ordered list of post-render mutations. Write it through the main resource or through /mutations. See Release mutations for the types, fields and admission rules.

lifecycle#

Lifecycle hooks per phase: preSync, postSync, syncFailed, preDelete, postDelete. Write them through the main resource or through /lifecycle. See Release lifecycle hooks for the fields, admission rules and status.

pin#

The pin holds the Release on one render. Write it through /pin.

• To pin, set renderRef. The apiserver sets pinnedAt and pinnedBy.
• To unpin, write an empty renderRef.
• A pin is not possible before the first successful render.
• To pin a render that is not the current one, convoy needs a render store that contains that render.

Status#

• lastAttempted is the most recent render attempt. lastSuccessful is the most recent render that convoy applied.
• rollout and lastHealthy record the progressive rollout. See Progressive rollout.
• waves records the sync waves of the last apply.
• lifecycle records the hooks of the current render.
• healthSummary counts resources per health state. suspended is never set.
• historyTruncated is never set.

Conditions#

Each condition has one writer. There is no combined Ready condition on a Release. Read the conditions together:

InSync and Healthy are written by the observer. Applied, RolloutSucceeded and LifecycleSucceeded are written by the controller-manager.

Printer columns#

kubectl get releases shows these columns: