Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 112 additions & 0 deletions docs/advanced/batch-node.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
---
title: batch process edge node

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For consistency with other documentation pages, please use Title Case for the title.

Suggested change
title: batch process edge node
title: Batch Process Edge Node

sidebar_position: 5
---

## Abstract
In edge scenarios, the node scale is often very large. The management process of a single node can no longer efficiently cope with such large-scale scenarios. How to manage large-scale nodes is becoming more and more important. This document will teach you how to use keadm to manage and maintain edge nodes on a large scale.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The phrasing in the abstract could be improved for clarity and conciseness. The current wording is a bit verbose, and using "teach you" is informal for technical documentation.

Suggested change
In edge scenarios, the node scale is often very large. The management process of a single node can no longer efficiently cope with such large-scale scenarios. How to manage large-scale nodes is becoming more and more important. This document will teach you how to use keadm to manage and maintain edge nodes on a large scale.
In edge scenarios, the node scale is often very large. Managing individual nodes is inefficient in such large-scale scenarios, making bulk node management crucial. This document explains how to use keadm to manage and maintain edge nodes on a large scale.


Please refer to the detailed design: [batch node proposal](https://github.com/kubeedge/kubeedge/blob/master/docs/proposals/batch-node-process.md)

## Getting Started

This case will guide you how to use the batch node join and reset capabilities, and introduce custom scripts using the `pre-run` and `post-run` parameters.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The phrasing here could be more direct and professional. "This case will guide you" is a bit informal.

Suggested change
This case will guide you how to use the batch node join and reset capabilities, and introduce custom scripts using the `pre-run` and `post-run` parameters.
This guide demonstrates how to use the batch node join and reset capabilities, and introduces custom scripts using the `pre-run` and `post-run` parameters.


**Pre-run and Post-run Parameter Description**

To support custom scripts, we have introduced the optional parameters `pre-run` and `post-run` in various commands of keadm. These parameters allow users to pass in custom script files to perform some pre or post script tasks. For specific usage, refer to the subsequent use cases.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The phrase "perform some pre or post script tasks" is a bit redundant. Consider rephrasing for better clarity.

Suggested change
To support custom scripts, we have introduced the optional parameters `pre-run` and `post-run` in various commands of keadm. These parameters allow users to pass in custom script files to perform some pre or post script tasks. For specific usage, refer to the subsequent use cases.
To support custom scripts, we have introduced the optional parameters `pre-run` and `post-run` in various commands of keadm. These parameters allow users to execute custom scripts before or after the main command. For specific usage, refer to the subsequent use cases.


Usage command reference:

```shell
keadm reset --post-run=test.sh xxx
keadm join --pre-run=test.sh xxx
```

**Batch Node Join Config File**

```yaml
keadm:
download:
  enable: true
  url: https://github.com/kubeedge/kubeedge/releases/download/v1.18.1 # If this parameter is not configured, the official github repository will be used by default

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For correctness and consistency, please capitalize "GitHub".

Suggested change
  url: https://github.com/kubeedge/kubeedge/releases/download/v1.18.1 # If this parameter is not configured, the official github repository will be used by default
  url: https://github.com/kubeedge/kubeedge/releases/download/v1.18.1 # If this parameter is not configured, the official GitHub repository will be used by default

keadmVersion: v1.18.1
archGroup: # This parameter can configure one or more of amd64\arm64\arm

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The use of backslashes (\) as separators for the architecture types is unconventional and could be confusing. Using commas would be clearer for the reader.

Suggested change
archGroup: # This parameter can configure one or more of amd64\arm64\arm
archGroup: # This parameter can configure one or more of amd64, arm64, arm

  - amd64
offlinePackageDir: /tmp/kubeedge/keadm/package/amd64  # When download.enable is true, this parameter can be left unconfigured
cmdTplArgs: # This parameter is the execution command template, which can be optionally configured and used in conjunction with nodes[x].keadmCmd
  cmd: join --pre-run=./install-containerd.sh --cgroupdriver=cgroupfs --cloudcore-ipport=192.168.1.102:10000 --hub-protocol=websocket --certport=10002 --image-repository=docker.m.daocloud.io/kubeedge --kubeedge-version=v1.18.1 --remote-runtime-endpoint=unix:///run/containerd/containerd.sock
  token: xxx
nodes:
- nodeName: ubuntu1   # Unique name
  arch: amd64
  keadmCmd: '{{.cmd}} --edgenode-name=containerd-node1 --token={{.token}}' # Used in conjunction with keadm.cmdTplArgs
  copyFrom: /root/test-keadm-batchjoin  # The file directory that needs to be remotely accessed to the joining node

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The comment "The file directory that needs to be remotely accessed to the joining node" is phrased awkwardly. It could be made clearer.

Suggested change
  copyFrom: /root/test-keadm-batchjoin  # The file directory that needs to be remotely accessed to the joining node
  copyFrom: /root/test-keadm-batchjoin  # The directory on the control node containing files to be copied to the joining node

  ssh:
    ip: 192.168.1.103
    username: root
    auth:
      type: privateKey   # Log in to the node using a private key
      privateKeyAuth:
        privateKeyPath: /root/ssh/id_rsa
- nodeName: ubuntu2
  arch: amd64
  keadmCmd: join --pre-run=./install-containerd.sh --edgenode-name=containerd-node2 --cgroupdriver=cgroupfs --cloudcore-ipport=192.168.1.102:10000 --hub-protocol=websocket --certport=10002 --image-repository=docker.m.daocloud.io/kubeedge --kubeedge-version=v1.17.0 --remote-runtime-endpoint=unix:///run/containerd/containerd.sock  # Used alone
  copyFrom: /root/test-keadm-batchjoin
  ssh:
    ip: 192.168.1.104
    username: root
    auth:
      type: privateKey
      privateKeyAuth:
        privateKeyPath: /root/ssh/id_rsa
maxRunNum: 5

```

In this configuration, `--pre-run=./install-containerd.sh` is introduced in the join command, which is used to install the containerd container runtime before the node accesses. The `install-containerd.sh` file is in the directory corresponding to `nodes[x].copyFrom` and is uploaded from the `control node` to the `remote node`.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The word "accesses" is vague in this context. It would be clearer to specify that the node is joining the cluster.

Suggested change
In this configuration, `--pre-run=./install-containerd.sh` is introduced in the join command, which is used to install the containerd container runtime before the node accesses. The `install-containerd.sh` file is in the directory corresponding to `nodes[x].copyFrom` and is uploaded from the `control node` to the `remote node`.
In this configuration, `--pre-run=./install-containerd.sh` is introduced in the join command, which is used to install the containerd container runtime before the node joins the cluster. The `install-containerd.sh` file is in the directory corresponding to `nodes[x].copyFrom` and is uploaded from the `control node` to the `remote node`.


**Usage:**

Save the above file on a `control node` that can access all edge nodes. For example, the file name is `batch-join-node.yaml`, and then execute `keadm batch -c ./batch-join-node.yaml` in the directory where the file is located.

**Batch Node Reset Config File**

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

There is a trailing space in this heading. Please remove it for clean formatting.

Suggested change
**Batch Node Reset Config File**
**Batch Node Reset Config File**


```yaml
keadm:
download:
  enable: true
  url: https://github.com/kubeedge/kubeedge/releases/download/v1.18.1
keadmVersion: v1.18.1
archGroup:
  - amd64
offlinePackageDir: /tmp/kubeedge/keadm/package/amd64
nodes:
- nodeName: ubuntu1
  keadmCmd: reset edge --post-run=./uninstall-containerd.sh
  ssh:
    ip: 192.168.1.103
    username: root
    auth:
      type: password  # Log in to the node using a password
      passwordAuth:
        password: dangerous

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Using a weak password like "dangerous" as an example, even in documentation, can encourage poor security practices. It's better to use a placeholder to indicate that a user should provide their own secure password.

Suggested change
        password: dangerous
        password: <your-password>

- nodeName: ubuntu2
  keadmCmd: reset edge --post-run=./uninstall-containerd.sh
  ssh:
    ip: 192.168.1.104
    username: root
    auth:
      type: password
      passwordAuth:
        password: dangerous

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Using a weak password like "dangerous" as an example, even in documentation, can encourage poor security practices. It's better to use a placeholder to indicate that a user should provide their own secure password.

Suggested change
        password: dangerous
        password: <your-password>

maxRunNum: 5
```

In this configuration, `--post-run=./uninstall-containerd.sh` is introduced in the reset command, which is used to uninstall the containerd container runtime after the node is reset. The `uninstall-containerd.sh` file is in the directory corresponding to `nodes[x].copyFrom` and is uploaded from the `control node` to the `remote node`.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

This paragraph states that the uninstall-containerd.sh script is located in the directory specified by nodes[x].copyFrom. However, the YAML configuration example for "Batch Node Reset" above does not include the copyFrom field. This is a significant inconsistency that will confuse users.

Please either:

  1. Add the copyFrom field to the reset configuration example (if it's required for the script to be available).
  2. Correct this descriptive text to explain how the script is made available on the remote node if copyFrom is not used in the reset scenario.


**Usage:**

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

There is a trailing space in this heading. Please remove it for clean formatting.

Suggested change
**Usage:**
**Usage:**

Save the above file on a `control node` that can access all edge nodes. For example, the file name is `batch-reset-node.yaml`, and then execute `keadm batch -c ./batch-reset-node.yaml` in the directory where the file is located.

#### Video Demo
![demo](..%2F..%2Fstatic%2Fimg%2Fkeadm%2Fbatch-node-demo.gif)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The image path uses URL-encoded forward slashes (%2F). While this may render correctly, it's not standard Markdown syntax and is harder to read and maintain. Please use normal forward slashes for clarity.

Suggested change
![demo](..%2F..%2Fstatic%2Fimg%2Fkeadm%2Fbatch-node-demo.gif)
![demo](../../static/img/keadm/batch-node-demo.gif)

Binary file added static/img/keadm/batch-node-demo.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.