Doc updates + add shutdown member command (#2)

Author: Tim Middleton

docs/about/01_overview.adoc

@@ -50,6 +50,13 @@ Configuration options.
 Coherence CLI Command Reference.
 --
 
+[CARD]
+.Security
+[icon=lock,link=docs/security/01_overview.adoc]
+--
+Securing CLI access.
+--
+
 [CARD]
 .Troubleshooting
 [icon=fa-question-circle,link=docs/troubleshooting/01_trouble-shooting.adoc]

docs/examples/01_overview.adoc

@@ -35,11 +35,4 @@ Using JSONPath expressions to refine output.
 Set cache attributes such as expiry delay.
 --
 
-[CARD]
-.Securing CLI Access
-[link=docs/examples/20_security.adoc]
---
-Securing access to the Management over REST endpoint.
---
-
 ====

docs/reference/15_members.adoc

@@ -16,6 +16,7 @@ There are various cluster commands that allow you to work with and manage cluste
 * <<get-members, `cohctl get members`>> - displays the members for a cluster
 * <<describe-member, `cohctl describe member`>> - shows information related to a specific member
 * <<set-member, `cohctl set member`>> - sets a member attribute for one or more members
+* <<shutdown-member, `cohctl shutdown member`>> - shuts down a members services in a controlled manner
 
 [#get-members]
 ==== Get Members
@@ -118,6 +119,21 @@ $ cohctl get members -o json | jq | grep loggingLevel
       "loggingLevel": 6,
 ----
 
+[#shutdown-member]
+==== Shutdown Member
+
+include::../../build/_output/docs-gen/shutdown_member.adoc[tag=text]
+
+[source,bash]
+----
+$ cohctl shutdown member 1 -c local
+Are you sure you want to shutdown member 1? (y/n) y
+operation completed
+----
+
+NOTE: This command may take a while to complete. Check the server logs for information regarding the
+member's status.  Once the member is shutdown it will restart with a new member id.
+
 === See Also
 
 * <<docs/reference/85_diagnostics.adoc,Diagnostics>>

docs/examples/20_security.adoc renamed to docs/security/01_overview.adoc

@@ -72,6 +72,14 @@ backend:
               items:
                 - includes:
                     - "docs/reference/*.adoc"
+            - title: "Security"
+              pathprefix: "/security"
+              glyph:
+                type: "icon"
+                value: "lock"
+              items:
+                - includes:
+                    - "docs/security/*.adoc"
             - title: "Troubleshooting"
               pathprefix: "/troubleshooting"
               glyph:

docs/sitegen.yaml

@@ -429,6 +429,69 @@ polls, in the logs files, for all members or the selected role by using the -r f
 	},
 }
 
+// shutdownMemberCmd represents the shutdown member command
+var shutdownMemberCmd = &cobra.Command{
+	Use:   "member node-id",
+	Short: "Shutdown a members services",
+	Long: `The 'shutdown member' command shuts down all the clustered services that are
+running on a specific member via a controlled shutdown. A new member will be started in its place.`,
+	Args: func(cmd *cobra.Command, args []string) error {
+		if len(args) != 1 {
+			displayErrorAndExit(cmd, "you must provide a node id")
+		}
+		return nil
+	},
+	RunE: func(cmd *cobra.Command, args []string) error {
+		var (
+			dataFetcher fetcher.Fetcher
+			connection  string
+			err         error
+			response    string
+			nodeIDArray []string
+			nodeID      = args[0]
+		)
+
+		// retrieve the current context or the value from "-c"
+		connection, dataFetcher, err = GetConnectionAndDataFetcher()
+		if err != nil {
+			return err
+		}
+
+		cmd.Println(FormatCurrentCluster(connection))
+
+		nodeIDArray, err = GetNodeIds(dataFetcher)
+		if err != nil {
+			return err
+		}
+
+		if !utils.IsValidInt(nodeID) {
+			return fmt.Errorf("invalid value for node id of %s", nodeID)
+		}
+
+		if !utils.SliceContains(nodeIDArray, nodeID) {
+			return fmt.Errorf("no node with node id %s exists in this cluster", nodeID)
+		}
+
+		// confirmation
+		if !automaticallyConfirm {
+			cmd.Printf("Are you sure you want to shutdown member %s? (y/n) ", nodeID)
+			_, err = fmt.Scanln(&response)
+			if response != "y" || err != nil {
+				cmd.Println(constants.NoOperation)
+				return nil
+			}
+		}
+
+		_, err = dataFetcher.ShutdownMember(nodeID)
+		if err != nil {
+			return err
+		}
+
+		cmd.Println("operation completed")
+		return nil
+	},
+}
+
 // issueClusterCommand issues a variety of cluster commands
 func issueClusterCommand(cmd *cobra.Command, command string) error {
 	var (
@@ -722,4 +785,6 @@ func init() {
 	configureTracingCmd.Flags().Float32VarP(&tracingRatio, "tracingRatio", "t", 1.0, "Tracing ratio to set. -1.0 turns off tracing")
 	_ = configureTracingCmd.MarkFlagRequired("tracingRatio")
 	configureTracingCmd.Flags().BoolVarP(&automaticallyConfirm, "yes", "y", false, confirmOptionMessage)
+
+	shutdownMemberCmd.Flags().BoolVarP(&automaticallyConfirm, "yes", "y", false, confirmOptionMessage)
 }

pkg/cmd/member.go

@@ -487,6 +487,7 @@ func Initialize(command *cobra.Command) *cobra.Command {
 	// shutdown
 	command.AddCommand(shutdownCmd)
 	shutdownCmd.AddCommand(shutdownServiceCmd)
+	shutdownCmd.AddCommand(shutdownMemberCmd)
 
 	return command
 }

pkg/cmd/root.go

@@ -100,6 +100,9 @@ type Fetcher interface {
 	// GetThreadDump retrieves a thread dump from a member
 	GetThreadDump(memberID string) ([]byte, error)
 
+	// ShutdownMember shuts down a member
+	ShutdownMember(memberID string) ([]byte, error)
+
 	// SetMemberAttribute sets the given attribute for a member
 	SetMemberAttribute(memberID, attribute string, value interface{}) ([]byte, error)
 

pkg/fetcher/fetcher.go

@@ -365,6 +365,15 @@ func (h HTTPFetcher) GetThreadDump(memberID string) ([]byte, error) {
 	return result, nil
 }
 
+// ShutdownMember shuts down a member
+func (h HTTPFetcher) ShutdownMember(memberID string) ([]byte, error) {
+	result, err := httpPostRequest(h, "/members/"+memberID+"/shutdown", constants.EmptyByte)
+	if err != nil {
+		return constants.EmptyByte, utils.GetError("cannot shutdown member "+memberID, err)
+	}
+	return result, nil
+}
+
 // DumpClusterHeap instructs the cluster to dump the cluster heap for the role.
 // role of "all" indicates all members
 func (h HTTPFetcher) DumpClusterHeap(role string) ([]byte, error) {

pkg/fetcher/http_fetcher.go

@@ -55,6 +55,7 @@ create_doc $DOCS_DIR/clear_context "${COHCTL} clear context --help"
 create_doc $DOCS_DIR/get_members "${COHCTL} get members --help"
 create_doc $DOCS_DIR/describe_member "${COHCTL} describe member --help"
 create_doc $DOCS_DIR/set_member "${COHCTL} set member --help"
+create_doc $DOCS_DIR/shutdown_member "${COHCTL} shutdown member --help"
 
 # Machines
 create_doc $DOCS_DIR/get_machines "${COHCTL} get machines --help"