Kubernetes Versioning and Annotations

Updated 2 months ago by Michael Cretzman

This topic covers how Harness tracks Kubernetes deployment releases, and the labels Harness applies during deployments:

Releases and Versioning

Every Harness deployment creates a new release with an incrementally increasing number. Release history is stored in the Kubernetes cluster in a ConfigMap. This ConfigMap is essential for release tracking, versioning and rollback.

By default, all the ConfigMap and Secrets resources are versioned by Harness. Corresponding references in PodSpec are also updated with versions.

You can see the use of release numbers and versioning in the Deployments page details:

INFO   2019-02-15 10:53:33    Kind                Name                                    Versioned 
INFO 2019-02-15 10:53:33 Namespace default false
INFO 2019-02-15 10:53:33 Secret image-pull-secret false
INFO 2019-02-15 10:53:33 Secret sample true
INFO 2019-02-15 10:53:33 Deployment nginx-deployment false
INFO 2019-02-15 10:53:33
INFO 2019-02-15 10:53:33
INFO 2019-02-15 10:53:33 Current release number is: 5
INFO 2019-02-15 10:53:33
INFO 2019-02-15 10:53:33 Previous Successful Release is 4
Versioning does not change how you use Secrets. You do not need to reference versions when using Secrets.

For cases where versioning is not required, the manifest entered in the Harness Service Manifests section should be annotated with harness.io/skip-versioning: "true".

For example. you might want to skip versioning is for an ImagePullSecret because it never changes, or for TLS certs if they are referred to in Kubernetes container command args.

Harness also uses a release name for tracking releases. You can supply a release name in an Environment's Infrastructure Definition Release Name field. By default, the value Harness uses is release-${infra.kubernetes.infraId}.

Harness Annotations and Labels

Harness applies labels during Kubernetes deployment that you can use to select objects you defined in your Harness Service Manifests section. Annotations are a way to pass additional metadata for resources to Harness. For a description of Annotations, see Annotations from Kubernetes.


In both annotations and labels, boolean strings require quotes. For example:

harness.io/skip-versioning: "true"

Regular strings do not requires quotes.


The following Annotations can be put on resource specifications in the Harness Service Manifests section.

Annotation values must use quotes.






To exclude versioning of a resource (ConfigMap or Secret).



If more than one workload is present in the Service Manifests files, use this annotation to apply an unmanaged workload.

Apply an unmanaged workload by setting the annotation to "true".

See Ignore a Manifest File During Deployment.

Multiple workloads are supported in Rolling Update deployment strategies. Multiple workloads are not supported in Canary and Blue/Green.



Identifies the primary Kubernetes service in a Blue/Green deployment.



Identifies the Kubernetes stage service in a Blue/Green deployment.



Required for Harness to identify that a DestinationRule or VirtualService is managed.

This annotation is used to identify which DestinationRule or VirtualService Harness should update during traffic splitting when there are more than one.

Harness requires that the managed VirtualService have only one route in the http list in order to know which one to update.

If the DestinationRule/VirtualService uses harness.io/managed: false, that is the same as if harness.io/managed were omitted. In this case, Harness will not perform any traffic shifting.

See Set Up Kubernetes Traffic Splitting.

Note on direct-apply

Harness Canary and Blue/Green Workflow default steps support a single Deployment workload as a managed entity.

In Harness, a managed workload is a Deployment, StatefulSet, or DaemonSet object deployed and managed to steady state.

Rolling Workflow default steps support Deployment, StatefulSet, or DaemonSet as managed workloads, but not Jobs.

You can deploy any Kubernetes workload in any Workflow type by using a Harness annotation to make it unmanaged (harness.io/direct-apply).

The Apply Step can deploy any workloads or objects in any Workflow type as a managed workload.

OpenShift: Harness supports OpenShift DeploymentConfig in OpenShift clusters as a managed workload across Canary, Blue Green, and Rolling deployment strategies. Please use apiVersion: apps.openshift.io/v1 and not apiVersion: v1.


The following labels are applied by Harness during deployment.





release name

Applied on pods. Harness uses a release name for tracking releases, rollback, etc. You can supply a release name in an Environment's Infrastructure Definition Release Name field.

By default, the value Harness uses is release-${infra.kubernetes.infraId}.

Use release-${infra.kubernetes.infraId} for the Release Name instead of just ${infra.kubernetes.infraId}. Kubernetes service and pod names follow DNS-1035 and must consist of lowercase alphanumeric characters or '-', start with an alphabetic character, and end with an alphanumeric character. Using release- as a prefix will prevent any issues.



Applied on pods in a Canary deployment.



Applied on pods in a Blue/Green deployment.

Next Steps

How did we do?