docs(cloud): add Meshery Server Registration concept page#952
docs(cloud): add Meshery Server Registration concept page#952
Conversation
Documents how a Meshery Server registers itself with Layer5 Cloud as its Remote Provider: identity (kind + user_id + server_id), the registration endpoint, first-registration vs re-registration paths, the field- preservation guarantees on update (Name/Kind/Type/SubType/Status survive re-registration), validation/error cases, and operator guidance for the common symptoms a misconfigured deployment surfaces. Removes draft status from the Concepts section index and replaces the placeholder copy with an intro that links to the new page. Signed-off-by: Lee Calcote <lee.calcote@layer5.io>
|
There was a problem hiding this comment.
Pull request overview
Adds in-repo Layer5 Cloud documentation for how Meshery Server registers with Layer5 Cloud as its Remote Provider, and publishes/updates the Concepts landing page to point to the new concept.
Changes:
- Added a new Concepts page detailing Meshery Server registration identity, endpoint, first vs re-registration behavior, and operator troubleshooting guidance.
- Published the Concepts section index (removed
draft: true) and replaced placeholder content with a short intro + link to the new page.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| content/en/cloud/concepts/meshery-server-registration.md | New concept page documenting registration behavior and operational guidance. |
| content/en/cloud/concepts/_index.md | Publishes Concepts index and links to the new registration concept page. |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new conceptual documentation page for Meshery Server Registration and updates the concepts index to include it. The new documentation details the registration lifecycle, identity management, and error handling for Meshery Servers connecting to Layer5 Cloud. Review feedback highlights an inconsistency in the documentation regarding whether the server_id field is strictly required and suggests aligning the reported HTTP status codes with standard practices by using 4xx codes instead of 500 for client-related errors.
| | `metadata.server_id` | Stable UUID generated by the Meshery Server. | | ||
|
|
||
| Optional payload fields: | ||
|
|
||
| | Field | Description | | ||
| |------------|-------------| | ||
| | `name` | Human-readable display name. If omitted, Cloud generates `meshery-<random>`. | | ||
| | `type` / `sub_type` | Free-form classification fields. | | ||
| | `metadata` | Additional JSON metadata (e.g. server version, hostname). | | ||
| | `status` | Initial status (defaults to the system's registered state). | | ||
|
|
||
| The handler chain is `RegisterConnection` → `MesheryConnectionUtilityHandlerRegistration` → either `CreateConnection` or `UpdateConnection`. | ||
|
|
||
| ## What Happens on First Registration | ||
|
|
||
| 1. The handler validates that the resolved session has a non-nil `user_id`. The `connections.user_id` column is `NOT NULL`; a missing user at this point is a hard error and the request is rejected. | ||
| 2. `CheckMesheryServerExistence` looks for a row matching `(meshery, user_id, server_id)`. | ||
| 3. No match is found, so a new row is inserted via `CreateConnection`. | ||
| 4. The new Connection inherits the user's Organization for tenant isolation. | ||
|
|
||
| ## What Happens on Re-Registration | ||
|
|
||
| A re-registration is any subsequent call from the same Meshery Server (same `server_id`) for the same user — typically after a Meshery Server restart, a new browser session, or a Cloud reconnect. | ||
|
|
||
| The handler: | ||
|
|
||
| 1. Validates the session's `user_id` (same as first registration). | ||
| 2. Finds the existing row via `CheckMesheryServerExistence`. | ||
| 3. **Preserves the existing row's stable identity fields** — `name`, `kind`, `type`, `sub_type`, `status` — so a freshly-minted random name from a payload that omitted `name` cannot rename the existing Meshery Server, and missing `type` / `sub_type` cannot blank them. | ||
| 4. **Preserves the existing row's `created_at`**, sets `updated_at = now()`. | ||
| 5. **Preserves a previously-set `user_id`**: if the row already has an owner, the existing owner wins; if the row's `user_id` is somehow nil, the validated incoming `user_id` is kept (this guard exists because a historical narrow `SELECT id, metadata` projection in the DAO could leave the in-memory row's UserID nil, which would otherwise UPDATE the row to a null `user_id` and violate the NOT NULL constraint). | ||
| 6. Calls `UpdateConnection`, which updates every column except `status`. | ||
|
|
||
| The net effect: re-registering a Meshery Server is **safe and idempotent** with respect to identity. Only `metadata` and `updated_at` are intended to change across re-registrations. | ||
|
|
||
| {{< alert type="info" title="Why status is excluded from updates" >}} | ||
| Connection status transitions are managed through dedicated lifecycle endpoints (e.g. connect / disconnect, ignore, delete), not through registration. A re-registration call cannot reset a previously-disconnected Meshery Server's status by accident. | ||
| {{< /alert >}} | ||
|
|
||
| ## Validation and Error Cases | ||
|
|
||
| | Condition | Behavior | | ||
| |-----------|----------| | ||
| | Session has no resolvable user | Registration is rejected before any DAO call. The caller sees an HTTP 500 with an error describing the missing `user_id`. | | ||
| | `kind` is not in the supported list | HTTP 500 with an "unsupported connection kind" error. | | ||
| | `server_id` is missing from `metadata` | The lookup degenerates to `metadata->>'server_id' IS NULL`, which will not match any prior registration; a fresh row will be created. Always send a stable `server_id`. | |
There was a problem hiding this comment.
There is an inconsistency between the definition of metadata.server_id as a Required field (line 50) and its described behavior when missing (line 95). If the API creates a fresh row instead of rejecting the request when server_id is absent, the field is technically optional for the request to succeed.
Consider moving metadata.server_id to the Optional payload fields table with a note that it is required for identity persistence, or update the behavior on line 95 to reflect a rejection if the API is intended to enforce its presence.
| | Session has no resolvable user | Registration is rejected before any DAO call. The caller sees an HTTP 500 with an error describing the missing `user_id`. | | ||
| | `kind` is not in the supported list | HTTP 500 with an "unsupported connection kind" error. | |
There was a problem hiding this comment.
The documentation lists HTTP 500 for 'Session has no resolvable user' and 'unsupported connection kind'. These scenarios typically correspond to 401 Unauthorized and 400 Bad Request, respectively. If the server implementation currently returns 500, it should be noted that this is a known implementation detail, or ideally, the implementation should be updated to use standard 4xx status codes and the documentation adjusted to match.
Summary
(kind, user_id, server_id)), the registration endpoint, first-registration vs re-registration paths, the field-preservation guarantees on update, validation/error cases, and operator guidance for common symptoms.draft: truefrom the Concepts section index and replaces the placeholder copy with an intro that links to the new page.Why now
This concept was previously only documented externally on docs.meshery.io. Companion to meshery-cloud#5071, which hardens the registration handler against null
user_idand against silent identity-field overwrites on re-registration — operators need an in-Cloud-Docs reference for the behavior and the symptoms.Test plan
alertshortcode already used elsewhere in the section)