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

@@ -45,14 +45,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

@@ -44,7 +44,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

@@ -36,7 +36,7 @@ import (
 var (
 	edit_federation_long = templates.LongDesc(i18n.T(`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.

cmd/kops/edit_instancegroup.go

@@ -37,7 +37,7 @@ 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 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.

cmd/kops/get.go

@@ -46,9 +46,15 @@ var (
 	# Get a cluster
 	kops get cluster k8s-cluster.example.com
 
-	# Get a cluster YAML cluster spec
+	# Get a cluster YAML cluster desired configuration
 	kops get cluster k8s-cluster.example.com -o yaml
 
+	# Get a cluster YAML cluster actual configuration
+	kops get cluster k8s-cluster.example.com --full -o yaml
+
+# Save a cluster desired configuration to YAML file
+kops get cluster k8s-cluster.example.com -o yaml > cluster-desired-config.yaml
+
 	# Get an instancegroup
 	kops get ig --name k8s-cluster.example.com nodes
 

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 (
 	replace_long = templates.LongDesc(i18n.T(`
-		Replace a resource specification by filename or stdin.`))
+		Replace a resource by filename or stdin.`))
 
 	replace_example = 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
 		`))
 

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

@@ -12,7 +12,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
@@ -21,7 +21,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

@@ -5,7 +5,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

@@ -7,7 +7,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

@@ -7,7 +7,7 @@ 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.

docs/cli/kops_edit_instancegroup.md

@@ -7,7 +7,7 @@ Edit instancegroup.
 
 Edit a cluster configuration. 
 
-This command changes the instancegroup cloud specification in the registry. 
+This command changes the instancegroup 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.

docs/cli/kops_get.md

@@ -28,9 +28,15 @@ kops get
   # Get a cluster
   kops get cluster k8s-cluster.example.com
   
-  # Get a cluster YAML cluster spec
+  # Get a cluster YAML cluster desired configuration
   kops get cluster k8s-cluster.example.com -o yaml
   
+  # Get a cluster YAML cluster actual configuration
+  kops get cluster k8s-cluster.example.com --full -o yaml
+  
+  # Save a cluster desired configuration to YAML file
+  kops get cluster k8s-cluster.example.com -o yaml > cluster-desired-config.yaml
+  
   # Get an instancegroup
   kops get ig --name k8s-cluster.example.com nodes
   

docs/cli/kops_get_clusters.md

@@ -19,6 +19,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

@@ -17,8 +17,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

@@ -5,7 +5,7 @@ Replace cluster resources.
 ### Synopsis
 
 
-Replace a resource specification by filename or stdin.
+Replace a resource by filename or stdin.
 
 ```
 kops replace -f FILENAME
@@ -14,7 +14,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
 ```
 

docs/cli/kops_update.md

@@ -5,7 +5,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