From 13dd54028915a6ddedc8374ca915b8b2824ce1b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hauke=20L=C3=B6ffler?= Date: Wed, 3 Jun 2026 13:32:15 +0200 Subject: [PATCH 1/3] docs: add example for adding a vessel to a formation via API --- src/multiplayer-servers/api/examples.md | 56 +++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/src/multiplayer-servers/api/examples.md b/src/multiplayer-servers/api/examples.md index fb7719b1..38764087 100644 --- a/src/multiplayer-servers/api/examples.md +++ b/src/multiplayer-servers/api/examples.md @@ -150,6 +150,62 @@ curl -X 'POST' \ }' ``` +## Adding a Vessel to a Formation + +To add a vessel to an existing formation via the API, you need to PATCH the formation resource itself. This adds the vessel to the formation's `vessels` list, and the formation controller will create and manage it. + +::: warning +Do **not** create a standalone vessel with `ownerReferences` pointing to a formation. This does not register the vessel in the formation's config. The formation controller will treat it as orphaned and delete it. +::: + +Use a JSON Patch request to append a vessel to the formation's `spec.vessels` array: + +```bash +curl -X 'PATCH' \ + "https://${GAMEFABRIC_URL}/api/formation/v1/environments/${ENV}/formations/${FORMATION_NAME}" \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json-patch+json' \ + -H "Authorization: Bearer ${GF_API_TOKEN}" \ + -d '[{ + "op": "add", + "path": "/spec/vessels/-", + "value": { + "name": "my-new-vessel", + "region": "" + } +}]' +``` + +The vessel inherits the formation's template configuration. If you need to override specific container settings for this vessel, add an `override` field: + +```bash +curl -X 'PATCH' \ + "https://${GAMEFABRIC_URL}/api/formation/v1/environments/${ENV}/formations/${FORMATION_NAME}" \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json-patch+json' \ + -H "Authorization: Bearer ${GF_API_TOKEN}" \ + -d '[{ + "op": "add", + "path": "/spec/vessels/-", + "value": { + "name": "my-new-vessel", + "region": "", + "override": { + "containers": [ + { + "name": "gameserver", + "image": "", + "args": [ + "/home/gameserver/server", + "--config=/home/gameserver/config.json" + ] + } + ] + } + } +}]' +``` + ## Listing Vessels Now that you created a Vessel, you might want to use the API to list Vessels in order to know whether yours was scheduled successfully. From a01598e33ab937e65b5d5b193a933a1b5a115d04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hauke=20L=C3=B6ffler?= Date: Wed, 3 Jun 2026 13:42:16 +0200 Subject: [PATCH 2/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/multiplayer-servers/api/examples.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/multiplayer-servers/api/examples.md b/src/multiplayer-servers/api/examples.md index 38764087..046c4ef5 100644 --- a/src/multiplayer-servers/api/examples.md +++ b/src/multiplayer-servers/api/examples.md @@ -152,10 +152,10 @@ curl -X 'POST' \ ## Adding a Vessel to a Formation -To add a vessel to an existing formation via the API, you need to PATCH the formation resource itself. This adds the vessel to the formation's `vessels` list, and the formation controller will create and manage it. +To add a vessel to an existing formation via the API, you need to PATCH the formation resource itself. This appends the vessel to the formation's `spec.vessels` list, and the formation controller creates and manages it. ::: warning -Do **not** create a standalone vessel with `ownerReferences` pointing to a formation. This does not register the vessel in the formation's config. The formation controller will treat it as orphaned and delete it. +Do **not** create a standalone vessel with `ownerReferences` pointing to a formation. Setting `ownerReferences` does not add the vessel to the formation's `spec.vessels`, so the formation controller treats it as an orphan and deletes it. ::: Use a JSON Patch request to append a vessel to the formation's `spec.vessels` array: From 750f2107697658186fe022b7674d2cfb35db6448 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hauke=20L=C3=B6ffler?= Date: Wed, 3 Jun 2026 15:39:25 +0200 Subject: [PATCH 3/3] docs: address PR review feedback - Capitalize Vessel and Formation when referring to resource kinds - Use consistent placeholder across the page --- src/multiplayer-servers/api/examples.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/multiplayer-servers/api/examples.md b/src/multiplayer-servers/api/examples.md index 046c4ef5..fb94ac28 100644 --- a/src/multiplayer-servers/api/examples.md +++ b/src/multiplayer-servers/api/examples.md @@ -116,7 +116,7 @@ curl -X 'POST' \ { "name":"gameserver", "branch":"", - "image":"", + "image":"", "ports":[ { "name":"game", @@ -152,13 +152,13 @@ curl -X 'POST' \ ## Adding a Vessel to a Formation -To add a vessel to an existing formation via the API, you need to PATCH the formation resource itself. This appends the vessel to the formation's `spec.vessels` list, and the formation controller creates and manages it. +To add a Vessel to an existing Formation via the API, you need to PATCH the Formation resource itself. This appends the Vessel to the Formation's `spec.vessels` list, and the formation controller creates and manages it. ::: warning -Do **not** create a standalone vessel with `ownerReferences` pointing to a formation. Setting `ownerReferences` does not add the vessel to the formation's `spec.vessels`, so the formation controller treats it as an orphan and deletes it. +Do **not** create a standalone Vessel with `ownerReferences` pointing to a Formation. Setting `ownerReferences` does not add the Vessel to the Formation's `spec.vessels`, so the formation controller treats it as an orphan and deletes it. ::: -Use a JSON Patch request to append a vessel to the formation's `spec.vessels` array: +Use a JSON Patch request to append a Vessel to the Formation's `spec.vessels` array: ```bash curl -X 'PATCH' \ @@ -176,7 +176,7 @@ curl -X 'PATCH' \ }]' ``` -The vessel inherits the formation's template configuration. If you need to override specific container settings for this vessel, add an `override` field: +The Vessel inherits the Formation's template configuration. If you need to override specific container settings for this Vessel, add an `override` field: ```bash curl -X 'PATCH' \