Add process subcommands for multiple machines

bin/cli.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+#
+# The Alluxio Open Foundation licenses this work under the Apache License, version 2.0
+# (the "License"). You may not use this work except in compliance with the License, which is
+# available at www.apache.org/licenses/LICENSE-2.0
+#
+# This software is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied, as more fully set forth in the License.
+#
+# See the NOTICE file distributed with this work for information regarding copyright ownership.
+#
+
+set -eu
+
+BIN_DIR=$(cd "$( dirname "$( readlink "$0" || echo "$0" )" )"; pwd)
+ROOT_PATH="${BIN_DIR}/.."
+CLI_PATH="${BIN_DIR}/../cli/src/alluxio.org/cli/bin/alluxioCli-$(uname)-$(uname -m)"
+"${ROOT_PATH}/build/cli/build-cli.sh"
+"${CLI_PATH}" --rootPath="${ROOT_PATH}" "$@"

build/cli/build-cli.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+#
+# The Alluxio Open Foundation licenses this work under the Apache License, version 2.0
+# (the "License"). You may not use this work except in compliance with the License, which is
+# available at www.apache.org/licenses/LICENSE-2.0
+#
+# This software is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+# either express or implied, as more fully set forth in the License.
+#
+# See the NOTICE file distributed with this work for information regarding copyright ownership.
+#
+
+set -eu
+
+CLI_DIR=$(cd "$( dirname "$( readlink "$0" || echo "$0" )" )"; pwd)
+
+# mapping of GOOS/GOARCH value to uname value
+declare -A ALL_OS
+ALL_OS["linux"]="Linux"
+ALL_OS["darwin"]="Darwin"
+declare -A ALL_ARCH
+ALL_ARCH["amd64"]="x86_64"
+ALL_ARCH["arm64"]="aarch64"
+
+MAIN_PATH="cli/main.go"
+USAGE="Usage: build-cli.sh [-a]
+-a   Build executables for all OS and architecture combinations
+"
+
+main() {
+  build_all="false"
+  while getopts "a" opt; do
+    case "${opt}" in
+      a)
+        build_all="true"
+        ;;
+      *)
+        echo -e "${USAGE}" >&2
+        exit 1
+        ;;
+    esac
+  done
+
+  cliBinDir="${CLI_DIR}/../../cli/src/alluxio.org/cli/bin"
+  mkdir -p "${cliBinDir}"
+
+  cd "${CLI_DIR}/../../cli/src/alluxio.org/"
+
+  if [[ ${build_all} == "false" ]]; then
+    GO111MODULE=on go build -o "${cliBinDir}/alluxioCli-$(uname)-$(uname -m)" "${MAIN_PATH}"
+  else
+    for osKey in "${!ALL_OS[@]}"; do
+      for archKey in "${!ALL_ARCH[@]}"; do
+        echo "Building executable for ${osKey} ${archKey}"
+        GO111MODULE=on GOOS="${osKey}" GOARCH="${archKey}" go build -o "${cliBinDir}/alluxioCli-${ALL_OS[$osKey]}-${ALL_ARCH[$archKey]}" "${MAIN_PATH}"
+      done
+    done
+  fi
+}
+
+main "$@"

cli/README.md

@@ -0,0 +1,58 @@
+# Alluxio CLI
+
+The Alluxio command line interface is the single entrypoint for users to:
+- Initialize and configure the Alluxio cluster
+- Start and stop processes
+- Expose information about the running cluster
+- Interact with the filesystem, running commands such as `ls` and `cp`
+- Perform administrator level actions such as format or backup
+
+The CLI is invoked through the shell script at `bin/cli.sh`.
+Commands follow the format of:
+```console
+bin/cli.sh <service> <operation> [--<flag>[=<value>]] [<args>]
+```
+
+Add the `-h` flag to view more details regarding a service or operation.
+
+## Layout and naming conventions
+
+The choice of names for services, operations, and flags should be succinct: short and unambiguous.
+Use of a single word is strongly preferred, but otherwise the name parts should be delimited by a dash such as `foo-bar`.
+
+For example, let's assume there is a `mark` operation as part of a `item` service that can be `set` or `unset` on an item `name`.
+The recommended format for a command is
+```console
+bin/cli.sh item mark --set name
+bin/cli.sh item mark --unset name
+```
+where it is expected that either `--set` or `--unset` are specified.
+This is preferred over the alternative of two separate commands with `setMark` and `unsetMark` as the operations.
+
+## User input
+
+### Flags and arguments
+After selecting the desired command, additional user input can be parsed, as a mix of arguments and/or flags:
+- Arguments: `bin/cli.sh command arg1 arg2 ...`
+- Flags: `bin/cli.sh command --flag1 --flag2 val2 ...`
+
+Flags are strictly preferred over arguments.
+- The flag name conveys context; an argument does not
+- Arguments must be ordered; flags can be declared arbitrarily
+- Flags can be designated as required to ensure user input.
+- Repeated flags can be defined to capture an ordered list of inputs, ex. `--target target1 --target target2`
+
+### Input validation
+
+User inputs should be validated by the CLI command as much as possible as opposed to the resulting invocation.
+
+## Output conventions and java invocation
+
+A majority of commands result in invoking a java class with arguments to execute the expected operation and possibly return some output.
+The output returned from the java invocation should tend towards being plain or machine parseable, such as a JSON formatted string,
+rather than terminal friendly or human readable format.
+When appropriate, the CLI command will default to formatting this output to be terminal friendly, with an option to output in a machine parseable format.
+
+## References
+
+Github CLI guidelines: https://primer.style/design/native/cli/foundations

cli/src/alluxio.org/cli/bin/.gitignore

@@ -0,0 +1 @@
+alluxioCli*

cli/src/alluxio.org/cli/cmd/conf/conf.go

@@ -0,0 +1,25 @@
+/*
+ * The Alluxio Open Foundation licenses this work under the Apache License, version 2.0
+ * (the "License"). You may not use this work except in compliance with the License, which is
+ * available at www.apache.org/licenses/LICENSE-2.0
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied, as more fully set forth in the License.
+ *
+ * See the NOTICE file distributed with this work for information regarding copyright ownership.
+ */
+
+package conf
+
+import (
+	"alluxio.org/cli/env"
+)
+
+var Service = &env.Service{
+	Name:        "conf",
+	Description: "Get, set, and validate configuration settings, primarily those defined in conf/alluxio-site.properties",
+	Commands: []env.Command{
+		Get,
+		Log,
+	},
+}

cli/src/alluxio.org/cli/cmd/conf/get.go

@@ -0,0 +1,90 @@
+/*
+ * The Alluxio Open Foundation licenses this work under the Apache License, version 2.0
+ * (the "License"). You may not use this work except in compliance with the License, which is
+ * available at www.apache.org/licenses/LICENSE-2.0
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied, as more fully set forth in the License.
+ *
+ * See the NOTICE file distributed with this work for information regarding copyright ownership.
+ */
+
+package conf
+
+import (
+	"bytes"
+	"fmt"
+	"github.com/palantir/stacktrace"
+	"github.com/spf13/cobra"
+
+	"alluxio.org/cli/env"
+	"alluxio.org/log"
+)
+
+var Get = &GetCommand{
+	BaseJavaCommand: &env.BaseJavaCommand{
+		CommandName:   "get",
+		JavaClassName: "alluxio.cli.GetConf",
+		ShellJavaOpts: fmt.Sprintf(env.JavaOptFormat, env.ConfAlluxioConfValidationEnabled, false),
+	},
+}
+
+type GetCommand struct {
+	*env.BaseJavaCommand
+
+	ShowMaster bool
+	ShowSource bool
+	Unit       string
+}
+
+func (c *GetCommand) Base() *env.BaseJavaCommand {
+	return c.BaseJavaCommand
+}
+
+func (c *GetCommand) ToCommand() *cobra.Command {
+	cmd := c.Base().InitRunJavaClassCmd(&cobra.Command{
+		Use:   fmt.Sprintf("%v [key]", Get.CommandName),
+		Short: "Look up a configuration value by its property key or print all configuration if no key is provided",
+		Args:  cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return c.Run(args)
+		},
+	})
+	cmd.Flags().BoolVar(&c.ShowMaster, "master", false, "Show configuration properties used by the master")
+	cmd.Flags().BoolVar(&c.ShowSource, "source", false, "Show source of the configuration property instead of the value")
+	cmd.Flags().StringVar(&c.Unit, "unit", "",
+		`Unit of the value to return, converted to correspond to the given unit.
+E.g., with "--unit KB", a configuration value of "4096B" will return 4
+Possible options include B, KB, MB, GB, TP, PB, MS, S, M, H, D`)
+	return cmd
+}
+
+func (c *GetCommand) Run(args []string) error {
+	var javaArgs []string
+	if c.ShowMaster {
+		javaArgs = append(javaArgs, "--master")
+	}
+	if c.ShowSource {
+		javaArgs = append(javaArgs, "--source")
+	}
+	if c.Unit != "" {
+		javaArgs = append(javaArgs, "--unit", c.Unit)
+	}
+	javaArgs = append(javaArgs, args...)
+
+	return c.Base().Run(javaArgs)
+}
+
+func (c *GetCommand) FetchValue(key string) (string, error) {
+	cmd := c.RunJavaClassCmd([]string{key})
+
+	errBuf := &bytes.Buffer{}
+	cmd.Stderr = errBuf
+
+	log.Logger.Debugln(cmd.String())
+	out, err := cmd.Output()
+	if err != nil {
+		return "", stacktrace.Propagate(err, "error getting conf for %v\nstderr: %v", key, errBuf.String())
+	}
+	return string(out), nil
+}

cli/src/alluxio.org/cli/cmd/conf/log.go

@@ -0,0 +1,69 @@
+/*
+ * The Alluxio Open Foundation licenses this work under the Apache License, version 2.0
+ * (the "License"). You may not use this work except in compliance with the License, which is
+ * available at www.apache.org/licenses/LICENSE-2.0
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied, as more fully set forth in the License.
+ *
+ * See the NOTICE file distributed with this work for information regarding copyright ownership.
+ */
+
+package conf
+
+import (
+	"github.com/spf13/cobra"
+	"strings"
+
+	"alluxio.org/cli/env"
+)
+
+var Log = &LogCommand{
+	BaseJavaCommand: &env.BaseJavaCommand{
+		CommandName:   "log",
+		JavaClassName: "alluxio.cli.LogLevel",
+	},
+}
+
+type LogCommand struct {
+	*env.BaseJavaCommand
+
+	LogName string
+	Level   string
+	Targets []string
+}
+
+func (c *LogCommand) Base() *env.BaseJavaCommand {
+	return c.BaseJavaCommand
+}
+
+func (c *LogCommand) ToCommand() *cobra.Command {
+	cmd := c.Base().InitRunJavaClassCmd(&cobra.Command{
+		Use:   Log.CommandName,
+		Short: "Get or set the log level for the specified logger",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return c.Run(args)
+		},
+	})
+	const name = "name"
+	cmd.Flags().StringVar(&c.LogName, name, "", "Logger name (ex. alluxio.master.file.DefaultFileSystemMaster)")
+	if err := cmd.MarkFlagRequired(name); err != nil {
+		panic(err)
+	}
+	cmd.Flags().StringVar(&c.Level, "level", "", "If specified, sets the specified logger at the given level")
+	cmd.Flags().StringSliceVar(&c.Targets, "target", nil, "A target name among <master|workers|job_master|job_workers|host:webPort[:role]>. Defaults to master,workers,job_master,job_workers")
+	return cmd
+}
+
+func (c *LogCommand) Run(_ []string) error {
+	javaArgs := []string{"--logName", c.LogName}
+	if c.Level != "" {
+		javaArgs = append(javaArgs, "--level", c.Level)
+	}
+	if len(c.Targets) > 0 {
+		javaArgs = append(javaArgs, "--target", strings.Join(c.Targets, ","))
+	}
+
+	return c.Base().Run(javaArgs)
+}

cli/src/alluxio.org/cli/cmd/fs/cat.go

@@ -0,0 +1,52 @@
+/*
+ * The Alluxio Open Foundation licenses this work under the Apache License, version 2.0
+ * (the "License"). You may not use this work except in compliance with the License, which is
+ * available at www.apache.org/licenses/LICENSE-2.0
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied, as more fully set forth in the License.
+ *
+ * See the NOTICE file distributed with this work for information regarding copyright ownership.
+ */
+
+package fs
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"alluxio.org/cli/env"
+)
+
+var Cat = &CatCommand{
+	BaseJavaCommand: &env.BaseJavaCommand{
+		CommandName:   "cat",
+		JavaClassName: "alluxio.cli.fs.FileSystemShell",
+		Parameters:    []string{"cat"},
+	},
+}
+
+type CatCommand struct {
+	*env.BaseJavaCommand
+}
+
+func (c *CatCommand) Base() *env.BaseJavaCommand {
+	return c.BaseJavaCommand
+}
+
+func (c *CatCommand) ToCommand() *cobra.Command {
+	cmd := c.Base().InitRunJavaClassCmd(&cobra.Command{
+		Use:   fmt.Sprintf("%v [path]", Cat.CommandName),
+		Short: "Print specified file's content",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return c.Run(args)
+		},
+	})
+	return cmd
+}
+
+func (c *CatCommand) Run(args []string) error {
+	return c.Base().Run(args)
+}