updating docs, adding verify-gendocs and more build tweaks

klstr · May 5, 2017 · 7487b0d · 7487b0d
1 parent ddc638f
commit 7487b0d
Show file tree

Hide file tree

Showing 23 changed files with 162 additions and 34 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -11,3 +11,5 @@ go_import_path: k8s.io/kops
 script:
   - make ci
 
+git:
+  submodules: false
diff --git a/Makefile b/Makefile
@@ -305,10 +305,10 @@ gofmt:
 	gofmt -w -s dns-controller/pkg
 
 goimports:
-	sh -c hack/update-goimports
+	hack/update-goimports
 
 verify-goimports:
-	sh -c hack/verify-goimports
+	hack/verify-goimports
 
 govet:
 	go vet \
@@ -328,7 +328,7 @@ govet:
 # Continuous integration targets
 
 verify-boilerplate:
-	sh -c hack/verify-boilerplate.sh
+	hack/verify-boilerplate.sh
 
 .PHONY: verify-gofmt
 verify-gofmt:
@@ -338,7 +338,14 @@ verify-gofmt:
 verify-packages:
 	hack/verify-packages.sh
 
-ci: govet verify-gofmt kops nodeup-gocode examples test verify-boilerplate verify-packages
+.PHONY: verify-gendocs
+verify-gendocs: kops
+	hack/verify-gendocs.sh
+
+# verify-gendocs will call kops target
+# verify-package has to be after verify-gendoc, because with .gitignore for federation bindata
+# it bombs in travis. verify-gendoc generates the bindata file.
+ci: govet verify-gofmt verify-boilerplate verify-gendocs verify-packages nodeup-gocode examples test 
 	echo "Done!"
 
 # --------------------------------------------------
@@ -368,7 +375,7 @@ examples:
 # api machinery regenerate
 
 apimachinery:
-	./hack/make-apimachinery.sh
+	sh -c hack/make-apimachinery.sh
 	${GOPATH}/bin/conversion-gen --skip-unsafe=true --input-dirs k8s.io/kops/pkg/apis/kops/v1alpha1 --v=0  --output-file-base=zz_generated.conversion
 	${GOPATH}/bin/conversion-gen --skip-unsafe=true --input-dirs k8s.io/kops/pkg/apis/kops/v1alpha2 --v=0  --output-file-base=zz_generated.conversion
 	${GOPATH}/bin/defaulter-gen --input-dirs k8s.io/kops/pkg/apis/kops/v1alpha1 --v=0  --output-file-base=zz_generated.defaults

diff --git a/cmd/kops/edit.go b/cmd/kops/edit.go
@@ -27,7 +27,6 @@ import (
 
 var (
 	edit_long = templates.LongDesc(i18n.T(`Edit a resource configuration.
-
     This command changes the cloud specification in the registry.
 
     It does not update the cloud resources, to apply the changes use "kops update cluster".`))

diff --git a/cmd/kops/gen_help_docs.go b/cmd/kops/gen_help_docs.go
@@ -50,6 +50,7 @@ func init() {
 
 func (c *GenHelpDocsCmd) Run() error {
 	rootCommand.cobraCommand.DisableAutoGenTag = true
+	rootCommand.RegistryPath = ""
 	err := doc.GenMarkdownTree(rootCommand.cobraCommand, c.OutDir)
 
 	return err

diff --git a/cmd/kops/replace.go b/cmd/kops/replace.go
@@ -51,7 +51,7 @@ func NewCmdReplace(f *util.Factory, out io.Writer) *cobra.Command {
 		},
 	}
 
-	cmd.Flags().StringSliceVarP(&options.Filenames, "filename", "f", options.Filenames, "Filename to use to replace the resource")
+	cmd.Flags().StringSliceVarP(&options.Filenames, "filename", "f", options.Filenames, "A list of one or more files separated by a comma.")
 	cmd.MarkFlagRequired("filename")
 
 	return cmd

diff --git a/cmd/kops/update_cluster.go b/cmd/kops/update_cluster.go
@@ -64,8 +64,12 @@ func NewCmdUpdateCluster(f *util.Factory, out io.Writer) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "cluster",
-		Short: "Update cluster",
-		Long:  `Updates a k8s cluster.`,
+		Short: "Create or update cloud or cluster resources to match current cluster state.",
+		Long: `Create or update cloud or cluster resources to match current cluster state.  If the cluster or cloud resources already
+		exist this command may modify those resources.
+
+		If nodes need updating such as during a Kubernetes upgrade, a rolling-update may
+		be required as well.`,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := rootCommand.ProcessArgs(args)
 			if err != nil {

diff --git a/docs/cli/kops.md b/docs/cli/kops.md
@@ -5,7 +5,8 @@ kops is kubernetes ops
 ### Synopsis
 
 
-kops is kubernetes ops.
+kops is kubernetes ops. 
+
 It allows you to create, destroy, upgrade and maintain clusters.
 
 ### Options
@@ -26,7 +27,7 @@ It allows you to create, destroy, upgrade and maintain clusters.
 ### SEE ALSO
 * [kops completion](kops_completion.md)	 - Output shell completion code for the given shell (bash or zsh).
 * [kops create](kops_create.md)	 - Create a resource by filename or stdin.
-* [kops delete](kops_delete.md)	 - Delete clusters and instancegroups
+* [kops delete](kops_delete.md)	 - Delete clusters and instancegroups.
 * [kops describe](kops_describe.md)	 - Get additional information about cloud resources.
 * [kops edit](kops_edit.md)	 - Edit clusters and other resrouces.
 * [kops export](kops_export.md)	 - Exports a kubecfg for target cluster.

diff --git a/docs/cli/kops_create.md b/docs/cli/kops_create.md
@@ -11,6 +11,19 @@ Create a resource by filename or stdin.
 kops create -f FILENAME
 ```
 
+### Examples
+
+```
+  # Create a cluster using a file
+  kops create -f my-cluster.yaml
+  
+  # Create a cluster in AWS
+  kops create cluster --name=example.com \
+  --state=s3://kops-state-1234 --zones=eu-west-1a \
+  --node-count=2 --node-size=t2.micro --master-size=t2.micro \
+  --dns-zone=example.com
+```
+
 ### Options
 
 ```

diff --git a/docs/cli/kops_create_cluster.md b/docs/cli/kops_create_cluster.md
@@ -11,6 +11,16 @@ Creates a k8s cluster.
 kops create cluster
 ```
 
+### Examples
+
+```
+  # Create a cluster in AWS
+  kops create cluster --name=example.com\
+  --state=s3://kops-state-1234 --zones=eu-west-1a \
+  --node-count=2 --node-size=t2.micro --master-size=t2.micro \
+  --dns-zone=example.com
+```
+
 ### Options
 
 ```
@@ -19,7 +29,7 @@ kops create cluster
       --authorization string                 Authorization mode to use: AlwaysAllow or RBAC (default "AlwaysAllow")
       --bastion                              Pass the --bastion flag to enable a bastion instance group. Only applies to private topology.
       --channel string                       Channel for default versions and configuration to use (default "stable")
-      --cloud string                         Cloud provider to use - gce, aws
+      --cloud string                         Cloud provider to use - gce, aws, vsphere
       --cloud-labels string                  A list of KV pairs used to tag all instance groups in AWS (eg "Owner=John Doe,Team=Some Team").
       --dns string                           DNS hosted zone to use: public|private. Default is 'public'. (default "Public")
       --dns-zone string                      DNS hosted zone to use (defaults to longest matching zone)

diff --git a/docs/cli/kops_delete.md b/docs/cli/kops_delete.md
@@ -1,16 +1,26 @@
 ## kops delete
 
-Delete clusters and instancegroups
+Delete clusters and instancegroups.
 
 ### Synopsis
 
 
-Delete clusters and instancegroups
+Delete clusters and instancegroups.
 
 ```
 kops delete -f FILENAME [--yes]
 ```
 
+### Examples
+
+```
+  # Create a cluster using a file
+  kops delete -f my-cluster.yaml
+  
+  # Delete a cluster in AWS.
+  kops delete cluster --name=k8s.cluster.site --state=s3://kops-state-1234
+```
+
 ### Options
 
 ```

diff --git a/docs/cli/kops_delete_cluster.md b/docs/cli/kops_delete_cluster.md
@@ -11,6 +11,13 @@ Deletes a k8s cluster.
 kops delete cluster CLUSTERNAME [--yes]
 ```
 
+### Examples
+
+```
+  # Delete a cluster in AWS.
+  kops delete cluster --name=k8s.cluster.site --yes
+```
+
 ### Options
 
 ```
@@ -36,5 +43,5 @@ kops delete cluster CLUSTERNAME [--yes]
 ```
 
 ### SEE ALSO
-* [kops delete](kops_delete.md)	 - Delete clusters and instancegroups
+* [kops delete](kops_delete.md)	 - Delete clusters and instancegroups.
 
diff --git a/docs/cli/kops_delete_instancegroup.md b/docs/cli/kops_delete_instancegroup.md
@@ -33,5 +33,5 @@ kops delete instancegroup
 ```
 
 ### SEE ALSO
-* [kops delete](kops_delete.md)	 - Delete clusters and instancegroups
+* [kops delete](kops_delete.md)	 - Delete clusters and instancegroups.
 
diff --git a/docs/cli/kops_delete_secret.md b/docs/cli/kops_delete_secret.md
@@ -27,5 +27,5 @@ kops delete secret
 ```
 
 ### SEE ALSO
-* [kops delete](kops_delete.md)	 - Delete clusters and instancegroups
+* [kops delete](kops_delete.md)	 - Delete clusters and instancegroups.
 
diff --git a/docs/cli/kops_edit.md b/docs/cli/kops_edit.md
@@ -5,12 +5,17 @@ Edit clusters and other resrouces.
 ### Synopsis
 
 
-Edit a resource configuration.
-
-This command changes the cloud specification in the registry.
+Edit a resource configuration. This command changes the cloud specification in the registry. 
 
 It does not update the cloud resources, to apply the changes use "kops update cluster".
 
+### Examples
+
+```
+  # Edit a cluster configuration in AWS.
+  kops edit cluster k8s.cluster.site --state=s3://kops-state-1234
+```
+
 ### Options inherited from parent commands
 
 ```

diff --git a/docs/cli/kops_edit_cluster.md b/docs/cli/kops_edit_cluster.md
@@ -5,16 +5,23 @@ Edit cluster
 ### Synopsis
 
 
-Edit a cluster configuration.
+Edit a cluster configuration. 
 
-This command changes the cloud specification in the registry.
+This command changes the cloud specification in the registry. 
 
 It does not update the cloud resources, to apply the changes use "kops update cluster".
 
 ```
 kops edit cluster
 ```
 
+### Examples
+
+```
+  # Edit a cluster configuration in AWS.
+  kops edit cluster k8s.cluster.site --state=s3://kops-state-1234
+```
+
 ### Options inherited from parent commands
 
 ```

diff --git a/docs/cli/kops_replace.md b/docs/cli/kops_replace.md
@@ -14,7 +14,7 @@ kops replace -f FILENAME
 ### Options
 
 ```
-  -f, --filename stringSlice   Filename to use to replace the resource
+  -f, --filename stringSlice   A list of one or more files separated by a comma.
 ```
 
 ### Options inherited from parent commands

diff --git a/docs/cli/kops_rolling-update_cluster.md b/docs/cli/kops_rolling-update_cluster.md
@@ -11,8 +11,11 @@ This command updates a kubernetes cluster to match the cloud, and kops specifica
 
 To perform rolling update, you need to update the cloud resources first with "kops update cluster"
 
+Note: terraform users will need run the following commands all from the same directory "kops update cluster --target=terraform" then "terraform plan" then "terraform apply"
+prior to running "kops rolling-update cluster"
+
 Use KOPS_FEATURE_FLAGS="+DrainAndValidateRollingUpdate" to use beta code that drains the nodes
-and validates the cluser.  New flags for Drain and Validation operations will be shown when
+and validates the cluster.  New flags for Drain and Validation operations will be shown when
 the environment variable is set.
 
 ```

diff --git a/docs/cli/kops_update.md b/docs/cli/kops_update.md
@@ -5,7 +5,14 @@ Creates or updates cloud resources to match cluster spec.
 ### Synopsis
 
 
-Update clusters
+Update clusters.
+
+### Examples
+
+```
+  # After cluster has been created, configure it with:
+  kops update cluster k8s.cluster.site --yes --state=s3://kops-state-1234
+```
 
 ### Options inherited from parent commands
 
@@ -24,6 +31,6 @@ Update clusters
 
 ### SEE ALSO
 * [kops](kops.md)	 - kops is kubernetes ops
-* [kops update cluster](kops_update_cluster.md)	 - Update cluster
+* [kops update cluster](kops_update_cluster.md)	 - Create or update cloud or cluster resources to match current cluster state.
 * [kops update federation](kops_update_federation.md)	 - Update federation
 
diff --git a/docs/cli/kops_update_cluster.md b/docs/cli/kops_update_cluster.md
@@ -1,11 +1,15 @@
 ## kops update cluster
 
-Update cluster
+Create or update cloud or cluster resources to match current cluster state.
 
 ### Synopsis
 
 
-Updates a k8s cluster.
+Create or update cloud or cluster resources to match current cluster state.  If the cluster or cloud resources already
+		exist this command may modify those resources.
+
+		If nodes need updating such as during a Kubernetes upgrade, a rolling-update may
+		be required as well.
 
 ```
 kops update cluster

diff --git a/docs/cli/kops_upgrade.md b/docs/cli/kops_upgrade.md
@@ -5,7 +5,14 @@ Automates checking for and applying Kubernetes updates.
 ### Synopsis
 
 
-upgrade clusters
+Upgrades a k8s cluster.
+
+### Examples
+
+```
+  # After cluster has been created, configure it with:
+  kops upgrade cluster k8s.cluster.site --yes --state=s3://kops-state-1234
+```
 
 ### Options inherited from parent commands
 

diff --git a/docs/cli/kops_upgrade_cluster.md b/docs/cli/kops_upgrade_cluster.md
@@ -11,6 +11,13 @@ Upgrades a k8s cluster.
 kops upgrade cluster
 ```
 
+### Examples
+
+```
+  # After cluster has been created, configure it with:
+  kops upgrade cluster k8s.cluster.site --yes --state=s3://kops-state-1234
+```
+
 ### Options
 
 ```

diff --git a/hack/verify-boilerplate.sh b/hack/verify-boilerplate.sh
@@ -14,15 +14,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 . $(dirname "${BASH_SOURCE}")/common.sh
 
-boiler="${KUBE_ROOT}/hack/boilerplate/boilerplate.py"
+boiler="${KUBE_ROOT}/hack/boilerplate/boilerplate.py $@"
+
+files_need_boilerplate=( `${boiler}` )
 
-files_need_boilerplate=($(${boiler} "$@"))
+if [[ -z ${files_need_boilerplate+x} ]]; then
+    exit
+fi
 
 TO_REMOVE=(${PWD}/federation/model/bindata.go ${PWD}/upup/models/bindata.go)
 TEMP_ARRAY=()
+
 for pkg in "${files_need_boilerplate[@]}"; do
     for remove in "${TO_REMOVE[@]}"; do
         KEEP=true
@@ -43,5 +47,3 @@ if [[ ${#TEMP_ARRAY[@]} -gt 0 ]]; then
   echo "Execute hack/update-header.sh to update headers"
   exit 1
 fi
-
-echo "Boilerplate headers validated"
-Original file line number
+Diff line change
@@ Expand Up / @@ -11,3 +11,5 @@ go_import_path: k8s.io/kops @@
     script:
       - make ci
+    git:
+      submodules: false