Add example for kustomize build {url}

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

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.

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.
+ * [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

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.
+
+<!-- @remoteBuild @test -->
+```
+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:
+
+<!-- @createOverlay @test -->
+```
+DEMO_HOME=$(mktemp -d)
+
+cat <<EOF >$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.
+<!-- @remoteBases @test -->
+```
+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`

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)

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.