From 54ae9ba9fca95913e9810bd1016994ab1bca9913 Mon Sep 17 00:00:00 2001 From: Thomas Dy Date: Fri, 2 Jul 2021 13:45:39 +0900 Subject: [PATCH] Update supported URLs in remoteBuild.md --- examples/remoteBuild.md | 66 ++++++++++++++++++++------------------ examples/zh/remoteBuild.md | 8 ++--- 2 files changed, 39 insertions(+), 35 deletions(-) diff --git a/examples/remoteBuild.md b/examples/remoteBuild.md index 446c0abcf0..ea86e28aa7 100644 --- a/examples/remoteBuild.md +++ b/examples/remoteBuild.md @@ -1,10 +1,30 @@ # remote targets -`kustomize build` can be run on a URL. +`kustomize build` can be run on a URL. Resources can also reference other +kustomization directories via URLs too. -A [lite version of go-getter module](https://github.com/yujunz/go-getter) is -leveraged to get remote content, then running `kustomize build` against the -desired directory in the local copy. +The URL format is an HTTPS or SSH `git clone` URL with an optional directory and +some query string parameters. The directory is specified by appending a `//` +after the repo URL. The following query string parameters can also be specified: + + * `ref` - a `git fetch`-able ref, typically a branch, tag, or full commit hash + (short hashes are not supported) + * `timeout` (default `27s`) - a number in seconds, or a go duration. specifies + the timeout for fetching the resource + * `submodules` (default `true`) - a boolean specifying whether to clone + submodules or not + +For example, +`https://github.com/kubernetes-sigs/kustomize//examples/multibases/dev/?ref=v1.0.6` +will essentially clone the git repo via HTTPS, checkout `v1.0.6` and run +`kustomize build` inside the `examples/multibases/dev` directory. + +SSH clones are also supported either with `git@github.com:owner/repo` or +`ssh://git@github.com/owner/repo` URLs. + +`file:///` clones are not supported. + +# Examples To try this immediately, run a build against the kustomization in the [multibases](multibases/README.md) example. There's @@ -12,7 +32,7 @@ one pod in the output: ``` -target="github.com/kubernetes-sigs/kustomize/examples/multibases/dev/?ref=v1.0.6" +target="https://github.com/kubernetes-sigs/kustomize//examples/multibases/dev/?ref=v1.0.6" test 1 == \ $(kustomize build $target | grep dev-myapp-pod | wc -l); \ echo $? @@ -24,25 +44,13 @@ someone who wants to send them all at the same time): ``` -target="https://github.com/kubernetes-sigs/kustomize/examples/multibases?ref=v1.0.6" +target="https://github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6" test 3 == \ $(kustomize build $target | grep cluster-a-.*-myapp-pod | wc -l); \ echo $? ``` -The URL can be an archive - - -``` -target="https://github.com/kustless/kustomize-examples/archive/master.zip//kustomize-examples-master" -test 1 == \ - $(kustomize build $target | grep remote-cm | wc -l); \ - echo $? -``` - -Note the kustomize root path inside archive must be appended after `//`. - -A base can be a URL: +A remote kustomization directory resource can also be a URL: ``` @@ -50,7 +58,7 @@ DEMO_HOME=$(mktemp -d) cat <$DEMO_HOME/kustomization.yaml resources: -- github.com/kubernetes-sigs/kustomize/examples/multibases?ref=v1.0.6 +- https://github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6 namePrefix: remote- EOF ``` @@ -65,18 +73,16 @@ test 3 == \ echo $? ``` -## URL format - -The url should follow -[hashicorp/go-getter URL format](https://github.com/hashicorp/go-getter#url-format). +## Legacy URL format -Note that using `//` in the url will only copy the directory specified by the path -after `//`, which means some relative paths, like `../xxx`, may not work. Using `/` to copy -entire repo. For more details please see [go-getter documentation](https://github.com/hashicorp/go-getter#subdirectories). +Historically, kustomize has supported a modified [hashicorp/go-getter URL format](https://github.com/hashicorp/go-getter#url-format). -Note that S3 and GCS are NOT supported to avoid introducing massive dependency. +This is still supported for backwards compatibility but is no longer recommended +to be used as kustomize supports different query parameters and the semantics of +what gets fetched in `go-getter` itself are different (particularly with +subdirectories). -Here are some example urls +Here are some examples of legacy urls ``` @@ -92,7 +98,5 @@ resources: - github.com/Liujingfang1/kustomize/examples/helloWorld?ref=repoUrl2 # a subdirectory in a repo on commit `7050a45134e9848fca214ad7e7007e96e5042c03` - github.com/Liujingfang1/kustomize/examples/helloWorld?ref=7050a45134e9848fca214ad7e7007e96e5042c03 -# a subdirectory in a remote archive -- https://github.com/kustless/kustomize-examples/archive/master.zip//kustomize-examples-master EOF ``` diff --git a/examples/zh/remoteBuild.md b/examples/zh/remoteBuild.md index b78147047e..ebdf0a62ee 100644 --- a/examples/zh/remoteBuild.md +++ b/examples/zh/remoteBuild.md @@ -9,7 +9,7 @@ ```bash -target="github.com/kubernetes-sigs/kustomize/examples/multibases/dev/?ref=v1.0.6" +target="https://github.com/kubernetes-sigs/kustomize//examples/multibases/dev/?ref=v1.0.6" test 1 == \ $(kustomize build $target | grep dev-myapp-pod | wc -l); \ echo $? @@ -19,7 +19,7 @@ test 1 == \ ```bash -target="https://github.com/kubernetes-sigs/kustomize/examples/multibases?ref=v1.0.6" +target="https://github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6" test 3 == \ $(kustomize build $target | grep cluster-a-.*-myapp-pod | wc -l); \ echo $? @@ -33,7 +33,7 @@ DEMO_HOME=$(mktemp -d) cat <$DEMO_HOME/kustomization.yaml resources: -- github.com/kubernetes-sigs/kustomize/examples/multibases?ref=v1.0.6 +- https://github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6 namePrefix: remote- EOF ``` @@ -47,7 +47,7 @@ test 3 == \ echo $? ``` -## URL format +## Legacy URL format URL 需要遵循 [hashicorp/go-getter URL 格式](https://github.com/hashicorp/go-getter#url-format) 。下面是一些遵循此约定的 Github repos 示例url。