Clarify docs: rename spec to desired conf

In the S3 bucket, the file cluster.spec is not actually the spec, but the
actual configuration. The file config is the spec. To avoid confusion,
this commit changes spec/specification into 'desired configuration' in
the documentation, to avoid associating cluster.spec with a cluster
'specification' that the users should use.

cmd/kops/create.go

@@ -44,14 +44,14 @@ var (
 	create_long = templates.LongDesc(i18n.T(`
 		Create a resource:` + validResources +
 		`
-	Create a cluster, instancegroup or secret using command line flags or
-	YAML cluster spec. Clusters and instancegroups can be created using the YAML
-	cluster spec.
+	Create a cluster, instancegroup or secret using command line parameters
+	or YAML configuration specification files.
+	(Note: secrets cannot be created from YAML config files yet).
 	`))
 
 	create_example = templates.Examples(i18n.T(`
 
-	# Create a cluster using a cluser spec file
+	# Create a cluster from the configuration specification in a YAML file
 	kops create -f my-cluster.yaml
 
 	# Create a cluster in AWS

cmd/kops/edit.go

@@ -27,7 +27,7 @@ import (
 
 var (
 	edit_long = templates.LongDesc(i18n.T(`Edit a resource configuration.
-	This command changes the cloud specification in the registry.
+	This command changes the desired configuration in the registry.
 
     	To set your preferred editor, you can define the EDITOR environment variable.
     	When you have done this, kops will use the editor that you have set.

cmd/kops/edit_cluster.go

@@ -45,7 +45,7 @@ type EditClusterOptions struct {
 var (
 	edit_cluster_long = templates.LongDesc(i18n.T(`Edit a cluster configuration.
 
-	This command changes the cluster cloud specification in the registry.
+	This command changes the desired cluster configuration in the registry.
 
     	To set your preferred editor, you can define the EDITOR environment variable.
     	When you have done this, kops will use the editor that you have set.

cmd/kops/edit_federation.go

@@ -37,10 +37,10 @@ var (
 	edit_federation_long = pretty.LongDesc(`
 		Edit a cluster configuration.
 
-		This command changes the federation cloud specification in the registry.
+		This command changes the federation cloud desired configuration in the registry.
 
-		To set your preferred editor, you can define the EDITOR environment variable.
-		When you have done this, kops will use the editor that you have set.
+			To set your preferred editor, you can define the EDITOR environment variable.
+			When you have done this, kops will use the editor that you have set.
 
 		kops edit does not update the cloud resources, to apply the changes use ` + pretty.Bash("kops update cluster") + `.`)
 

cmd/kops/edit_instancegroup.go

@@ -38,15 +38,15 @@ import (
 var (
 	edit_instancegroup_long = templates.LongDesc(i18n.T(`Edit a cluster configuration.
 
-	This command changes the instancegroup cloud specification in the registry.
+	This command changes the instancegroup desired configuration in the registry.
 
     	To set your preferred editor, you can define the EDITOR environment variable.
     	When you have done this, kops will use the editor that you have set.
 
 	kops edit does not update the cloud resources, to apply the changes use "kops update cluster".`))
 
 	edit_instancegroup_example = templates.Examples(i18n.T(`
-	# Edit a instancegroup configuration.
+	# Edit an instancegroup desired configuration.
 	kops edit ig --name k8s-cluster.example.com node --state=s3://kops-state-1234
 	`))
 

cmd/kops/get.go

@@ -37,20 +37,17 @@ var (
 	Display one or many resources.` + validResources))
 
 	get_example = templates.Examples(i18n.T(`
-	# Get all resource in a single cluster as yaml
-	kops get --name k8s-cluster.example.com -o yaml
-
 	# Get all clusters in a state store
 	kops get clusters
 
-	# Get a cluster
-	kops get cluster k8s-cluster.example.com
+	# Get a cluster and its instancegroups
+	kops get k8s-cluster.example.com
 
-	# Get a cluster YAML cluster spec
-	kops get cluster k8s-cluster.example.com -o yaml
+	# Get a cluster and its instancegroups' YAML desired configuration
+	kops get k8s-cluster.example.com -o yaml
 
-	# Get an instancegroup
-	kops get ig --name k8s-cluster.example.com nodes
+	# Save a cluster and its instancegroups' desired configuration to YAML file
+	kops get k8s-cluster.example.com -o yaml > cluster-desired-config.yaml
 
 	# Get a secret
 	kops get secrets kube -oplaintext

cmd/kops/get_cluster.go

@@ -43,7 +43,14 @@ var (
 	kops get clusters
 
 	# Get a cluster
-	kops get cluster k8s-cluster.example.com`))
+	kops get cluster k8s-cluster.example.com
+
+	# Get a cluster YAML desired configuration
+	kops get cluster k8s-cluster.example.com -o yaml
+
+	# Save a cluster desired configuration to YAML file
+	kops get cluster k8s-cluster.example.com -o yaml > cluster-desired-config.yaml
+	`))
 
 	get_cluster_short = i18n.T(`Get one or many clusters.`)
 

cmd/kops/get_instancegroups.go

@@ -22,8 +22,9 @@ import (
 	"strconv"
 	"strings"
 
-	"github.com/spf13/cobra"
 	"io"
+
+	"github.com/spf13/cobra"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/kops/cmd/kops/util"
 	api "k8s.io/kops/pkg/apis/kops"
@@ -40,8 +41,12 @@ var (
 	# Get all instancegroups in a state store
 	kops get ig
 
-	# Get a cluster
-	kops get ig --name k8s-cluster.example.com nodes`))
+	# Get a cluster's instancegroup
+	kops get ig --name k8s-cluster.example.com nodes
+
+	# Save a cluster's instancegroups desired configuration to YAML file
+	kops get ig --name k8s-cluster.example.com -o yaml > instancegroups-desired-config.yaml
+	`))
 
 	get_instancegroups_short = i18n.T(`Get one or many instancegroups`)
 )

cmd/kops/replace.go

@@ -36,10 +36,10 @@ import (
 
 var (
 	replaceLong = templates.LongDesc(i18n.T(`
-		Replace a resource specification by filename or stdin.`))
+		Replace a resource desired configuration by filename or stdin.`))
 
 	replaceExample = templates.Examples(i18n.T(`
-		# Replace a cluster specification using a file
+		# Replace a cluster desired configuration using a YAML file
 		kops replace -f my-cluster.yaml
 
 		# Note, if the resource does not exist the command will error, use --force to provision resource

cmd/kops/update.go

@@ -27,7 +27,7 @@ import (
 
 var (
 	update_long = templates.LongDesc(i18n.T(`
-	Creates or updates cloud resources to match cluster spec.
+	Creates or updates cloud resources to match cluster desired configuration.
 	`))
 
 	update_example = templates.Examples(i18n.T(`

docs/cli/kops_create.md

@@ -15,7 +15,7 @@ Create a resource:
   * secret  
   * federation  
 
-Create a cluster, instancegroup or secret using command line flags or YAML cluster spec. Clusters and instancegroups can be created using the YAML cluster spec.
+Create a cluster, instancegroup or secret using command line parameters or YAML configuration specification files. (Note: secrets cannot be created from YAML config files yet).
 
 ```
 kops create -f FILENAME
@@ -24,7 +24,7 @@ kops create -f FILENAME
 ### Examples
 
 ```
-  # Create a cluster using a cluser spec file
+  # Create a cluster from the configuration specification in a YAML file
   kops create -f my-cluster.yaml
   
   # Create a cluster in AWS

docs/cli/kops_edit.md

@@ -8,7 +8,7 @@ Edit clusters and other resources.
 ### Synopsis
 
 
-Edit a resource configuration. This command changes the cloud specification in the registry. 
+Edit a resource configuration. This command changes the desired configuration in the registry. 
 
   To set your preferred editor, you can define the EDITOR environment variable.
   When you have done this, kops will use the editor that you have set.

docs/cli/kops_edit_cluster.md

@@ -10,7 +10,7 @@ Edit cluster.
 
 Edit a cluster configuration. 
 
-This command changes the cluster cloud specification in the registry. 
+This command changes the desired cluster configuration in the registry. 
 
   To set your preferred editor, you can define the EDITOR environment variable.
   When you have done this, kops will use the editor that you have set.

docs/cli/kops_edit_federation.md

@@ -10,10 +10,10 @@ Edit federation.
 
 Edit a cluster configuration.
 
-This command changes the federation cloud specification in the registry.
+This command changes the federation cloud desired configuration in the registry.
 
-To set your preferred editor, you can define the EDITOR environment variable.
-When you have done this, kops will use the editor that you have set.
+	To set your preferred editor, you can define the EDITOR environment variable.
+	When you have done this, kops will use the editor that you have set.
 
 kops edit does not update the cloud resources, to apply the changes use `kops update cluster`.
 

docs/cli/kops_edit_instancegroup.md

@@ -10,7 +10,7 @@ Edit instancegroup.
 
 Edit a cluster configuration. 
 
-This command changes the instancegroup cloud specification in the registry. 
+This command changes the instancegroup desired configuration in the registry. 
 
   To set your preferred editor, you can define the EDITOR environment variable.
   When you have done this, kops will use the editor that you have set.
@@ -24,7 +24,7 @@ kops edit instancegroup
 ### Examples
 
 ```
-  # Edit a instancegroup configuration.
+  # Edit an instancegroup desired configuration.
   kops edit ig --name k8s-cluster.example.com node --state=s3://kops-state-1234
 ```
 

docs/cli/kops_get.md

@@ -22,20 +22,17 @@ kops get
 ### Examples
 
 ```
-  # Get all resource in a single cluster as yaml
-  kops get --name k8s-cluster.example.com -o yaml
-  
   # Get all clusters in a state store
   kops get clusters
   
-  # Get a cluster
-  kops get cluster k8s-cluster.example.com
+  # Get a cluster and its instancegroups
+  kops get k8s-cluster.example.com
   
-  # Get a cluster YAML cluster spec
-  kops get cluster k8s-cluster.example.com -o yaml
+  # Get a cluster and its instancegroups' YAML desired configuration
+  kops get k8s-cluster.example.com -o yaml
   
-  # Get an instancegroup
-  kops get ig --name k8s-cluster.example.com nodes
+  # Save a cluster and its instancegroups' desired configuration to YAML file
+  kops get k8s-cluster.example.com -o yaml > cluster-desired-config.yaml
   
   # Get a secret
   kops get secrets kube -oplaintext

docs/cli/kops_get_clusters.md

@@ -22,6 +22,12 @@ kops get clusters
   
   # Get a cluster
   kops get cluster k8s-cluster.example.com
+  
+  # Get a cluster YAML desired configuration
+  kops get cluster k8s-cluster.example.com -o yaml
+  
+  # Save a cluster desired configuration to YAML file
+  kops get cluster k8s-cluster.example.com -o yaml > cluster-desired-config.yaml
 ```
 
 ### Options

docs/cli/kops_get_instancegroups.md

@@ -20,8 +20,11 @@ kops get instancegroups
   # Get all instancegroups in a state store
   kops get ig
   
-  # Get a cluster
+  # Get a cluster's instancegroup
   kops get ig --name k8s-cluster.example.com nodes
+  
+  # Save a cluster's instancegroups desired configuration to YAML file
+  kops get ig --name k8s-cluster.example.com -o yaml > instancegroups-desired-config.yaml
 ```
 
 ### Options inherited from parent commands

docs/cli/kops_replace.md

@@ -8,7 +8,7 @@ Replace cluster resources.
 ### Synopsis
 
 
-Replace a resource specification by filename or stdin.
+Replace a resource desired configuration by filename or stdin.
 
 ```
 kops replace -f FILENAME
@@ -17,7 +17,7 @@ kops replace -f FILENAME
 ### Examples
 
 ```
-  # Replace a cluster specification using a file
+  # Replace a cluster desired configuration using a YAML file
   kops replace -f my-cluster.yaml
   
   # Note, if the resource does not exist the command will error, use --force to provision resource

docs/cli/kops_update.md

@@ -8,7 +8,7 @@ Update a cluster.
 ### Synopsis
 
 
-Creates or updates cloud resources to match cluster spec.
+Creates or updates cloud resources to match cluster desired configuration.
 
 ### Examples