From 8237eed8b7c339e8dff166f93b57566524bc911f Mon Sep 17 00:00:00 2001 From: David Crespo Date: Mon, 5 Feb 2024 22:05:44 -0600 Subject: [PATCH] tweak a few API endpoint summaries and descriptions --- nexus/src/external_api/http_entrypoints.rs | 39 +++++++++++++--------- openapi/nexus.json | 28 ++++++++-------- 2 files changed, 39 insertions(+), 28 deletions(-) diff --git a/nexus/src/external_api/http_entrypoints.rs b/nexus/src/external_api/http_entrypoints.rs index ccd8cebad6..28755e5959 100644 --- a/nexus/src/external_api/http_entrypoints.rs +++ b/nexus/src/external_api/http_entrypoints.rs @@ -759,7 +759,11 @@ async fn silo_view( apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await } -/// List IP pools available within silo +/// List IP pools linked to silo +/// +/// Linked IP pools are available to users in the specified silo. A silo can +/// have at most one default pool. IPs are allocated from the default pool when +/// users ask for one without specifying a pool. #[endpoint { method = GET, path = "/v1/system/silos/{silo}/ip-pools", @@ -803,7 +807,7 @@ async fn silo_ip_pool_list( /// Delete a silo /// -/// Delete a silo by name. +/// Delete a silo by name or ID. #[endpoint { method = DELETE, path = "/v1/system/silos/{silo}", @@ -1569,7 +1573,11 @@ async fn ip_pool_silo_list( apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await } -/// Make an IP pool available within a silo +/// Link an IP pool to a silo +/// +/// Users in linked silos can allocate external IPs from this pool for their +/// instances. A silo can have at most one default pool. IPs are allocated from +/// the default pool when users ask for one without specifying a pool. #[endpoint { method = POST, path = "/v1/system/ip-pools/{pool}/silos", @@ -1620,10 +1628,12 @@ async fn ip_pool_silo_unlink( apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await } -/// Make an IP pool default or not-default for a silo +/// Make IP pool default for silo /// -/// When a pool is made default for a silo, any existing default will remain -/// linked to the silo, but will no longer be the default. +/// When a user asks for an IP (e.g., at instance create time) without +/// specifying a pool, the IP comes from the default pool if a default is +/// configured. When a pool is made the default for a silo, any existing default +/// will remain linked to the silo, but will no longer be the default. #[endpoint { method = PUT, path = "/v1/system/ip-pools/{pool}/silos/{silo}", @@ -1650,7 +1660,7 @@ async fn ip_pool_silo_update( apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await } -/// Fetch the IP pool used for Oxide services +/// Fetch the Oxide service IP pool #[endpoint { method = GET, path = "/v1/system/ip-pools-service", @@ -1765,10 +1775,9 @@ async fn ip_pool_range_remove( apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await } -/// List ranges for the IP pool used for Oxide services +/// List IP ranges for the Oxide service pool /// -/// List ranges for the IP pool used for Oxide services. Ranges are ordered by -/// their first address. +/// Ranges are ordered by their first address. #[endpoint { method = GET, path = "/v1/system/ip-pools-service/ranges", @@ -1809,7 +1818,7 @@ async fn ip_pool_service_range_list( apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await } -/// Add a range to an IP pool used for Oxide services +/// Add IP range to Oxide service pool #[endpoint { method = POST, path = "/v1/system/ip-pools-service/ranges/add", @@ -1830,7 +1839,7 @@ async fn ip_pool_service_range_add( apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await } -/// Remove a range from an IP pool used for Oxide services +/// Remove IP range from Oxide service pool #[endpoint { method = POST, path = "/v1/system/ip-pools-service/ranges/remove", @@ -3539,7 +3548,7 @@ async fn networking_bgp_announce_set_delete( apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await } -/// Enable a BFD session. +/// Enable a BFD session #[endpoint { method = POST, path = "/v1/system/networking/bfd-enable", @@ -3560,7 +3569,7 @@ async fn networking_bfd_enable( apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await } -/// Disable a BFD session. +/// Disable a BFD session #[endpoint { method = POST, path = "/v1/system/networking/bfd-disable", @@ -3581,7 +3590,7 @@ async fn networking_bfd_disable( apictx.external_latencies.instrument_dropshot_handler(&rqctx, handler).await } -/// Get BFD status. +/// Get BFD status #[endpoint { method = GET, path = "/v1/system/networking/bfd-status", diff --git a/openapi/nexus.json b/openapi/nexus.json index 7aedd1b523..8baf1a6316 100644 --- a/openapi/nexus.json +++ b/openapi/nexus.json @@ -5331,7 +5331,8 @@ "tags": [ "system/networking" ], - "summary": "Make an IP pool available within a silo", + "summary": "Link an IP pool to a silo", + "description": "Users in linked silos can allocate external IPs from this pool for their instances. A silo can have at most one default pool. IPs are allocated from the default pool when users ask for one without specifying a pool.", "operationId": "ip_pool_silo_link", "parameters": [ { @@ -5379,8 +5380,8 @@ "tags": [ "system/networking" ], - "summary": "Make an IP pool default or not-default for a silo", - "description": "When a pool is made default for a silo, any existing default will remain linked to the silo, but will no longer be the default.", + "summary": "Make IP pool default for silo", + "description": "When a user asks for an IP (e.g., at instance create time) without specifying a pool, the IP comes from the default pool if a default is configured. When a pool is made the default for a silo, any existing default will remain linked to the silo, but will no longer be the default.", "operationId": "ip_pool_silo_update", "parameters": [ { @@ -5472,7 +5473,7 @@ "tags": [ "system/networking" ], - "summary": "Fetch the IP pool used for Oxide services", + "summary": "Fetch the Oxide service IP pool", "operationId": "ip_pool_service_view", "responses": { "200": { @@ -5499,8 +5500,8 @@ "tags": [ "system/networking" ], - "summary": "List ranges for the IP pool used for Oxide services", - "description": "List ranges for the IP pool used for Oxide services. Ranges are ordered by their first address.", + "summary": "List IP ranges for the Oxide service pool", + "description": "Ranges are ordered by their first address.", "operationId": "ip_pool_service_range_list", "parameters": [ { @@ -5552,7 +5553,7 @@ "tags": [ "system/networking" ], - "summary": "Add a range to an IP pool used for Oxide services", + "summary": "Add IP range to Oxide service pool", "operationId": "ip_pool_service_range_add", "requestBody": { "content": { @@ -5589,7 +5590,7 @@ "tags": [ "system/networking" ], - "summary": "Remove a range from an IP pool used for Oxide services", + "summary": "Remove IP range from Oxide service pool", "operationId": "ip_pool_service_range_remove", "requestBody": { "content": { @@ -5909,7 +5910,7 @@ "tags": [ "system/networking" ], - "summary": "Disable a BFD session.", + "summary": "Disable a BFD session", "operationId": "networking_bfd_disable", "requestBody": { "content": { @@ -5939,7 +5940,7 @@ "tags": [ "system/networking" ], - "summary": "Enable a BFD session.", + "summary": "Enable a BFD session", "operationId": "networking_bfd_enable", "requestBody": { "content": { @@ -5969,7 +5970,7 @@ "tags": [ "system/networking" ], - "summary": "Get BFD status.", + "summary": "Get BFD status", "operationId": "networking_bfd_status", "responses": { "200": { @@ -6980,7 +6981,7 @@ "system/silos" ], "summary": "Delete a silo", - "description": "Delete a silo by name.", + "description": "Delete a silo by name or ID.", "operationId": "silo_delete", "parameters": [ { @@ -7011,7 +7012,8 @@ "tags": [ "system/silos" ], - "summary": "List IP pools available within silo", + "summary": "List IP pools linked to silo", + "description": "Linked IP pools are available to users in the specified silo. A silo can have at most one default pool. IPs are allocated from the default pool when users ask for one without specifying a pool.", "operationId": "silo_ip_pool_list", "parameters": [ {