Kustomize’s ability to reference remote Git repositories as bases is a game-changer for managing Kubernetes configurations, but the real magic lies in how it achieves immutability and version pinning without needing a full GitOps operator.
Let’s see this in action. Imagine you have a common set of base configurations for your microservices, like resource limits, common labels, and a default ingress class. This base lives in a Git repository:
# repo: https://github.com/my-org/kustomize-bases.git
# ref: v1.2.0
# path: common/base
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- service.yaml
- deployment.yaml
commonLabels:
app.kubernetes.io/managed-by: kustomize
environment: production
resources:
- ../../base/deployment
- ../../base/service
images:
- name: my-app
newName: my-registry/my-app
newTag: v2.5.0
Now, in your application-specific Kustomization file, you can reference this remote base:
# app/my-service/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
bases:
- https://github.com/my-org/kustomize-bases.git//common/base?ref=v1.2.0
patchesStrategicMerge:
- deployment-patch.yaml
- service-patch.yaml
commonLabels:
app.kubernetes.io/name: my-service
When you run kustomize build app/my-service, Kustomize will clone the specified Git repository, check out the v1.2.0 tag, and use the common/base directory as if it were a local directory. The output will be a merged configuration:
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.kubernetes.io/managed-by: kustomize
environment: production
app.kubernetes.io/name: my-service
name: my-app-deployment
spec:
template:
metadata:
labels:
app.kubernetes.io/managed-by: kustomize
environment: production
app.kubernetes.io/name: my-service
spec:
containers:
- name: my-app
image: my-registry/my-app:v2.5.0
---
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/managed-by: kustomize
environment: production
app.kubernetes.io/name: my-service
name: my-app-service
spec:
selector:
app.kubernetes.io/name: my-service
The problem this solves is the proliferation of duplicated configurations and the difficulty in updating common components across many microservices. Before remote bases, you’d either copy-paste the base configuration into each service’s repository, leading to drift and maintenance nightmares, or you’d use a Git submodule, which has its own set of complexities and can be hard to manage. Remote bases provide a clean, declarative way to inherit configurations.
Internally, Kustomize uses the go-git library (or similar mechanisms) to fetch the remote repository. When you specify a URL like https://github.com/my-org/kustomize-bases.git//common/base?ref=v1.2.0, Kustomize parses this:
https://github.com/my-org/kustomize-bases.git: The Git repository URL.//common/base: The path within the repository to the Kustomization directory. The double slash//is important to distinguish the path from query parameters.?ref=v1.2.0: The Git reference (tag, branch, or commit hash) to use. This is crucial for reproducibility.
Kustomize caches these remote bases locally to avoid re-cloning on every run, but this cache is managed by Kustomize itself. The key is that the ref parameter pins the configuration to a specific version, ensuring that when you build your application’s configuration today, it uses the exact same base configuration as it did yesterday, and as it will tomorrow, unless you explicitly change the ref.
The one thing most people don’t realize is that Kustomize’s remote base resolution is inherently version-pinned by default when you use a ref. It doesn’t just pull the latest from a branch unless you specifically omit the ref parameter (which is generally discouraged for production). This immutability is the core strength; your application deployment is tied to a specific, immutable state of the base configuration, preventing unexpected breakages from upstream changes.
The next concept you’ll likely grapple with is how to manage secrets and sensitive configuration values when using remote bases, as these bases are often shared across multiple teams and environments.