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

Jump to bottom

Docs: Improving the CloudCore && EdgeCore Config docs #564

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

Docs: Improving the CloudCore && EdgeCore Config docs #564

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
212 changes: 108 additions & 104 deletions docs/setup/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,57 +2,58 @@
title: CloudCore && EdgeCore Config
sidebar_position: 7
---
KubeEdge requires configuration on both [Cloud side (KubeEdge Master)](#configuration-cloud-side-kubeedge-master) and [Edge side (KubeEdge Worker Node)](#configuration-edge-side-kubeedge-worker-node)

## Configuration Cloud side (KubeEdge Master)
KubeEdge requires configuration on both [Cloud side (KubeEdge Master)](#configuration-cloud-side-kubeedge-master) and [Edge side (KubeEdge Worker Node)](#configuration-edge-side-kubeedge-worker-node).

Setting up cloud side requires two steps
## Configuring Cloud side (KubeEdge Master)

1. [Modification of the configuration files](#modification-of-the-configuration-file)
2. Edge node will be auto registered by default. [Users can still choose to register manually](#adding-the-edge-nodes-kubeedge-worker-node-on-the-cloud-side-kubeedge-master).
Setting up the cloud side involves two steps:

### Modification of the configuration file
1. [Modifying the configuration file](#modification-of-the-configuration-file)
2. Registering Edge nodes (happens automatically by default), [users can also choose to register manually](#adding-the-edge-nodes-kubeedge-worker-node-on-the-cloud-side-kubeedge-master).

Cloudcore requires changes in `cloudcore.yaml` configuration file.
### Modifying the configuration file

Create and set cloudcore config file
CloudCore requires changes in the `cloudcore.yaml` configuration file. Follow these steps to create and set up the CloudCore config file:

Create the `/etc/kubeedge/config` folder
1. Create the `/etc/kubeedge/config` folder to store the configuration file:

```shell
# the default configuration file path is '/etc/kubeedge/config/cloudcore.yaml'
# also you can specify it anywhere with '--config'
mkdir -p /etc/kubeedge/config/
```

Either create a minimal configuration with command `~/kubeedge/cloudcore --minconfig`
2. You have two options for creating the configuration file:

```shell
~/kubeedge/cloudcore --minconfig > /etc/kubeedge/config/cloudcore.yaml
```
- Either create a minimal configuration file using the `~/kubeedge/cloudcore --minconfig` command:

or a full configuration with command `~/kubeedge/cloudcore --defaultconfig`
```shell
~/kubeedge/cloudcore --minconfig > /etc/kubeedge/config/cloudcore.yaml
```

```shell
~/kubeedge/cloudcore --defaultconfig > /etc/kubeedge/config/cloudcore.yaml
```
- or create a full configuration file using the `~/kubeedge/cloudcore --defaultconfig` command:

Edit the configuration file
```shell
~/kubeedge/cloudcore --defaultconfig > /etc/kubeedge/config/cloudcore.yaml
```

```shell
vim /etc/kubeedge/config/cloudcore.yaml
```
3. Edit the configuration file:

Verify the configurations before running `cloudcore`
```shell
vim /etc/kubeedge/config/cloudcore.yaml
```

#### Modification in cloudcore.yaml
4. Ensure all configurations are correct before running `cloudcore`.

In the cloudcore.yaml, modify the below settings.
#### Modifying cloudcore.yaml

1. Either `kubeAPIConfig.kubeConfig` or `kubeAPIConfig.master` : This would be the path to your kubeconfig file. It might be either
In the cloudcore.yaml, modify the following settings:

1. Configure either `kubeAPIConfig.kubeConfig` or `kubeAPIConfig.master` to specify the path to your kubeconfig file. The path might be either:

```shell
/root/.kube/config
/root/.kube/config
```

or
Expand All @@ -61,20 +62,20 @@ In the cloudcore.yaml, modify the below settings.
/home/<your_username>/.kube/config
```

depending on where you have setup your kubernetes by performing the below step:
depending on where you have set up your Kubernetes cluster. To generate the kubeconfig file, run the following commands:

```shell
To start using your cluster, you need to run the following as a regular user:
# To start using your cluster, you need to run the following as a regular user:

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
```

By default, cloudcore use https connection to Kubernetes apiserver. If `master` and `kubeConfig` are both set, `master` will override any value in kubeconfig.
By default, CloudCore uses an HTTPS connection to Kubernetes API server. If both `master` and `kubeConfig` are set, the value in `master` will override the one in kubeConfig.


2. Configure all the IP addresses of CloudCore which are exposed to the edge nodes(like floating IP) in the `advertiseAddress`, which will be add to SANs in cert of cloudcore.
2. Configure all the IP addresses of CloudCore that are exposed to the edge nodes (e.g., floating IP) in the `advertiseAddress` field. These IP addresses will be added to the SANs in the CloudCore cert.

```yaml
modules:
Expand All @@ -83,113 +84,117 @@ In the cloudcore.yaml, modify the below settings.
- 10.1.11.85
```

### Adding the edge nodes (KubeEdge Worker Node) on the Cloud side (KubeEdge Master)
### Registering the Edge nodes (KubeEdge Worker Node) on the Cloud side (KubeEdge Master)

Node registration can be completed in two ways:
Edge nodes can be registered with the KubeEdge Master using one of the following ways:

1. Node - Automatic Registration
2. Node - Manual Registration
1. Automatic Registration
2. Manual Registration

#### Node - Automatic Registration
#### 1. Automatic Registration

Edge node can be registered automatically if the value of field `modules.edged.registerNode` in edgecore's [config](#create-and-set-edgecore-config-file) is set to true.
Edge nodes can be automatically registered if the `modules.edged.registerNode` field in [edgecore's config](#create-and-set-edgecore-config-file) is set to true:

```yaml
modules:
edged:
registerNode: true
```

#### Node - Manual Registration
#### 2. Manual Registration

##### Copy `$GOPATH/src/github.com/kubeedge/kubeedge/build/node.json` to your working directory and change `metadata.name` to the name of edge node
To manually register an edge node, follow the given steps:

```shell
mkdir -p ~/kubeedge/yaml
cp $GOPATH/src/github.com/kubeedge/kubeedge/build/node.json ~/kubeedge/yaml
```
- **Copy the `$GOPATH/src/github.com/kubeedge/kubeedge/build/node.json` file to your working directory:**

```shell
mkdir -p ~/kubeedge/yaml
cp $GOPATH/src/github.com/kubeedge/kubeedge/build/node.json ~/kubeedge/yaml
```

Node.json
- **Modify the `metadata.name` field in the node.json file to the name of the edge node:**

```json
{
"kind": "Node",
"apiVersion": "v1",
"metadata": {
"name": "edge-node",
"labels": {
```json
{
"kind": "Node",
"apiVersion": "v1",
"metadata": {
"name": "edge-node",
"node-role.kubernetes.io/edge": ""
"labels": {
"name": "edge-node",
"node-role.kubernetes.io/edge": ""
}
}
}
}
```
```

**Note:**
1. the `metadata.name` must keep in line with edgecore's config `modules.edged.hostnameOverride`.
:::note

2. Make sure role is set to edge for the node. For this a key of the form `"node-role.kubernetes.io/edge"` must be present in `metadata.labels`.
If role is not set for the node, the pods, configmaps and secrets created/updated in the cloud cannot be synced with the node they are targeted for.
- The `metadata.name` field must match the `modules.edged.hostnameOverride` in the edgecore config.

##### Deploy edge node (**you must run the command on cloud side**)
- Make sure role is set to edge for the node. For this a key of the form `"node-role.kubernetes.io/edge"` must be present in `metadata.labels`. If this role is not set for the node, the pods, configmaps and secrets created/updated in the cloud cannot be synced with the targeted edge node.
:::

```shell
kubectl apply -f ~/kubeedge/yaml/node.json
```
- **To deploy edge node, run the command on the cloud side:**

```shell
kubectl apply -f ~/kubeedge/yaml/node.json
```

## Configuration Edge side (KubeEdge Worker Node)

### Create and set edgecore config file

Create the `/etc/kubeedge/config` folder
EdgeCore requires changes in the `edgecore.yaml` configuration file. Follow these steps to create and set up the EdgeCore config file:

```shell
# the default configration file path is '/etc/kubeedge/config/edgecore.yaml'
# also you can specify it anywhere with '--config'
mkdir -p /etc/kubeedge/config/
```
1. Create the `/etc/kubeedge/config` folder to store the configuration file:

```shell
# the default configration file path is '/etc/kubeedge/config/edgecore.yaml'
# also you can specify it anywhere with '--config'
mkdir -p /etc/kubeedge/config/
```
2. You have two options for creating the configuration file:

Either create a minimal configuration with command `~/kubeedge/edgecore --minconfig`
- Either create a minimal configuration file using the `~/kubeedge/edgecore --minconfig` command:

```shell
```shell
~/kubeedge/edgecore --minconfig > /etc/kubeedge/config/edgecore.yaml
```
```

or a full configuration with command `~/kubeedge/edgecore --defaultconfig`
- or create a full configuration file using the `~/kubeedge/edgecore --defaultconfig` command:

```shell
~/kubeedge/edgecore --defaultconfig > /etc/kubeedge/config/edgecore.yaml
```
```shell
~/kubeedge/edgecore --defaultconfig > /etc/kubeedge/config/edgecore.yaml
```

Edit the configuration file
3. Edit the configuration file:

```shell
vim /etc/kubeedge/config/edgecore.yaml
```
```shell
vim /etc/kubeedge/config/edgecore.yaml
```

Verify the configurations before running `edgecore`
4. Ensure all configurations are correct before running `edgecore`.

#### Modification in edgecore.yaml

1. Check `modules.edged.podSandboxImage` : This is very important and must be set correctly.

To check the architecture of your machine run the following
1. Check `modules.edged.podSandboxImage`, This setting is critical and must be configured correctly. To check the architecture of your machine, run the following command:

```shell
getconf LONG_BIT
```

+ `kubeedge/pause-arm:3.1` for arm arch
+ `kubeedge/pause-arm64:3.1` for arm64 arch
+ `kubeedge/pause:3.1` for x86 arch
+ Use `kubeedge/pause-arm:3.1` for arm arch
+ Use `kubeedge/pause-arm64:3.1` for arm64 arch
+ Use `kubeedge/pause:3.1` for x86 arch

2. Before KubeEdge v1.3: check whether the cert files for `modules.edgehub.tlsCaFile` and `modules.edgehub.tlsCertFile` and `modules.edgehub.tlsPrivateKeyFile` exists. If those files not exist, you need to copy them from cloud side.
2. **For KubeEdge versions before v1.3:** Verify that the cert files specified for `modules.edgehub.tlsCaFile`, `modules.edgehub.tlsCertFile`, and `modules.edgehub.tlsPrivateKeyFile` exist. If these files do not exist, you need to copy them from the cloud side.File` and `modules.edgehub.tlsPrivateKeyFile` exists. If those files not exist, you need to copy them from cloud side.

From KubeEdge v1.3: just skip above check about cert files. However, if you configure the edgecore certificate manually, you must check if the path of certificate is right.
**From KubeEdge v1.3 onwards:** You can skip the above check for cert files. However, if you configure the edgecore certificate manually, ensure that the certificat path is correct.

3. Update the IP address and port of the KubeEdge CloudCore in the `modules.edgehub.websocket.server` and `modules.edgehub.quic.server` field. You need set cloudcore ip address.
3. Update the IP address and port of the KubeEdge CloudCore in the `modules.edgehub.websocket.server` and `modules.edgehub.quic.server` fields. Set the CloudCore IP address accordingly.

4. Configure the desired container runtime to be used as either docker or remote (for all CRI based runtimes including containerd). If this parameter is not specified docker runtime will be used by default
4. Configure the desired container runtime to be used as either Docker or remote (for all CRI-based runtimes, including containerd). If this parameter is not specified, the Docker runtime will be used by default.

```yaml
runtimeType: docker
Expand All @@ -201,27 +206,25 @@ Verify the configurations before running `edgecore`
runtimeType: remote
```

5. If your runtime-type is remote, follow this guide [KubeEdge CRI Configuration](../setup/prerequisites/runtime.md) to setup KubeEdge with the remote/CRI based runtimes.

5. If your runtime-type is remote, follow the [KubeEdge CRI Configuration](../setup/prerequisites/runtime.md) guide to set up KubeEdge with the remote/CRI-based runtimes.

**Note:** If your KubeEdge version is before v1.3, you can skip steps 6-7.

**Note:** If your KubeEdge version is before the v1.3, then just skip the steps 6-7.

6. Configure the IP address and port of the KubeEdge cloudcore in the `modules.edgehub.httpServer` which is used to apply for the certificate. For example:
6. Configure the IP address and port of the KubeEdge CloudCore in `modules.edgehub.httpServer`, which is used to apply for the certificate. For example:

```yaml
modules:
edgeHub:
httpServer: https://10.1.11.85:10002
```

7. Configure the token.
7. Configure the token:

```shell
kubectl get secret tokensecret -n kubeedge -oyaml
```

Then you get it like this:
You will get an output similar to the following:

```yaml
apiVersion: v1
Expand All @@ -238,15 +241,15 @@ Verify the configurations before running `edgecore`
type: Opaque
```

Decode the tokendata field by base64:
Decode the tokendata field using base64:

```shell
echo ODEzNTZjY2MwODIzMmIxMTU0Y2ExYmI5MmRlZjY4YWQwMGQ3ZDcwOTIzYmU3YjcyZWZmOTVlMTdiZTk5MzdkNS5leUpoYkdjaU9pSklVekkxTmlJc0luUjVjQ0k2SWtwWFZDSjkuZXlKbGVIQWlPakUxT0RreE5qRTVPRGw5LmpxNENXNk1WNHlUVkpVOWdBUzFqNkRCdE5qeVhQT3gxOHF5RnFfOWQ4WFkK |base64 -d
# then we get:
81356ccc08232b1154ca1bb92def68ad00d7d70923be7b72eff95e17be9937d5.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1ODkxNjE5ODl9.jq4CW6MV4yTVJU9gAS1j6DBtNjyXPOx18qyFq_9d8XY
```

Copy the decoded string to the edgecore.yaml just like follow:
Copy the decoded string to the edgecore.yaml file as follows:

```yaml
modules:
Expand All @@ -256,11 +259,12 @@ Verify the configurations before running `edgecore`

#### Configuring MQTT mode

The Edge part of KubeEdge uses MQTT for communication between deviceTwin and devices. KubeEdge supports 3 MQTT modes (`internalMqttMode`, `bothMqttMode`, `externalMqttMode`), set `mqttMode` field in edgecore.yaml to the desired mode.
+ internalMqttMode: internal mqtt broker is enabled (`mqttMode`=0).
+ bothMqttMode: internal as well as external broker are enabled (`mqttMode`=1).
+ externalMqttMode: only external broker is enabled (`mqttMode`=2).
The Edge part of KubeEdge uses MQTT for communication between deviceTwin and devices. KubeEdge supports 3 MQTT modes (`internalMqttMode`, `bothMqttMode`, `externalMqttMode`). Set the `mqttMode` field in edgecore.yaml to the desired mode:

+ **internalMqttMode:** Internal MQTT broker is enabled (`mqttMode`=0).
+ **bothMqttMode:** Both internal and external brokers are enabled (`mqttMode`=1).
+ **externalMqttMode:** Only external broker is enabled (`mqttMode`=2).

To use KubeEdge in double mqtt or external mode, you need to make sure that mosquitto or emqx edge is installed on the edge node as an MQTT Broker.
To use KubeEdge in double MQTT or external mode, ensure that mosquitto or emqx edge is installed on the edge node as an MQTT Broker.

At this point we have completed all configuration changes related to edgecore.
At this point, we have completed all configuration changes related to edgecore.