feat(project): inject custom playbooks at arbitrary positions via playbooks order (#3191)

Hard-coding an import slot in every builtin playbook was brittle and could not
place custom playbooks at arbitrary positions. Generalize injection so users can
insert custom playbooks anywhere in the top-level source playbook by weight.

- Add a `playbooks` config list; each entry has `order` (float, can be fractional
  or negative) and `path` (template-rendered). Original plays get weights
  0,1,2,... by document order; injected items are merged and sorted by a
  deterministic comparator: order ascending -> config items precede file plays
  -> definition order (duplicate order does not error).
- Empty or unset `path` is skipped silently; a set path that does not exist still
  errors. Injection applies only to the top-level (first) source playbook.
- Remove the hard-coded `inject_playbooks_path` import slot from builtin
  playbooks; injection now goes exclusively through the `playbooks` order list.
- Add unit tests for order-based injection (incl. empty-path skip and pure
  import-directive anchors) and zh/en docs (framework + reference page).

Signed-off-by: redscholar <blacktiledhouse@gmail.com>

Author: redscholar

docs/en/framework/002-playbook.md

@@ -55,3 +55,44 @@ A playbook file can execute multiple plays in the defined order; each play speci
 - **Multiple plays**: Execute in defined order; `import_playbook` expands to the corresponding play first.
 - **Within the same play**: `pre_tasks` → `roles` → `tasks` → `post_tasks`.
 - Any task failure (without `ignore_errors`) results in play failure.
+
+## Inject Playbooks
+
+Besides hardcoding `import_playbook` inside a playbook file, you can declare a `playbooks`
+list in the playbook's config spec to inject a **custom playbook at any position of the
+top-level (first) source playbook**. This lets you override/modify parameters after the
+default parameters are loaded, without touching builtin playbooks or role code.
+
+### Configuration
+
+```yaml
+spec:
+  playbooks:
+    - order: 1.5                        # insert between the 1st and 2nd original plays
+      path: hook/inject_playbooks.yaml # playbook to inject (relative to project root, templated)
+    - order: 0                          # 0 means insert at the very front (before the 1st play)
+      path: hook/pre_custom.yaml
+```
+
+### Rules
+
+- **Original plays get weights `1, 2, 3, ...` automatically** (by document order, 1-based).
+- **Injected items use an explicit `order`** (float, can be fractional or negative) to
+  position the insertion; e.g. `order: 1.5` inserts between the 1st and 2nd original plays,
+  `order: 0` inserts at the very front.
+- **Sort comparator (deterministic; duplicate `order` does not error)**:
+  1. `order` ascending;
+  2. `playbooks` config items take precedence over file plays;
+  3. within the same source, by definition order (config list order / file order).
+- **`path` is rendered through templates**:
+  - rendered to empty / unset variable → that item is **skipped** (no error);
+  - path set but file not found → **errors** (as usual), to catch typos.
+- This mechanism applies **only to the top-level (first) source playbook.yaml**; imported
+  sub-playbooks are not injected again.
+
+### Example
+
+The builtin package ships an example playbook `hook/inject_playbooks.yaml` (bundled, directly
+referenced via `path: hook/inject_playbooks.yaml`). It is a no-op by default; uncomment to
+override variables. For the full example and field reference, see
+[Inject Playbook (inject_playbooks.yaml)](../reference/playbooks/inject_playbooks.md).

docs/en/reference/playbooks/inject_playbooks.md

@@ -0,0 +1,72 @@
+# Inject Playbook (inject_playbooks.yaml)
+
+![architecture](../../images/architecture.png)
+
+`inject_playbooks.yaml` is a builtin **example playbook for injection**. It is a no-op by
+default, used to override/modify parameters after the default parameters are loaded, without
+changing builtin playbooks or role code.
+
+The file is bundled with the builtin package at `builtin/core/playbooks/hook/inject_playbooks.yaml`.
+Reference it directly via the
+[`playbooks` injection mechanism](../framework/002-playbook.md#inject-playbooks):
+
+```yaml
+spec:
+  playbooks:
+    - order: 1.5                        # insert between the 1st and 2nd original plays
+      path: hook/inject_playbooks.yaml # this file, bundled with the builtin package
+```
+
+## What you can do
+
+- Use `set_fact` to override runtime variables of the current host (for a single host play).
+- Use `add_hostvars` to write/override variables on multiple hosts in bulk (like `set_fact`
+  but across hosts).
+- Use `debug` to print variables and verify the injection took effect.
+
+## Full example
+
+The file content is commented out by default; uncomment the relevant block to enable it:
+
+```yaml
+- name: Inject | Inject and override playbook variables
+  hosts:
+    - all
+  tasks:
+    # Example 1: override a single variable (applies to all hosts of the current play)
+    # - name: Inject | Override a single variable via set_fact
+    #   set_fact:
+    #     .kubernetes.version: "v1.31.0"
+
+    # Example 2: override variables by group / host condition
+    # - name: Inject | Override variables for a specific group
+    #   set_fact:
+    #     .kubernetes.container_manager: "containerd"
+    #   when:
+    #     - .groups.k8s_cluster | default list | has .inventory_hostname
+
+    # Example 3: inject variables to multiple hosts in bulk (add_hostvars)
+    # - name: Inject | Add host variables to multiple hosts
+    #   add_hostvars:
+    #     hosts: ["all"]
+    #     vars:
+    #       custom_label: "injected-by-hook"
+
+    # Example 4: debug — confirm variable values before injection
+    # - name: Inject | Debug current variables
+    #   debug:
+    #     msg: "kubernetes version is {{ .kubernetes.version }}"
+```
+
+## Notes
+
+- Injected variables are only valid **during the current playbook run** (runtime variables)
+  and are not written back to your config file. For persistent customization, prefer
+  declaring it in the config spec.
+- Only enable the example when you truly need "recompute / conditional override after the
+  default parameters are loaded".
+- **Builtin playbooks** can reference the bundled `hook/inject_playbooks.yaml` directly;
+  **local projects** (non-builtin playbooks) should create this file under their own project
+  directory and reference it by relative path.
+- For `order` positioning, sorting rules, empty-path skipping, etc., see
+  [Inject Playbooks](../framework/002-playbook.md#inject-playbooks).

docs/zh/framework/002-playbook.md

@@ -55,3 +55,41 @@
 - **多个 play**：按定义顺序执行；`import_playbook` 会先展开为对应 play。
 - **同一 play 内**：`pre_tasks` → `roles` → `tasks` → `post_tasks`。
 - 任一 task 失败（且未 `ignore_errors`）则 play 失败。
+
+## 注入自定义 Playbook（Inject Playbooks）
+
+除在 playbook 文件内写死 `import_playbook` 外，还可以通过 playbook 的 config spec 声明
+`playbooks` 列表，把**自定义 playbook 注入到顶层（第一个）源 playbook 的任意位置**。
+这样无需改动内置 playbook 与 role 代码，就能在默认参数加载完成后覆盖 / 修改参数。
+
+### 配置
+
+```yaml
+spec:
+  playbooks:
+    - order: 1.5                        # 插在第 1、2 个原始 play 之间
+      path: hook/inject_playbooks.yaml # 要注入的 playbook（相对项目根，支持模板渲染）
+    - order: 0                          # 0 表示插在最前面（第 1 个 play 之前）
+      path: hook/pre_custom.yaml
+```
+
+### 规则
+
+- **原始 play 自动获得权重 `1, 2, 3, ...`**（按文档顺序，1-based）。
+- **注入项给显式 `order`**（float，可小数、可负数），用于定位插入位置；例如
+  `order: 1.5` 表示插在第 1 个与第 2 个原始 play 之间，`order: 0` 表示插在最前。
+- **排序比较器（确定性裁决，order 相同不报错）**：
+  1. `order` 升序；
+  2. `playbooks` 配置项优先于文件内 play；
+  3. 同来源内按定义顺序（配置列表顺序 / 文件内顺序）。
+- **`path` 走模板渲染**：
+  - 渲染为空串 / 未设置变量 → 该项被**跳过**（不报错）；
+  - 设置了路径但文件不存在 → 按原逻辑**报错**，便于发现路径拼写错误。
+- 该机制**仅作用于顶层（第一个）源 playbook.yaml**；被导入的子 playbook 不再二次注入。
+
+### 示例
+
+内置包已提供一个示例 playbook `hook/inject_playbooks.yaml`（随内置包发布，可直接用
+`path: hook/inject_playbooks.yaml` 引用）。它默认是空操作，取消注释即可覆盖变量。
+完整示例与字段说明见参考页：[注入 Playbook（inject_playbooks.yaml）](../reference/playbooks/inject_playbooks.md)。
+

docs/zh/reference/playbooks/inject_playbooks.md

@@ -0,0 +1,66 @@
+# 注入 Playbook（inject_playbooks.yaml）
+
+![architecture](../../images/architecture.png)
+
+`inject_playbooks.yaml` 是 KubeKey 内置的一个**注入用示例 playbook**。它本身默认是空操作，
+用于在不改动内置 playbook 与 role 代码的前提下，在默认参数加载完成后覆盖 / 修改参数。
+
+该文件随内置包发布，位于 `builtin/core/playbooks/hook/inject_playbooks.yaml`。可直接通过
+[`playbooks` 注入机制](../framework/002-playbook.md#注入自定义-playbookinject-playbooks) 引用：
+
+```yaml
+spec:
+  playbooks:
+    - order: 1.5                        # 插在第 1、2 个原始 play 之间
+      path: hook/inject_playbooks.yaml # 本文件，已随内置包提供
+```
+
+## 你能做什么
+
+- 用 `set_fact` 覆盖当前主机的运行时变量（针对单个 host play）。
+- 用 `add_hostvars` 批量给多台主机写入 / 覆盖变量（类似 `set_fact` 但作用于多主机）。
+- 用 `debug` 打印变量，方便排查注入是否正确生效。
+
+## 完整示例
+
+文件内容默认全部以注释形式给出，取消对应注释即可生效：
+
+```yaml
+- name: Inject | Inject and override playbook variables
+  hosts:
+    - all
+  tasks:
+    # 示例 1：覆盖单一变量（针对当前 play 的所有主机生效）
+    # - name: Inject | Override a single variable via set_fact
+    #   set_fact:
+    #     .kubernetes.version: "v1.31.0"
+
+    # 示例 2：按分组 / 主机条件覆盖变量
+    # - name: Inject | Override variables for a specific group
+    #   set_fact:
+    #     .kubernetes.container_manager: "containerd"
+    #   when:
+    #     - .groups.k8s_cluster | default list | has .inventory_hostname
+
+    # 示例 3：批量给多台主机注入变量（add_hostvars）
+    # - name: Inject | Add host variables to multiple hosts
+    #   add_hostvars:
+    #     hosts: ["all"]
+    #     vars:
+    #       custom_label: "injected-by-hook"
+
+    # 示例 4：调试 —— 确认注入前的变量取值
+    # - name: Inject | Debug current variables
+    #   debug:
+    #     msg: "kubernetes version is {{ .kubernetes.version }}"
+```
+
+## 注意事项
+
+- 注入的变量仅在「当前 playbook 运行期间」有效（运行时变量），不会写回你的 config 文件。
+  如需持久化定制，应当优先在 config 的 spec 中声明。
+- 仅当确有「默认参数加载后仍需二次计算 / 条件覆盖」的需求时才启用示例。
+- **内置 playbook** 可直接引用随包提供的 `hook/inject_playbooks.yaml`；
+  **本地项目**（非内置 playbook）请在自己的项目目录下创建该文件，并用相对路径引用。
+- 关于 `order` 定位、排序规则、空路径跳过等行为，详见
+  [注入自定义 Playbook](../framework/002-playbook.md#注入自定义-playbookinject-playbooks)。

pkg/project/project.go

@@ -23,13 +23,15 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 
 	"github.com/cockroachdb/errors"
 	kkcorev1 "github.com/kubesphere/kubekey/api/core/v1"
 	kkcorev1alpha1 "github.com/kubesphere/kubekey/api/core/v1alpha1"
 	kkprojectv1 "github.com/kubesphere/kubekey/api/project/v1"
 	"gopkg.in/yaml.v3"
+	"k8s.io/klog/v2"
 
 	_const "github.com/kubesphere/kubekey/v4/pkg/const"
 	"github.com/kubesphere/kubekey/v4/pkg/converter/tmpl"
@@ -134,6 +136,15 @@ func (f *project) loadPlaybook(fromPlayBook, basePlaybook string) error {
 		return errors.Wrapf(err, "failed to unmarshal playbook %q", basePlaybook)
 	}
 
+	// Inject configured playbooks at their orders for the top-level playbook
+	// only. Imported playbooks keep their own content.
+	if fromPlayBook == "" {
+		plays, err = f.injectPlaybooks(plays)
+		if err != nil {
+			return err
+		}
+	}
+
 	for _, p := range plays {
 		if err := f.dealImportPlaybook(p, basePlaybook); err != nil {
 			return err
@@ -166,6 +177,13 @@ func (f *project) loadPlaybook(fromPlayBook, basePlaybook string) error {
 			}
 		}
 
+		// A play that is purely an import_playbook directive carries no
+		// standalone content; skip appending it so it does not show up as an
+		// empty play in the final playbook. Its imported plays are already
+		// loaded by dealImportPlaybook above.
+		if p.ImportPlaybook != "" {
+			continue
+		}
 		f.Play = append(f.Play, p)
 	}
 
@@ -175,7 +193,22 @@ func (f *project) loadPlaybook(fromPlayBook, basePlaybook string) error {
 // dealImportPlaybook handles the "import_playbook" argument in a play
 func (f *project) dealImportPlaybook(p kkprojectv1.Play, basePlaybook string) error {
 	if p.ImportPlaybook != "" {
-		importPlaybook, _ := f.getPath(GetImportPlaybookRelPath(basePlaybook, p.ImportPlaybook))
+		// Render the import path with template syntax so that it can be
+		// customized via variables and the `playbooks` order injection.
+		importPlaybookPath, err := tmpl.ParseFunc(f.config, p.ImportPlaybook, tmpl.StringFunc)
+		if err != nil {
+			return errors.Wrapf(err, "failed to parse import_playbook %q", p.ImportPlaybook)
+		}
+		// An import_playbook that renders to an empty string is treated as a
+		// no-op and skipped silently. This makes variable-driven imports
+		// opt-in: reference them as `{{ .var | default "" }}`, leave the
+		// variable unset (or set it to "") to disable the import, and point it
+		// at a path to enable it.
+		if strings.TrimSpace(importPlaybookPath) == "" {
+			klog.V(5).InfoS("skip empty import_playbook", "import_playbook", p.ImportPlaybook, "base", basePlaybook)
+			return nil
+		}
+		importPlaybook, _ := f.getPath(GetImportPlaybookRelPath(basePlaybook, importPlaybookPath))
 		if importPlaybook == "" {
 			return errors.Errorf("failed to find import_playbook %q base on %q. it's should be:\n %s", p.ImportPlaybook, basePlaybook, PathFormatImportPlaybook)
 		}
@@ -191,6 +224,88 @@ func (f *project) dealImportPlaybook(p kkprojectv1.Play, basePlaybook string) er
 	return nil
 }
 
+// playbookInjection defines a playbook to inject into the top-level playbook at
+// a specific position. Order is a sort weight: original (file) plays get
+// 1,2,3,... by their document order (1-based), while injected (config) plays
+// keep their explicit order.
+type playbookInjection struct {
+	Order float64 `yaml:"order" json:"order"`
+	Path  string  `yaml:"path" json:"path"`
+}
+
+// injectPlaybooks merges configured playbook injections into the play list and
+// returns the combined list sorted by order. The sort contract is:
+//   - original (file) plays get orders 1,2,3,... by document order (1-based);
+//   - injected (config) plays keep their explicit order (float, may be negative
+//     or fractional);
+//   - on a tie, config plays win over file plays, then definition order
+//     (config list order / file document order).
+//
+// The injected paths are rendered as templates; an empty rendered path is
+// skipped. Only the top-level playbook is injected (see loadPlaybook).
+func (f *project) injectPlaybooks(plays []kkprojectv1.Play) ([]kkprojectv1.Play, error) {
+	raw, ok := f.config["playbooks"]
+	if !ok || raw == nil {
+		return plays, nil
+	}
+	// Round-trip through YAML so we don't depend on the exact map types
+	// produced by the config JSON decoder.
+	buf, err := yaml.Marshal(raw)
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to marshal playbooks injection config")
+	}
+	var injections []playbookInjection
+	if err := yaml.Unmarshal(buf, &injections); err != nil {
+		return nil, errors.Wrap(err, "failed to unmarshal playbooks injection config")
+	}
+
+	type entry struct {
+		order   float64
+		fromCfg bool
+		seq     int
+		play    kkprojectv1.Play
+	}
+	entries := make([]entry, 0, len(plays)+len(injections))
+	for i, p := range plays {
+		// Original plays are ordered 1,2,3,... (1-based), so that order: 0 is a
+		// natural "insert at the very front" sentinel.
+		entries = append(entries, entry{order: float64(i + 1), fromCfg: false, seq: i, play: p})
+	}
+	for i, inj := range injections {
+		path, err := tmpl.ParseFunc(f.config, inj.Path, tmpl.StringFunc)
+		if err != nil {
+			return nil, errors.Wrapf(err, "failed to parse injected playbook path %q", inj.Path)
+		}
+		if strings.TrimSpace(path) == "" {
+			klog.V(5).InfoS("skip empty injected playbook", "order", inj.Order, "path", inj.Path)
+			continue
+		}
+		entries = append(entries, entry{
+			order:   inj.Order,
+			fromCfg: true,
+			seq:     i,
+			play:    kkprojectv1.Play{ImportPlaybook: path},
+		})
+	}
+
+	sort.SliceStable(entries, func(a, b int) bool {
+		if entries[a].order != entries[b].order {
+			return entries[a].order < entries[b].order
+		}
+		// Config injections win over file plays on a tie.
+		if entries[a].fromCfg != entries[b].fromCfg {
+			return entries[a].fromCfg
+		}
+		return entries[a].seq < entries[b].seq
+	})
+
+	out := make([]kkprojectv1.Play, len(entries))
+	for i, e := range entries {
+		out[i] = e.play
+	}
+	return out, nil
+}
+
 // dealVarsFiles handles the "vars_files" argument in a play
 func (f *project) dealVarsFiles(p *kkprojectv1.Play, basePlaybook string) error {
 	for _, varsFileStr := range p.VarsFiles {