kustomize localize

Downloads url content to a local directory, and replaces urls with paths to downloaded content

Disclaimer: This is an alpha command. Please see the command proposal for full capabilities.

Description

The kustomize localize command makes a copy of a kustomization root, in which referenced urls are replaced by local paths to their downloaded content. The command copies files referenced under kustomization fields in the source kustomization, and all base kustomizations under it.

The purpose of this command is to create a copied root on which kustomize build[build] produces the same output without a network connection. The original motivation for this command is documented here. A kustomize build use case precluding network use could be a CI/CD pipeline that only has access to the internal network.

Usage

The command takes the following form:

kustomize localize [target [newDir]] [--scope scope]

where

  • target is the kustomization root to localize. This value can be a local path or a remote root. The default value is the current working directory.
  • newDir is the destination of the “localized” copy that the command creates. The destination directory cannot already exist. The command creates the destination directory, but not any of its parents. The default destination is a directory in the current working directory named:
    • localized-{target} for local target
    • localized-{target}-{ref}[ref] for remote target. See an example.
  • scope is the “bounding directory”; in other words, the command can only copy files inside this directory. The default is {target}. This flag cannot be specified for remote target, as its value is implicitly the repo containing target.

Structure

The localized destination directory at newDir is a copy[absolute], [symlink] of scope, excluding files that target does not reference and with the addition of downloaded remote content. Note that if scope is not equal to target, the localized root that produces the same kustomize build output as target is at the same relative path inside newDir as target inside scope.

Downloaded files are copied to a directory named localized-files located in the same directory as the referencing kustomization file. Inside localized-files, the content of remote

  • roots are written to path[localized root]:

    host / path/to/repo / ref / path/to/file/in/repo

  • files are written to the following path[localized file] constructed from its url components:

    host / path

Example

Running the following command:

$ kustomize localize "https://github.com/kubernetes-sigs/kustomize//api/krusty/testdata/localize/remote?submodules=0&ref=kustomize/v5.0.0&timeout=300"

in an empty directory named example creates the localized destination with the following contents:

example
└── localized-remote-kustomize-v5.0.0
    ├── localized-files
    │   └── github.com
    │       └── kubernetes-sigs
    │           └── kustomize
    │               └── kustomize
    │                   └── v5.0.0
    │                       └── api
    │                           └── krusty
    │                               └── testdata
    │                                   └── localize
    │                                       └── simple
    │                                           ├── deployment.yaml
    │                                           ├── service.yaml
    │                                           └── kustomization.yaml
    └── hpa.yaml

# example/localized-remote-kustomize-v5.0.0/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
commonLabels:
  purpose: remoteReference
kind: Kustomization
resources:
- localized-files/github.com/kubernetes-sigs/kustomize/kustomize/v5.0.0/api/krusty/testdata/localize/simple
- hpa.yaml

# example/localized-remote-kustomize-v5.0.0/localized-files/github.com/kubernetes-sigs/kustomize/kustomize/v5.0.0/api/krusty/testdata/localize/simple/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namePrefix: localize-
resources:
- deployment.yaml
- service.yaml

The proposal contains more examples.

Fields

The command localizes, copying or downloading, files under the following kustomization fields[resource]:

  • resources
  • components
  • openapi.path
  • configurations
  • crds
  • configMapGenerator[gen]
  • secretGenerator[gen]
  • helmCharts[helm]
  • helmGlobals[helm]
  • patches
  • replacements

In addition to localizing files[plugin] under the following plugin fields:

  • generators
  • transformers
  • validators

the command localizes files referenced by the following plugins[resource], which have a built-in kustomization field counterpart:

  • ConfigMapGenerator[gen]
  • SecretGenerator[gen]
  • HelmChartInflationGenerator[helm]
  • PatchTransformer
  • PatchJson6902Transformer
  • PatchStrategicMergeTransformer
  • ReplacementTransformer

The command also localizes the following deprecated fields:

  • bases
  • helmChartInflationGenerator[helm]
  • patchesStrategicMerge
  • patchesJson6902

Notes

  • [absolute]: The alpha version of this command does not handle and throws an error for absolute paths.

  • [build]: This command may not catch build errors in the kustomization, as this command serves a different purpose than kustomize build and does not look to overstep its scope.

    However, this command will fail on a kustomization that requires the kustomize build --load-restrictor LoadRestrictionsNone flag to run, as this command copies files following security best practices.[symlink]

  • [gen]: If a key is not specified for a ConfigMapGenerator, SecretGenerator files entry, this command does not add one. Because in such a case the build output key is the file name, the output key will be different on the localized copy if the file for said entry is a symlink to a file with a different name[symlink].

  • [helm]: Because helm support in kustomize is intentionally limited, this command does not download remote content referenced by helm transformers. This command does, however, minimally copy local valuesFile and chartHome, albeit without following symlinks in chartHome.

  • [localized file]: This command is primarily concerned with supporting remote files of the form https://raw.githubusercontent.com/kubernetes-sigs/kustomize/kustomize/v4.5.7/proposals/22-04-localize-command.md, generated by clicking Raw in the GitHub UI. The url path of these files consists of

    path/to/repo / ref / path/to/file/in/repo

    The localized file path format was chosen as host / path so that the path for these GitHub files would match the localized root path format.

  • [localized root]: A remote root is a git url specifying a repo, a double slash // delimiter, a path to the root inside the repo, and query string parameters including [ref]. The different segments of a localized remote root path are the:

    • host of the git url. Because file-schemed git urls do not have a host, their localized paths under the localized-files directory begin with a directory named file-schemed instead of a host value.
    • path/to/repo of the git url
    • [ref]
    • path/to/file/in/repo, which refers to the path to the root after the // delimiter, concatenated with the relative path from said root to referenced local files. This path is delinked[symlink].

    This command does not include scheme, userinfo, or port in the remote root’s localized path for the sake of simplicity. Please leave feedback if omitting these url components affects the correctness of your localized copy.

  • [plugin]: The alpha version of this command handles plugin files, but not kustomization roots producing plugins. The command throws an error upon encountering such roots under the plugin fields.

  • [ref]: This command requires remote roots to have a ref query string parameter. Ideally, if the ref is a stable tag, the content of the remote root is always the same. See [localized root] for more on remote roots.

  • [resource]: As a byproduct of processing yaml files such as the kustomization file, this command writes their keys in alphabetical order to the destination.

  • [symlink]: To avoid kustomize build load restriction errors on the localized copy, this command copies files using their actual locations, after following symlinks. kustomize build enforces load restrictions using the “delinked” locations of files. As long as this command preserves the delinked structure of scope in the localized copy, the copy will satisfy load requirements.

Feedback

Please leave your feedback for this command under the following issue.


Last modified February 7, 2023: Clarify localized target inside scope (ebf0374)