How can I standardize the 'v' prefix in image tags for Helm charts using release-please and Docker actions?

Kubernetes itself doesn’t mandate a specific version format for container images—it only recommends avoiding ambiguous tags like :latest and opting for explicit, immutable references. In practice, many teams follow semantic versioning where a “v” prefix is common (for example, v1.2.3) and even shown in some examples in the docs. However, tooling on your CI/CD side (such as release-please and Docker’s metadata-action) might have different defaults.

Choosing a Consistent Approach

The key is to adopt one consistent versioning scheme across your toolchain. You have two main options:

1. Adopt the “v” prefix throughout:
   Ensure that all tools produce and consume tags with the “v” prefix. This might mean configuring release-please to output versions with a “v”, or adjusting the Docker metadata-action settings if possible. Your Helm charts would then reference the tag verbatim without needing a hack in the deployment template.

2. Use no “v” prefix for image tags:
   Alternatively, you can configure your release and build actions to strip the “v” (or avoid adding it in the first place) so that both the image build process and your Helm deployment follow the same convention. In this scenario, your image tags would be semantic versions like 1.2.3.

Handling the Discrepancy

Since you mentioned that release-please produces the “non‑v” version while Docker actions are using the “v” variant, you have two paths:

• Adjust your tooling configuration:
  Wherever possible, configure either your release-please action or your metadata-action to align their outputs. For example, if you can modify release-please to include a “v”, that might provide consistency.

• Transform the version during deployment:
  If reconfiguring isn’t an option, your templating hack (adding “v” conditionally) is a practical workaround. While it may seem suboptimal, it’s a quick fix to ensure the deployment picks the correct image tag. Over time it’s often better to unify version formatting end-to-end.

Community Examples

There isn’t a single “standard” end-to-end example that covers all languages (Java, Rust, Python, etc.) because this is more a matter of your release and CI/CD pipelines rather than a Kubernetes-specific requirement. Many projects:

• Use semantic versioning with a “v” prefix in their Git tags.
• Configure their image build and push pipelines to mirror this versioning.
• Reference images by digest in production for reproducibility (e.g., image@sha256:…).

For instance, some open source projects using Helm with Java or Rust microservices follow a pattern like:

• Git tag: v1.2.3
• Docker image: tagged as v1.2.3
• Helm chart: pulls the image tag directly (without adding or stripping a “v”).

A simplified Helm template snippet might then be:

YAMLCopied
containers:
  - name: myservice
    image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

And your CI/CD pipelines are aligned to produce the correct tag that the chart expects.

Summary

There’s no “official” Kubernetes standard dictating how you handle the “v” prefix—what matters most is consistency. Whether you choose to include the “v” everywhere or eliminate it, ideally your version output from release-please, the tag created by metadata-action, and the value consumed by your Helm charts should be harmonized. Adopting one approach also reduces potential errors when pulling the image in your Kubernetes Deployment.

By aligning your tooling and pipeline configurations, you can eliminate the need for hacky template adjustments and ensure that your deployments are both predictable and maintainable.