Skip to content

Commit f3d6133

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #313 from annasong20/document-localize
Add `kustomize localize` Documentation
2 parents 12b1077 + ebf0374 commit f3d6133

File tree

1 file changed

+262
-0
lines changed
  • site/content/en/references/kustomize/cmd/localize

1 file changed

+262
-0
lines changed

‎site/content/en/references/kustomize/cmd/localize/_index.md‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
---
2+
title: "kustomize localize"
3+
linkTitle: "localize"
4+
type: docs
5+
weight: 9
6+
description: >
7+
Downloads url content to a local directory, and replaces urls with paths to downloaded content
8+
---
9+
10+
Disclaimer: This is an alpha command. Please see the [command proposal](https://github.com/kubernetes-sigs/kustomize/blob/master/proposals/22-04-localize-command.md)
11+
for full capabilities.
12+
13+
### Description
14+
15+
The `kustomize localize` command makes a copy of a [kustomization root](https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#kustomization-root),
16+
in which referenced urls are replaced by local paths to their downloaded content.
17+
The command copies files referenced under kustomization [fields](#fields)
18+
in the source kustomization, and all base kustomizations under it.
19+
20+
The purpose of this command is to create a copied root on which
21+
`kustomize build`<sup>[[build]](#notes)</sup> produces the same output
22+
without a network connection. The original motivation for this command
23+
is documented [here](https://github.com/kubernetes-sigs/kustomize/issues/3980).
24+
A `kustomize build` use case precluding network use could be a CI/CD pipeline
25+
that only has access to the internal network.
26+
27+
### Usage
28+
29+
The command takes the following form:
30+
31+
<pre>
32+
<b>kustomize localize</b> [<ins>target</ins> [<ins>newDir</ins>]] [--scope <ins>scope</ins>]
33+
</pre>
34+
35+
where
36+
37+
* `target` is the kustomization root to localize.
38+
This value can be a local path or a [remote root](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/remoteBuild.md).
39+
The default value is the current working directory.
40+
* `newDir` is the destination of the "localized" copy that the command creates.
41+
The destination directory cannot already exist.
42+
The command creates the destination directory, but not any of its parents.
43+
The default destination is a directory in the current working directory named:
44+
* `localized-{target}` for local `target`
45+
* `localized-{target}-{ref}`<sup>[[ref]](#notes)</sup> for remote `target`.
46+
See an [example](#example).
47+
* `scope` is the "bounding directory"; in other words, the command
48+
can only copy files inside this directory. The default is `{target}`.
49+
This flag cannot be specified for remote `target`, as its value is implicitly
50+
the repo containing `target`.
51+
52+
### Structure
53+
54+
The localized destination directory at `newDir` is a copy<sup>[[absolute]](#notes), [[symlink]](#notes)</sup>
55+
of `scope`, excluding files that `target` does not reference and
56+
with the addition of downloaded remote content.
57+
Note that if `scope` is not equal to `target`, the localized root
58+
that produces the same `kustomize build` output as `target`
59+
is at the same relative path inside `newDir` as `target` inside `scope`.
60+
61+
Downloaded files are copied to a directory named `localized-files` located in
62+
the same directory as the referencing kustomization file.
63+
Inside `localized-files`, the content of remote
64+
65+
* roots are written to path<sup>[[localized root]](#notes)</sup>:
66+
67+
<pre>
68+
<ins>host</ins> / <ins>path/to/repo</ins> / <ins>ref</ins> / <ins>path/to/file/in/repo</ins>
69+
</pre>
70+
71+
* files are written to the following path<sup>[[localized file]](#notes)</sup>
72+
constructed from its url components:
73+
74+
<pre>
75+
<ins>host</ins> / <ins>path</ins>
76+
</pre>
77+
78+
### Example
79+
80+
Running the following command:
81+
82+
```shell
83+
$ kustomize localize "https://github.com/kubernetes-sigs/kustomize//api/krusty/testdata/localize/remote?submodules=0&ref=kustomize/v5.0.0&timeout=300"
84+
```
85+
86+
in an empty directory named `example` creates the localized destination
87+
with the following contents:
88+
89+
```shell
90+
example
91+
└── localized-remote-kustomize-v5.0.0
92+
├── localized-files
93+
│ └── github.com
94+
│ └── kubernetes-sigs
95+
│ └── kustomize
96+
│ └── kustomize
97+
│ └── v5.0.0
98+
│ └── api
99+
│ └── krusty
100+
│ └── testdata
101+
│ └── localize
102+
│ └── simple
103+
│ ├── deployment.yaml
104+
│ ├── service.yaml
105+
│ └── kustomization.yaml
106+
└── hpa.yaml
107+
```
108+
```shell
109+
# example/localized-remote-kustomize-v5.0.0/kustomization.yaml
110+
apiVersion: kustomize.config.k8s.io/v1beta1
111+
commonLabels:
112+
purpose: remoteReference
113+
kind: Kustomization
114+
resources:
115+
- localized-files/github.com/kubernetes-sigs/kustomize/kustomize/v5.0.0/api/krusty/testdata/localize/simple
116+
- hpa.yaml
117+
```
118+
```shell
119+
# 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
120+
apiVersion: kustomize.config.k8s.io/v1beta1
121+
kind: Kustomization
122+
namePrefix: localize-
123+
resources:
124+
- deployment.yaml
125+
- service.yaml
126+
```
127+
128+
The [proposal](https://github.com/kubernetes-sigs/kustomize/blob/master/proposals/22-04-localize-command.md)
129+
contains more examples.
130+
131+
### Fields
132+
133+
The command localizes, copying or downloading, files under
134+
the following kustomization fields<sup>[[resource]](#notes)</sup>:
135+
136+
* `resources`
137+
* `components`
138+
* `openapi.path`
139+
* `configurations`
140+
* `crds`
141+
* `configMapGenerator`<sup>[[gen]](#notes)</sup>
142+
* `secretGenerator`<sup>[[gen]](#notes)</sup>
143+
* `helmCharts`<sup>[[helm]](#notes)</sup>
144+
* `helmGlobals`<sup>[[helm]](#notes)</sup>
145+
* `patches`
146+
* `replacements`
147+
148+
In addition to localizing files<sup>[[plugin]](#notes)</sup> under the following
149+
plugin fields:
150+
151+
* `generators`
152+
* `transformers`
153+
* `validators`
154+
155+
the command localizes files referenced by the following plugins<sup>[[resource]](#notes)</sup>,
156+
which have a built-in kustomization field counterpart:
157+
158+
* `ConfigMapGenerator`<sup>[[gen]](#notes)</sup>
159+
* `SecretGenerator`<sup>[[gen]](#notes)</sup>
160+
* `HelmChartInflationGenerator`<sup>[[helm]](#notes)</sup>
161+
* `PatchTransformer`
162+
* `PatchJson6902Transformer`
163+
* `PatchStrategicMergeTransformer`
164+
* `ReplacementTransformer`
165+
166+
The command also localizes the following deprecated fields:
167+
* `bases`
168+
* `helmChartInflationGenerator`<sup>[[helm]](#notes)</sup>
169+
* `patchesStrategicMerge`
170+
* `patchesJson6902`
171+
172+
### Notes
173+
* [absolute]: The alpha version of this command does not handle and
174+
throws an error for absolute paths.
175+
<br></br>
176+
177+
* [build]: This command may not catch `build` errors in the kustomization, as
178+
this command serves a different purpose than `kustomize build` and does not look
179+
to overstep its scope.
180+
<br></br>
181+
182+
However, this command will fail on a kustomization that requires the
183+
`kustomize build --load-restrictor LoadRestrictionsNone` flag to run, as
184+
this command copies files following security best practices.<sup>[[symlink]](#notes)</sup>
185+
<br></br>
186+
187+
* [gen]: If a key is not specified for a `ConfigMapGenerator`, `SecretGenerator`
188+
`files` entry, this command does not add one. Because in such a case the
189+
`build` output key is the file name, the output key will be different on the
190+
localized copy if the file for said entry is a symlink to a file with a
191+
different name<sup>[[symlink]](#notes)</sup>.
192+
<br></br>
193+
194+
* [helm]: Because helm support in kustomize is [intentionally limited](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/helmcharts/),
195+
this command does not download remote content referenced by helm transformers.
196+
This command does, however, minimally copy local `valuesFile` and `chartHome`,
197+
albeit without following symlinks in `chartHome`.
198+
<br></br>
199+
200+
* [localized file]: This command is primarily concerned with supporting
201+
remote files of the form `https://raw.githubusercontent.com/kubernetes-sigs/kustomize/kustomize/v4.5.7/proposals/22-04-localize-command.md`,
202+
generated by clicking `Raw` in the GitHub UI. The url path of these files
203+
consists of
204+
205+
<pre>
206+
<ins>path/to/repo</ins> / <ins>ref</ins> / <ins>path/to/file/in/repo</ins>
207+
</pre>
208+
209+
The localized file path format was chosen as `host / path` so that the path
210+
for these GitHub files would match the localized root path format.
211+
<br></br>
212+
213+
* [localized root]: A [remote root](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/remoteBuild.md)
214+
is a [git url](https://git-scm.com/docs/git-fetch#_git_urls) specifying a repo,
215+
a double slash `//` delimiter, a path to the root inside the repo, and
216+
query string parameters including [[ref]](#notes). The different segments of a
217+
localized remote root path are the:
218+
219+
* [host](https://git-scm.com/docs/git-fetch#_git_urls) of the git url.
220+
Because [`file`-schemed](https://git-scm.com/docs/git-fetch#_git_urls)
221+
git urls do not have a `host`, their localized paths under the
222+
`localized-files` directory begin with a directory named `file-schemed`
223+
instead of a `host` value.
224+
* [path/to/repo](https://git-scm.com/docs/git-fetch#_git_urls) of the git url
225+
* [[ref]](#notes)
226+
* `path/to/file/in/repo`, which refers to the path to the root after the
227+
`//` delimiter, concatenated with the relative path from said root
228+
to referenced local files. This path is delinked<sup>[[symlink]](#notes)</sup>.
229+
<br></br>
230+
231+
This command does not include `scheme`, `userinfo`, or `port`
232+
in the remote root's localized path for the sake of simplicity. Please leave
233+
[feedback](https://github.com/kubernetes-sigs/kustomize/issues/4996)
234+
if omitting these url components affects the correctness of your localized copy.
235+
<br></br>
236+
237+
* [plugin]: The alpha version of this command handles plugin files, but not
238+
kustomization roots producing plugins. The command throws an error upon
239+
encountering such roots under the plugin fields.
240+
<br></br>
241+
242+
* [ref]: This command requires [remote roots](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/remoteBuild.md)
243+
to have a `ref` query string parameter. Ideally, if the ref is a stable tag,
244+
the content of the remote root is always the same.
245+
See [[localized root]](#notes) for more on remote roots.
246+
<br></br>
247+
248+
* [resource]: As a byproduct of processing yaml files
249+
such as the kustomization file, this command writes their keys
250+
in alphabetical order to the destination.
251+
<br></br>
252+
253+
* [symlink]: To avoid `kustomize build` load restriction errors on the
254+
localized copy, this command copies files using their actual locations, after
255+
following symlinks. `kustomize build` enforces load restrictions using the
256+
"delinked" locations of files. As long as this command preserves the delinked
257+
structure of `scope` in the localized copy, the copy will satisfy
258+
load requirements.
259+
260+
### Feedback
261+
262+
Please leave your feedback for this command under [the following issue](https://github.com/kubernetes-sigs/kustomize/issues/4996).

0 commit comments

Comments
 (0)