Guide 05
Merak Nodes
The edge routing nodes that actually carry traffic between members and services.
Route: /meraknode · Menu: Merak Nodes · Page permission: merakNode:R
A Merak Node is an edge router. Applications are reachable only through the node fabric, so a node must exist and be deployed before traffic can flow.
| Deployment type | How it is created |
|---|---|
| On-premises | You create it here, download a bootstrap kit, and run the installer on your own Linux host. |
| Cloud | Provisioned automatically when the tenant is created. You cannot create one from here. |
What you can do here
- As a network engineer, I want to see every routing node and whether it is up, so that I can spot outages.
- As a network engineer, I want to add an on-premises node and install it, so that I can extend coverage to another site.
- As a network engineer, I want to re-issue an enrollment token, so that an installation whose token expired can still complete.
- As a security officer, I want a deployed node to stop handing out installers, so that its enrollment credential is not redistributed.
- As a network engineer, I want to remove a node that is gone, so that the fabric reflects reality.
1. The node list
1.1 Columns
| Column | Notes |
|---|---|
| Name | Node name, unique within the tenant. |
| Host | The address Agents connect to. Cloud nodes show a public domain; on-premises nodes show the hostname or IP the router reports. - when unknown. |
| Deploy status | See §1.2. |
| Created At | - when unknown. |
| Updated At | - when unknown. |
| Action | Buttons filtered by deployment status. |
1.2 Deployment statuses
| Status | Label | Meaning |
|---|---|---|
| PENDING | 等待佈署 | Created; the installer has not run yet. |
| PROVISIONING | 佈署中 | Installation in progress. |
| ONLINE | 已部署 | Enrolled and deployed. |
| OFFLINE | 未部署 | The node is currently unreachable. It does not count as deployed, so the installer and JWT stay available — but a node also lands here after enrolling and later going down. |
| ERROR | 錯誤 | Deployment failed. |
The node also carries a separate live connection status (ONLINE / OFFLINE / UNKNOWN) read from the routing layer in real time. If that layer is unreachable it reads as unknown.
1.3 Filtering and sorting
| Filter | Type | Notes |
|---|---|---|
| Name | Text | Partial match. |
| Deployment type | Checkboxes, multi | On-premises / Cloud. Nothing ticked = all. |
| Deploy status | Checkboxes, multi | The five statuses above. Nothing ticked = all. |
| Sort | — | Default: created time, newest first. |
1.4 Row shortcuts
Double-click a row to open its detail. Single-clicking a row body does nothing — the node list has no multi-select.
2. Row actions
| Action | Shown when |
|---|---|
| Detail | Always |
| Download bootstrap kit | Deploy status is not ONLINE |
| Delete | Always |
2.1 Why a deployed node offers no installer
Once a node has enrolled successfully, the installer script deletes the single-use enrollment credential it carried, so there is genuinely no kit left to hand out. Download bootstrap kit and Regenerate JWT are both hidden on a deployed node — hiding the regenerate button too closes the obvious detour of re-issuing a credential in order to get a fresh installer.
Every other status (waiting, provisioning, offline, error) still offers the kit.
3. Creating a node
Route: /meraknode/create · Permission: merakNode:C
Only on-premises nodes can be created here. Cloud nodes are provisioned for you.
3.1 Step 1 — Node information
| Field | Required | Notes |
|---|---|---|
| Name | Yes | Unique within the tenant. |
| Router role | Yes | No default — you must choose. See below. |
| Router role | Meaning |
|---|---|
| Can host services | The node may terminate traffic for applications — services can live behind it. |
| Ingress only | The node is an entry point only; it forwards but does not terminate. |
3.2 Step 2 — Bootstrap kit
The installer script and its embedded enrollment token are shown here.
The script carries a one-time enrollment credential and is offered once. Download it now. If you lose it you must regenerate the token from the node’s detail page.
Installation requirements:
- Ubuntu 22.04 LTS only. The
install.shscript checks the OS version and refuses to run elsewhere. - The enrollment token is valid for 24 hours.
3.3 Step 3 — Result
Success or failure, with the error shown on failure.
3.4 Creation failures
| Cause | What you see |
|---|---|
| Duplicate name, malformed field, missing router role | A field-level error; you stay on step 1. |
| Router quota exceeded | The result step fails with “node quota reached”. |
4. Node detail
Route: /meraknode/:nodeId · Permission: merakNode:R
4.1 Basic information
| Field | Notes |
|---|---|
| Deployment type | On-premises / Cloud (chip). |
| Connection status | Live: online / offline / unknown. |
| Deploy status | Chip, as in §1.2. |
| Router role | Can host services / ingress only. |
| Host | The address Agents connect to. |
| Created / updated at | Read-only. |
| Created by | Read-only. |
4.2 Editing
Only the name is editable. Saving it also renames the corresponding edge router in the routing layer.
4.3 Toolbar
| Action | Shown when |
|---|---|
| Download bootstrap kit | Deploy status is not ONLINE |
| Regenerate JWT | Deploy status is neither PENDING nor ONLINE — i.e. the node was provisioned but has not deployed |
| Delete | Always |
These buttons are filtered by deployment status only — see §8 for why permission does not hide them here.
5. Enrollment tokens
The enrollment token (JWT) is what lets a freshly installed node join the fabric.
| Property | Value |
|---|---|
| Lifetime | 24 hours |
| Exists while | The router has not completed enrollment |
| After expiry | Regenerate it, then download a fresh bootstrap kit |
To regenerate: open the node detail, select Regenerate JWT, confirm. For an on-premises node the bootstrap kit dialog opens automatically afterwards with the new credential.
If you open the bootstrap kit and the node has no valid token, the dialog says so and offers Regenerate JWT directly.
Cloud nodes cannot produce a bootstrap kit. The button is still shown, but pressing it reports a load failure — there is no installer to give you.
6. Deleting a node
From the row action or the detail toolbar, with merakNode:D. The confirmation warns that the corresponding edge router and its policy are deleted from the routing layer at the same time. Traffic that depended on this node will stop flowing.
7. Quotas
Creating a node consumes the tenant’s router quota. When it is exhausted, creation fails with a quota message. Current usage is visible on your profile page under Merak Node.
8. Permission summary
| Task | Permission | Enforced where |
|---|---|---|
| Open the page | merakNode:R | Console and backend |
| Create | merakNode:C | Backend only |
| Rename, regenerate JWT | merakNode:U | Backend only |
| Delete | merakNode:D | Backend only |
⚠️ Merak Nodes are the one exception to “missing permission = missing button”. Everywhere else in the Console, a control you cannot use is not rendered. Here only the page is gated (
merakNode:R); the create, rename, regenerate and delete controls are shown to anyone who can open the page and are filtered by deployment status only. ThemerakNode:C/U/Dkeys exist and the backend applies them, so an action you are not entitled to fails at submit rather than being hidden. Treat a visible button here as “you may try”, not “you may do”.
Next
- Publish services that will ride this fabric: 03 · Applications
- Check who is actually connecting through it: 07 · Logs