feat: debug support msg and var

redscholar · redscholar · commit d8eb7b1d7eae · 2026-04-03T10:56:17.000+08:00
Signed-off-by: redscholar &lt;blacktiledhouse@gmail.com&gt;
diff --git a/api/project/v1/playbook.go b/api/project/v1/playbook.go
@@ -58,7 +58,7 @@ func IsTmplSyntax(s string) bool {
 // ParseTmplSyntax wraps a string with template syntax delimiters "{{" and "}}"
 // to make it a valid Go template expression
 func ParseTmplSyntax(s string) string {
-	return "{{ " + s + "}}"
+	return "{{" + s + "}}"
 }
 
 func TrimTmplSyntax(s string) string {
diff --git a/docs/en/custom/modules/debug.md b/docs/en/custom/modules/debug.md
@@ -6,7 +6,10 @@ Print variables or strings for troubleshooting.
 
 | Parameter | Description | Type | Required | Default |
 |-----------|-------------|------|----------|---------|
-| msg | Content to output, supports [template syntax](../101-syntax.md) | string | Yes | - |
+| msg | Content to output, supports [template syntax](../101-syntax.md) with filters | string | No | - |
+| var | Variable path to output, supports template syntax `{{ .var }}` or simple path `.var` | string | No | - |
+
+**Note:** One of `msg` or `var` must be specified.
 
 ## Examples
 
@@ -25,7 +28,22 @@ DEBUG:
 I'm kubekey
 ```
 
-**2. Print map**
+**2. Print with template filter**
+
+```yaml
+- name: debug with default filter
+  debug:
+    msg: "Name is {{ .name | default \"unknown\" }}"
+```
+
+When `name` is not defined, output:
+
+```text
+DEBUG:
+Name is unknown
+```
+
+**3. Print map**
 
 ```yaml
 - name: debug map
@@ -43,7 +61,7 @@ DEBUG:
 }
 ```
 
-**3. Print array**
+**4. Print array**
 
 ```yaml
 - name: debug array
@@ -61,3 +79,48 @@ DEBUG:
     "2"
 ]
 ```
+
+**5. Print variable using var field (template syntax)**
+
+```yaml
+- name: debug variable with template
+  debug:
+    var: "{{ .config.version }}"
+```
+
+When `config.version` is `v1.0.0`, output:
+
+```text
+DEBUG:
+"v1.0.0"
+```
+
+**6. Print variable using var field (simple path)**
+
+```yaml
+- name: debug variable with path
+  debug:
+    var: ".config.version"
+```
+
+When `config.version` is `v1.0.0`, output:
+
+```text
+DEBUG:
+"v1.0.0"
+```
+
+**7. Print nested variable**
+
+```yaml
+- name: debug nested variable
+  debug:
+    var: ".data.level1.level2"
+```
+
+When `data.level1.level2` is `value`, output:
+
+```text
+DEBUG:
+"value"
+```
diff --git a/docs/zh/custom/modules/debug.md b/docs/zh/custom/modules/debug.md
@@ -6,7 +6,10 @@
 
 | 参数 | 说明 | 类型 | 必填 | 默认值 |
 |------|------|------|------|--------|
-| msg | 要输出的内容，支持 [模板语法](../101-syntax.md) | 字符串 | 是 | - |
+| msg | 要输出的内容，支持带过滤器的 [模板语法](../101-syntax.md) | 字符串 | 否 | - |
+| var | 要输出的变量路径，支持模板语法 `{{ .var }}` 或简单路径 `.var` | 字符串 | 否 | - |
+
+**注意：** `msg` 和 `var` 至少需要一个。
 
 ## 示例
 
@@ -25,7 +28,22 @@ DEBUG:
 I'm kubekey
 ```
 
-**2. 打印 map**
+**2. 使用模板过滤器打印**
+
+```yaml
+- name: debug with default filter
+  debug:
+    msg: "Name is {{ .name | default \"unknown\" }}"
+```
+
+当 `name` 未定义时，输出：
+
+```text
+DEBUG:
+Name is unknown
+```
+
+**3. 打印 map**
 
 ```yaml
 - name: debug map
@@ -43,7 +61,7 @@ DEBUG:
 }
 ```
 
-**3. 打印数组**
+**4. 打印数组**
 
 ```yaml
 - name: debug array
@@ -61,3 +79,48 @@ DEBUG:
     "2"
 ]
 ```
+
+**5. 使用 var 字段打印变量（模板语法）**
+
+```yaml
+- name: debug variable with template
+  debug:
+    var: "{{ .config.version }}"
+```
+
+当 `config.version` 为 `v1.0.0` 时，输出：
+
+```text
+DEBUG:
+"v1.0.0"
+```
+
+**6. 使用 var 字段打印变量（简单路径）**
+
+```yaml
+- name: debug variable with path
+  debug:
+    var: ".config.version"
+```
+
+当 `config.version` 为 `v1.0.0` 时，输出：
+
+```text
+DEBUG:
+"v1.0.0"
+```
+
+**7. 打印嵌套变量**
+
+```yaml
+- name: debug nested variable
+  debug:
+    var: ".data.level1.level2"
+```
+
+当 `data.level1.level2` 为 `value` 时，输出：
+
+```text
+DEBUG:
+"value"
+```
diff --git a/pkg/modules/debug/debug.go b/pkg/modules/debug/debug.go
@@ -27,6 +27,7 @@ import (
 	"github.com/cockroachdb/errors"
 	kkprojectv1 "github.com/kubesphere/kubekey/api/project/v1"
 
+	"github.com/kubesphere/kubekey/v4/pkg/converter/tmpl"
 	"github.com/kubesphere/kubekey/v4/pkg/modules/internal"
 	"github.com/kubesphere/kubekey/v4/pkg/variable"
 )
@@ -39,8 +40,10 @@ Configuration:
 Users can specify either a message or a variable path to debug.
 
 debug:
-  msg: "message"        # optional: direct message to print
-  msg: "{{ .var }}"     # optional: template syntax to print variable value
+  msg: "message"                    # optional: direct message to print
+  msg: "value is {{ .var }}"        # optional: template syntax with filters
+  var: "{{ .var }}"                 # optional: template syntax to get variable
+  var: ".var"                       # optional: simple variable path
 
 Usage Examples in Playbook Tasks:
 1. Print direct message:
@@ -51,11 +54,27 @@ Usage Examples in Playbook Tasks:
      register: debug_result
    ```
 
-2. Print variable value:
+2. Print message with template:
+   ```yaml
+   - name: Debug with template
+     debug:
+       msg: "Version is {{ .config.version | default \"unknown\" }}"
+     register: debug_result
+   ```
+
+3. Print variable value:
    ```yaml
    - name: Debug variable
      debug:
-       msg: "{{ .config.version }}"
+       var: "{{ .config.version }}"
+     register: var_debug
+   ```
+
+4. Print variable with simple path:
+   ```yaml
+   - name: Debug variable simple
+     debug:
+       var: ".config.version"
      register: var_debug
    ```
 
@@ -72,40 +91,89 @@ func ModuleDebug(_ context.Context, opts internal.ExecOptions) (string, string,
 		return internal.StdoutFailed, internal.StderrGetHostVariable, err
 	}
 	args := variable.Extension2Variables(opts.Args)
-	v := reflect.ValueOf(args["msg"])
-	switch v.Kind() {
-	case reflect.Invalid:
-		return internal.StdoutFailed, internal.StderrUnsupportArgs, errors.New("\"msg\" is not found")
+
+	// Handle "var" field - for getting variable values
+	if v, ok := args["var"]; ok {
+		return handleVarField(v, ha, opts.LogOutput)
+	}
+
+	// Handle "msg" field - for printing messages with template support
+	if v, ok := args["msg"]; ok {
+		return handleMsgField(v, ha, opts.LogOutput)
+	}
+
+	return internal.StdoutFailed, internal.StderrUnsupportArgs, errors.New("either \"msg\" or \"var\" must be specified")
+}
+
+// handleVarField handles the "var" field for variable debugging
+// Supports both template syntax "{{ .var }}" and simple path ".var"
+func handleVarField(v any, ha map[string]any, output io.Writer) (string, string, error) {
+	rv := reflect.ValueOf(v)
+	switch rv.Kind() {
 	case reflect.String:
-		if !kkprojectv1.IsTmplSyntax(v.String()) {
-			return formatOutput([]byte(v.String()), opts.LogOutput), "", nil
+		val := rv.String()
+		// Check if it's template syntax
+		if kkprojectv1.IsTmplSyntax(val) {
+			val = kkprojectv1.TrimTmplSyntax(val)
 		}
-		val := kkprojectv1.TrimTmplSyntax(v.String())
+		// Ensure it starts with "."
 		if !strings.HasPrefix(val, ".") {
-			return internal.StdoutFailed, internal.StderrUnsupportArgs, errors.New("error tmpl value syntax")
+			return internal.StdoutFailed, internal.StderrUnsupportArgs, errors.New("variable path must start with '.'")
 		}
-		data, err := variable.PrintVar(ha, strings.Split(val, ".")[1:]...)
+		// Remove leading "." and split path
+		path := strings.TrimPrefix(val, ".")
+		if path == "" {
+			return internal.StdoutFailed, internal.StderrUnsupportArgs, errors.New("variable path cannot be empty")
+		}
+		data, err := variable.PrintVar(ha, strings.Split(path, ".")...)
 		if err != nil {
 			return internal.StdoutFailed, internal.StderrParseArgument, err
 		}
-		return formatOutput(data, opts.LogOutput), "", nil
+		return formatOutput(data, output), "", nil
 	default:
-		// do not parse by ctx
-		data, err := json.Marshal(v.Interface())
-		if err != nil {
-			return internal.StdoutFailed, "failed to marshal value to json", err
+		// For non-string types, pass directly to formatOutput for pretty printing
+		return formatOutput(rv.Interface(), output), "", nil
+	}
+}
+
+// handleMsgField handles the "msg" field for message debugging
+// Supports template syntax with filters like "a is {{ .var | default 'b' }}"
+func handleMsgField(v any, ha map[string]any, output io.Writer) (string, string, error) {
+	rv := reflect.ValueOf(v)
+	switch rv.Kind() {
+	case reflect.String:
+		msg := rv.String()
+		// If it contains template syntax, parse it
+		if kkprojectv1.IsTmplSyntax(msg) {
+			parsed, err := tmpl.Parse(ha, msg)
+			if err != nil {
+				return internal.StdoutFailed, internal.StderrParseArgument, err
+			}
+			return formatOutput(string(parsed), output), "", nil
 		}
-		return formatOutput(data, opts.LogOutput), "", nil
+		// Direct message without template
+		return formatOutput(msg, output), "", nil
+	default:
+		// For non-string types, pass directly to formatOutput for pretty printing
+		return formatOutput(rv.Interface(), output), "", nil
 	}
 }
 
 // formatOutput formats data as pretty JSON and logs it with DEBUG prefix if output is provided
 // Returns the formatted string
 func formatOutput(data any, output io.Writer) string {
 	var msg string
-	prettyJSON, err := json.MarshalIndent(data, "", "  ")
-	if err == nil {
-		msg = string(prettyJSON)
+	// Handle string data directly without JSON marshaling
+	switch v := data.(type) {
+	case string:
+		msg = v
+	case []byte:
+		msg = string(v)
+	default:
+		prettyJSON, err := json.MarshalIndent(v, "", "  ")
+		if err == nil {
+			msg = string(prettyJSON)
+		}
 	}
 	if output != nil {
 		_, _ = fmt.Fprintln(output, "DEBUG: \n"+msg) // Ignore error in test context
diff --git a/pkg/modules/debug/debug_test.go b/pkg/modules/debug/debug_test.go

Original file line number	Diff line number	Diff line change
`@@ -58,7 +58,7 @@ func IsTmplSyntax(s string) bool {`
`58`	`58`	`// ParseTmplSyntax wraps a string with template syntax delimiters "{{" and "}}"`
`59`	`59`	`// to make it a valid Go template expression`
`60`	`60`	`func ParseTmplSyntax(s string) string {`
`61`		`- return "{{ " + s + "}}"`
	`61`	`+ return "{{" + s + "}}"`
`62`	`62`	`}`
`63`	`63`
`64`	`64`	`func TrimTmplSyntax(s string) string {`