feat: add "get-versions" command to replace "orchestrators" (Azure#448)

* feat: "get-versions" command to replace "orchestrators"

* docs: replace mentions of "aks-engine orchestrators" command

cmd/get_versions.go

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+)
+
+const (
+	getVersionsName             = "get-versions"
+	getVersionsShortDescription = "Display info about supported Kubernetes versions"
+	getVersionsLongDescription  = "Display supported Kubernetes versions and upgrade versions"
+)
+
+func newGetVersionsCmd() *cobra.Command {
+	oc := orchestratorsCmd{}
+
+	command := &cobra.Command{
+		Use:   getVersionsName,
+		Short: getVersionsShortDescription,
+		Long:  getVersionsLongDescription,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return oc.run(cmd, args)
+		},
+	}
+
+	f := command.Flags()
+	oc.orchestrator = "Kubernetes" // orchestrator is always Kubernetes
+	f.StringVar(&oc.version, "version", "", "Kubernetes version (optional)")
+	f.BoolVar(&oc.windows, "windows", false, "Kubernetes cluster with Windows nodes (optional)")
+
+	return command
+}

cmd/get_versions_test.go

@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+package cmd
+
+import (
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("The get-versions command", func() {
+	It("should create a get-versions command", func() {
+		output := newGetVersionsCmd()
+
+		Expect(output.Use).Should(Equal(getVersionsName))
+		Expect(output.Short).Should(Equal(getVersionsShortDescription))
+		Expect(output.Long).Should(Equal(getVersionsLongDescription))
+		Expect(output.Flags().Lookup("orchestrator")).To(BeNil())
+		Expect(output.Flags().Lookup("version")).NotTo(BeNil())
+	})
+})

cmd/orchestrators.go

@@ -34,6 +34,7 @@ func newOrchestratorsCmd() *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return oc.run(cmd, args)
 		},
+		Hidden: true,
 	}
 
 	f := command.Flags()

cmd/root.go

@@ -61,6 +61,7 @@ func NewRootCmd() *cobra.Command {
 	rootCmd.AddCommand(newVersionCmd())
 	rootCmd.AddCommand(newGenerateCmd())
 	rootCmd.AddCommand(newDeployCmd())
+	rootCmd.AddCommand(newGetVersionsCmd())
 	rootCmd.AddCommand(newOrchestratorsCmd())
 	rootCmd.AddCommand(newUpgradeCmd())
 	rootCmd.AddCommand(newScaleCmd())

cmd/root_test.go

@@ -16,7 +16,7 @@ func TestNewRootCmd(t *testing.T) {
 	if output.Use != rootName || output.Short != rootShortDescription || output.Long != rootLongDescription {
 		t.Fatalf("root command should have use %s equal %s, short %s equal %s and long %s equal to %s", output.Use, rootName, output.Short, rootShortDescription, output.Long, rootLongDescription)
 	}
-	expectedCommands := []*cobra.Command{getCompletionCmd(output), newDeployCmd(), newGenerateCmd(), newOrchestratorsCmd(), newScaleCmd(), newUpgradeCmd(), newVersionCmd()}
+	expectedCommands := []*cobra.Command{getCompletionCmd(output), newDeployCmd(), newGenerateCmd(), newGetVersionsCmd(), newOrchestratorsCmd(), newScaleCmd(), newUpgradeCmd(), newVersionCmd()}
 	rc := output.Commands()
 	for i, c := range expectedCommands {
 		if rc[i].Use != c.Use {

cmd/upgrade.go

@@ -174,7 +174,7 @@ func (uc *upgradeCmd) loadCluster(cmd *cobra.Command) error {
 		}
 	}
 	if !found {
-		return errors.Errorf("upgrading from Kubernetes version %s to version %s is not supported. To see a list of available upgrades, use 'aks-engine orchestrators --orchestrator kubernetes --version %s'", uc.containerService.Properties.OrchestratorProfile.OrchestratorVersion, uc.upgradeVersion, uc.containerService.Properties.OrchestratorProfile.OrchestratorVersion)
+		return errors.Errorf("upgrading from Kubernetes version %s to version %s is not supported. To see a list of available upgrades, use 'aks-engine get-versions --version %s'", uc.containerService.Properties.OrchestratorProfile.OrchestratorVersion, uc.upgradeVersion, uc.containerService.Properties.OrchestratorProfile.OrchestratorVersion)
 	}
 
 	// Read the name suffix from the parameters to identify VMs in the resource group that belong to this cluster.

docs/topics/clusterdefinitions.md

@@ -24,10 +24,10 @@ Here are the valid values for the orchestrator types:
 
 1. `Kubernetes` - this represents the Kubernetes orchestrator.
 
-To learn more about supported orchestrators and versions, run the orchestrators command:
+To learn more about supported versions, run the get-versions command:
 
 ```console
-$ aks-engine orchestrators
+$ aks-engine get-versions
 ```
 
 ### kubernetesConfig

docs/topics/upgrade.md

@@ -22,16 +22,16 @@ In order to ensure that your `aks-engine upgrade` operation runs smoothly, there
 
 3) `aks-engine upgrade` allows upgrading the Kubernetes version to any AKS Engine-supported patch release in the current minor release channel that is greater than the current version on the cluster (e.g., from `1.11.4` to `1.11.5`), or to the next aks-engine-supported minor version (e.g., from `1.11.4` to `1.12.5`). In practice, the next AKS Engine-supported minor version will commonly be a single minor version ahead of the current cluster version. However, if the cluster has not been upgraded in a significant amount of time, the "next" minor version may have actually been deprecated by aks-engine. In such a case, your long-lived cluster will be upgradable to the nearest, supported minor version that `aks-engine` supports at the time of upgrade (e.g., from `1.7.16` to `1.9.11`).
 
-    To get the list of all available Kubernetes versions and upgrades, run the `orchestrators` command and specify Kubernetes orchestrator type:
+    To get the list of all available Kubernetes versions and upgrades, run the `get-versions` command:
 
     ```bash
-    ./bin/aks-engine orchestrators --orchestrator Kubernetes
+    ./bin/aks-engine get-versions
     ```
 
     To get the versions of Kubernetes that your particular cluster version is upgradable to, provide its current Kubernetes version in the `version` arg:
 
     ```bash
-    ./bin/aks-engine orchestrators --orchestrator Kubernetes --version 1.11.5
+    ./bin/aks-engine get-versions --version 1.11.7
     ```
 
 4) If using `aks-engine upgrade` in production, it is recommended to stage an upgrade test on an cluster that was built to the same specifications (built with the same cluster configuration + the same version of the `aks-engine` binary) as your production cluster before performing the upgrade, especially if the cluster configuration is "interesting", or in other words differs significantly from defaults. The reason for this is that AKS Engine supports many different cluster configurations and the extent of E2E testing that the AKS Engine team runs cannot practically cover every possible configuration. Therefore, it is recommended that you ensure in a staging environment that your specific cluster configuration is upgradable using `aks-engine upgrade` before attempting this potentially destructive operation on your production cluster.

docs/tutorials/quickstart.zh-CN.md

@@ -25,23 +25,24 @@ make build
 
 ```
 # ./bin/aks-engine
-AKS Engine deploys and manages Kubernetes, Swarm Mode, and DC/OS clusters in Azure
-
 Usage:
+  aks-engine [flags]
   aks-engine [command]
 
 Available Commands:
+  completion    Generates bash completion scripts
   deploy        Deploy an Azure Resource Manager template
   generate      Generate an Azure Resource Manager template
+  get-versions  Display info about supported Kubernetes versions
   help          Help about any command
-  orchestrators Display info about supported orchestrators
   scale         Scale an existing Kubernetes cluster
   upgrade       Upgrade an existing Kubernetes cluster
   version       Print the version of AKS Engine
 
 Flags:
-      --debug   enable verbose debug logs
-  -h, --help    help for aks-engine
+      --debug                enable verbose debug logs
+  -h, --help                 help for aks-engine
+      --show-default-model   Dump the default API model to stdout
 
 Use "aks-engine [command] --help" for more information about a command.
 ```