Kustomize’s replicas transform is a surprisingly blunt instrument for environment-specific scaling, often leading to more headaches than it solves if you’re not careful.
Let’s see it in action. Imagine you have a base Kustomization that defines a deployment with a single replica:
# base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 1
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: main
image: nginx:latest
Now, you want to scale this up for your production environment. You’d create an overlay:
# overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
patchesStrategicMerge:
- deployment-patch.yaml
And the patch itself:
# overlays/production/deployment-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 5
When you run kustomize build overlays/production, the output will be:
# ... other metadata ...
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 5 # <-- Scaled!
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: main
image: nginx:latest
# ... other metadata ...
This replicas field in spec is what the replicas transform targets. Kustomize uses strategic merge patching by default for patchesStrategicMerge. When it sees a Deployment with the same name and kind, it merges the fields. If spec.replicas exists in both the base and the patch, the patch value wins.
The core problem Kustomize’s replicas transform solves is the need for environment-specific configurations without duplicating entire resource definitions. Instead of having base/deployment.yaml, dev/deployment.yaml, and prod/deployment.yaml, you have a single base and then small, focused patches or generators in each environment’s overlay. This dramatically reduces YAML sprawl and makes it easier to manage variations. The replicas field is a common variable across environments – development might need 1, staging 3, and production 10. The replicas transform allows you to declare these differences concisely.
Internally, Kustomize processes your kustomization.yaml files. It first resolves all resources, including those from resources and bases. Then, it applies any patches or generators. For patchesStrategicMerge, it’s a structured merge. For patchesJson6902, it’s JSON patch operations. The replicas transform is a specific type of patch that targets spec.replicas within Deployment and StatefulSet objects. When you use kustomize edit set image ..., Kustomize is essentially applying a JSON patch. The replicas transform operates similarly, but it’s designed to be applied to the spec.replicas field directly.
The replicas transform is often misunderstood as a primary mechanism for scaling. While it can be used to set the number of replicas, it’s less about dynamic scaling and more about static, environment-specific configuration. You might see people trying to use it with variables or complex logic, which isn’t its intended use. The true power lies in its simplicity for defining distinct replica counts per environment.
Consider a scenario where you have a kustomization.yaml that includes a commonLabels generator. If you then try to use the replicas transform to set the replica count for a deployment defined in that same kustomization, Kustomize will first apply the generator to add labels to your deployment object, and then it will apply the replicas transform to set the spec.replicas field. The order of operations matters, and Kustomize handles this by processing generators first, then patches.
What most users don’t realize is that the replicas transform can also be applied to StatefulSet resources, not just Deployments. The same mechanism of targeting spec.replicas applies, allowing you to manage the instance count for stateful applications in an environment-aware manner.
The next concept you’ll likely encounter is managing more complex environment-specific configurations beyond just replica counts, such as different resource limits or ingress hosts.