docs(k8s): review wording k8s docs (#2864)

Co-authored-by: Rémy Léone <rleone@scaleway.com>

Author: scaleway-bot

cmd/scw/testdata/test-all-usage-k8s-cluster-create-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-This method allows to create a new Kubernetes cluster on an account.
+Creates a new Kubernetes cluster on a Scaleway account.
 
 USAGE:
   scw k8s cluster create [arg=value ...]
@@ -14,28 +14,28 @@ EXAMPLES:
 
 ARGS:
   [project-id]                                           Project ID to use. If none is passed the default project ID will be used
-  [type]                                                 The type of the cluster
-  name=<generated>                                       The name of the cluster
-  [description]                                          The description of the cluster
-  [tags.{index}]                                         The tags associated with the cluster
-  version=latest                                         The Kubernetes version of the cluster
-  cni=cilium                                             The Container Network Interface (CNI) plugin that will run in the cluster (unknown_cni | cilium | calico | weave | flannel | kilo)
-  pools.{index}.name                                     The name of the pool
-  pools.{index}.node-type                                The node type is the type of Scaleway Instance wanted for the pool
-  [pools.{index}.placement-group-id]                     The placement group ID in which all the nodes of the pool will be created
-  [pools.{index}.autoscaling]                            The enablement of the autoscaling feature for the pool
-  pools.{index}.size                                     The size (number of nodes) of the pool
-  [pools.{index}.min-size]                               The minimum size of the pool
-  [pools.{index}.max-size]                               The maximum size of the pool
-  [pools.{index}.container-runtime]                      The container runtime for the nodes of the pool (unknown_runtime | docker | containerd | crio)
-  [pools.{index}.autohealing]                            The enablement of the autohealing feature for the pool
-  [pools.{index}.tags.{index}]                           The tags associated with the pool
-  [pools.{index}.kubelet-args.{key}]                     The Kubelet arguments to be used by this pool. Note that this feature is to be considered as experimental
+  [type]                                                 Type of the cluster
+  name=<generated>                                       Name of the cluster
+  [description]                                          Description of the cluster
+  [tags.{index}]                                         Tags associated with the cluster
+  version=latest                                         Kubernetes version of the cluster
+  cni=cilium                                             Container Network Interface (CNI) plugin that will run in the cluster (unknown_cni | cilium | calico | weave | flannel | kilo)
+  pools.{index}.name                                     Name of the pool
+  pools.{index}.node-type                                Node type is the type of Scaleway Instance wanted for the pool
+  [pools.{index}.placement-group-id]                     Placement group ID in which all the nodes of the pool will be created
+  [pools.{index}.autoscaling]                            Defines whether the autoscaling feature is enabled for the pool
+  pools.{index}.size                                     Size (number of nodes) of the pool
+  [pools.{index}.min-size]                               Minimum size of the pool
+  [pools.{index}.max-size]                               Maximum size of the pool
+  [pools.{index}.container-runtime]                      Container runtime for the nodes of the pool (unknown_runtime | docker | containerd | crio)
+  [pools.{index}.autohealing]                            Defines whether the autohealing feature is enabled for the pool
+  [pools.{index}.tags.{index}]                           Tags associated with the pool
+  [pools.{index}.kubelet-args.{key}]                     Kubelet arguments to be used by this pool. Note that this feature is to be considered as experimental
   [pools.{index}.upgrade-policy.max-unavailable]         The maximum number of nodes that can be not ready at the same time
   [pools.{index}.upgrade-policy.max-surge]               The maximum number of nodes to be created during the upgrade
-  [pools.{index}.zone]                                   The Zone in which the Pool's node will be spawn in
-  [pools.{index}.root-volume-type]                       The system volume disk type (default_volume_type | l_ssd | b_ssd)
-  [pools.{index}.root-volume-size]                       The system volume disk size
+  [pools.{index}.zone]                                   Zone in which the pool's nodes will be spawned
+  [pools.{index}.root-volume-type]                       System volume disk type (default_volume_type | l_ssd | b_ssd)
+  [pools.{index}.root-volume-size]                       System volume disk size
   [autoscaler-config.scale-down-disabled]                Disable the cluster autoscaler
   [autoscaler-config.scale-down-delay-after-add]         How long after scale up that scale down evaluation resumes
   [autoscaler-config.estimator]                          Type of resource estimator to be used in scale up (unknown_estimator | binpacking)
@@ -47,8 +47,8 @@ ARGS:
   [autoscaler-config.scale-down-utilization-threshold]   Node utilization level, defined as sum of requested resources divided by capacity, below which a node can be considered for scale down
   [autoscaler-config.max-graceful-termination-sec]       Maximum number of seconds the cluster autoscaler waits for pod termination when trying to scale down a node
   [auto-upgrade.enable]                                  Whether or not auto upgrade is enabled for the cluster
-  [auto-upgrade.maintenance-window.start-hour]           The start hour of the 2-hour maintenance window
-  [auto-upgrade.maintenance-window.day]                  The day of the week for the maintenance window (any | monday | tuesday | wednesday | thursday | friday | saturday | sunday)
+  [auto-upgrade.maintenance-window.start-hour]           Start time of the two-hour maintenance window
+  [auto-upgrade.maintenance-window.day]                  Day of the week for the maintenance window (any | monday | tuesday | wednesday | thursday | friday | saturday | sunday)
   [feature-gates.{index}]                                List of feature gates to enable
   [admission-plugins.{index}]                            List of admission plugins to enable
   [open-id-connect-config.issuer-url]                    URL of the provider which allows the API server to discover public signing keys
@@ -57,14 +57,14 @@ ARGS:
   [open-id-connect-config.username-prefix]               Prefix prepended to username
   [open-id-connect-config.groups-claim.{index}]          JWT claim to use as the user's group
   [open-id-connect-config.groups-prefix]                 Prefix prepended to group claims
-  [open-id-connect-config.required-claim.{index}]        Multiple key=value pairs that describes a required claim in the ID Token
+  [open-id-connect-config.required-claim.{index}]        Multiple key=value pairs that describes a required claim in the ID token
   [apiserver-cert-sans.{index}]                          Additional Subject Alternative Names for the Kubernetes API server certificate
   [organization-id]                                      Organization ID to use. If none is passed the default organization ID will be used
   [region=fr-par]                                        Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw)
 
 DEPRECATED ARGS:
-  [enable-dashboard]   The enablement of the Kubernetes Dashboard in the cluster
-  [ingress]            The Ingress Controller that will run in the cluster (unknown_ingress | none | nginx | traefik | traefik2)
+  [enable-dashboard]   Defines if the Kubernetes Dashboard is enabled in the cluster
+  [ingress]            Ingress Controller that will run in the cluster (unknown_ingress | none | nginx | traefik | traefik2)
 
 FLAGS:
   -h, --help   help for create

cmd/scw/testdata/test-all-usage-k8s-cluster-delete-usage.golden

@@ -1,16 +1,16 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-This method allows to delete a specific cluster and all its associated pools and nodes. Note that this method will not delete any Load Balancers or Block Volumes that are associated with the cluster.
+Deletes a specific cluster and all its associated pools and nodes. Note that this method will not delete any Load Balancers or Block Volumes that are associated with the cluster.
 
 USAGE:
   scw k8s cluster delete <cluster-id ...> [arg=value ...]
 
 EXAMPLES:
-  Delete a given cluster
+  Delete a cluster
     scw k8s cluster delete 11111111-1111-1111-111111111111
 
 ARGS:
-  cluster-id                    The ID of the cluster to delete
+  cluster-id                    ID of the cluster to delete
   [with-additional-resources]   Set true if you want to delete all volumes (including retain volume type) and loadbalancers whose name start with cluster ID
   [region=fr-par]               Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw)
 

cmd/scw/testdata/test-all-usage-k8s-cluster-get-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-This method allows to get details about a specific Kubernetes cluster.
+Get details about a specific Kubernetes cluster.
 
 USAGE:
   scw k8s cluster get <cluster-id ...> [arg=value ...]
 
 EXAMPLES:
-  Get a given cluster
+  Get a cluster information
     scw k8s cluster get 11111111-1111-1111-111111111111
 
 ARGS:

cmd/scw/testdata/test-all-usage-k8s-cluster-list-available-versions-usage.golden

@@ -1,16 +1,16 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-This method allows to list the versions that a specific Kubernetes cluster is allowed to upgrade to. Note that it will be every patch version greater than the actual one as well a one minor version ahead of the actual one. Upgrades skipping a minor version will not work.
+List the versions that a specific Kubernetes cluster is allowed to upgrade to. Results will comprise every patch version greater than the current patch, as well as one minor version ahead of the current version. Any upgrade skipping a minor version will not work.
 
 USAGE:
   scw k8s cluster list-available-versions <cluster-id ...> [arg=value ...]
 
 EXAMPLES:
-  List all available versions for a given cluster to upgrade to
+  List all available versions for a cluster to upgrade to
     scw k8s cluster list-available-versions 11111111-1111-1111-111111111111
 
 ARGS:
-  cluster-id        The ID of the cluster which the available Kuberentes versions will be listed from
+  cluster-id        ID of the cluster which the available Kuberentes versions will be listed from
   [region=fr-par]   Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-k8s-cluster-list-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-This method allows to list all the existing Kubernetes clusters in an account.
+List all the existing Kubernetes clusters in a specific Region.
 
 USAGE:
   scw k8s cluster list [arg=value ...]
 
 EXAMPLES:
-  List all the clusters on your default region
+  List all clusters on your default region
     scw k8s cluster list
 
   List the ready clusters on your default region
@@ -16,12 +16,12 @@ EXAMPLES:
     scw k8s cluster list region=fr-par name=cluster1
 
 ARGS:
-  [project-id]        The project ID on which to filter the returned clusters
-  [order-by]          The sort order of the returned clusters (created_at_asc | created_at_desc | updated_at_asc | updated_at_desc | name_asc | name_desc | status_asc | status_desc | version_asc | version_desc)
-  [name]              The name on which to filter the returned clusters
-  [status]            The status on which to filter the returned clusters (unknown | creating | ready | deleting | deleted | updating | locked | pool_required)
-  [type]              The type on which to filter the returned clusters
-  [organization-id]   The organization ID on which to filter the returned clusters
+  [project-id]        Project ID on which to filter the returned clusters
+  [order-by]          Sort order of the returned clusters (created_at_asc | created_at_desc | updated_at_asc | updated_at_desc | name_asc | name_desc | status_asc | status_desc | version_asc | version_desc)
+  [name]              Name on which to filter the returned clusters
+  [status]            Status on which to filter the returned clusters (unknown | creating | ready | deleting | deleted | updating | locked | pool_required)
+  [type]              Type on which to filter the returned clusters
+  [organization-id]   Organization ID on which to filter the returned clusters
   [region=fr-par]     Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw | all)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-k8s-cluster-reset-admin-token-usage.golden

@@ -1,16 +1,16 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-This method allows to reset the admin token for a specific Kubernetes cluster. This will invalidate the old admin token (which will not be usable after) and create a new one. Note that the redownload of the kubeconfig will be necessary to keep interacting with the cluster (if the old admin token was used).
+Reset the admin token for a specific Kubernetes cluster. This will invalidate the old admin token (which will not be usable afterwards) and create a new one. Note that you will need to redownload kubeconfig in order to keep interacting with the cluster.
 
 USAGE:
   scw k8s cluster reset-admin-token <cluster-id ...> [arg=value ...]
 
 EXAMPLES:
-  Reset the admin token for a given cluster
+  Reset the admin token for a cluster
     scw k8s cluster reset-admin-token 11111111-1111-1111-111111111111
 
 ARGS:
-  cluster-id        The ID of the cluster of which the admin token will be renewed
+  cluster-id        ID of the cluster on which the admin token will be renewed
   [region=fr-par]   Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-k8s-cluster-update-usage.golden

@@ -1,22 +1,22 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-This method allows to update a specific Kubernetes cluster. Note that this method is not made to upgrade a Kubernetes cluster.
+Update a specific Kubernetes cluster. Note that this method is designed to update details such as name, description, tags and configuration. However, you cannot upgrade a cluster with this method. To do so, use the dedicated endpoint.
 
 USAGE:
   scw k8s cluster update <cluster-id ...> [arg=value ...]
 
 EXAMPLES:
-  Enable dashboard on a given cluster
+  Enable dashboard on a cluster
     scw k8s cluster update 11111111-1111-1111-111111111111 enable-dashboard=true
 
-  Add TTLAfterFinished and ServiceNodeExclusion as feature gates on a given cluster
+  Add TTLAfterFinished and ServiceNodeExclusion as feature gates on a cluster
     scw k8s cluster update 11111111-1111-1111-111111111111 feature-gates.0=TTLAfterFinished feature-gates.1=ServiceNodeExclusion
 
 ARGS:
-  cluster-id                                             The ID of the cluster to update
-  [name]                                                 The new name of the cluster
-  [description]                                          The new description of the cluster
-  [tags.{index}]                                         The new tags associated with the cluster
+  cluster-id                                             ID of the cluster to update
+  [name]                                                 New external name of the cluster
+  [description]                                          New description of the cluster
+  [tags.{index}]                                         New tags associated with the cluster
   [autoscaler-config.scale-down-disabled]                Disable the cluster autoscaler
   [autoscaler-config.scale-down-delay-after-add]         How long after scale up that scale down evaluation resumes
   [autoscaler-config.estimator]                          Type of resource estimator to be used in scale up (unknown_estimator | binpacking)
@@ -28,8 +28,8 @@ ARGS:
   [autoscaler-config.scale-down-utilization-threshold]   Node utilization level, defined as sum of requested resources divided by capacity, below which a node can be considered for scale down
   [autoscaler-config.max-graceful-termination-sec]       Maximum number of seconds the cluster autoscaler waits for pod termination when trying to scale down a node
   [auto-upgrade.enable]                                  Whether or not auto upgrade is enabled for the cluster
-  [auto-upgrade.maintenance-window.start-hour]           The start hour of the 2-hour maintenance window
-  [auto-upgrade.maintenance-window.day]                  The day of the week for the maintenance window (any | monday | tuesday | wednesday | thursday | friday | saturday | sunday)
+  [auto-upgrade.maintenance-window.start-hour]           Start time of the two-hour maintenance window
+  [auto-upgrade.maintenance-window.day]                  Day of the week for the maintenance window (any | monday | tuesday | wednesday | thursday | friday | saturday | sunday)
   [feature-gates.{index}]                                List of feature gates to enable
   [admission-plugins.{index}]                            List of admission plugins to enable
   [open-id-connect-config.issuer-url]                    URL of the provider which allows the API server to discover public signing keys
@@ -38,13 +38,13 @@ ARGS:
   [open-id-connect-config.username-prefix]               Prefix prepended to username
   [open-id-connect-config.groups-claim.{index}]          JWT claim to use as the user's group
   [open-id-connect-config.groups-prefix]                 Prefix prepended to group claims
-  [open-id-connect-config.required-claim.{index}]        Multiple key=value pairs that describes a required claim in the ID Token
+  [open-id-connect-config.required-claim.{index}]        Multiple key=value pairs that describes a required claim in the ID token
   [apiserver-cert-sans.{index}]                          Additional Subject Alternative Names for the Kubernetes API server certificate
   [region=fr-par]                                        Region to target. If none is passed will use default region from the config (fr-par | nl-ams | pl-waw)
 
 DEPRECATED ARGS:
-  [enable-dashboard]   The new value of the Kubernetes Dashboard enablement
-  [ingress]            The new Ingress Controller for the cluster (unknown_ingress | none | nginx | traefik | traefik2)
+  [enable-dashboard]   New value of the Kubernetes Dashboard enablement
+  [ingress]            New Ingress Controller for the cluster (unknown_ingress | none | nginx | traefik | traefik2)
 
 FLAGS:
   -h, --help   help for update