Skip to content

Commit 46904d0

Browse files
annasong20annasong20
committed
Address feedback
1 parent 5501325 commit 46904d0

File tree

1 file changed

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

1 file changed

+109
-109
lines changed

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

Lines changed: 109 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,28 @@ linkTitle: "localize"
44
type: docs
55
weight: 9
66
description: >
7-
Replace urls with local paths
7+
Replace urls with local paths to downloaded content
88
---
99

1010
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)
1111
for full capabilities.
1212

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
13+
### Description
1814

1915
The `kustomize localize` command makes a recursive copy of a kustomization
2016
in which referenced urls are replaced by local paths to their downloaded content.
17+
The command copies files referenced under kustomization [fields](#fields).
18+
The copy contains files referenced both by the kustomization in question
19+
and by recursively referenced kustomizations.
2120

2221
The purpose of this command is to create a copy on which
2322
`kustomize build`<sup>[[build]](#notes)</sup> produces the same output
24-
without a network connection.
23+
without a network connection. The original motivation for this command
24+
is documented [here](https://github.com/kubernetes-sigs/kustomize/issues/3980).
25+
A `kustomize build` use case precluding network use could be a CI/CD pipeline
26+
that only has access to the internal network.
27+
28+
### Usage
2529

2630
The command takes the following form:
2731

@@ -34,71 +38,35 @@ where
3438
* `target` is the [kustomization directory](https://kubectl.docs.kubernetes.io/references/kustomize/glossary/#kustomization-root)
3539
to localize. This value can be a local path or a [remote root](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/remoteBuild.md).
3640
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.
41+
* `newDir` is the destination of the "localized" copy that the command creates.
42+
The destination cannot already exist.
43+
The command creates the destination directory, but not any of its parents.
3944
The default destination is a directory in the current working directory named:
4045
* `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`
46+
* `localized-{target}-{ref}`<sup>[[ref]](#notes)</sup> for remote `target`.
47+
See an [example](#example).
48+
* `scope` is the "bounding directory"; in other words, the command
49+
can only copy files inside this directory. The default is `{target}`.
50+
This flag cannot be specified for remote `target`, as its value is implicitly
51+
the repo containing `target`.
8452

8553
### Structure
8654

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
55+
The localized destination directory is a copy<sup>[[absolute]](#notes), [[symlink]](#notes)</sup>
56+
of `scope`, excluding files that `target` does not reference and
8957
with the addition of downloaded remote content.
9058

9159
Downloaded files are copied to a directory named `localized-files` located in
9260
the same directory as the referencing kustomization. Inside `localized-files`,
93-
the content of remote
61+
the content of remote
9462
* roots are written to path<sup>[[localized root]](#notes)</sup>:
9563

9664
<pre>
9765
<ins>host</ins> / <ins>path/to/repo</ins> / <ins>ref</ins> / <ins>path/to/file/in/repo</ins>
9866
</pre>
9967

100-
* files are written to the following path<sup>[[localized file]](#notes)</sup>
101-
constructed from its url components:
68+
* files are written to the following path<sup>[[localized file]](#notes)</sup>
69+
constructed from its url components:
10270

10371
<pre>
10472
<ins>host</ins> / <ins>path</ins>
@@ -108,73 +76,101 @@ constructed from its url components:
10876

10977
Running the following command:
11078

79+
<!--
80+
TODO(annasong): Replace ref with kustomize/v5.0 after release.
81+
The kustomize/v4.5.7 version is very slow to execute because it fetches
82+
submodules.
83+
-->
11184
```shell
112-
$ kustomize localize src dst
85+
$ kustomize localize https://github.com/kubernetes-sigs/kustomize//api/krusty/testdata/localize/remote?ref=kustomize/v4.5.7&submodules=0&timeout=300
11386
```
11487

115-
in the `example` directory shown below:
88+
in an empty directory named `example` creates the localized destination
89+
with the following contents:
11690

11791
```shell
11892
example
119-
└── src
120-
├── configMap.yaml
121-
└── kustomization.yaml
93+
└── localized-remote-kustomize-v4.5.7
94+
├── localized-files
95+
│ └── github.com
96+
│ └── kubernetes-sigs
97+
│ └── kustomize
98+
│ └── kustomize
99+
│ └── v4.5.7
100+
│ └── api
101+
│ └── krusty
102+
│ └── testdata
103+
│ └── localize
104+
│ └── simple
105+
│ ├── deployment.yaml
106+
│ ├── service.yaml
107+
│ └── kustomization.yaml
108+
└── hpa.yaml
122109
```
123110
```shell
124-
# example/src/kustomization.yaml
111+
# example/localized-remote-kustomize-v4.5.7/kustomization.yaml
112+
apiVersion: kustomize.config.k8s.io/v1beta1
113+
commonLabels:
114+
purpose: remoteReference
115+
kind: Kustomization
125116
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
117+
- localized-files/github.com/kubernetes-sigs/kustomize/kustomize/v4.5.7/api/krusty/testdata/localize/simple
118+
- hpa.yaml
129119
```
130-
131-
creates `dst` with the following contents:
132-
133120
```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
121+
# example/localized-remote-kustomize-v4.5.7/localized-files/github.com/kubernetes-sigs/kustomize/kustomize/v4.5.7/api/krusty/testdata/localize/simple/kustomization.yaml
122+
apiVersion: kustomize.config.k8s.io/v1beta1
123+
kind: Kustomization
124+
namePrefix: localize-
169125
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
126+
- deployment.yaml
127+
- service.yaml
173128
```
174129

175-
The [proposal](https://github.com/kubernetes-sigs/kustomize/blob/master/proposals/22-04-localize-command.md)
130+
The [proposal](https://github.com/kubernetes-sigs/kustomize/blob/master/proposals/22-04-localize-command.md)
176131
contains more examples.
177132

133+
### Fields
134+
135+
The command localizes, copying or downloading, files under
136+
the following kustomization fields<sup>[[resource]](#notes)</sup>:
137+
138+
* `resources`
139+
* `components`
140+
* `openapi.path`
141+
* `configurations`
142+
* `crds`
143+
* `configMapGenerator`<sup>[[gen]](#notes)</sup>
144+
* `secretGenerator`<sup>[[gen]](#notes)</sup>
145+
* `helmCharts`<sup>[[helm]](#notes)</sup>
146+
* `helmGlobals`<sup>[[helm]](#notes)</sup>
147+
* `patches`
148+
* `replacements`
149+
150+
In addition to localizing files<sup>[[plugin]](#notes)</sup> under the following
151+
plugin fields:
152+
153+
* `generators`
154+
* `transformers`
155+
* `validators`
156+
157+
the command localizes files referenced by the following plugins<sup>[[resource]](#notes)</sup>,
158+
which have a built-in kustomization field counterpart:
159+
160+
* `ConfigMapGenerator`<sup>[[gen]](#notes)</sup>
161+
* `SecretGenerator`<sup>[[gen]](#notes)</sup>
162+
* `HelmChartInflationGenerator`<sup>[[helm]](#notes)</sup>
163+
* `PatchTransformer`
164+
* `PatchJson6902Transformer`
165+
* `PatchStrategicMergeTransformer`
166+
* `ReplacementTransformer`
167+
168+
The command also localizes the following deprecated fields:
169+
* `bases`
170+
* `helmChartInflationGenerator`<sup>[[helm]](#notes)</sup>
171+
* `patchesStrategicMerge`
172+
* `patchesJson6902`
173+
178174
### Notes
179175
* [absolute]: The alpha version of this command does not handle and
180176
throws an error for absolute paths.
@@ -260,4 +256,8 @@ localized copy, this command copies files using their actual locations, after
260256
following symlinks. `kustomize build` enforces load restrictions using the
261257
"delinked" locations of files. As long as this command preserves the delinked
262258
structure of `scope` in the localized copy, the copy will satisfy
263-
load requirements.
259+
load requirements.
260+
261+
### Feedback
262+
263+
Please leave your feedback for this command under [the following issue](https://github.com/kubernetes-sigs/kustomize/issues/4996).

0 commit comments

Comments
 (0)