Introduction

Kubernetes versioning can mean two different things, and they are easy to confuse. One is API versioning such as apps/v1; the other is metadata.resourceVersion, which is an internal version marker used by the API server for concurrency control and watches.

API Version Versus resourceVersion

API versioning tells you which schema and endpoint a resource uses.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: web

That apps/v1 value is not the same thing as metadata.resourceVersion. The resourceVersion field is generated by the API server and changes as the stored object changes.

What resourceVersion Is For

Kubernetes API concepts documentation explains that every object has a resourceVersion representing the version of that resource in the underlying persistence layer. Clients use that value to watch for changes and to avoid lost updates.

A typical object returned by the API includes something like:

1metadata:
2  name: web
3  namespace: default
4  resourceVersion: "128734"

You should treat that value as opaque. It is not a semantic version, timestamp, or counter you should parse for business logic.

Why It Matters For Watches

The common Kubernetes watch pattern is:

• list the current objects
• capture the returned resourceVersion
• start a watch from that version to receive later changes

For example:

kubectl get pods -o json

The list response includes a collection-level resourceVersion. A controller or client library can use that value to continue from a consistent point in time.

Why It Matters For Updates

resourceVersion is also used for optimistic concurrency. If two clients read the same object and both try to update it, Kubernetes can reject the stale write because the resource changed after the older read.

That behavior prevents one client from accidentally overwriting another client's newer state.

In practice, client libraries usually manage this for you, but it helps to understand why update conflicts happen.

Get The Field With kubectl

You can inspect the field directly.

kubectl get deployment web -o jsonpath='{.metadata.resourceVersion}'

This is useful for debugging controllers, watches, and conflict errors, but it should not become application data.

A Simple Conflict Example

Suppose two operators both fetch the same Deployment. Operator A updates the image first. Operator B then submits an older copy of the object with the stale resourceVersion. Kubernetes can reject that write with a conflict because B is trying to overwrite state based on an outdated read.

That is the practical reason resourceVersion exists: it gives the API server a safe way to detect racing updates.

API Version Maturity Still Matters Too

Separately from resourceVersion, Kubernetes resources also have API maturity levels such as alpha, beta, and stable v1. Those versions affect compatibility and deprecation.

For example, apps/v1 is an API version choice in your manifests. It tells Kubernetes how to interpret the object schema. It does not tell you which specific stored revision of the object you are looking at.

Common Pitfalls

A common mistake is assuming resourceVersion is a portable revision number you can compare numerically across all situations. Kubernetes treats it as an opaque value, so client code should not depend on numeric ordering semantics beyond the API contract.

Another mistake is confusing API version deprecation with resourceVersion changes. They solve different problems.

It is also easy to hardcode resourceVersion in manifests. That field is generally server-managed and should not be treated like a normal desired-state field.

Summary

• 'apps/v1 and metadata.resourceVersion are different kinds of versioning in Kubernetes.'
• 'resourceVersion is an opaque server-managed value for watches and optimistic concurrency.'
• Clients often list resources, capture a resourceVersion, and then watch for later changes.
• Update conflicts often happen because a stale resourceVersion is being used.
• Do not treat resourceVersion as business data or a semantic version number.