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.
kubernetes · Jun 11, 2017 · fe08226 · fe08226
1 parent 5aa9b5f
commit fe08226
Show file tree

Hide file tree

Showing 20 changed files with 62 additions and 29 deletions.
diff --git a/cmd/kops/create.go b/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

diff --git a/cmd/kops/edit.go b/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.

diff --git a/cmd/kops/edit_cluster.go b/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.

diff --git a/cmd/kops/edit_federation.go b/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.

diff --git a/cmd/kops/edit_instancegroup.go b/cmd/kops/edit_instancegroup.go
@@ -37,15 +37,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
 	`))
 

diff --git a/cmd/kops/get.go b/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
 

diff --git a/cmd/kops/get_cluster.go b/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.`)
 )

diff --git a/cmd/kops/get_instancegroups.go b/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`)
 )

diff --git a/cmd/kops/replace.go b/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
 		`))
 

diff --git a/cmd/kops/update.go b/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(`

diff --git a/docs/cli/kops_create.md b/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

diff --git a/docs/cli/kops_edit.md b/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.

diff --git a/docs/cli/kops_edit_cluster.md b/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.

diff --git a/docs/cli/kops_edit_federation.md b/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.

diff --git a/docs/cli/kops_edit_instancegroup.md b/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 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.
@@ -21,7 +21,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
 ```
 

diff --git a/docs/cli/kops_get.md b/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
   

diff --git a/docs/cli/kops_get_clusters.md b/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

diff --git a/docs/cli/kops_get_instancegroups.md b/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

diff --git a/docs/cli/kops_replace.md b/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
 ```
 

diff --git a/docs/cli/kops_update.md b/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