docs(lb): add documentation (#2414)

Co-authored-by: Rémy Léone <rleone@scaleway.com>
scaleway · Jul 7, 2022 · d9d6b05 · d9d6b05
1 parent 963c835
commit d9d6b05
Show file tree

Hide file tree

Showing 3 changed files with 50 additions and 36 deletions.
diff --git a/cmd/scw/testdata/test-all-usage-lb-backend-update-usage.golden b/cmd/scw/testdata/test-all-usage-lb-backend-update-usage.golden
@@ -3,26 +3,26 @@
 Update a backend in a given load balancer.
 
 USAGE:
-  scw lb backend update [arg=value ...]
+  scw lb backend update <backend-id ...> [arg=value ...]
 
 ARGS:
-  backend-id                      
-  [name]                          
-  [forward-protocol]               (tcp | http)
-  [forward-port]                  
-  [forward-port-algorithm]         (roundrobin | leastconn | first)
-  [sticky-sessions]                (none | cookie | table)
-  [sticky-sessions-cookie-name]   
-  [timeout-server]                
-  [timeout-connect]               
-  [timeout-tunnel]                
-  [on-marked-down-action]          (on_marked_down_action_none | shutdown_sessions)
-  [proxy-protocol]                 (proxy_protocol_unknown | proxy_protocol_none | proxy_protocol_v1 | proxy_protocol_v2 | proxy_protocol_v2_ssl | proxy_protocol_v2_ssl_cn)
-  [failover-host]                 
+  backend-id                      Backend ID to update
+  name                            Resource name
+  forward-protocol                Backend protocol. TCP or HTTP (tcp | http)
+  forward-port                    User sessions will be forwarded to this port of backend servers
+  forward-port-algorithm          Load balancing algorithm (roundrobin | leastconn | first)
+  sticky-sessions                 Enable cookie-based session persistence (none | cookie | table)
+  [sticky-sessions-cookie-name]   Cookie name for for sticky sessions
+  [timeout-server]                Maximum server connection inactivity time
+  [timeout-connect]               Maximum initial server connection establishment time
+  [timeout-tunnel]                Maximum tunnel inactivity time
+  [on-marked-down-action]         Modify what occurs when a backend server is marked down (on_marked_down_action_none | shutdown_sessions)
+  [proxy-protocol]                PROXY protocol, forward client's address (must be supported by backend servers software) (proxy_protocol_unknown | proxy_protocol_none | proxy_protocol_v1 | proxy_protocol_v2 | proxy_protocol_v2_ssl | proxy_protocol_v2_ssl_cn)
+  [failover-host]                 Scaleway S3 bucket website to be served in case all backend servers are down
   [zone=fr-par-1]                 Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | nl-ams-1 | nl-ams-2 | pl-waw-1)
 
 DEPRECATED ARGS:
-  [send-proxy-v2]   
+  [send-proxy-v2]   Deprecated in favor of proxy_protocol field!
 
 FLAGS:
   -h, --help   help for update

diff --git a/docs/commands/lb.md b/docs/commands/lb.md
@@ -385,28 +385,28 @@ Update a backend in a given load balancer.
 **Usage:**
 
 ```
-scw lb backend update [arg=value ...]
+scw lb backend update <backend-id ...> [arg=value ...]
 ```
 
 
 **Args:**
 
 | Name |   | Description |
 |------|---|-------------|
-| backend-id | Required |  |
-| name |  |  |
-| forward-protocol | One of: `tcp`, `http` |  |
-| forward-port |  |  |
-| forward-port-algorithm | One of: `roundrobin`, `leastconn`, `first` |  |
-| sticky-sessions | One of: `none`, `cookie`, `table` |  |
-| sticky-sessions-cookie-name |  |  |
-| ~~send-proxy-v2~~ | Deprecated |  |
-| timeout-server |  |  |
-| timeout-connect |  |  |
-| timeout-tunnel |  |  |
-| on-marked-down-action | One of: `on_marked_down_action_none`, `shutdown_sessions` |  |
-| proxy-protocol | One of: `proxy_protocol_unknown`, `proxy_protocol_none`, `proxy_protocol_v1`, `proxy_protocol_v2`, `proxy_protocol_v2_ssl`, `proxy_protocol_v2_ssl_cn` |  |
-| failover-host |  |  |
+| backend-id | Required | Backend ID to update |
+| name | Required | Resource name |
+| forward-protocol | Required<br />One of: `tcp`, `http` | Backend protocol. TCP or HTTP |
+| forward-port | Required | User sessions will be forwarded to this port of backend servers |
+| forward-port-algorithm | Required<br />One of: `roundrobin`, `leastconn`, `first` | Load balancing algorithm |
+| sticky-sessions | Required<br />One of: `none`, `cookie`, `table` | Enable cookie-based session persistence |
+| sticky-sessions-cookie-name |  | Cookie name for for sticky sessions |
+| ~~send-proxy-v2~~ | Deprecated | Deprecated in favor of proxy_protocol field! |
+| timeout-server |  | Maximum server connection inactivity time |
+| timeout-connect |  | Maximum initial server connection establishment time |
+| timeout-tunnel |  | Maximum tunnel inactivity time |
+| on-marked-down-action | One of: `on_marked_down_action_none`, `shutdown_sessions` | Modify what occurs when a backend server is marked down |
+| proxy-protocol | One of: `proxy_protocol_unknown`, `proxy_protocol_none`, `proxy_protocol_v1`, `proxy_protocol_v2`, `proxy_protocol_v2_ssl`, `proxy_protocol_v2_ssl_cn` | PROXY protocol, forward client's address (must be supported by backend servers software) |
+| failover-host |  | Scaleway S3 bucket website to be served in case all backend servers are down |
 | zone | Default: `fr-par-1`<br />One of: `fr-par-1`, `fr-par-2`, `nl-ams-1`, `nl-ams-2`, `pl-waw-1` | Zone to target. If none is passed will use default zone from the config |
 
 

diff --git a/internal/namespaces/lb/v1/lb_cli.go b/internal/namespaces/lb/v1/lb_cli.go
@@ -918,89 +918,103 @@ func lbBackendUpdate() *core.Command {
 		ArgSpecs: core.ArgSpecs{
 			{
 				Name:       "backend-id",
+				Short:      `Backend ID to update`,
 				Required:   true,
 				Deprecated: false,
-				Positional: false,
+				Positional: true,
 			},
 			{
 				Name:       "name",
-				Required:   false,
+				Short:      `Resource name`,
+				Required:   true,
 				Deprecated: false,
 				Positional: false,
 			},
 			{
 				Name:       "forward-protocol",
-				Required:   false,
+				Short:      `Backend protocol. TCP or HTTP`,
+				Required:   true,
 				Deprecated: false,
 				Positional: false,
 				EnumValues: []string{"tcp", "http"},
 			},
 			{
 				Name:       "forward-port",
-				Required:   false,
+				Short:      `User sessions will be forwarded to this port of backend servers`,
+				Required:   true,
 				Deprecated: false,
 				Positional: false,
 			},
 			{
 				Name:       "forward-port-algorithm",
-				Required:   false,
+				Short:      `Load balancing algorithm`,
+				Required:   true,
 				Deprecated: false,
 				Positional: false,
 				EnumValues: []string{"roundrobin", "leastconn", "first"},
 			},
 			{
 				Name:       "sticky-sessions",
-				Required:   false,
+				Short:      `Enable cookie-based session persistence`,
+				Required:   true,
 				Deprecated: false,
 				Positional: false,
 				EnumValues: []string{"none", "cookie", "table"},
 			},
 			{
 				Name:       "sticky-sessions-cookie-name",
+				Short:      `Cookie name for for sticky sessions`,
 				Required:   false,
 				Deprecated: false,
 				Positional: false,
 			},
 			{
 				Name:       "send-proxy-v2",
+				Short:      `Deprecated in favor of proxy_protocol field!`,
 				Required:   false,
 				Deprecated: true,
 				Positional: false,
 			},
 			{
 				Name:       "timeout-server",
+				Short:      `Maximum server connection inactivity time`,
 				Required:   false,
 				Deprecated: false,
 				Positional: false,
 			},
 			{
 				Name:       "timeout-connect",
+				Short:      `Maximum initial server connection establishment time`,
 				Required:   false,
 				Deprecated: false,
 				Positional: false,
 			},
 			{
 				Name:       "timeout-tunnel",
+				Short:      `Maximum tunnel inactivity time`,
 				Required:   false,
 				Deprecated: false,
 				Positional: false,
 			},
 			{
 				Name:       "on-marked-down-action",
+				Short:      `Modify what occurs when a backend server is marked down`,
 				Required:   false,
 				Deprecated: false,
 				Positional: false,
 				EnumValues: []string{"on_marked_down_action_none", "shutdown_sessions"},
 			},
 			{
 				Name:       "proxy-protocol",
+				Short:      `PROXY protocol, forward client's address (must be supported by backend servers software)`,
 				Required:   false,
 				Deprecated: false,
 				Positional: false,
 				EnumValues: []string{"proxy_protocol_unknown", "proxy_protocol_none", "proxy_protocol_v1", "proxy_protocol_v2", "proxy_protocol_v2_ssl", "proxy_protocol_v2_ssl_cn"},
 			},
 			{
 				Name:       "failover-host",
+				Short:      `Scaleway S3 bucket website to be served in case all backend servers are down`,
 				Required:   false,
 				Deprecated: false,
 				Positional: false,