Kustomize – Kustomize

Blog: v3.3.0

Thu, 24 Oct 2019 00:00:00 +0000

Summary of changes

First release of the Go API-only module

Many of the PRs since the last vrelease were around restructuring the sigs.k8s.io/kustomize repository into three Go modules instead of just one.

The reasons for this are detailed in the versioning policy documentation, and what it means for releasing is explained in the release process documentation.

The tl;dr is that the top level module sigs.k8s.io/kustomize now defines the kustomize Go API, and the kustomize CLI sits below it in an independent module sigs.k8s.io/kustomize/kustomize.

The modules release independently, though in practice a new release of the kustomize Go API will likely be followed quickly by a new release of the kustomize executable.

This is a necessary step to creating a much smaller kustomize Go API surface that has some hope of conforming to semantic versioning and being of some use to clients.

The kustomize CLI will see the same kustomize Go API as any other client.

The new semver-able API will begin with v4.0.0 (not yet released) and be a clean break with v3 etc.

Change log since v3.2.0

3c9d828f - Have kustomize CLI depend on kustomize Go API v3.3.0 (Jeffrey Regan)
5d800f0b - Merge pull request #1595 from monopole/threeReleases (Jeff Regan)
4eb2d5bc - Three builders. (Jeffrey Regan)
988af1ff - Update README.md (Jeff Regan)
1617183e - Merge pull request #1590 from monopole/releaseProcessUpdate (Kubernetes Prow Robot)
ee727464 - update release process doc (jregan)
c9e7dc3b - Merge pull request #1589 from monopole/moreTestsAroundKustFileName (Jeff Regan)
07e0e46a - improve tests for alternative kustomization file names (Jeffrey Regan)
404d2d63 - Merge pull request #1587 from monopole/reducePgmconfig (Jeff Regan)
baa0296a - Reduce size of pgmconfig package (Jeffrey Regan)
0f665ac1 - Merge pull request #1544 from ptux/add-transformer-href (Jeff Regan)
14b0a650 - Merge pull request #1581 from monopole/refactorFs (Jeff Regan)
2d58f8b8 - Break the dep between fs and pgmconfig. (Jeffrey Regan)
9a43ca53 - Merge pull request #1578 from nlamirault/fix/build-plugins-doc (Jeff Regan)
5372fc6f - Merge pull request #1579 from monopole/fsPackageCleanup (Jeff Regan)
86bc3440 - Merge pull request #1513 from nimohunter/fix_empty_list_item (Kubernetes Prow Robot)
a014f7d4 - Merge pull request #1561 from beautytiger/dev-190925 (Jeff Regan)
9a94bcb8 - Improve fs package and doc in prep to officially go public (Jeffrey Regan)
07634ef0 - Merge pull request #1575 from monopole/versioning (Jeff Regan)
995f88d6 - Update versioning notes. (jregan)
334a6467 - Fix: documentation link for plugins (Nicolas Lamirault)
08963ba5 - improve test code coverage in transformers (Guangming Wang)
326fb689 - Merge pull request #1570 from bzub/1234-go_plugin_doc (Jeff Regan)
970ce67c - Update goPluginCaveats.md (Jeff Regan)
98d18930 - Update INSTALL.md (Jeff Regan)
d89b448c - Fix git tag recovery in cloud build. (Jeff Regan)
17bf9d32 - Update releasing README. (Jeff Regan)
a99aff1d - Merge pull request #1571 from monopole/updateCloudBuildProcess (Kubernetes Prow Robot)
a694ac7b - Update cloud build process for kustomize. (Jeffrey Regan)
b5b11ef6 - Fix compile kustomize example. (bzub)
fa1af6f5 - Merge pull request #1473 from richardmarshall/execpluginhash (Jeff Regan)
9288dec0 - Fix failing BashedConfigMapTest (Jeff Regan)
1a45dd0b - Merge pull request #1566 from monopole/releaseNotes3.2.1 (Kubernetes Prow Robot)
592c5acf - docs: Exec plugin generator options (Richard Marshall)
ac9424fa - tests: Add unit tests for update resource options (Richard Marshall)
79fbe7c4 - Support resource generator options in exec plugins (Richard Marshall)
f69d526f - v3.2.1 release notes (Jeff Regan)
07a95a60 - Merge pull request #1565 from monopole/tweakBinaryDepsBeforeTagging (Jeff Regan)
032b3857 - Pin the kustomize binary's dependence on kustomize libs. (jregan)
81062959 - Merge pull request #1564 from monopole/moveKustomizeBinaryToOwnModule (Kubernetes Prow Robot)
b82a8fd3 - Move the kustomize binary to its own module. (Jeffrey Regan)
2d0c22d6 - Merge pull request #1562 from keleustes/tools (Kubernetes Prow Robot)
aa342def - Pin tool versions using go modules (Ian Howell)
10786ec0 - Merge pull request #1554 from keleustes/readme (Kubernetes Prow Robot)
7c705687 - Update README.md to include Kubernetes 1.16 (Jerome Brette)
e8933d97 - Merge pull request #1560 from monopole/precommitTuneup (Jeff Regan)
9d7b6544 - Make pre-commit more portable and less tricky. (jregan)
7a0946a9 - Merge pull request #1558 from monopole/dependOnNewPluginatorModule (Jeff Regan)
def4f045 - Depend on new pluginator location. (Jeffrey Regan)
2f2408f1 - Merge pull request #1559 from monopole/compressCopyright (Jeff Regan)
3b9bcc48 - Compress copyright in the commands package. (Jeffrey Regan)
d0429ff4 - Merge pull request #1557 from monopole/pluginatorModule (Jeff Regan)
33deefc3 - Copy pluginator to its own module. (Jeffrey Regan)
9b3de82b - Merge pull request #1506 from Liujingfang1/release (Jeff Regan)
d217074f - Merge pull request #1550 from keleustes/apiversion (Kubernetes Prow Robot)
1d90ba7c - Fix typo in apiVersion yaml declaration (Jerome Brette)
eeeb4c36 - Merge pull request #1547 from keleustes/extensions (Kubernetes Prow Robot)
b1faa989 - Update Ingress apiVersion to networking.k8s.io/v1beta1 (Jerome Brette)
d8250c9e - move test case (nimohunter)
c9500466 - add transformer href (Wang(わん))
0c32691e - Merge pull request #1537 from jaypipes/gomod-install-note (Kubernetes Prow Robot)
88b1d627 - Merge pull request #1541 from rtnpro/patch-1 (Jeff Regan)
aec82066 - Update INSTALL.md (Jeff Regan)
20c2b53a - Merge pull request #1542 from monopole/tweakFilePathsInTest (Jeff Regan)
274b5c3b - Tweak file path handling and logging in test. (Jeffrey Regan)
b1fdaa23 - Fix typo in transformerconfigs README (Ratnadeep Debnath)
b5d5e70b - empty list or map item return error (nimohunter)
2e829853 - empty list or map item return error (nimohunter)
55941f57 - add note about GO111MODULE for source install (Jay Pipes)
9e226001 - empty list or map item return error (nimohunter)
77b63f96 - add release note for v3.2.0 (jingfangliu)

Blog: v3.2.1

Thu, 26 Sep 2019 00:00:00 +0000

This is a patch release, with no new features from 3.2.0.

It reflects a change in dependence.

The kustomize binary is now built as a client, with no special consideration, of the set of public packages represented by the Go module at [https://github.com/kubernetes-sigs/kustomize].

kustomize the binary is now a client of the kustomize API represented by the public package surface presented by https://github.com/kubernetes-sigs/kustomize/v{whatever}

Blog: v3.2.0

Tue, 17 Sep 2019 00:00:00 +0000

Inline Patch

Since this version, Kustomize allows inline patches in all three of patchesStrategicMerge, patchesJson6902 and patches. Take a look at inline patch.

New Subcommand

Since this version, one can create a kustomization.yaml file in a directory through a create subcommand.

Create a new overlay from the base ../base

kustomize create --resources ../base

Create a new kustomization detecing resources in the current directory

kustomize create --autodetect

Once can also add all resources in the current directory recursively by

kustomize create --autodetect --recursive

New Example Generator

A new example generator of using go-getter to download resources is added. Take a look at go-getter generator.

Blog: v3.1.0

Fri, 26 Jul 2019 00:00:00 +0000

Extended patches

Since this version, Kustomize allows applying one patch to multiple resources. This works for both Strategic Merge Patch and JSON Patch. Take a look at patch multiple objects.

Improved Resource Matching

Multiple improvements have been made to allow the user to leverage “namespace” instead/or with “name suffix/prefix” to segregate resources.

Patch resolution improvement

The following example demonstrates how using the namespace field in the patch definition, will let the user define two different patches against two different Deployment having the same “deploy1” name but in different namespaces in the same Kustomize context/folder. Unless the namespace: field has been specified in the kustomization.yaml, no namespace value will be handled as Kubernetes default namespace.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: deploy1
  namespace: main
spec:
  template:
    spec:
      containers:
      - name: nginx
        env:
        - name: ANOTHERENV
          value: TESTVALUE
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: deploy1
  namespace: production
spec:
  template:
    spec:
      containers:
      - name: main
        env:
        - name: ANOTHERENV
          value: PRODVALUE

Variable resolution improvement

It is possible to add namespace field to the variable declaration. In the following example, two Service objects with the same elasticsearch name have been declared. Specifying the namespace in the objRef of the corresponding varriables, allows Kustomize to resovlve thoses variables. If the namespace is not specified, Kustomize will handle it has a “wildcard” value.

Extract of kustomization.yaml:

vars:
- name: elasticsearch-test-protocol
  objref:
    kind: Service
    name: elasticsearch
    namespace: test
    apiVersion: v1
  fieldref:
    fieldpath: spec.ports[0].protocol
- name: elasticsearch-dev-protocol
  objref:
    kind: Service
    name: elasticsearch
    namespace: dev
    apiVersion: v1
  fieldref:
    fieldpath: spec.ports[0].protocol

Simultaneous change of names and namespaces

Kustomize is now able to deal with simultaneous changes of name and namespace. Special attention has been paid the handling of:

ClusterRoleBinding/RoleBinding “subjects” field,
ValidatingWebhookConfiguration “webhooks” field.

The user should be able to use a kustomization.yaml as shown in the example bellow even if ClusterRoleBind,RoleBinding and ValidatingWebookConfiguration are part of the resources he needs to declare.

Extract of kustomization.yaml:

namePrefix: pfx-
nameSuffix: -sfx
namespace: testnamespace

resources:
...

Resource and Kustomize Context matching

Kustomize is now able to support more aggregation patterns.

If for instance, the top level of kustomization.yaml, is simply combining sub-components, (as in the following example), Kustomize has improved resource matching capabilities. This removes some of the constraints which were present on the utilization of prefix/suffix and namespace transformers in the individual components.

resources:
- ../component1
- ../component2
- ../component3

Other improvements

Image transformation has been improved. This allows the user to update the sha256 of an image with another sha256.
Multiple default transformer configuration entries have been added, removing the need for the user to add them as part of the configurations: section of the kustomization.yaml.
kustomize help command has been tidied up.

Blog: v3.0.0

Wed, 03 Jul 2019 00:00:00 +0000

This release is basically v2.1.0, with many post-v2.1.0 bugs fixed (in about 150 commits) and a v3 in Go package paths.

The major version increment to v3 puts a new floor on a stable API for plugin developers (both Go plugin developers and exec plugin developers who happen to use Go).

Why so soon after v2.1.0

We made a mistake - v2.1.0 should have been v3.0.0. Per the Go modules doc (which have improved a great deal recently), a release that’s already tagged v2 or higher should increment the major version when performing their first Go module-based release.

This advice applies to kustomize, since it was already at major version 2 when it began using Go modules to state its own dependencies in v2.1.0.

But the more important reason for v3 is a change to the kustomize versioning policy, forced by the introduction of plugins.

Historically, kustomize’s versioning policy didn’t involve Go modules and addressed only the command line tool’s behavior and the fields in a kustomization file. The underlying packages were an implementation detail, not under semantic versioning, because they weren’t intended for export (and should have all been under internal). Thus although the v2.1.0 CLI is backward compatible with v2.0.3, the underlying package APIs are not.

With Go modules, the go tool must assume that Go packages respect semantic versioning, so it can perform minimal version selection.

With the introduction of alpha plugins, kustomize sub-packages - in particular loader and resmap - become part of an API formally exposed to plugin authors, and so must be semantically versioned. This allows plugins defined in other repositories to clarify that they depend on kustomize v3.0.0, and not see confusing errors arising from incompatibilities between v2.1.0 and v2.0.3. Hence, the jump to v3.

Aside - the set of kustomize packages outside internal is too large, and over time, informed by package use, this API surface must shrink. Such shrinkage will trigger a major version increment.

Blog: v2.1.0

Tue, 18 Jun 2019 00:00:00 +0000

Go modules, resource ordering respected, generator and transformer plugins, eased loading restrictions, the notion of inventory, eased replica count modification. About ~90 issues closed since v2.0.3 in ~400 commits.

Download here.

Go modules

Kustomize now defines its dependencies in a top level go.mod file. This is the first step towards a package structure intentially exported as one or more Go modules for use in other programs (kubectl, kubebuilder, etc.) and in kustomize plugins (see below).

Resource ordering

Kustomize now retains the depth-first order of resources as read, a frequently requested feature.

This means resource order can be controlled by editting kustomization files. This is also vital to applying user-defined transformations (plugins) in a particular order.

Nothing needs to be done to activate this; it happens automatically.

The build command now accepts a --reorder flag with values legacy and none, with a default value of legacy.

legacy means apply an ordering based on GVK, that currently emits Namespace objects first, and ValidatingWebhookConfiguration objects last. This means that despite automatic retention of load order, your build output won’t change by default.

none means don’t reorder the resources before output. Specify this to see output order respect input order.

Generator and transformer plugins

Since the beginning (as kinflate back in Sep 2017), kustomize has read or generated resources, applied a series of pipelined transformation to them, and emitted the result to stdout.

At that time, the only way to change the behavior of a generator (e.g. a secret generator), or change the behavior of a transformer (e.g. a name changer, or json patcher), was to modify source code and put out a release.

v1.0.9 introduced generator options as a means to change the behavior of the only two generators available at the time - Secret and ConfigMap generators. It also introduced transformer configs as a way to fine tune the targets of transformations (e.g. to which fields selectors should be added). Most of the feature requests for kustomize revolve around changing the behavior of the builtin generators and transformers.

v2.1.0 adds an alpha plugin framework, that encourages users to write their own generators or transformers, declaring them as kubernetes objects just like everything else, and apply them as part of the kustomize build process.

To inform the API exposed to plugins, and to confirm that the plugin framework can offer plugin authors the same capabilities as builtin operations, all the builtin generators and tranformers have been converted to plugin form (with one exceptions awaiting Go module refinements). This means that adding, say, a secretGenerator or commonAnnotations directive to your kustomization will (in v2.1.0) trigger execution of code committed as a plugin.

For more information, see the kustomize plugin documentation.

Remove load restrictions

The following usage:

kustomize build --load_restrictor none $target

allows a kustomization.yaml file used in this build to refer to files outside its own directory (i.e. outside its root).

This is an opt-in to suppress a security feature that denies this precise behavior.

This feature should only be used to allow multiple overlays (e.g. prod, staging and dev) to share a patch file. To share resources, use a relative path or URL to a kustomization directory in the resources directive.

Inventory generation for pruning

Alpha

Users can add an inventory stanza to their kustomization file, to add a special inventory object to the build result.

This object applies to the cluster along with everything else in the build result and can be used by other clients to intelligently prune orphaned cluster resources.

For more information see the kustomize inventory object documentation.

Field changes / deprecations

`resources` expanded, `bases` deprecated

The resources field has been generalized; it now accepts what formerly could only be specified in the bases field.

This change was made to allow users fine control over resource processing order. With a distinct bases field, bases had to be loaded separately from resources as a group. Now, base loading may be interleaved as desired with the loading of resource files from the current directory. Resource ordering had to be respected before this feature could be introduced.

The bases field is now deprecated, and will be deleted in some future major release. Manage the deprecation simply moving the arguments of the bases field to the resources field in the desired order, e.g.

resources:
- someResouceFile.yaml
- someOtherResourceFile.yaml
bases:
- ../../someBaseDir

could become

resources:
- someResouceFile.yaml
- ../../someBaseDir
- someOtherResourceFile.yaml

The kustomized edit fix command will do this for you, though it will always put the bases at the end.

As an aside, the resources, generators and transformers fields now all accept the same argument format.

Each field’s argument is a string list, where each entry is either a resource (a relative path to a YAML file) or a kustomization (a path or URL pointing to a directory with a kustomization file). A kustomization directory used in this context is called a base.

The fact that the generators and transformers field accept bases and the fact that generator and transformer configuration objects are just normal k8s resources means that one can generate or transform a generator or a transformer (see TestTransformerTransformers).

`replicas` field

The common task of patching a deployment to edit the number of replicas is now made easier with the new replicas field.

`envs` field

An envs sub-field has been added to both configMapGenerator and secretGenerator, replacing the now deprecated (and singular) env field. The new field accepts lists, just like its sibling fields files and literals.

Optionally use kustomize edit fix to merge singular env field into a plural field.

Blog: v2.0.0

Tue, 05 Feb 2019 00:00:00 +0000

After security review, a field used in secret generation (see below) was removed from the definition of a kustomization file with no mechanism to convert it to a new form. Also, the set of files accessible from a kustomization file has been further constrained.

Per the versioning policy, backward incompatible changes trigger an increment of the major version number, hence we go from 1.0.11 to 2.0.0. We’re taking this major version increment opportunity to remove some already deprecated fields, and the code paths associated with them.

Backward Incompatible Changes

Kustomization Path Constraints

A kustomization file can specify paths to other files, including resources, patches, configmap generation data, secret generation data and bases. In the case of a base, the path can be a git URL instead.

In 1.x, these paths had to be relative to the current kustomization directory (the location of the kustomization file used in the build command).

In 2.0, bases can continue to specify, via relative paths, kustomizations outside the current kustomization directory. But non-base paths are constrained to terminate in or below the current kustomization directory. Further, bases specified via a git URL may not reference files outside of the directory used to clone the repository.

Kustomization Field Removals

patches

patches was deprecated and replaced by patchesStrategicMerge when patchesJson6902 was introduced. In Kustomize 2.0.0, patches is removed. Please use patchesStrategicMerge instead.

imageTags

imageTags is replaced by images since images can provide more features to change image names, registries, tags and digests.

secretGenerator/commands

commands is removed from SecretGenerator due to a security concern. One can use files or literals, similar to ConfigMapGenerator, to generate a secret.

secretGenerator:
- name: app-tls
  files:
    - secret/tls.cert
    - secret/tls.key
  type: "kubernetes.io/tls"

Compatible Changes (New Features)

As this release is triggered by a security change, there are no major new features to announce. A few things that are worth mentioning in this release are:

More than 40 issues closed since 1.0.11 release (including many extensions to transformation rules).

Users can run kustomize edit fix to migrate a kustomization file working with previous versions to one working with 2.0.0. For example, a kustomization.yaml with following content

patches:
  - deployment-patch.yaml
imageTags:
  - name: postgres
    newTag: v1

will be converted to

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
patchesStrategicMerge:
  - deployment-patch.yaml
images:
  - name: postgres
    newTag: v1

Kustomization filename

In previous versions, the name of a kustomization file had to be kustomization.yaml. Kustomize allows kustomization.yaml, kustomization.yml and Kustomization. In a directory, only one of those filenames is allowed. If there are more than one found, Kustomize will exit with an error. Please select the best filename for your use cases.
Cancelled plans to deprecate applying prefix/suffix to namespace. The deprecation warning
```
Adding nameprefix and namesuffix to Namespace resource will be deprecated in next release.
```
was removed.

Blog: v1.0.1

Mon, 21 May 2018 00:00:00 +0000

Initial release after move from github.com/kubernetes/kubectl to github.com/kubernetes-sigs/kustomize.

History

May 2018: v1.0 after move to github.com/kubernetes-sigs/kubectl from github.com/kubernetes/kubectl. Has kustomization file, bases, overlays, basic transforms.
Apr 2018: s/kinflate/kustomize/, s/manifest/kustomization/
Oct 2017: s/kexpand/kinflate/
Sep 2017: kexpand starts in github.com/kubernetes/kubectl
Aug 2017: DAM authored by Brian Grant