Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

optimize docs install-with-keadm #581

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

optimize docs install-with-keadm #581

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
28 changes: 18 additions & 10 deletions docs/setup/install-with-keadm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,12 @@ Keadm is used to install the cloud and edge components of KubeEdge. It does not

Please refer to [Kubernetes compatibility](https://github.com/kubeedge/kubeedge#kubernetes-compatibility) documentation to check **Kubernetes compatibility** and ascertain the Kubernetes version to be installed.

:::tip
According to the compatibility rules of keadm, keadm only supports the installation of the same version and the immediately preceding version of KubeEdge. For example, keadm v1.17 is only compatible with KubeEdge versions v1.16 and v1.17.

It is recommended to ensure that the `keadm` version is consistent with the version of kubeedge you are planning to install.
:::

## Prerequisite

- It Requires super user rights (or root rights) to run.
Expand Down Expand Up @@ -37,6 +43,8 @@ There're three ways to download the `keadm` binary:

## Setup Cloud Side (KubeEdge Master Node)

### keadm init

By default, ports `10000` and `10002` on your CloudCore needs to be accessible for your edge nodes.

**IMPORTANT NOTES:**
Expand All @@ -47,14 +55,12 @@ By default, ports `10000` and `10002` on your CloudCore needs to be accessible f

3. `--advertise-address` is the address exposed by the cloud side (it will be added to the SANs of the CloudCore certificate). The default value is the local IP.

### keadm init

`keadm init` provides a solution for integrating the CloudCore Helm chart. CloudCore will be deployed to cloud nodes in container mode.
4. `keadm init` provides a solution for integrating the CloudCore Helm chart. CloudCore will be deployed to cloud nodes in container mode.

Example:

```shell
keadm init --advertise-address="THE-EXPOSED-IP" --profile version=v1.12.1 --kube-config=/root/.kube/config
keadm init --advertise-address="THE-EXPOSED-IP" --kubeedge-version=v1.17.0 --kube-config=/root/.kube/config
```

Output:
Expand Down Expand Up @@ -89,11 +95,11 @@ replicaset.apps/cloudcore-56b8454784 1 1 1 46s

**IMPORTANT NOTES:**

1. Set flags `--set key=value` for CloudCore helm chart could refer to [KubeEdge CloudCore Helm Charts README.md](https://github.com/kubeedge/kubeedge/blob/master/manifests/charts/cloudcore/README.md).
1. Use `keadm init -h` to get the explains of parameters and usage instructions.

2. You can start with one of Keadm’s built-in configuration profiles and then further customize the configuration for your specific needs. Currently, the built-in configuration profile keyword is `version`. Refer to [version.yaml](https://github.com/kubeedge/kubeedge/blob/master/manifests/profiles/version.yaml) as `values.yaml`, you can make your custom values file here, and add flags like `--profile version=v1.9.0 --set key=value` to use this profile. `--external-helm-root` flag provides a feature function to install the external helm charts like edgemesh.
2. Set flags `--set key=value` for CloudCore helm chart could refer to [KubeEdge CloudCore Helm Charts README.md](https://github.com/kubeedge/kubeedge/blob/master/manifests/charts/cloudcore/README.md).

3. `keadm init` by default, deploys CloudCore in container mode. If you want to deploy CloudCore as a binary, please refer to [`keadm deprecated init`](#keadm-deprecated-init).
3. You can start with one of Keadm’s built-in configuration profiles and then further customize the configuration for your specific needs. Currently, the built-in configuration profile keyword is `version`. Refer to [version.yaml](https://github.com/kubeedge/kubeedge/blob/master/manifests/profiles/version.yaml) as `values.yaml`, you can make your custom values file here, and add flags like `--profile version=v1.9.0 --set key=value` to use this profile. `--external-helm-root` flag provides a feature function to install the external helm charts like edgemesh.

Example:

Expand All @@ -116,7 +122,7 @@ keadm manifest generate --advertise-address="THE-EXPOSED-IP" --kube-config=/root

> Add `--skip-crds` flag to skip outputting the CRDs.

### keadm deprecated init
### keadm deprecated init (deprecated)

`keadm deprecated init` installs CloudCore in binary process, generates certificates, and installs the CRDs. It also provides a flag to set a specific version.

Expand Down Expand Up @@ -169,7 +175,7 @@ Run `keadm gettoken` on the **cloud side** to retrieve the token, which will be
Example:

```shell
keadm join --cloudcore-ipport="THE-EXPOSED-IP":10000 --token=27a37ef16159f7d3be8fae95d588b79b3adaaf92727b72659eb89758c66ffda2.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTAyMTYwNzd9.JBj8LLYWXwbbvHKffJBpPd5CyxqapRQYDIXtFZErgYE --kubeedge-version=v1.12.1
keadm join --cloudcore-ipport="THE-EXPOSED-IP":10000 --token=27a37ef16159f7d3be8fae95d588b79b3adaaf92727b72659eb89758c66ffda2.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTAyMTYwNzd9.JBj8LLYWXwbbvHKffJBpPd5CyxqapRQYDIXtFZErgYE --kubeedge-version=v1.17.0
```

**IMPORTANT NOTES:**
Expand All @@ -180,6 +186,8 @@ keadm join --cloudcore-ipport="THE-EXPOSED-IP":10000 --token=27a37ef16159f7d3be8

3. The KubeEdge version used on the cloud and edge sides should be the same.

4. Please ref to [runtime configuration](./prerequisites/runtime.md) to get how to configure edge runtime.

Output:

```shell
Expand All @@ -200,7 +208,7 @@ You can run the `systemctl status edgecore` command to ensure EdgeCore is runnin
└─2745865 /usr/local/bin/edgecore
```

#### keadm deprecated join
#### keadm deprecated join (deprecated)

You can also use `keadm deprecated join` to start EdgeCore from the release pacakge. It will download release packages from [KubeEdge release website](https://github.com/kubeedge/kubeedge/releases), and then start `edgecore` in binary progress.

Expand Down
120 changes: 68 additions & 52 deletions i18n/zh/docusaurus-plugin-content-docs/current/setup/install-with-keadm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,65 +9,98 @@ Keadm 不负责 K8s 的安装和运行,在使用它之前，请先准备好一
KubeEdge 对 Kubernetes 的版本兼容性，更多详细信息您可以参考 [kubernetes-兼容性](https://github.com/kubeedge/kubeedge#kubernetes-compatibility)
来了解，以此来确定安装哪个版本的 Kubernetes 以及 KubeEdge。

:::tip
根据keadm的兼容性规则，keadm仅支持安装同版本或前一个版本的KubeEdge，例如，v1.17的keadm仅兼容v1.16和v1.17的KubeEdge。

请尽可能保证keadm与要安装的KubeEdge版本一致。
:::

## 使用限制

- `keadm` 目前支持 Ubuntu 和 CentOS OS。RaspberryPi 的支持正在进行中。
- 需要超级用户权限（或 root 权限）才能运行。
- `keadm beta`功能在 v1.10.0 上线，如果您需要使用相关功能，请使用 v1.10.0 及以上版本的 keadm。

## 安装keadm

有三种方式安装keadm

1. 从社区发布的[版本二进制包](https://github.com/kubeedge/kubeedge/releases)中下载

请根据自己的需求选择对应的架构与版本


```shell
wget https://github.com/kubeedge/kubeedge/releases/download/v1.17.0/keadm-v1.17.0-linux-amd64.tar.gz
tar -zxvf keadm-v1.17.0-linux-amd64.tar.gz
cp keadm-1.17.0-linux-amd64/keadm/keadm /usr/local/bin/keadm
```

2. 下载KubeEdge官方镜像

```shell
docker run --rm kubeedge/installation-package:v1.17.0 cat /usr/local/bin/keadm > /usr/local/bin/keadm && chmod +x /usr/local/bin/keadm
```

3. 下载源代码并编译


## 设置云端（KubeEdge 主节点）

### keadm init

默认情况下边缘节点需要访问 cloudcore 中 `10000` ，`10002` 端口。
默认情况下边缘节点需要访问 CloudCore 中 `10000` ，`10002` 端口。
若要确保边缘节点可以成功地与集群通信，您需要创建防火墙规则以允许流量进入这些端口（10000 至 10004）。

> `keadm init` 将安装并运行 cloudcore，生成证书并安装 CRD。它还提供了一个命令行参数，通过它可以设置特定的版本。不过需要注意的是：\
> 在 v1.11.0 之前，`keadm init` 将以进程方式安装并运行 cloudcore，生成证书并安装 CRD。它还提供了一个命令行参数，通过它可以设置特定的版本。\
> 在 v1.11.0 之后，`keadm init` 集成了 Helm Chart，这意味着 cloudcore 将以容器化的方式运行。\
> 如果您仍需要使用进程的方式启动 cloudcore ，您可以使用`keadm deprecated init` 进行安装，或者使用 v1.10.0 之前的版本。
`keadm init` 将安装并运行 CloudCore，生成证书并安装 CRD。它还提供了一个命令行参数，通过它可以设置特定的版本。

**重要提示：**

1. 必须正确配置 kubeconfig 或 master 中的至少一个，以便可以将其用于验证 k8s 集群的版本和其他信息。
2. 请确保边缘节点可以使用云节点的本地 IP 连接云节点，或者需要使用 `--advertise-address` 标记指定云节点的公共 IP 。
3. `--advertise-address`（仅从 1.3 版本开始可用）是云端公开的地址（将添加到 CloudCore 证书的 SAN 中），默认值为本地 IP。
4. `keadm init` 将会使用二进制方式部署 cloudcore 为一个系统服务，如果您想实现容器化部署，可以参考 `keadm beta init` 。
4. 从v1.11.0开始，`keadm init` 集成了 Helm Chart，这意味着 CloudCore 将以容器化的方式运行。如果您仍需要使用进程的方式启动 cloudcore ，您可以使用`keadm deprecated init` 进行安装。


举个例子：
举例：

```shell
# keadm init --advertise-address="THE-EXPOSED-IP"(only work since 1.3 release)
# keadm init --advertise-address="THE-EXPOSED-IP" --kubeedge-version=v1.9.0 --kube-config=/root/.kube/config
```

输出：

```
```shell
Kubernetes version verification passed, KubeEdge installation will start...
...
KubeEdge cloudcore is running, For logs visit: /var/log/kubeedge/cloudcore.log
CLOUDCORE started
=========CHART DETAILS=======
NAME: cloudcore
LAST DEPLOYED: Wed Oct 26 11:10:04 2022
NAMESPACE: kubeedge
STATUS: deployed
REVISION: 1
```

当您看到以上信息，说明 KubeEdge 的云端组件 cloudcore 已经成功运行。
当您看到以上信息，说明 KubeEdge 的云端组件 CloudCore 已经安装完成。 您可以执行`kubectl get all -n kubeedge`来检查CloudCore是否正常运行：

### keadm beta init
```shell
# kubectl get all -n kubeedge
NAME READY STATUS RESTARTS AGE
pod/cloudcore-56b8454784-ngmm8 1/1 Running 0 46s

如果您想要使用容器化方式部署云端组件 cloudcore ，您可以使用 `keadm beta init` 进行云端组件安装。
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/cloudcore ClusterIP 10.96.96.56 <none> 10000/TCP,10001/TCP,10002/TCP,10003/TCP,10004/TCP 46s

> keadm beta 功能在 v1.10.0 上线，如果您想要使用 `keadm beta init` 部署云端组件，请使用 v1.10.0 及以上版本的 keadm 进行安装。\
> 在 v1.11.0 版本之后，keadm init 将直接使用容器化方式部署云端组件 cloudcore。
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/cloudcore 1/1 1 1 46s

举个例子:

```shell
# keadm beta init --advertise-address="THE-EXPOSED-IP" --set cloudcore-tag=v1.9.0 --kube-config=/root/.kube/config
NAME DESIRED CURRENT READY AGE
replicaset.apps/cloudcore-56b8454784 1 1 1 46s
```

**重要提示：**

1. 自定义 `--set key=value`
值可以参考 [KubeEdge Cloudcore Helm Charts README.md](https://github.com/kubeedge/kubeedge/blob/master/build/helm/charts/cloudcore/README.md)
2. 您可以从 Keadm 的一个内置配置概要文件开始，然后根据您的特定需求进一步定制配置。目前，内置的配置概要文件关键字是 `version`
1. 您可以使用`keadm init -h`了解每个参数的意义与使用方法
2. 自定义 `--set key=value`值可以参考 [KubeEdge Cloudcore Helm Charts README.md](https://github.com/kubeedge/kubeedge/blob/master/build/helm/charts/cloudcore/README.md)
3. 您可以从 Keadm 的一个内置配置概要文件开始，然后根据您的特定需求进一步定制配置。目前，内置的配置概要文件关键字是 `version`
。请参考 [`version.yaml`](https://github.com/kubeedge/kubeedge/blob/master/manifests/profiles/version.yaml)
，您可以在这里创建您的自定义配置文件, 使用 `--profile version=v1.9.0 --set key=value` 来使用它。

Expand All @@ -82,17 +115,17 @@ KubeEdge cloudcore is running, For logs visit: /var/log/kubeedge/cloudcore.log
如果您对 Helm Chart 比较熟悉，可以直接参考 [KubeEdge Helm Charts](https://github.com/kubeedge/kubeedge/tree/master/keadm/cmd/keadm/app/cmd/helm)
进行安装。

### keadm beta manifest generate
### keadm manifest generate

`keadm beta manifest generate` 可以帮助我们快速渲染生成期望的 manifests 文件，并输出在终端显示。
`keadm manifest generate` 可以帮助我们快速渲染生成期望的 manifests 文件，并输出在终端显示。

Example:

```shell
# keadm beta manifest generate --advertise-address="THE-EXPOSED-IP" --kube-config=/root/.kube/config > kubeedge-cloudcore.yaml
# keadm manifest generate --advertise-address="THE-EXPOSED-IP" --kube-config=/root/.kube/config > kubeedge-cloudcore.yaml
```

> 使用 --skip-crds 跳过打印 CRDs
> 使用 --skip-crds 可以跳过打印 CRDs

## 设置边缘端（KubeEdge 工作节点）

Expand All @@ -109,46 +142,29 @@ Example:

#### keadm join

`keadm join` 将安装 edgecore 和 mqtt。它还提供了一个命令行参数，通过它可以设置特定的版本。

举个例子：

```shell
# keadm join --cloudcore-ipport=192.168.20.50:10000 --token=27a37ef16159f7d3be8fae95d588b79b3adaaf92727b72659eb89758c66ffda2.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTAyMTYwNzd9.JBj8LLYWXwbbvHKffJBpPd5CyxqapRQYDIXtFZErgYE
```

#### keadm beta join

现在可以使用 `keadm beta join` 通过镜像下载所需资源，进行节点接入。

##### Docker

```shell
# keadm beta join --cloudcore-ipport=192.168.20.50:10000 --token=27a37ef16159f7d3be8fae95d588b79b3adaaf92727b72659eb89758c66ffda2.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTAyMTYwNzd9.JBj8LLYWXwbbvHKffJBpPd5CyxqapRQYDIXtFZErgYE
```
执行`keadm join` 会下载边缘镜像`kubeedge/installation-package`，安装EdgeCore， EdgeCore会以system service形式启动。

##### CRI
举例：

```shell
# keadm beta join --cloudcore-ipport=192.168.20.50:10000 --runtimetype remote --remote-runtime-endpoint unix:///run/containerd/containerd.sock --token=27a37ef16159f7d3be8fae95d588b79b3adaaf92727b72659eb89758c66ffda2.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTAyMTYwNzd9.JBj8LLYWXwbbvHKffJBpPd5CyxqapRQYDIXtFZErgYE
# keadm join --cloudcore-ipport=192.168.20.50:10000 --token=27a37ef16159f7d3be8fae95d588b79b3adaaf92727b72659eb89758c66ffda2.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTAyMTYwNzd9.JBj8LLYWXwbbvHKffJBpPd5CyxqapRQYDIXtFZErgYE --kubeedge-version=v1.17.0
```

**重要提示：**

1. `--cloudcore-ipport` 是必填参数。
2. 加上 `--token` 会自动为边缘节点生成证书，如果您需要的话。
2. 加上 `--token` 会自动为边缘节点生成证书。
3. 需要保证云和边缘端使用的 KubeEdge 版本相同。
4. 加上 `--with-mqtt` 会自动为边缘节点以容器运行的方式部署 `mosquitto` 服务
4. 边缘运行时的配置请参考[runtime配置](./prerequisites/runtime.md)

输出：

```shell
Host has mosquit+ already installed and running. Hence skipping the installation steps !!!
...
KubeEdge edgecore is running, For logs visit: /var/log/kubeedge/edgecore.log
```

> 也可以使用 `keadm beta join` 来添加边缘节点。
您可以在云端执行`kubectl get node`查看边缘节点是否成功接入云端，如果没有对应边缘节点或者节点状态是`NotReady`，您可以在边缘节点上执行`journalctl -f -u edgecore.service`查看EdgeCore日志。

### 启用 `kubectl logs` 功能

Expand Down