Skip to content

Commit

Permalink
update for en doc
Browse files Browse the repository at this point in the history
  • Loading branch information
chongyuanyin committed Jul 11, 2024
1 parent 1d5dce0 commit 2f416ef
Show file tree
Hide file tree
Showing 26 changed files with 161 additions and 258 deletions.
2 changes: 1 addition & 1 deletion ecp/directory.json
Original file line number Diff line number Diff line change
Expand Up @@ -326,7 +326,7 @@
},
{
"title": "Monitor EMQX Clusters",
"path": "https://docs.emqx.com/en/enterprise/v4.4/getting-started/dashboard-ee.html#monitor"
"path": "monitor/monitor_cluster"
},
{
"title": "Monitor Edge Services",
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added ecp/en_US/cluster/_assets/cluster-delete.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified ecp/en_US/cluster/_assets/cluster-detail.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified ecp/en_US/cluster/_assets/cluster-list.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified ecp/en_US/cluster/_assets/cluster-log.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified ecp/en_US/cluster/_assets/cluster-ops.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
116 changes: 20 additions & 96 deletions ecp/en_US/cluster/add_manage.md
Original file line number Diff line number Diff line change
@@ -1,76 +1,26 @@
# Add EMQX Clusters

ECP supports adding clusters by creating (recommended) or adding existing EMQX clusters. It is recommended to add clusters by creating with ECP, which offers more extensive functionality and allows for license and connection quota sharing.

There are functional differences between creating (**Hosted Clusters**) and managing clusters (**Managed Clusters**) on the ECP platform, as shown in the table below.

|Function|Hosted Clusters|Managed Clusters|
|:--------:|:----:|:----:|
|Start/Stop|||
|Horizontal Scaling|||
|Vertical Scaling|||
|Update Network Type|||
|Update Connection Limit|||
|Upgrade/Downgrade|||
|Cluster Transfer|||
|Delete|||
|Log|||

## Create a Hosted Cluster

1. Log in to the ECP platform as a system admin, organization admin, or project admin. In **Workspace - Cluster** page, click **Add Cluster**.
2. For **Cluster Type**, keep the default setting, **New Cluster**.
3. Provide a name for the cluster in the **Cluster Name** field. The name should be between 1-200 characters long and can include "\_" and blank spaces.
4. Specify the maximum connection limit for the cluster in the **Connect Limit** field. Note that the limit is subject to the license quota and [EMQX Cluster Quota](../system_admin/resource_config.md#configure-emqx-cluster-quota).
5. Select the appropriate cluster specification based on your business requirements in the **Specification** section. For details on cluster specification, see [EMQX Cluster Quota](../system_admin/resource_config.md#configure-emqx-cluster-quota).
6. Set the desired number of EMQX nodes for the cluster in the **Replicas** field. A maximum of 7 nodes can be configured for a single cluster.
7. Specify the EMQX cluster version to be hosted by setting the **EMQX Image**.
8. Click **Confirm** to finish the creation process.

![cluster-new](./_assets/cluster-new.png)

The newly-created clusters will be listed in the **Cluster List** panel with the status **Creating**. Wait till the status changes to **Running**, indicating the cluster is ready for production use.

<img src="./_assets/cluster-running.png" alt="cluster-running" style="zoom:50%;" />
ECP supports adding existing EMQX clusters. ECP supports management for EMQX v4 Enterprise Edition (4.4.6 and above) and EMQX v5 Enterprise Edition (5.6.0 and above).

## Add an Existing Cluster

ECP also provides the capability to manage existing EMQX clusters. ECP supports the management of EMQX v4 (version 4.4.6 and above) and EMQX v5 (version 5.6.0 and above).
1. Log in to the ECP platform as a system admin, organization admin, or project admin. In **Workspace - Data Integration - Data Access** page, click **Add Cluster**.

### EMQX V4 Managed Cluster
2. Provide a name for the cluster in the **Cluster Name** field. The name should be between 1-200 characters long and can include "\_" and blank spaces.

1. Log in to the ECP platform as a system admin, organization admin, or project admin. In **Workspace - Cluster** page, click **Add Cluster**.
3. If you try to add an EMQX v5 cluster, fill in the **Cluster Address** (i.e. EMQX dashboard access address). You can also input the **Cluster Address** later by **Edit** operation.

2. Click to select **Existing Cluster** under **Cluster Type**.
4. Click **Confirm** to finish the adding process. The newly-created clusters will be listed in the **Cluster List** panel with the status **Created**.

3. Select **v4** under **Cluster Version**.

4. Provide a name for the cluster in the **Cluster Name** field. The name should be between 1-200 characters long and can include "\_" and blank spaces.

5. Click **Confirm** to finish the adding process. The newly-created clusters will be listed in the **Cluster List** panel with the status **Created**.

6. Click **Register Node** and a cluster registration guide page will pop up.
5. Click **Register Node** and follow the instructions on the cluster registration guide page to register the cluster node.

<img src="./_assets/cluster-existing-init.png" alt="cluster-running" style="zoom:50%;" />

7. Select the CPU architecture in the **CPU Architecture** field, amd64, arm, and arm64 are supported. Follow the steps on this page to finish adding the existing cluster.
6. Select the CPU architecture in the **CPU Architecture** field, amd64, arm, and arm64 are supported. Follow the steps on this page to finish adding the existing cluster.

<img src="./_assets/cluster-existing-reg.png" style="zoom: 50%;" align="middle">

8. Log in to the virtual machine or container environment hosting the EMQX cluster, such as the container named `emqx-69f4249c-emax-ee-0` in the namespace `emqx-69f4249c`.

```bash
# Check the Pod name
$ kubectl -n emqx-69f4249c get pod

NAME READY STATUS RESTARTS AGE
emqx-69f4249c-emax-ee-0 3/3 Running 0 28d

# Enter the Pod
$ kubectl -n emqx-69f4249c exec -it emqx-69f4249c-emqx-ee-0 -c emqx -- sh
```

8. Execute the commands provided on the registration guide page in sequential order.
7. Log in to the virtual machine hosting the EMQX cluster, execute the commands provided on the registration guide page in sequential order.

```bash
# Download EMQX Agent
Expand All @@ -86,53 +36,27 @@ ECP also provides the capability to manage existing EMQX clusters. ECP supports
sudo /usr/local/bin/emqxee-agent register --url https://[emqxee-agent] --registration-token bf2779e5176446cd8e18fde81d826497
```

9. Upon returning to the **ECP Workbench - Cluster** page, you will find that the newly added existing cluster is now in the **Running** status.![](./_assets/cluster-existing.png)

### EMQX V5 Managed Cluster

1. Log in to the ECP platform as a system admin, organization admin, or project admin. In **Workspace - Cluster** page, click **Add Cluster**.

2. Click to select **Existing Cluster** under **Cluster Type**.

3. Select **v5** under **Cluster Version**.
8. Upon returning to the **Workspace - Data Integration - Data Access** page, you will find that the newly added existing cluster is now in the **Running** status.![](./_assets/cluster-existing.png)

4. Provide a name for the cluster in the **Cluster Name** field. The name should be between 1-200 characters long and can include "\_" and blank spaces.
9. If an EMQX v4 cluster is added for management, an **Enter Dashboard** button will display. Click it to view the EMQX v4 dashboard. If the **Enter Dashboard** button is not visible, please make sure `cluster.agent` section is correctly configured in ECP configuration file and the MQTT broker configured in it can be accessed by the agent.

5. Fill in the **Cluster Address** (i.e. EMQX dashboard access address) and dashboard login username and password.
10. If an EMQX v5 cluster is added for management, an **Enter Dashboard** button will display if the **Cluster Address** has been configured. Click it to directly view the EMQX v5 dashboard in a new window.

6. Click **Confirm** to finish the adding process. The newly-created clusters will be listed in the **Cluster List** panel with the status **Created**.

![cluster-v5](./_assets/cluster-v5.png)

7. Click the **Details** button in the operation column to enter the cluster details, and then click the **Enter Dashboard** button. You will directly view the EMQX v5 dashboard in a new window.

![cluster-v5-dashboard](./_assets/cluster-v5-dashboard.png)


## Cluster Status

You can start or stop a cluster as your business requirement changes.

1. Log in as system admin, organization admin, or project admin.
2. On the target cluster, click the more icon and select **Stop**/**Start**.



EMQX cluster can be in the following states:
Managed EMQX cluster can be in the following states:

| Status | Description |
| ------------------ | ------------------------------------------------------------ |
| Creating | Intermediate state during the process of new cluster creation |
| Updating | Intermediate state during cluster OM operations, such as horizontal or vertical scaling, network type modifications, connection number modifications, cluster upgrade or downgrade |
| Starting | When starting the service |
| Running | Normal running state of the cluster |
| Stopping | When stopping the service or an intermediate state after deleting a cluster |
| Stopped | After stopping or deleting |
| Syncing Status | Intermediate state during horizontal or vertical scaling, cluster upgrade or downgrade, network type modifications, connection number modifications |
| Downgraded Running | One or more nodes of the cluster are unavailable, but the overall cluster is still usable |
| Error | The most recent task executed by the cluster failed (can auto-recover), or a cluster fault or dirty data occurred (this state rarely appears)<!--shall we remove the dirty data part?--> |
| Nonexistent | The task to create the cluster was not successfully issued |
| Status | Description |
| ----------- | ------------------------------------------------------------ |
| Created | Cluster with no node registered yet |
| Registering | Intermediate state during cluster node registration |
| Running | Normal running state of the cluster |
| Deleting | Intermediate state before cluster deletion completes |
| Error | Abnormal running state of the cluster, or network connection issue between agent and cluster or between agent and ECP |

For clusters in the state of Error, you can click the more icon and click **Try Fix**. If the problem is successfully solved, the cluster state will be Running; or consider deleting the cluster or reaching out to EMQ's technical support.
For clusters in the state of Error, you can click the Error status icon to view possible cause.

<!--also the English for the status should be confirmed-->
20 changes: 8 additions & 12 deletions ecp/en_US/cluster/cluster_details.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,25 @@
# View EMQX Cluster Details

In the **Cluster List** panel, you can see the clusters managed/hosted within the current organization, you can choose to view them as cards or lists.
In the **Data Access** panel, you can see the clusters managed within the current organization, you can choose to view them as cards or lists.

![emqx_card](./_assets/emqx_card.png)
![emqx_detail](_assets/cluster-detail.png)

Below is the explanation of each field:

- **Cluster Name**: Cluster name, you can click the name (or **Cluster ID** in the list view) to enter the cluster details page to find the network information.
- **Status**: Operational status of the cluster, could be **Creating**, **Running**, **Created** (for managed clusters, usually paired with **Register Node**), **stopping**, **stopped**, **Starting**, and **Error**.
- **Register Node**: Register to an existing EMQX cluster.
- **Start Time**: Indicate when the cluster is started.
- **Cluster Name**: Cluster name can be modified by **Edit** operation.
- **Version**: Indicate the EMQX version.
- **Replicas**: Number of EMQX nodes configured in each cluster.
- **Status**: Operational status of the cluster, could be **Created**, **Registering**, **Running**, **Deleting** and **Error**.
- **Connections**: Indicate the current established connections and maximum number of connections that can be established.
- **Running Time**: Indicate how long the cluster has running.
- **Create Time**: Indicate when the cluster is created.
- **Connections**: Indicate the maximum number of connections that can be established.
- **Specifications**: Indicate the cluster specifications. For hosted clusters, ECP allows system admins to change the cluster specifications to better serve their business needs. For details, see [Resource Settings](../system_admin/resource_config.md#configure-emqx-cluster-quota).
- **Type**: Indicate whether it is a hosted cluster (created by ECP) or managed cluster (created by users).
- **Version**: Indicate the EMQX version.

## Check Cluster Details via EMQX Dashboard

On the **Cluster / Detail** page, you can click on **Enter Dashboard** in the top-right corner to enter the EMQX Enterprise Edition Dashboard. This web-based control panel provided by EMQX allows users to monitor the operational status and statistical metrics of server nodes and clusters.
On the **Data Access** page, you can click on **Enter Dashboard** in the top-right corner to enter the EMQX Enterprise Edition Dashboard. This web-based control panel provided by EMQX allows users to monitor the operational status and statistical metrics of server nodes and clusters.

![console](./_assets/cluster-console.png)

EMQX Dashboard provides insights into client connectivity and subscription relationships. It also offers capabilities to configure and enable/disable plugins, manage HTTP API keys, perform hot configuration management for EMQX clusters, and conduct MQTT connection testing.

For detailed guidance on managing and controlling EMQX Enterprise Edition, please refer to the [EMQX 4.4 Documentation](https://docs.emqx.com/zh/enterprise/v4.4/).

24 changes: 18 additions & 6 deletions ecp/en_US/cluster/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,37 @@

In ECP, clusters refer to the EMQX clusters deployed on cloud servers, which serve as high-performance message broker for IoT devices. Built on the MQTT protocol, EMQX offers a lightweight, reliable, and scalable solution for communication between IoT devices. It excels in real-time, high availability, and easy implementation. For a comprehensive understanding of EMQX, please refer to the detailed documentation available on [EMQX Enterprise](https://docs.emqx.com/en/enterprise/v4.4/).

With ECP's cluster management features, users can efficiently handle multiple clusters, create new ones, onboard existing ones, and perform various tasks like troubleshooting, scaling, modifying network types, adjusting connections, upgrading/downgrading, transferring ownership, and deletion. The platform's user-friendly interface offers cluster information overview and log access for improved visibility.
With ECP's cluster management features, users can efficiently managing multiple existing clusters, and perform various tasks like adjusting connections, transferring ownership, and deletion. The platform's user-friendly interface offers cluster information overview and monitor, alarm and log access for improved visibility.

## Access Cluster Workspace

After logging in, you can find the **Workspace** option in the ribbon area. Click on it to navigate to the **Workspace - Cluster** page. This page provides an overview of the EMQX clusters hosted or managed by ECP and displays this project's current number of members.
After logging in, you can find the **Workspace** option in the ribbon area. Click on it to navigate to the **Workspace - Data Integration - Data Access** page. This page provides an overview of the EMQX clusters managed by ECP.

:::tip
System admin, organization admin, project admin, and regular users all can access this page, however, regular users do not have access to the administration page, and the **Workspace - Cluster** page serves as their landing page.
System admin, organization admin, project admin, and regular users all can access this page.

For the permission of each role, see [Permissions and Roles](../acl/authorize.md#roles-and-permissions).
:::

![集群列表](./_assets/cluster-list.png)

System admin, organization admin, and project admin can create clusters or add an existing cluster to be managed by ECP. For details on how to add clusters, see [Add Clusters](./add_manage.md).
System admin, organization admin, and project admin can add an existing cluster to be managed by ECP. For details on how to add clusters, see [Add Clusters](./add_manage.md).

After clusters are added, they will appear in the Cluster List panel, you can choose to view them in cards (default) or as lists. For a detailed explanation of these cluster details, see [View EMQX Cluster Details](./cluster_details.md).
After clusters are added, they will appear in the Data Access panel, you can choose to view them in cards (default) or as lists. For a detailed explanation of these cluster details, see [View EMQX Cluster Details](./cluster_details.md).

<!--Overall, I think we should state the difference between K8s and docker deployment-->
## Functional Differences across Cluster Versions

The management functionalities for different EMQX clusters vary across cluster versions.

| Function | ECP v4 cluster | ECP v5 cluster |
| :---------------------: | :------------: | :------------: |
| Update Connection Limit || ✅ * |
| Cluster Log |||
| Cluster Monitor |||
| Cluster Alarm |||
| Cluster Transfer |||
| Deletion |||

\* **Update Connection Limit** feature applies to EMQX v5.7.0 and above.

<!--Overall, I think we should state the difference between K8s and docker deployment-->
Loading

0 comments on commit 2f416ef

Please sign in to comment.