Skip to content

Commit 5501325

Browse files
annasong20annasong20
committed
Add localize command documentation
1 parent 12b1077 commit 5501325

File tree

1 file changed

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

1 file changed

+263
-0
lines changed

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

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

0 commit comments

Comments
 (0)