Usage Guide

Preparations

MEF provides the function of managing containerized applications on edge nodes, including edge node access management and containerized application management. Through secondary development and docking with the ISV service platform, users can use the RESTful API of MEF Center to initialize the configuration of third-party image repositories and software repositories, pull images, and upgrade MEF Edge software packages.

MEF Center Development Precautions

On the device environment of MEF Center, MEF has occupied the following ports. Avoid using the same ports when developing third-party components.

Table 1 Ports used by MEF Center

Destination Port	Component	Port Description
30003	MEF Center	Service port for edge nodes to dock with the MEF Center network management
30004	MEF Center	Port for testing the connection and authentication information when edge nodes dock with the MEF Center network management
10002	CloudCore	Used for operations such as certificate acquisition when the edge node's edgecore docks with CloudCore
10000	CloudCore	Used for service interaction when the edge node's edgecore docks with CloudCore
6443	K8s	Listening port of the K8s API server, providing services for the MEF Center client
30035	MEF Center	Used to access the RESTful API provided by MEF Center

Preparing the User Management Platform

Users need to prepare a user management platform capable of transmission via HTTPS. After exchanging root certificates with MEF Center for authentication, the platform successfully docks through a RESTful API and uses the functions provided by MEF.

Preparing the Image Repository

Users need to prepare an open-source image repository or their own image repository that complies with Docker interface standards. The image repository must support uploading and pulling images via HTTPS.

Preparing the Software Repository

Users need to prepare an open-source software repository or their own software repository with a unified RESTful API. The software repository must support file upload and download via HTTPS.

Connecting MEF Center to Service Platforms

Use the northbound RESTful API to dock with the user management platform, image repository, and software repository.

Integrating with the User Management Platform

The external interface of MEF Center requires mutual certificate authentication with third-party platforms.

Exchange the root certificates of MEF Center and the third-party management platform. MEF Center must have cert-manager started to perform certificate exchange.

Run the following command to exchange certificates.

installation path/MEF-Center/mef-center/run.sh exchangeca -export_path MEF root certificate path -import_path management platform root certificate path

Note

If you need to update the root certificate of the third-party management platform after docking, MEF Center must restart nginx-manager after running the certificate exchange command. For details, see Restarting MEF Center.
The validity period of the root certificate is recommended to be longer than the detection period for certificate alarms (default value: 7).
Importing a root certificate repeatedly backs up the previously imported certificate.

Table 1 exchangeca parameters

Parameter	Description
-export_path/--export_path	Path to save the MEF root certificate file, used for third-party modules to authenticate MEF Center. The file name must be specified. This file path only supports absolute paths and must not be an existing file.
-import_path/--import_path	Path to the management platform root certificate file, used for MEF Center to authenticate third-party modules. The file name must be specified. Supports certificate chains with a maximum of 10 levels and single certificate verification. This file path only supports absolute paths. The management platform root certificate must meet the following requirements: The certificate must be in PEM format. The signature in the root CA certificate must be correct. The root CA certificate must be within its validity period. The certificate must be an X.509 V3 digital certificate. The "Basic Constraints" extension field of the root CA certificate must indicate "CA", and the "Key Usage" extension field must include "Certificate Signing". The key must use the RSA algorithm with a length of at least 3072 bits, and the digest algorithm must be SHA256, SHA384, or SHA512; or ECDSA with a length of at least 256 bits.

Parameter

Description

-export_path/--export_path

Path to save the MEF root certificate file, used for third-party modules to authenticate MEF Center. The file name must be specified. This file path only supports absolute paths and must not be an existing file.

-import_path/--import_path

Path to the management platform root certificate file, used for MEF Center to authenticate third-party modules. The file name must be specified. Supports certificate chains with a maximum of 10 levels and single certificate verification. This file path only supports absolute paths. The management platform root certificate must meet the following requirements:

The certificate must be in PEM format.
The signature in the root CA certificate must be correct.
The root CA certificate must be within its validity period.
The certificate must be an X.509 V3 digital certificate. The "Basic Constraints" extension field of the root CA certificate must indicate "CA", and the "Key Usage" extension field must include "Certificate Signing".
The key must use the RSA algorithm with a length of at least 3072 bits, and the digest algorithm must be SHA256, SHA384, or SHA512; or ECDSA with a length of at least 256 bits.

Note

The directory for export_path does not support soft links. The path length must be less than 4096 characters, the directory hierarchy must be fewer than 99 levels, and the group and other users must not have write permissions. The owner must be root.
The file specified by export_path must have root as the owner, the group and other users must not have write permissions, and the file size must not exceed 1 MB.
The file specified by import_path must exist, have root as the owner, the group and other users must not have write permissions, and the file size must not exceed 1 MB.

A response example like the following or a command return value of 0 indicates that the operation was successful.
```
exchange certs successful
```
If the response example is as follows or the command return value is 4, wait for cert-manager initialization to complete and then retry the certificate exchange.
```
the root ca has not yet generated, please start cert manager first
exchange certs failed
```

Confirm the docking result. Call the version query interface to confirm the docking result. A successful call indicates successful docking.
```
https://{ip}:{port}/edgemanager/v1/version
```
For details about the interface, see Querying the edge-manager Version.

Note
After the certificate exchange is successful, wait for 1s before confirming the docking result.

Follow-up Procedure

If you need to obtain the root certificate information of a third-party management platform, see Obtaining Integrator Certificate Information.

Integrating with the Image Repository

To use a third-party image repository, users must first import the root certificate of the image repository and then configure the image download information to complete the docking. When configuring a third-party image repository, the account and password provided by the third-party image repository will be used. The security of this account and password is the responsibility of the user.

Import the root certificate of the image repository.

To use a third-party image repository, users must first import the image repository certificate.
```
https://{ip}:{port}/certmanager/v1/certificates/import
```
For specific interface details, see Importing the Root Certificate.
Import the image repository configuration.

Used to configure the third-party image repository address and account password. The repository server address supports domain names or IP addresses. When the interface is called repeatedly, the existing image download information configuration will be updated.
```
https://{ip}:{port}/edgemanager/v1/image/config
```
For details about the interface, see Configuring Image Download Information.
(Optional) Configure the mapping between domain names and IP addresses.

If a domain name is used when importing the image repository configuration, you need to configure the mapping between the domain name and IP address in the "/etc/hosts" file of the MEF Edge host directory on the edge device. For details, see Configuring Local Domain Name Mapping.
```
./run.sh domainconfig -domain=xxx -ip=xxx
```

Integrating with the Software Repository

To use a third-party software repository, you need to first import the root certificate of the software repository to complete the docking.

https://{ip}:{port}/certmanager/v1/certificates/import

For details about the API, see Importing the Root Certificate.

Authentication and Integration Between MEF Center and MEF Edge

Obtain the MEF Center root certificate and cloud-edge authentication token, and perform network management configuration on the MEF Edge device for mutual authentication and cloud-edge docking between MEF Center and MEF Edge.

Prerequisites

The system time of the device to be managed must be consistent with the system time of MEF Center. Otherwise, docking with MEF Center may fail.

Procedure

Log in to the MEF Edge device environment as the root user.
Obtain the MEF Center root certificate and cloud-edge authentication token.
1. Export the root certificate. For details, see Exporting the Root Certificate. Select "hub_svr" for the URL parameter.
2. Obtain a valid cloud-edge authentication token. For details, see Obtaining the Cloud-Edge Authentication Token. The obtained token is valid for 7 days.
Upload the MEF Center root certificate to any path on the MEF Edge device. It is recommended that the directory permission be set to non-writable for other users.
Run the following command to go to the path where the network management configuration file is located.
```
cd installation path/MEFEdge/software/
```

Run the following command to perform network management configuration.

./run.sh netconfig -root_ca=<MEF Center root certificate path/certificate name.crt> -ip=<MEF Center IP> [-port=<MEF Center port>] [-net_type=MEF]  [-test_connect=true] [-auth_port=<MEF Center authentication port>]

Table 1 netconfig parameters

Parameter	Mandatory/Optional	Description
root_ca	Mandatory	Indicates the path of the imported MEF Center root certificate file, which must be an absolute path. The path must be owned by root, with no write permission for the group and other users, and the file size must not exceed 1 MB. [!NOTE] Note: If the device cannot dock with MEF Center because the certificate has expired or been revoked, re-import the MEF Center root certificate file.
ip	Mandatory	The access IP address of MEF Center. [!NOTE] Note: Only IPv4 is supported. The all-zero address (0.0.0.0), broadcast address (255.255.255.255), and local IP addresses are not allowed.
port	Optional	Indicates the port number of MEF Center, with a value range of 1025 to 65535. If this parameter is not configured, the default port 30003 is used. If the port number has been configured multiple times, the most recently configured port number takes effect.
net_type	Optional	Indicates the network management mode. The value is MEF. If this parameter is not configured, the default value is MEF.
test_connect	Optional	Indicates whether to test the connectivity between the MEF Edge device and MEF Center during network management configuration. The default value is true. If this value is not configured, the connectivity test is performed by default. If this parameter is configured and set to true, the connectivity between the device and MEF Center is tested. If the test fails, docking with MEF Center fails. If this parameter is configured and set to false, the connectivity between the device and MEF Center is not tested, but this may cause subsequent docking with MEF Center to fail.
auth_port	Optional	The port number used by MEF Center for authentication, with a value range of 1025 to 65535. This parameter is optional. If this parameter is not configured, the default port 30004 is used.

Enter the cloud-edge authentication token as prompted to complete the docking.
```
Please enter token:
```
The response example is as follows, indicating that the docking is successful. If the docking fails, see MEF Center and MEF Edge Failed to Configure NMS.
```
Execute [netconfig] command success!
```
After the docking is successful, run the following command to restart MEF Edge.
```
./run.sh restart
```
The response example is as follows, indicating that the restart command was executed successfully.
```
Execute [restart] command success!
```

Note

MEF Center does not support migrating containerized applications. Before reconfiguring network management, you are advised to uninstall deployed containers to avoid resource residue.
To configure the time threshold and detection period for MEF Center root certificate expiration alarms, see Configuring and Querying MEF Edge Certificate Expiration Alarm.
After reconfiguring network management parameters, you need to restart MEF Edge for the changes to take effect.

Deploying Containerized Applications

This chapter guides developers on deploying containerized applications through the RESTful APIs provided by MEF Center, following the operation steps shown in Figure 1 below.

Note

It is recommended not to operate cluster resources (such as containerized applications) on MEF Center nodes through commands or API calls, as this may cause MEF Center environment exceptions.

Figure 1 Deploying a containerized application

Introduction to the containerized application deployment process

Table 1 Containerized application deployment process

Scenario	Operation	Description	API Reference
Managing edge nodes	Creating a node group	Create a node group through RESTful APIs or use an existing node group.	For details about the node management API, see Node Management APIs.
	(Optional) Querying the list of unmanaged nodes	Before managing nodes, you can query the list of unmanaged nodes through RESTful APIs to find the node ID corresponding to the current unmanaged MEF Edge device node.
	Managing a node	Manage a node through RESTful APIs.
	(Optional) Adding a node to a node group	If "groupIDs" is not specified when managing a node, you can add the node to a specified node group through RESTful APIs.
	(Optional) Modifying a node	Modify the name and description of a node through RESTful APIs.
	(Optional) Deleting a node	Delete nodes in batches through RESTful APIs.
	(Optional) Removing a node from a node group	Remove a node from a specified node group through RESTful APIs to delete the pod of a single containerized application and uninstall the corresponding containerized application.
Preparing container images	Preparing container images	MEF can use containerized application images in three ways: through the Docker public image repository, a third-party image repository, or manually importing images to MEF Edge. When using an image repository, you need to ensure that the network connection between the MEF Edge device and the image repository is functional, and that the image repository itself is usable. [!NOTE] Note: When deploying a containerized application, the image repository account and password issued by the third-party image repository will be used. This account and password are managed by the third party.	If you manually import images in the MEF Edge device environment, you can use the following Docker command in any path to import: docker load -i xxxx.tar.gz If you need to use a third-party image repository to obtain images, for details about the process, see Configuration APIs. For details about how to create container images, see Creating an Inference Image or the "Container Deployment Scenario > Creating a Container Image" section in Atlas 200I A2 Acceleration Module Ascend Software Quick Installation Guide.
Managing containerized applications	Creating a containerized application	Create a containerized application for a node group through RESTful APIs.	For details about the containerized application management API, see Containerized Application Management APIs. [!NOTE] Note: If you deploy containerized applications that are not managed by MEF Center to device nodes, the containerized applications may fail to be deployed due to insufficient resources.
	(Optional) Querying the containerized application list	Query the list of containerized applications to be deployed through RESTful APIs.
	Deploying a containerized application	Create a containerized application for a node group through RESTful APIs.
	(Optional) Querying the deployed containerized application list	After deploying a containerized application, you can query the list of deployed containerized applications through RESTful APIs.
	(Optional) Updating a containerized application	Update the corresponding deployed containerized application through RESTful APIs. Currently, only modifications to the container image name and container image version are supported.
	(Optional) Uninstalling a containerized application	Uninstall a containerized application through RESTful APIs.
	(Optional) Deleting a containerized application	Delete a containerized application through RESTful APIs. When deleting a containerized application, only undeployed applications can be deleted. If the corresponding containerized application has been deployed, you must uninstall it first.

Note

To collect logs from MEF Edge node devices using the RESTful API provided by MEF Center, see Log Collection APIs. To directly log in to the device environment to view logs, see Viewing Log Information.