From 759ba1cbf43d6ec147a6beb3f4dd96d259e7090a Mon Sep 17 00:00:00 2001 From: Jingfang Liu Date: Thu, 16 Aug 2018 10:46:27 -0700 Subject: [PATCH] Add example for kustomize build {url} --- docs/glossary.md | 2 +- docs/kustomization.yaml | 8 ++++++ examples/README.md | 4 ++- examples/remoteBuild.md | 58 ++++++++++++++++++++++++++++++++++++++ pkg/commands/build.go | 22 ++++++++++++--- pkg/types/kustomization.go | 17 ++++++----- 6 files changed, 96 insertions(+), 15 deletions(-) create mode 100644 examples/remoteBuild.md diff --git a/docs/glossary.md b/docs/glossary.md index 3657d76c6..ff2c0e0a9 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -285,7 +285,7 @@ The _target_ is the argument to `kustomize build`, e.g.: > kustomize build $target > ``` -`$target` must be a path to a directory that +`$target` must be a path or a url to a directory that immediately contains a [kustomization]. The target contains, or refers to, all the information diff --git a/docs/kustomization.yaml b/docs/kustomization.yaml index d1599d4ae..2cfb89a4e 100644 --- a/docs/kustomization.yaml +++ b/docs/kustomization.yaml @@ -101,6 +101,11 @@ secretGenerator: # containing a kustomization file, else the # customization fails. # +# The entry could be a relative path pointing to a local directory +# or a url pointing to a directory in a remote repo. +# The url should follow hashicorp/go-getter URL format +# https://github.com/hashicorp/go-getter#url-format +# # The presence of this field means this file (the file # you a reading) is an _overlay_ that further # customizes information coming from these _bases_. @@ -111,6 +116,9 @@ secretGenerator: # etc. that differ from the common base). bases: - ../../base +- github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6 +- github.com/Liujingfang1/mysql +- github.com/Liujingfang1/kustomize//examples/helloWorld?ref=test-branch # Each entry in this list should resolve to # a partial or complete resource definition file. diff --git a/examples/README.md b/examples/README.md index e94221e7d..675811982 100644 --- a/examples/README.md +++ b/examples/README.md @@ -37,4 +37,6 @@ go get github.com/kubernetes-sigs/kustomize * [image tags](imageTags.md) - Updating image tags without applying a patch. - * [multibases](multibases/README.md) - Composing three variants (dev, staging, production) with a common base. \ No newline at end of file + * [multibases](multibases/README.md) - Composing three variants (dev, staging, production) with a common base. + + * [remote target](remoteBuild.md) - Building a kustomization from a github URL diff --git a/examples/remoteBuild.md b/examples/remoteBuild.md new file mode 100644 index 000000000..63073deac --- /dev/null +++ b/examples/remoteBuild.md @@ -0,0 +1,58 @@ +# remote targets + +`kustomize build` can be run against a url. The effect is the same as cloing the repo, checking out the specified ref, +then running `kustomize build` against the desired directory in the local copy. + +Take `github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6` as an example. +According to [multibases](multibases/README.md) demo, this kustomization contains three Pod objects with names as +`cluster-a-dev-myapp-pod`, `cluster-a-stag-myapp-pod`, `cluster-a-prod-myapp-pod`. +Running `kustomize build` against the url gives the same output. + + +``` +target=github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6 +test 3 == \ + $(kustomize build $target | grep cluster-a-.*-myapp-pod | wc -l); \ + echo $? +``` + +A base can also be specified as a URL: + + +``` +DEMO_HOME=$(mktemp -d) + +cat <$DEMO_HOME/kustomization.yaml +bases: +- github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6 +namePrefix: remote- +EOF +``` +Running `kustomize build $DEMO_HOME` and confirm the output contains three Pods and all have `remote-` prefix. + +``` +test 3 == \ + $(kustomize build $DEMO_HOME | grep remote-.*-myapp-pod | wc -l); \ + echo $? +``` + +## URL format +The url should follow +[hashicorp/go-getter URL format](https://github.com/hashicorp/go-getter#url-format). +Here are some example urls pointing to Github repos following this convention. + +- a repo with a root level kustomization.yaml + + `github.com/Liujingfang1/mysql` +- a repo with a root level kustomization.yaml on branch test + + `github.com/Liujingfang1/mysql?ref=test` +- a subdirectory in a repo on version v1.0.6 + + `github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6` +- a subdirectory in a repo on branch repoUrl2 + + `github.com/Liujingfang1/kustomize//examples/helloWorld?ref=repoUrl2` +- a subdirectory in a repo on commit `7050a45134e9848fca214ad7e7007e96e5042c03` + + `github.com/Liujingfang1/kustomize//examples/helloWorld?ref=7050a45134e9848fca214ad7e7007e96e5042c03` \ No newline at end of file diff --git a/pkg/commands/build.go b/pkg/commands/build.go index e268dfff5..35616cee3 100644 --- a/pkg/commands/build.go +++ b/pkg/commands/build.go @@ -34,15 +34,29 @@ type buildOptions struct { outputPath string } +var examples = ` +Use the file somedir/kustomization.yaml to generate a set of api resources: + build somedir + +Use a url pointing to a remote directory/kustomization.yaml to generate a set of api resources: + build url +The url should follow hashicorp/go-getter URL format described in +https://github.com/hashicorp/go-getter#url-format + +url examples: + github.com/kubernetes-sigs/kustomize//examples/multibases?ref=v1.0.6 + github.com/Liujingfang1/mysql + github.com/Liujingfang1/kustomize//examples/helloWorld?ref=repoUrl2 +` + // newCmdBuild creates a new build command. func newCmdBuild(out io.Writer, fs fs.FileSystem) *cobra.Command { var o buildOptions cmd := &cobra.Command{ - Use: "build [path]", - Short: "Print current configuration per contents of " + constants.KustomizationFileName, - Example: "Use the file somedir/" + constants.KustomizationFileName + - " to generate a set of api resources:\nbuild somedir/", + Use: "build [path]", + Short: "Print current configuration per contents of " + constants.KustomizationFileName, + Example: examples, SilenceUsage: true, RunE: func(cmd *cobra.Command, args []string) error { err := o.Validate(args) diff --git a/pkg/types/kustomization.go b/pkg/types/kustomization.go index 45d2bc1d8..ddd48cf0e 100644 --- a/pkg/types/kustomization.go +++ b/pkg/types/kustomization.go @@ -35,23 +35,22 @@ type Kustomization struct { // Annotations to add to all objects. CommonAnnotations map[string]string `json:"commonAnnotations,omitempty" yaml:"commonAnnotations,omitempty"` - // Each entry should be either a path to a file with a name matching the value of - // constants.KustomizationFileName, or a path to a directory containing a file with that name. + // Each entry should be either a path to a directory containing kustomization.yaml + // Or a repo URL pointing to a remote directory containing kustomization.yaml + // The repo URL should follow hashicorp/go-getter URL format + // https://github.com/hashicorp/go-getter#url-format Bases []string `json:"bases,omitempty" yaml:"bases,omitempty"` - // Resources specifies the relative paths within the package. - // It could be any format that kubectl -f allows, i.e. files, directories, - // URLs and globs. + // Resources specifies the relative paths for resource files within the package. + // URLs and globs are not supported Resources []string `json:"resources,omitempty" yaml:"resources,omitempty"` // Crds specifies relative paths to custom resource definition files. Crds []string `json:"crds,omitempty" yaml:"crds,omitempty"` // An Patch entry is very similar to an Resource entry. - // It specifies the relative paths within the package, and could be any - // format that kubectl -f allows. - // It should be able to be merged by Strategic Merge Patch on top of its - // corresponding base resource. + // It specifies the relative paths for patch files within the package. + // URLs and globs are not supported Patches []string `json:"patches,omitempty" yaml:"patches,omitempty"` // List of configmaps to generate from configuration sources.