From d5e369c90dc38b39c9e4228747edfd8f9ea9a493 Mon Sep 17 00:00:00 2001 From: Clemens Hoffmann Date: Wed, 13 Nov 2024 13:35:48 +0100 Subject: [PATCH] Add route-options documentation Add documentation for the route options object, and its supported fields. --- .../source/includes/api_resources/_routes.erb | 12 +++++++ .../includes/resources/routes/_create.md.erb | 26 ++++++++------- .../includes/resources/routes/_object.md.erb | 33 ++++++++++--------- .../routes/_route_options_object.md.erb | 12 +++++++ .../includes/resources/routes/_update.md.erb | 14 +++++--- docs/v3/source/index.html.md | 1 + 6 files changed, 66 insertions(+), 32 deletions(-) create mode 100644 docs/v3/source/includes/resources/routes/_route_options_object.md.erb diff --git a/docs/v3/source/includes/api_resources/_routes.erb b/docs/v3/source/includes/api_resources/_routes.erb index 3782b4a124f..c1448303e35 100644 --- a/docs/v3/source/includes/api_resources/_routes.erb +++ b/docs/v3/source/includes/api_resources/_routes.erb @@ -34,6 +34,9 @@ "protocol": "tcp" } ], + "options": { + "lb_algo": "round-robin" + }, "metadata": { "labels": <%= metadata.fetch(:labels, {}).to_json(space: ' ', object_nl: ' ')%>, "annotations": <%= metadata.fetch(:annotations, {}).to_json(space: ' ', object_nl: ' ')%> @@ -124,6 +127,9 @@ "protocol": "http1" } ], + "options": { + "lb_algo": "round-robin" + }, "metadata": { "labels": {}, "annotations": {} @@ -212,3 +218,9 @@ "protocol": "http2" } <% end %> + +<% content_for :route_options do %> + { + "lb_algo": "round-robin" + } +<% end %> diff --git a/docs/v3/source/includes/resources/routes/_create.md.erb b/docs/v3/source/includes/resources/routes/_create.md.erb index e6e28d87019..d0315ea03e1 100644 --- a/docs/v3/source/includes/resources/routes/_create.md.erb +++ b/docs/v3/source/includes/resources/routes/_create.md.erb @@ -21,6 +21,9 @@ curl "https://api.example.org/v3/routes" \ "data": { "guid": "space-guid" } } }, + "options": { + "lb_algo": "round-robin" + } "metadata": { "labels": { "key": "value" }, "annotations": { "note": "detailed information"} @@ -44,20 +47,21 @@ Content-Type: application/json #### Required parameters -| Name | Type | Description | -| ----------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| **relationships.space** | [_to-one relationship_](#to-one-relationships) | A relationship to the space containing the route; routes can only be mapped to destinations in that space | -| **relationships.domain** | [_to-one relationship_](#to-one-relationships) | A relationship to the domain of the route | +| Name | Type | Description | +|--------------------------|------------------------------------------------|-----------------------------------------------------------------------------------------------------------| +| **relationships.space** | [_to-one relationship_](#to-one-relationships) | A relationship to the space containing the route; routes can only be mapped to destinations in that space | +| **relationships.domain** | [_to-one relationship_](#to-one-relationships) | A relationship to the domain of the route | #### Optional parameters -| Name | Type | Description | -| ------------------------ | ----------------------------------- | --------------------------------- | -| **host** | _string_ | The host component for the route; not compatible with routes specifying the `tcp` protocol | -| **path** | _string_ | The path component for the route; should begin with a `/` and not compatible with routes specifying the `tcp` protocol | -| **port** | _integer_ | The port the route will listen on; only compatible with routes leveraging a domain that supports the `tcp` protocol. For `tcp` domains, a port will be randomly assigned if not specified -| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route | -| **metadata.labels** | [_label object_](#labels) | Labels applied to the route | +| Name | Type | Description | +|--------------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **host** | _string_ | The host component for the route; not compatible with routes specifying the `tcp` protocol | +| **path** | _string_ | The path component for the route; should begin with a `/` and not compatible with routes specifying the `tcp` protocol | +| **port** | _integer_ | The port the route will listen on; only compatible with routes leveraging a domain that supports the `tcp` protocol. For `tcp` domains, a port will be randomly assigned if not specified | +| **options** | [_route option object_](#the-route-options-object) | Options applied to the route | +| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route | +| **metadata.labels** | [_label object_](#labels) | Labels applied to the route | #### Permitted roles diff --git a/docs/v3/source/includes/resources/routes/_object.md.erb b/docs/v3/source/includes/resources/routes/_object.md.erb index 4809097f531..a0de69a1675 100644 --- a/docs/v3/source/includes/resources/routes/_object.md.erb +++ b/docs/v3/source/includes/resources/routes/_object.md.erb @@ -8,19 +8,20 @@ Example Route object <%= yield_content :single_route %> ``` -| Name | Type | Description -| -------------- | ------------------------ | ------------------------------------------------------ -| **guid** | _uuid_ | Unique identifier for the route -| **created_at** | _[timestamp](#timestamps)_ | The time with zone when the object was created -| **updated_at** | _[timestamp](#timestamps)_ | The time with zone when the object was last updated -| **protocol** | _string_ | The protocol supported by the route, based on the route's domain configuration. Valid protocols are `http` and `tcp` -| **host** | _string_ | The hostname for the route; not compatible with routes specifying the `tcp` protocol;
must be either a wildcard (*) or be under 63 characters long and only contain letters, numbers, dashes (-) or underscores(_) -| **path** | _string_ | The path for the route; not compatible with routes specifying the `tcp` protocol;
must be under 128 characters long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from [RFC 2396](https://tools.ietf.org/html/rfc2396) -| **port** | _integer or `null`_ | The port that the route listens on. Only compatible with routes specifying the `tcp` protocol -| **url** | _string_ | The URL for the route; URLs of protocol `http` are a combination of host, domain name, and path; URLs of protocol `tcp` are a combination of domain name and port -| **destinations** | array of [_destination objects_](#the-destination-object) | List of destinations for the route -| **relationships.space** | [_to-one relationship_](#to-one-relationships) | A relationship to the space containing the route. Routes can only be mapped to destinations in that space -| **relationships.domain** | [_to-one relationship_](#to-one-relationships) | A relationship to the domain of the route -| **metadata.labels** | [_label object_](#labels) | Labels applied to the route -| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route -| **links** | [_links object_](#links) | Links to related resources +| Name | Type | Description | +|--------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **guid** | _uuid_ | Unique identifier for the route | +| **created_at** | _[timestamp](#timestamps)_ | The time with zone when the object was created | +| **updated_at** | _[timestamp](#timestamps)_ | The time with zone when the object was last updated | +| **protocol** | _string_ | The protocol supported by the route, based on the route's domain configuration. Valid protocols are `http` and `tcp` | +| **host** | _string_ | The hostname for the route; not compatible with routes specifying the `tcp` protocol;
must be either a wildcard (*) or be under 63 characters long and only contain letters, numbers, dashes (-) or underscores(_) | +| **path** | _string_ | The path for the route; not compatible with routes specifying the `tcp` protocol;
must be under 128 characters long and not contain question marks (?), begin with a slash (/) and not be exactly a slash (/). Must conform to path components from [RFC 2396](https://tools.ietf.org/html/rfc2396) | +| **port** | _integer or `null`_ | The port that the route listens on. Only compatible with routes specifying the `tcp` protocol | +| **url** | _string_ | The URL for the route; URLs of protocol `http` are a combination of host, domain name, and path; URLs of protocol `tcp` are a combination of domain name and port | +| **destinations** | array of [_destination objects_](#the-destination-object) | List of destinations for the route | +| **relationships.space** | [_to-one relationship_](#to-one-relationships) | A relationship to the space containing the route. Routes can only be mapped to destinations in that space | +| **relationships.domain** | [_to-one relationship_](#to-one-relationships) | A relationship to the domain of the route | +| **options** | [_route option object_](#the-route-options-object) | Options applied to the route | +| **metadata.labels** | [_label object_](#labels) | Labels applied to the route | +| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route | +| **links** | [_links object_](#links) | Links to related resources | diff --git a/docs/v3/source/includes/resources/routes/_route_options_object.md.erb b/docs/v3/source/includes/resources/routes/_route_options_object.md.erb new file mode 100644 index 00000000000..c891ad9ee47 --- /dev/null +++ b/docs/v3/source/includes/resources/routes/_route_options_object.md.erb @@ -0,0 +1,12 @@ +### The route options object + +``` +Example Route-Options object +``` +```json +<%= yield_content :route_options %> +``` + +| Name | Type | Description | +|-------------|----------|----------------------------------------------------------------------------------------------------------| +| **lb_algo** | _string_ | The load balancer associated with this route. Valid algorithms are 'round-robin' and 'least-connections' | diff --git a/docs/v3/source/includes/resources/routes/_update.md.erb b/docs/v3/source/includes/resources/routes/_update.md.erb index d1fa9d5ea79..4814a23d171 100644 --- a/docs/v3/source/includes/resources/routes/_update.md.erb +++ b/docs/v3/source/includes/resources/routes/_update.md.erb @@ -10,6 +10,9 @@ curl "https://api.example.org/v3/routes/[guid]" \ -H "Authorization: bearer [token]" \ -H "Content-type: application/json" \ -d '{ + "options": { + "lb_algo": "round-robin" + } "metadata": { "labels": {"key": "value"}, "annotations": {"note": "detailed information"} @@ -33,14 +36,15 @@ Content-Type: application/json #### Optional parameters -| Name | Type | Description | Default | -| ----------- | -------- | ------------------------------------------------------------------------ | ------- | -| **metadata.labels** | [_label object_](#labels) | Labels applied to the route | | -| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route | | +| Name | Type | Description | Default | +|----------------------------|-----------------------------------------------------|----------------------------------|---------| +| **options** | [_route option object_](#the-route-options-object) | Options applied to the route | | +| **metadata.labels** | [_label object_](#labels) | Labels applied to the route | | +| **metadata.annotations** | [_annotation object_](#annotations) | Annotations applied to the route | | #### Permitted roles - | +| ----- | Admin | Space Developer | diff --git a/docs/v3/source/index.html.md b/docs/v3/source/index.html.md index cc60bfea116..03c63aecaca 100644 --- a/docs/v3/source/index.html.md +++ b/docs/v3/source/index.html.md @@ -243,6 +243,7 @@ includes: - resources/routes/header - resources/routes/object - resources/routes/destination_object + - resources/routes/route_options_object - resources/routes/create - resources/routes/get - resources/routes/list