From b7a0712e6b3ebb412dff2215e800aea8e36e491a Mon Sep 17 00:00:00 2001 From: tytv2 Date: Fri, 3 Jul 2026 22:20:42 +0700 Subject: [PATCH] docs(vks): AWS-CLI-style reference format for all commands Rewrite every docs/commands/vks/*.md into a consistent AWS-CLI-style reference: each option shows its type, description, Required, Default, Possible values, and Constraints; structure flags list their members plus Shorthand and JSON syntax. Adds a Global options note per command. Also fills in flags that were missing from the old docs (e.g. --dry-run on several commands) and corrects a few types (booleans/integers) sourced from the Go flag definitions and the API spec. Co-Authored-By: Claude Opus 4.8 --- docs/commands/vks/config-auto-healing.md | 74 ++++-- docs/commands/vks/config-auto-upgrade.md | 56 ++++- docs/commands/vks/create-cluster.md | 222 +++++++++++++----- docs/commands/vks/create-nodegroup.md | 222 ++++++++++++++---- .../vks/delete-auto-upgrade-config.md | 51 +++- docs/commands/vks/delete-cluster.md | 31 ++- docs/commands/vks/delete-nodegroup.md | 46 +++- docs/commands/vks/generate-kubeconfig.md | 39 ++- docs/commands/vks/get-cluster-events.md | 57 +++-- docs/commands/vks/get-cluster.md | 15 +- docs/commands/vks/get-nodegroup.md | 18 +- docs/commands/vks/get-quota.md | 15 +- docs/commands/vks/list-cluster-versions.md | 14 +- docs/commands/vks/list-clusters.md | 31 ++- docs/commands/vks/list-nodegroups.md | 38 ++- docs/commands/vks/list-nodes.md | 36 ++- docs/commands/vks/update-cluster.md | 61 +++-- docs/commands/vks/update-kubeconfig.md | 49 +++- .../commands/vks/update-nodegroup-metadata.md | 69 +++++- docs/commands/vks/update-nodegroup.md | 108 ++++++--- .../commands/vks/upgrade-nodegroup-version.md | 52 +++- docs/commands/vks/wait.md | 194 +++++++++++++-- 22 files changed, 1166 insertions(+), 332 deletions(-) diff --git a/docs/commands/vks/config-auto-healing.md b/docs/commands/vks/config-auto-healing.md index 9fbb692..4c58336 100644 --- a/docs/commands/vks/config-auto-healing.md +++ b/docs/commands/vks/config-auto-healing.md @@ -4,33 +4,68 @@ Configure auto-healing for a VKS cluster. Auto-healing automatically replaces unhealthy nodes to keep the cluster in a working state. +Only `--enable-auto-healing` is sent unconditionally. The optional threshold flags (`--max-unhealthy`, `--unhealthy-range`, `--timeout-unhealthy`) are only included in the request when explicitly provided on the command line. + +Use `--dry-run` to preview the configuration that would be sent without executing the request. + ## Synopsis ``` grn vks config-auto-healing --cluster-id - --enable-auto-healing + --enable-auto-healing [--max-unhealthy ] [--unhealthy-range ] [--timeout-unhealthy ] + [--dry-run] ``` ## Options -`--cluster-id` (required) -: The ID of the cluster. +**`--cluster-id`** (string) + +ID of the cluster to configure auto-healing for. + +- Required: Yes + +**`--enable-auto-healing`** (boolean) + +Enable or disable auto-healing. Pass `true` to enable or `false` to disable. + +- Required: Yes +- Possible values: `true`, `false` + +**`--max-unhealthy`** (string) + +Maximum proportion of unhealthy nodes tolerated before auto-healing is triggered. Accepts a percentage string. + +- Required: No +- Constraints: percentage string, e.g. `30%` + +**`--unhealthy-range`** (string) + +Unhealthy node count range. When the number of unhealthy nodes falls within this range, auto-healing is triggered. -`--enable-auto-healing` (required) -: Whether to enable auto-healing. Pass `--enable-auto-healing` to enable, or `--enable-auto-healing=false` to disable. +- Required: No +- Constraints: bracket-enclosed range string, e.g. `[2-5]` -`--max-unhealthy` (optional) -: Maximum number (or percentage) of unhealthy nodes tolerated, e.g. `30%`. +**`--timeout-unhealthy`** (integer) -`--unhealthy-range` (optional) -: The unhealthy range threshold. +Time in seconds that a node may remain unhealthy before it is replaced. -`--timeout-unhealthy` (optional) -: Time in seconds a node may stay unhealthy before it is replaced. +- Required: No +- Default: `0` + +**`--dry-run`** (boolean) + +Preview the configuration that would be sent without executing the request. + +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -39,7 +74,7 @@ Enable auto-healing with default thresholds: ```bash grn vks config-auto-healing \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ - --enable-auto-healing + --enable-auto-healing true ``` Enable auto-healing with custom thresholds: @@ -47,8 +82,9 @@ Enable auto-healing with custom thresholds: ```bash grn vks config-auto-healing \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ - --enable-auto-healing \ + --enable-auto-healing true \ --max-unhealthy 30% \ + --unhealthy-range '[2-5]' \ --timeout-unhealthy 300 ``` @@ -57,5 +93,15 @@ Disable auto-healing: ```bash grn vks config-auto-healing \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ - --enable-auto-healing=false + --enable-auto-healing false +``` + +Preview the configuration without applying it: + +```bash +grn vks config-auto-healing \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ + --enable-auto-healing true \ + --max-unhealthy 20% \ + --dry-run ``` diff --git a/docs/commands/vks/config-auto-upgrade.md b/docs/commands/vks/config-auto-upgrade.md index 70a5155..5c6a665 100644 --- a/docs/commands/vks/config-auto-upgrade.md +++ b/docs/commands/vks/config-auto-upgrade.md @@ -2,9 +2,11 @@ ## Description -Configure auto-upgrade schedule for a cluster. Sets the days and time when automatic Kubernetes version upgrades will be performed. +Configure the auto-upgrade schedule for a VKS cluster. Sets the days of the week and the time of day when automatic Kubernetes version upgrades will be performed. -> Formerly `set-auto-upgrade-config`. That name still works as a deprecated alias. +Use `--dry-run` to preview the configuration that would be sent without executing the request. + +> **Alias:** `set-auto-upgrade-config` is a deprecated alias retained for backward compatibility. Prefer `config-auto-upgrade`. ## Synopsis @@ -13,18 +15,42 @@ grn vks config-auto-upgrade --cluster-id --weekdays --time + [--dry-run] ``` ## Options -`--cluster-id` (required) -: The ID of the cluster. +**`--cluster-id`** (string) + +ID of the cluster to configure auto-upgrade for. + +- Required: Yes + +**`--weekdays`** (string) + +Days of the week on which auto-upgrade will run, comma-separated. + +- Required: Yes +- Possible values: `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun` +- Constraints: one or more values from the allowed set, e.g. `Mon,Wed,Fri` + +**`--time`** (string) + +Time of day at which auto-upgrade will run, in 24-hour `HH:mm` format. + +- Required: Yes +- Constraints: `HH:mm`, e.g. `03:00` -`--weekdays` (required) -: Days of the week to perform auto upgrade, comma-separated. Valid values: `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun`. Example: `Mon,Wed,Fri` +**`--dry-run`** (boolean) -`--time` (required) -: Time of day to perform auto upgrade in 24-hour format `HH:mm`. Example: `03:00` +Preview the configuration that would be sent without executing the request. + +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -32,7 +58,7 @@ Set auto-upgrade to run on weekdays at 3 AM: ```bash grn vks config-auto-upgrade \ - --cluster-id k8s-xxxxx \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ --weekdays Mon,Tue,Wed,Thu,Fri \ --time 03:00 ``` @@ -41,7 +67,17 @@ Set auto-upgrade to run on weekends at midnight: ```bash grn vks config-auto-upgrade \ - --cluster-id k8s-xxxxx \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ --weekdays Sat,Sun \ --time 00:00 ``` + +Preview the configuration without applying it: + +```bash +grn vks config-auto-upgrade \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ + --weekdays Mon,Wed,Fri \ + --time 02:00 \ + --dry-run +``` diff --git a/docs/commands/vks/create-cluster.md b/docs/commands/vks/create-cluster.md index 78c370d..ef63318 100644 --- a/docs/commands/vks/create-cluster.md +++ b/docs/commands/vks/create-cluster.md @@ -2,13 +2,11 @@ ## Description -Create a new VKS cluster (control plane only). This command provisions the cluster itself; add worker nodes afterwards with [create-nodegroup](create-nodegroup.md). +Create a new VKS cluster. By default only the control plane is provisioned; add worker nodes afterwards with [create-nodegroup](create-nodegroup.md). -Cluster names must be 5–20 characters, lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. +When `--network-type` is `TIGERA` or `CILIUM_OVERLAY`, `--cidr` is required. The load balancer and block store CSI plugins are enabled by default. -When `--network-type` is `TIGERA` or `CILIUM_OVERLAY`, the `--cidr` option is required. By default, both the load balancer plugin and the block store CSI plugin are enabled; use `--load-balancer-plugin disabled` or `--block-store-csi-plugin disabled` to turn them off. - -Use `--dry-run` to validate all parameters without sending a create request. +Use `--dry-run` to validate parameters without sending a create request. ## Synopsis @@ -19,6 +17,7 @@ grn vks create-cluster --network-type --vpc-id [--subnet-id ] + [--list-subnet-ids ] [--cidr ] [--description ] [--private-cluster ] @@ -28,7 +27,6 @@ grn vks create-cluster [--service-endpoint ] [--az-strategy ] [--secondary-subnets ] - [--list-subnet-ids ] [--node-netmask-size ] [--auto-upgrade-config ] [--auto-healing-config ] @@ -37,97 +35,198 @@ grn vks create-cluster ## Options -`--name` (required) -: Cluster name. Must be 5–20 characters, lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. +**`--name`** (string) + +Name of the cluster. + +- Required: Yes +- Constraints: 5–20 characters; lowercase letters, digits, and hyphens; must start and end with a letter or digit. + +**`--k8s-version`** (string) + +Kubernetes version for the cluster (e.g. `v1.29.13-vks.1740045600`). + +- Required: Yes +- See available versions with [list-cluster-versions](list-cluster-versions.md). + +**`--network-type`** (string) + +Cluster network plugin. + +- Required: Yes +- Possible values: `TIGERA`, `CILIUM_OVERLAY`, `CILIUM_NATIVE_ROUTING` + +**`--vpc-id`** (string) + +ID of the VPC to provision the cluster in. + +- Required: Yes + +**`--subnet-id`** (string) + +Subnet ID for the cluster control plane. + +- Required: No +- Provide `--subnet-id`, `--list-subnet-ids`, or neither — the server validates the combination. + +**`--list-subnet-ids`** (list<string>) + +Subnet IDs for the cluster, comma-separated. + +- Required: No +- Syntax: `sub-aaa,sub-bbb` + +**`--cidr`** (string) + +Pod CIDR block (e.g. `10.96.0.0/12`). + +- Required: Conditional — required when `--network-type` is `TIGERA` or `CILIUM_OVERLAY`. + +**`--description`** (string) + +Human-readable description for the cluster. + +- Required: No + +**`--private-cluster`** (string) + +Control-plane accessibility. `enabled` makes the control plane unreachable from the public internet. + +- Required: No +- Default: `disabled` +- Possible values: `enabled`, `disabled` + +**`--release-channel`** (string) + +Release channel for automatic upgrades. + +- Required: No +- Default: `STABLE` +- Possible values: `RAPID`, `STABLE` -`--k8s-version` (required) -: Kubernetes version for the cluster (e.g. `v1.29.1`). +**`--load-balancer-plugin`** (string) -`--network-type` (required) -: Network type for the cluster. Accepted values: `TIGERA`, `CILIUM_OVERLAY`, `CILIUM_NATIVE_ROUTING`. +Load balancer plugin state. -`--vpc-id` (required) -: VPC ID where the cluster will be provisioned. +- Required: No +- Default: `enabled` +- Possible values: `enabled`, `disabled` -`--subnet-id` (optional) -: Subnet ID for the cluster control plane. Optional per the API — provide either `--subnet-id` or `--list-subnet-ids` (or neither); the server validates. +**`--block-store-csi-plugin`** (string) -`--cidr` (optional) -: Pod CIDR block. Required when `--network-type` is `TIGERA` or `CILIUM_OVERLAY` (e.g. `10.96.0.0/12`). +Block store CSI plugin state. -`--description` (optional) -: Human-readable description for the cluster. +- Required: No +- Default: `enabled` +- Possible values: `enabled`, `disabled` -`--private-cluster` (optional, default `disabled`) -: Control plane accessibility. `enabled` makes the control plane inaccessible from the public internet. Accepted values: `enabled`, `disabled`. +**`--service-endpoint`** (string) -`--release-channel` (optional) -: Release channel for automatic upgrades. Accepted values: `RAPID`, `STABLE`. Default: `STABLE`. +Service endpoint state. -`--load-balancer-plugin` (optional, default `enabled`) -: Load balancer plugin state. Accepted values: `enabled`, `disabled`. +- Required: No +- Default: `disabled` +- Possible values: `enabled`, `disabled` -`--block-store-csi-plugin` (optional, default `enabled`) -: Block store CSI plugin state. Accepted values: `enabled`, `disabled`. +**`--az-strategy`** (string) -`--service-endpoint` (optional, default `disabled`) -: Service endpoint state. Accepted values: `enabled`, `disabled`. +Availability-zone strategy for the cluster. -`--az-strategy` (optional, default `SINGLE`) -: Availability-zone strategy for the cluster. +- Required: No +- Default: `SINGLE` -`--secondary-subnets` (optional) -: Comma-separated list of secondary subnet IDs. +**`--secondary-subnets`** (list<string>) -`--list-subnet-ids` (optional) -: Comma-separated list of subnet IDs for the cluster. +Secondary subnet IDs, comma-separated. -`--node-netmask-size` (optional) -: Node netmask size (integer). Only sent when explicitly provided. +- Required: No +- Syntax: `sub-aaa,sub-bbb` -`--auto-upgrade-config` (optional) -: Auto-upgrade schedule. Shorthand `time=03:00,weekdays=Mon` or JSON `{"weekdays":"Mon,Wed,Fri","time":"03:00"}`. Use JSON when `weekdays` has multiple days (shorthand splits on commas). +**`--node-netmask-size`** (integer) -`--auto-healing-config` (optional) -: Auto-healing config. Shorthand `enableAutoHealing=true,maxUnhealthy=20%,unhealthyRange=[2-5],timeoutUnhealthy=10` or JSON. `enableAutoHealing` is a boolean, `timeoutUnhealthy` an integer. +Node netmask size. Only sent when explicitly provided. -`--dry-run` (optional) -: Validate all parameters and print a report without sending the create request. +- Required: No + +**`--auto-upgrade-config`** (structure) + +Auto-upgrade schedule. Accepts shorthand or JSON. + +- Required: No +- Members: + - `weekdays` (string) — days to run auto-upgrade, e.g. `Mon,Wed,Fri` + - `time` (string) — time of day, 24-hour `HH:mm`, e.g. `03:00` + +Shorthand syntax (use JSON when `weekdays` has multiple days, since shorthand splits on commas): + +``` +time=03:00,weekdays=Mon +``` + +JSON syntax: + +```json +{"weekdays": "Mon,Wed,Fri", "time": "03:00"} +``` + +**`--auto-healing-config`** (structure) + +Auto-healing configuration. Accepts shorthand or JSON. + +- Required: No +- Members: + - `enableAutoHealing` (boolean) — enable or disable auto-healing + - `maxUnhealthy` (string) — maximum unhealthy nodes, e.g. `20%` + - `unhealthyRange` (string) — unhealthy node count range, e.g. `[2-5]` + - `timeoutUnhealthy` (integer) — unhealthy timeout in seconds + +Shorthand syntax: + +``` +enableAutoHealing=true,maxUnhealthy=20%,unhealthyRange=[2-5],timeoutUnhealthy=10 +``` + +JSON syntax: + +```json +{"enableAutoHealing": true, "maxUnhealthy": "20%", "unhealthyRange": "[2-5]", "timeoutUnhealthy": 10} +``` + +**`--dry-run`** (boolean) + +Validate parameters and print a report without sending the create request. + +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples -Create a cluster with CILIUM_NATIVE_ROUTING: +Create a cluster (control plane only) with CILIUM_NATIVE_ROUTING: ```bash grn vks create-cluster \ --name my-cluster \ - --k8s-version v1.29.1 \ + --k8s-version v1.29.13-vks.1740045600 \ --network-type CILIUM_NATIVE_ROUTING \ --vpc-id net-abc12345-0000-0000-0000-000000000001 \ --subnet-id sub-abc12345-0000-0000-0000-000000000001 ``` -Create a cluster with TIGERA network type (CIDR required): +Create a cluster with TIGERA (CIDR required) and auto-healing: ```bash grn vks create-cluster \ --name prod-cluster \ - --k8s-version v1.29.1 \ + --k8s-version v1.29.13-vks.1740045600 \ --network-type TIGERA \ --cidr 10.96.0.0/12 \ --vpc-id net-abc12345-0000-0000-0000-000000000001 \ - --subnet-id sub-abc12345-0000-0000-0000-000000000001 -``` - -Then add a node group: - -```bash -grn vks create-nodegroup \ - --cluster-id \ - --name default-ng \ - --flavor-id flv-2c4g \ - --disk-type SSD \ - --ssh-key-id key-abc12345-0000-0000-0000-000000000001 + --subnet-id sub-abc12345-0000-0000-0000-000000000001 \ + --auto-healing-config 'enableAutoHealing=true,maxUnhealthy=20%,timeoutUnhealthy=10' ``` Validate parameters without creating (dry run): @@ -135,9 +234,8 @@ Validate parameters without creating (dry run): ```bash grn vks create-cluster \ --name my-cluster \ - --k8s-version v1.29.1 \ + --k8s-version v1.29.13-vks.1740045600 \ --network-type CILIUM_NATIVE_ROUTING \ --vpc-id net-abc12345-0000-0000-0000-000000000001 \ - --subnet-id sub-abc12345-0000-0000-0000-000000000001 \ --dry-run ``` diff --git a/docs/commands/vks/create-nodegroup.md b/docs/commands/vks/create-nodegroup.md index fb45f4d..b8a25fb 100644 --- a/docs/commands/vks/create-nodegroup.md +++ b/docs/commands/vks/create-nodegroup.md @@ -2,7 +2,9 @@ ## Description -Create a new node group within an existing VKS cluster. Node group names must be 5–15 characters, lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. +Create a new node group within an existing VKS cluster. By default, one node is created with an Ubuntu OS image, a 100 GiB disk, and a SURGE upgrade strategy. + +Node group names must be 5–15 characters, contain only lowercase letters, digits, and hyphens, and must start and end with a letter or digit. Use `--dry-run` to validate parameters (name format, disk size range, node count range) without sending a create request. @@ -12,10 +14,10 @@ Use `--dry-run` to validate parameters (name format, disk size range, node count grn vks create-nodegroup --cluster-id --name - [--os ] --flavor-id --disk-type --ssh-key-id + [--os ] [--private-nodes ] [--num-nodes ] [--disk-size ] @@ -34,65 +36,193 @@ grn vks create-nodegroup ## Options -`--cluster-id` (required) -: ID of the cluster to add the node group to. +**`--cluster-id`** (string) + +ID of the cluster to add the node group to. + +- Required: Yes + +**`--name`** (string) + +Name of the node group. + +- Required: Yes +- Constraints: 5–15 characters; lowercase letters, digits, and hyphens; must start and end with a letter or digit. + +**`--flavor-id`** (string) + +Flavor (instance type) ID for the nodes. + +- Required: Yes + +**`--disk-type`** (string) + +Disk type ID for the node boot volumes (e.g. `SSD`, `NVME`). + +- Required: Yes + +**`--ssh-key-id`** (string) + +SSH key pair ID to inject into each node. + +- Required: Yes + +**`--os`** (string) + +Operating system image for the nodes. + +- Required: No +- Default: `ubuntu` +- Possible values: `ubuntu`, `linux`, `rocky` + +**`--private-nodes`** (string) + +Private nodes state. `enabled` means nodes will not have public IP addresses. + +- Required: No +- Default: `disabled` +- Possible values: `enabled`, `disabled` + +**`--num-nodes`** (integer) + +Number of nodes to create in the node group. + +- Required: No +- Default: `1` +- Constraints: 0–10 + +**`--disk-size`** (integer) + +Boot disk size in GiB. + +- Required: No +- Default: `100` +- Constraints: 20–5000 + +**`--security-groups`** (list<string>) + +Security group IDs to attach to the nodes, comma-separated. + +- Required: No +- Syntax: `secg-aaa111,secg-bbb222` + +**`--subnet-id`** (string) -`--name` (required) -: Node group name. Must be 5–15 characters, lowercase alphanumeric and hyphens, starting and ending with an alphanumeric character. +Subnet ID for the node group. Uses the cluster subnet when not specified. -`--os` (optional, default `ubuntu`) -: Node group OS image. Supported values: `ubuntu`, `linux`, `rocky`. +- Required: No -`--flavor-id` (required) -: Flavor (instance type) ID for the nodes. +**`--labels`** (map) -`--disk-type` (required) -: Disk type ID for the node boot volumes. +Kubernetes node labels as comma-separated `key=value` pairs. -`--ssh-key-id` (required) -: SSH key pair ID to inject into each node. +- Required: No +- Syntax: `env=prod,tier=app` -`--private-nodes` (optional, default `disabled`) -: Private nodes state. `enabled` means nodes will not have public IP addresses. Accepted values: `enabled`, `disabled`. +**`--taints`** (list<string>) -`--num-nodes` (optional) -: Number of nodes to create. Accepted range: 0–10. Default: `1`. +Kubernetes node taints as comma-separated `key=value:effect` entries. -`--disk-size` (optional) -: Boot disk size in GiB. Accepted range: 20–5000. Default: `100`. +- Required: No +- Syntax: `dedicated=gpu:NoSchedule` -`--security-groups` (optional) -: Comma-separated list of security group IDs to attach to the nodes (e.g. `sg-aaa111,sg-bbb222`). +**`--tags`** (map) -`--subnet-id` (optional) -: Subnet ID for the node group. Uses the cluster subnet when not specified. +Cloud tags for the node group as comma-separated `key=value` pairs. -`--labels` (optional) -: Comma-separated `key=value` pairs to add as Kubernetes node labels (e.g. `env=prod,tier=app`). +- Required: No +- Syntax: `team=platform,cost-center=42` + +**`--secondary-subnets`** (list<string>) + +Secondary subnet IDs for the node group, comma-separated. + +- Required: No +- Syntax: `sub-aaa,sub-bbb` + +**`--auto-scale`** (structure) + +Auto-scaling configuration for the node group. Accepts shorthand or JSON. + +- Required: No +- Members: + - `minSize` (integer) — minimum number of nodes; minimum value `0` + - `maxSize` (integer) — maximum number of nodes; minimum value `1` + +Shorthand syntax: + +``` +minSize=2,maxSize=10 +``` + +JSON syntax: + +```json +{"minSize": 2, "maxSize": 10} +``` + +**`--placement-group`** (structure) + +Placement group configuration for the node group. Accepts shorthand or JSON. + +- Required: No +- Members: + - `type` (string) — `NEW` to create a new placement group, `EXISTING` to use an existing one + - `placementGroupId` (string) — ID of an existing placement group; used when `type` is `EXISTING` + - `placementGroupName` (string) — name for a new placement group; used when `type` is `NEW` + +Shorthand syntax: + +``` +type=NEW,placementGroupName=pg-1 +``` + +JSON syntax: + +```json +{"type": "EXISTING", "placementGroupId": "server-group-06b86747-eaf7-47dd-9e41-579c2e30bfdd"} +``` + +**`--upgrade-config`** (structure) + +Upgrade strategy configuration for the node group. Accepts shorthand or JSON. + +- Required: No +- Default: `maxSurge=1,maxUnavailable=0,strategy=SURGE` +- Members: + - `strategy` (string) — upgrade strategy; currently only `SURGE` is supported + - `maxSurge` (integer) — maximum number of extra nodes added during upgrade; range 1–100 + - `maxUnavailable` (integer) — maximum number of nodes that may be unavailable during upgrade; range 0–100 + +Shorthand syntax: + +``` +maxSurge=1,maxUnavailable=0,strategy=SURGE +``` + +JSON syntax: + +```json +{"maxSurge": 1, "maxUnavailable": 0, "strategy": "SURGE"} +``` -`--taints` (optional) -: Comma-separated node taints in `key=value:effect` format (e.g. `dedicated=gpu:NoSchedule`). +**`--enable-encryption-volume`** (boolean) -`--tags` (optional) -: Comma-separated `key=value` pairs to attach as node group tags (e.g. `team=platform,cost-center=42`). +Enable encryption for the node boot volumes. -`--secondary-subnets` (optional) -: Comma-separated list of secondary subnet IDs for the node group. +- Required: No +- Default: `false` -`--auto-scale` (optional) -: Auto-scale configuration. Shorthand `minSize=2,maxSize=10` or JSON `{"minSize":2,"maxSize":10}`. +**`--dry-run`** (boolean) -`--placement-group` (optional) -: Placement group configuration. Shorthand `type=NEW,placementGroupName=pg-1` or JSON. `type` is `NEW` or `EXISTING`; use `placementGroupName` (with `NEW`) or `placementGroupId` (with `EXISTING`). +Validate parameters and print a report without sending the create request. -`--upgrade-config` (optional, default `maxSurge=1,maxUnavailable=0,strategy=SURGE`) -: Upgrade configuration. Shorthand `maxSurge=1,maxUnavailable=0,strategy=SURGE` or JSON `{"maxSurge":1,"maxUnavailable":0,"strategy":"SURGE"}`. +- Required: No +- Default: `false` -`--enable-encryption-volume` (optional) -: Enable encryption for the node boot volumes. +## Global options -`--dry-run` (optional) -: Validate parameters and print a report without sending the create request. +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -102,7 +232,6 @@ Create a basic node group: grn vks create-nodegroup \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ --name worker-ng \ - --os ubuntu \ --flavor-id flv-4c8g \ --disk-type SSD \ --ssh-key-id key-abc12345-0000-0000-0000-000000000001 @@ -114,7 +243,6 @@ Create a GPU node group with taints and labels: grn vks create-nodegroup \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ --name gpu-ng \ - --os ubuntu \ --flavor-id flv-8c32g-gpu \ --disk-type SSD \ --disk-size 200 \ @@ -125,13 +253,12 @@ grn vks create-nodegroup \ --enable-encryption-volume ``` -Create an auto-scaling node group with a custom upgrade config (shorthand and JSON are both accepted): +Create an auto-scaling node group with a custom upgrade config: ```bash grn vks create-nodegroup \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ --name auto-ng \ - --os ubuntu \ --flavor-id flv-4c8g \ --disk-type SSD \ --ssh-key-id key-abc12345-0000-0000-0000-000000000001 \ @@ -140,13 +267,12 @@ grn vks create-nodegroup \ --tags team=platform,env=prod ``` -Validate parameters without creating: +Validate parameters without creating (dry run): ```bash grn vks create-nodegroup \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ --name worker-ng \ - --os ubuntu \ --flavor-id flv-4c8g \ --disk-type SSD \ --ssh-key-id key-abc12345-0000-0000-0000-000000000001 \ diff --git a/docs/commands/vks/delete-auto-upgrade-config.md b/docs/commands/vks/delete-auto-upgrade-config.md index 0b0f2c9..3860a47 100644 --- a/docs/commands/vks/delete-auto-upgrade-config.md +++ b/docs/commands/vks/delete-auto-upgrade-config.md @@ -2,35 +2,68 @@ ## Description -Delete the auto-upgrade configuration for a cluster. This disables automatic Kubernetes version upgrades. +Delete the auto-upgrade configuration for a VKS cluster. Removing this configuration disables scheduled automatic Kubernetes version upgrades for the cluster. + +Before executing, the command displays the cluster ID whose auto-upgrade config will be removed. Unless `--force` is provided, you are prompted to confirm. Use `--dry-run` to see the preview without being prompted and without deleting anything. + +**This action is irreversible.** ## Synopsis ``` grn vks delete-auto-upgrade-config --cluster-id + [--dry-run] [--force] ``` ## Options -`--cluster-id` (required) -: The ID of the cluster. +**`--cluster-id`** (string) + +ID of the cluster whose auto-upgrade configuration will be deleted. + +- Required: Yes + +**`--dry-run`** (boolean) + +Display what would be deleted without sending the delete request. + +- Required: No +- Default: `false` + +**`--force`** (boolean) -`--force` (optional) -: Skip the confirmation prompt. +Skip the interactive confirmation prompt and delete immediately. Useful in non-interactive scripts. + +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples Delete auto-upgrade config with confirmation: ```bash -grn vks delete-auto-upgrade-config --cluster-id k8s-xxxxx -# Are you sure you want to delete the auto-upgrade config? (yes/no): yes +grn vks delete-auto-upgrade-config \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 +``` + +Preview what will be deleted without deleting: + +```bash +grn vks delete-auto-upgrade-config \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ + --dry-run ``` -Delete without confirmation (for scripting): +Delete without confirmation (for use in scripts): ```bash -grn vks delete-auto-upgrade-config --cluster-id k8s-xxxxx --force +grn vks delete-auto-upgrade-config \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ + --force ``` diff --git a/docs/commands/vks/delete-cluster.md b/docs/commands/vks/delete-cluster.md index fb6d01f..f5dd30e 100644 --- a/docs/commands/vks/delete-cluster.md +++ b/docs/commands/vks/delete-cluster.md @@ -2,9 +2,9 @@ ## Description -Delete a VKS cluster and all of its associated node groups. Before executing the delete, the command always fetches and displays a preview of the cluster and node groups that will be removed. +Delete a VKS cluster and all of its associated node groups. Before executing, the command fetches and displays a preview showing the cluster name, status, version, node count, and the list of node groups that will be removed. -Unless `--force` is provided, you will be prompted to type `yes` to confirm. Use `--dry-run` to see the preview without being prompted and without deleting anything. +Unless `--force` is provided, you are prompted to confirm. Use `--dry-run` to see the preview without being prompted and without deleting anything. **This action is irreversible.** @@ -19,14 +19,29 @@ grn vks delete-cluster ## Options -`--cluster-id` (required) -: ID of the cluster to delete. +**`--cluster-id`** (string) -`--dry-run` (optional) -: Display the resources that would be deleted without executing the delete request. +ID of the cluster to delete. -`--force` (optional) -: Skip the interactive confirmation prompt and delete immediately. +- Required: Yes + +**`--dry-run`** (boolean) + +Display the resources that would be deleted without sending the delete request. + +- Required: No +- Default: `false` + +**`--force`** (boolean) + +Skip the interactive confirmation prompt and delete immediately. Useful in non-interactive scripts. + +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples diff --git a/docs/commands/vks/delete-nodegroup.md b/docs/commands/vks/delete-nodegroup.md index 0a64e7c..cc97697 100644 --- a/docs/commands/vks/delete-nodegroup.md +++ b/docs/commands/vks/delete-nodegroup.md @@ -2,9 +2,9 @@ ## Description -Delete a specific node group from a VKS cluster. Before executing, the command always fetches and displays a preview of the node group that will be removed (name, status, node count). +Delete a specific node group from a VKS cluster. Before executing, the command fetches and displays a preview of the node group that will be removed (name, status, node count). -Unless `--force` is provided, you will be prompted to type `yes` to confirm. Use `--dry-run` to see the preview without being prompted and without deleting anything. Use `--force-delete` to instruct the API to perform a forced deletion. +Unless `--force` is provided, you are prompted to confirm. Use `--dry-run` to see the preview without being prompted and without deleting anything. Use `--force-delete` to instruct the API to perform a forced deletion. **This action is irreversible.** @@ -21,20 +21,42 @@ grn vks delete-nodegroup ## Options -`--cluster-id` (required) -: ID of the cluster that owns the node group. +**`--cluster-id`** (string) -`--nodegroup-id` (required) -: ID of the node group to delete. +ID of the cluster that owns the node group. -`--force-delete` (optional) -: Instruct the API to perform a forced deletion of the node group. +- Required: Yes -`--dry-run` (optional) -: Display the node group that would be deleted without executing the delete request. +**`--nodegroup-id`** (string) -`--force` (optional) -: Skip the interactive confirmation prompt and delete immediately. +ID of the node group to delete. + +- Required: Yes + +**`--force-delete`** (boolean) + +Instruct the API to perform a forced deletion of the node group. Passes `forceDelete=true` as a query parameter to the delete endpoint. + +- Required: No +- Default: `false` + +**`--dry-run`** (boolean) + +Display the node group that would be deleted without sending the delete request. + +- Required: No +- Default: `false` + +**`--force`** (boolean) + +Skip the interactive confirmation prompt and delete immediately. Useful in non-interactive scripts. + +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples diff --git a/docs/commands/vks/generate-kubeconfig.md b/docs/commands/vks/generate-kubeconfig.md index 4bd40c4..b905487 100644 --- a/docs/commands/vks/generate-kubeconfig.md +++ b/docs/commands/vks/generate-kubeconfig.md @@ -4,7 +4,9 @@ Request the VKS API to generate (or renew) a kubeconfig for a cluster. -This operation is **asynchronous**: the server accepts the request (HTTP 202) and generates the kubeconfig in the background. Once the kubeconfig becomes `ACTIVE`, run `grn vks update-kubeconfig` to fetch it and merge it into your local kubeconfig file. +This operation is asynchronous: the server accepts the request and generates the kubeconfig in the background. Once the kubeconfig status becomes `ACTIVE`, run [update-kubeconfig](update-kubeconfig.md) to fetch it and merge it into your local kubeconfig file. + +Use `--dry-run` to validate parameters and preview the request without sending it. ## Synopsis @@ -12,15 +14,34 @@ This operation is **asynchronous**: the server accepts the request (HTTP 202) an grn vks generate-kubeconfig --cluster-id [--expiration-days ] + [--dry-run] ``` ## Options -`--cluster-id` (required) -: The ID of the cluster. +**`--cluster-id`** (string) + +ID of the cluster for which to generate the kubeconfig. + +- Required: Yes + +**`--expiration-days`** (integer) + +Number of days until the generated kubeconfig expires. + +- Required: No +- Default: `30` + +**`--dry-run`** (boolean) + +Validate parameters and print a report without sending the generation request. -`--expiration-days` (optional) -: Number of days until the generated kubeconfig expires. Default: `30`. +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -42,3 +63,11 @@ grn vks generate-kubeconfig \ grn vks update-kubeconfig \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 ``` + +Preview the request without sending it: + +```bash +grn vks generate-kubeconfig \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ + --dry-run +``` diff --git a/docs/commands/vks/get-cluster-events.md b/docs/commands/vks/get-cluster-events.md index ba3797b..6c4ef45 100644 --- a/docs/commands/vks/get-cluster-events.md +++ b/docs/commands/vks/get-cluster-events.md @@ -2,7 +2,7 @@ ## Description -Get the list of events for a VKS cluster. Events can be filtered by action and type, and the results are paginated. +Retrieve the event log for a VKS cluster. Events record lifecycle actions such as cluster creation, upgrades, and scaling. Results can be filtered by action and event type, and are paginated (0-based page index). ## Synopsis @@ -17,37 +17,66 @@ grn vks get-cluster-events ## Options -`--cluster-id` (required) -: The ID of the cluster. +**`--cluster-id`** (string) -`--action` (optional) -: Filter events by action. +ID of the cluster whose events to retrieve. -`--type` (optional) -: Filter events by event type. +- Required: Yes -`--page` (optional) -: Page number to retrieve. Pagination is 0-based (page 0 is the first page). Default: `0`. +**`--action`** (string) -`--page-size` (optional) -: Number of events per page. Default: `50`. +Filter events by action name (e.g. `UPGRADE`, `CREATE`, `DELETE`). When omitted, all actions are returned. + +- Required: No + +**`--type`** (string) + +Filter events by event type (e.g. `INFO`, `WARNING`, `ERROR`). When omitted, all types are returned. + +- Required: No + +**`--page`** (integer) + +Page number to retrieve. Pagination is 0-based: page `0` is the first page. Only the specified page is returned; auto-pagination is not performed for this command. + +- Required: No +- Default: `0` + +**`--page-size`** (integer) + +Number of events to return per page. + +- Required: No +- Default: `50` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples -Get the first page of cluster events: +Get the first page of events for a cluster: ```bash grn vks get-cluster-events \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 ``` -Filter events by action and type with a custom page size: +Filter by action and event type with a custom page size: ```bash grn vks get-cluster-events \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ --action UPGRADE \ --type INFO \ - --page 0 \ --page-size 20 ``` + +Retrieve the second page of events: + +```bash +grn vks get-cluster-events \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ + --page 1 \ + --page-size 50 +``` diff --git a/docs/commands/vks/get-cluster.md b/docs/commands/vks/get-cluster.md index 7d1aaca..4842cb1 100644 --- a/docs/commands/vks/get-cluster.md +++ b/docs/commands/vks/get-cluster.md @@ -13,8 +13,15 @@ grn vks get-cluster ## Options -`--cluster-id` (required) -: The ID of the cluster to retrieve. +**`--cluster-id`** (string) + +ID of the cluster to retrieve. + +- Required: Yes + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -24,13 +31,13 @@ Get cluster details: grn vks get-cluster --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 ``` -Get cluster details and output as JSON: +Get cluster details as JSON: ```bash grn vks get-cluster --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 --output json ``` -Use with `jq` to extract just the cluster status: +Extract only the cluster status: ```bash grn vks get-cluster --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 --output json \ diff --git a/docs/commands/vks/get-nodegroup.md b/docs/commands/vks/get-nodegroup.md index be82fcd..f2e3914 100644 --- a/docs/commands/vks/get-nodegroup.md +++ b/docs/commands/vks/get-nodegroup.md @@ -14,11 +14,21 @@ grn vks get-nodegroup ## Options -`--cluster-id` (required) -: ID of the cluster that owns the node group. +**`--cluster-id`** (string) -`--nodegroup-id` (required) -: ID of the node group to retrieve. +ID of the cluster that owns the node group. + +- Required: Yes + +**`--nodegroup-id`** (string) + +ID of the node group to retrieve. + +- Required: Yes + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples diff --git a/docs/commands/vks/get-quota.md b/docs/commands/vks/get-quota.md index 4b8f755..e4eb68b 100644 --- a/docs/commands/vks/get-quota.md +++ b/docs/commands/vks/get-quota.md @@ -2,7 +2,7 @@ ## Description -Get VKS quota limits and current usage for the current user, including maximum number of clusters, node groups per cluster, nodes per node group, and current cluster count. +Get VKS quota limits and current usage for the authenticated user, including the maximum number of clusters, node groups per cluster, nodes per node group, and the current cluster count. ## Synopsis @@ -12,16 +12,11 @@ grn vks get-quota ## Options -No command-specific options. See [Global Options](../../usage/global-options.md) for flags available on all commands. +This command takes only the global options. -## Output fields +## Global options -| Field | Description | -|-------|-------------| -| `maxClusters` | Maximum number of clusters allowed | -| `maxNodeGroupsPerCluster` | Maximum number of node groups per cluster | -| `maxNodesPerNodeGroup` | Maximum number of nodes per node group | -| `numClusters` | Current number of clusters in use | +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -42,7 +37,7 @@ Output: } ``` -Get only the maximum cluster limit: +Extract only the maximum cluster limit: ```bash grn vks get-quota --query maxClusters diff --git a/docs/commands/vks/list-cluster-versions.md b/docs/commands/vks/list-cluster-versions.md index 1c1faa1..bc8eaa6 100644 --- a/docs/commands/vks/list-cluster-versions.md +++ b/docs/commands/vks/list-cluster-versions.md @@ -2,7 +2,7 @@ ## Description -List the Kubernetes versions available for VKS clusters. Use this to discover valid version strings before upgrading a cluster or node group. +List the Kubernetes versions available for VKS clusters. Use the version strings returned here as the value of `--k8s-version` when running [create-cluster](create-cluster.md) or upgrade commands. ## Synopsis @@ -12,7 +12,11 @@ grn vks list-cluster-versions ## Options -This command takes no options. +This command takes only the global options. + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -21,3 +25,9 @@ List available Kubernetes versions: ```bash grn vks list-cluster-versions ``` + +Extract only the version strings: + +```bash +grn vks list-cluster-versions --output json | jq '.[].version' +``` diff --git a/docs/commands/vks/list-clusters.md b/docs/commands/vks/list-clusters.md index 748d52e..78243cd 100644 --- a/docs/commands/vks/list-clusters.md +++ b/docs/commands/vks/list-clusters.md @@ -2,7 +2,7 @@ ## Description -List all VKS clusters. By default, automatically paginates through all pages and returns the complete result set. Use `--page` to fetch a specific page, or `--no-paginate` to return only the first page. +List all VKS clusters. By default, auto-pagination is enabled and the command fetches all pages, returning the complete result set. Pass `--page` to retrieve a single specific page, or `--no-paginate` to return only page 0 without fetching further pages. ## Synopsis @@ -15,14 +15,29 @@ grn vks list-clusters ## Options -`--page` (optional) -: Specific page number to fetch (0-based index). When provided, disables auto-pagination and returns only that page. +**`--page`** (integer) -`--page-size` (optional) -: Number of items per page. Default: `50`. +Page number to retrieve (0-based). When provided, disables auto-pagination and returns only the requested page. -`--no-paginate` (optional) -: Disable auto-pagination and return only the first page (page 0). Equivalent to `--page 0`. +- Required: No + +**`--page-size`** (integer) + +Number of clusters to return per page. + +- Required: No +- Default: `50` + +**`--no-paginate`** (boolean) + +Disable auto-pagination and return only page 0. Equivalent to `--page 0`. + +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -32,7 +47,7 @@ List all clusters (auto-paginated): grn vks list-clusters ``` -List clusters with custom page size: +List clusters with a custom page size: ```bash grn vks list-clusters --page-size 20 diff --git a/docs/commands/vks/list-nodegroups.md b/docs/commands/vks/list-nodegroups.md index 970f90d..302a5b4 100644 --- a/docs/commands/vks/list-nodegroups.md +++ b/docs/commands/vks/list-nodegroups.md @@ -2,7 +2,7 @@ ## Description -List all node groups belonging to a cluster. By default, automatically paginates through all pages and returns the complete result set. Use `--page` to fetch a specific page, or `--no-paginate` to return only the first page. +List all node groups belonging to a cluster. By default, auto-pagination is enabled and the command fetches all pages, returning the complete result set. Pass `--page` to retrieve a single specific page, or `--no-paginate` to return only page 0. ## Synopsis @@ -16,17 +16,35 @@ grn vks list-nodegroups ## Options -`--cluster-id` (required) -: ID of the cluster whose node groups to list. +**`--cluster-id`** (string) -`--page` (optional) -: Specific page number to fetch (0-based index). When provided, disables auto-pagination and returns only that page. +ID of the cluster whose node groups to list. -`--page-size` (optional) -: Number of items per page. Default: `50`. +- Required: Yes -`--no-paginate` (optional) -: Disable auto-pagination and return only the first page (page 0). +**`--page`** (integer) + +Page number to retrieve (0-based). When provided, disables auto-pagination and returns only the requested page. + +- Required: No + +**`--page-size`** (integer) + +Number of node groups to return per page. + +- Required: No +- Default: `50` + +**`--no-paginate`** (boolean) + +Disable auto-pagination and return only page 0. Equivalent to `--page 0`. + +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -44,7 +62,7 @@ grn vks list-nodegroups \ --page-size 20 ``` -Fetch only the first page: +Fetch only page 0: ```bash grn vks list-nodegroups \ diff --git a/docs/commands/vks/list-nodes.md b/docs/commands/vks/list-nodes.md index 18b03d8..3ac2647 100644 --- a/docs/commands/vks/list-nodes.md +++ b/docs/commands/vks/list-nodes.md @@ -2,7 +2,7 @@ ## Description -List the nodes belonging to a node group, including their status and details. Results are paginated. +List the nodes belonging to a node group, including their status and details. Results are paginated (0-based page index). Unlike `list-clusters` and `list-nodegroups`, this command does not auto-paginate; pass `--page` to navigate through result pages. ## Synopsis @@ -16,17 +16,35 @@ grn vks list-nodes ## Options -`--cluster-id` (required) -: ID of the cluster that owns the node group. +**`--cluster-id`** (string) -`--nodegroup-id` (required) -: ID of the node group whose nodes to list. +ID of the cluster that owns the node group. -`--page` (optional, default 0) -: Page number. Pagination is 0-based (page 0 is the first page). +- Required: Yes -`--page-size` (optional, default 50) -: Number of nodes per page. +**`--nodegroup-id`** (string) + +ID of the node group whose nodes to list. + +- Required: Yes + +**`--page`** (integer) + +Page number to retrieve. Pagination is 0-based: page `0` is the first page. + +- Required: No +- Default: `0` + +**`--page-size`** (integer) + +Number of nodes to return per page. + +- Required: No +- Default: `50` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples diff --git a/docs/commands/vks/update-cluster.md b/docs/commands/vks/update-cluster.md index 7a4f014..655e017 100644 --- a/docs/commands/vks/update-cluster.md +++ b/docs/commands/vks/update-cluster.md @@ -2,9 +2,11 @@ ## Description -Update a VKS cluster's Kubernetes version, whitelist CIDRs, and plugin configuration. The Kubernetes version and at least one whitelist CIDR are always required by the API, even when only updating plugin settings. +Update a VKS cluster's Kubernetes version, node CIDR whitelist, and plugin configuration. The cluster ID, target Kubernetes version, and at least one whitelist CIDR are always required by the API, even when the intent is only to toggle a plugin. -Use `--dry-run` to preview the update request without executing it. +Plugin flags (`--load-balancer-plugin`, `--block-store-csi-plugin`) are only sent when explicitly provided; omitting them leaves the current plugin state unchanged. + +Use `--dry-run` to preview the update payload without executing the request. ## Synopsis @@ -20,27 +22,56 @@ grn vks update-cluster ## Options -`--cluster-id` (required) -: ID of the cluster to update. +**`--cluster-id`** (string) + +ID of the cluster to update. + +- Required: Yes + +**`--k8s-version`** (string) + +Target Kubernetes version (e.g. `v1.29.1`). Must be the same or a higher version than the cluster's current version. + +- Required: Yes +- Constraints: 1–50 characters. +- See available versions with [list-cluster-versions](list-cluster-versions.md). + +**`--whitelist-node-cidrs`** (list<string>) + +CIDRs allowed to communicate with cluster nodes, comma-separated. At least one value is required. + +- Required: Yes +- Constraints: 1–30 entries. +- Syntax: `10.0.0.0/8,192.168.0.0/16` + +**`--load-balancer-plugin`** (string) + +Load balancer plugin state. When omitted, the current state is left unchanged. + +- Required: No +- Possible values: `enabled`, `disabled` + +**`--block-store-csi-plugin`** (string) + +Block store CSI plugin state. When omitted, the current state is left unchanged. + +- Required: No +- Possible values: `enabled`, `disabled` -`--k8s-version` (required) -: Target Kubernetes version (e.g. `v1.29.1`). Must be the same or a higher patch/minor version than the current version. +**`--dry-run`** (boolean) -`--whitelist-node-cidrs` (required) -: Comma-separated list of CIDRs allowed to communicate with cluster nodes. At least one value is required (e.g. `10.0.0.0/8,192.168.0.0/16`). +Print the update payload without sending the request. -`--load-balancer-plugin` (optional) -: Set the load balancer plugin state. When omitted, the current state is left unchanged. Accepted values: `enabled`, `disabled`. +- Required: No +- Default: `false` -`--block-store-csi-plugin` (optional) -: Set the block store CSI plugin state. When omitted, the current state is left unchanged. Accepted values: `enabled`, `disabled`. +## Global options -`--dry-run` (optional) -: Print the update payload without sending the request. +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples -Upgrade Kubernetes version and set whitelist CIDRs: +Upgrade the Kubernetes version and set whitelist CIDRs: ```bash grn vks update-cluster \ diff --git a/docs/commands/vks/update-kubeconfig.md b/docs/commands/vks/update-kubeconfig.md index dacd9f8..35d7fe4 100644 --- a/docs/commands/vks/update-kubeconfig.md +++ b/docs/commands/vks/update-kubeconfig.md @@ -2,12 +2,14 @@ ## Description -Fetch the cluster kubeconfig and merge it into your local kubeconfig file, then (by default) set it as the current context. This is similar to `aws eks update-kubeconfig`. +Fetch the cluster kubeconfig and merge it into your local kubeconfig file. By default the merged context is set as the current context. This is similar to `aws eks update-kubeconfig`. -The kubeconfig must already be `ACTIVE`. If no kubeconfig exists yet (status `NONE`), run `grn vks generate-kubeconfig --cluster-id ` first and wait until it becomes active. +The kubeconfig must already be `ACTIVE`. If no kubeconfig exists yet (status `NONE`), run [generate-kubeconfig](generate-kubeconfig.md) first and wait until it becomes active. The target file is resolved in this order: the `--kubeconfig` flag, then the first entry of `$KUBECONFIG`, then `~/.kube/config`. The merged context is named `vks_` by default; override it with `--alias`. +Use `--dry-run` to preview what would be written without modifying any file. + ## Synopsis ``` @@ -21,20 +23,43 @@ grn vks update-kubeconfig ## Options -`--cluster-id` (required) -: The ID of the cluster. +**`--cluster-id`** (string) + +ID of the cluster whose kubeconfig to fetch and merge. + +- Required: Yes + +**`--kubeconfig`** (string) + +Path to the kubeconfig file to update. + +- Required: No +- Default: first entry of `$KUBECONFIG`, or `~/.kube/config` + +**`--alias`** (string) + +Context name to use for the merged cluster entry. + +- Required: No +- Default: `vks_` + +**`--no-set-context`** (boolean) + +Do not set the merged context as the current context after merging. + +- Required: No +- Default: `false` + +**`--dry-run`** (boolean) -`--kubeconfig` (optional) -: Path to the kubeconfig file to update. Defaults to `$KUBECONFIG` (first entry) or `~/.kube/config`. +Print what would be written without modifying the kubeconfig file. -`--alias` (optional) -: Context name to use for the merged cluster. Default: `vks_`. +- Required: No +- Default: `false` -`--no-set-context` (optional) -: Do not set the merged context as the current context. +## Global options -`--dry-run` (optional) -: Print what would be written without modifying the kubeconfig file. +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples diff --git a/docs/commands/vks/update-nodegroup-metadata.md b/docs/commands/vks/update-nodegroup-metadata.md index 7b99a31..f1901c0 100644 --- a/docs/commands/vks/update-nodegroup-metadata.md +++ b/docs/commands/vks/update-nodegroup-metadata.md @@ -2,7 +2,11 @@ ## Description -Update the labels, tags, and taints of a node group. At least one of `--labels`, `--tags`, or `--taints` must be provided. +Update the labels, tags, and taints of a node group without touching its infrastructure. This is a partial-update (PATCH) operation: only the fields explicitly provided are changed; absent fields are left as-is. Sending an empty value for a field (e.g. `--labels ""`) clears that field. + +At least one of `--labels`, `--tags`, or `--taints` must be provided. + +Use `--dry-run` to preview the metadata patch without executing the request. ## Synopsis @@ -13,26 +17,57 @@ grn vks update-nodegroup-metadata [--labels ] [--tags ] [--taints ] + [--dry-run] ``` ## Options -`--cluster-id` (required) -: The ID of the cluster. +**`--cluster-id`** (string) -`--nodegroup-id` (required) -: The ID of the node group to update. +ID of the cluster that owns the node group. -`--labels` (optional) -: Comma-separated `key=value` pairs to set as Kubernetes node labels (e.g. `env=prod,tier=app`). +- Required: Yes -`--tags` (optional) -: Comma-separated `key=value` pairs to set as tags (e.g. `team=platform,cost-center=123`). +**`--nodegroup-id`** (string) -`--taints` (optional) -: Comma-separated node taints in `key=value:effect` format (e.g. `dedicated=gpu:NoSchedule`). +ID of the node group to update. -At least one of `--labels`, `--tags`, or `--taints` must be provided. +- Required: Yes + +**`--labels`** (map) + +Kubernetes node labels as comma-separated `key=value` pairs. Replaces the existing label set on all nodes in the group. + +- Required: Conditional — at least one of `--labels`, `--tags`, or `--taints` must be provided. +- Constraints: maximum 50 entries. Each key may have an optional DNS-subdomain prefix (`prefix/name`); the name segment must be 63 characters or less, alphanumeric with `-`, `_`, `.` allowed. +- Syntax: `env=prod,tier=app` + +**`--tags`** (map) + +Cloud tags for the node group resources as comma-separated `key=value` pairs. Replaces the existing tag set. + +- Required: Conditional — at least one of `--labels`, `--tags`, or `--taints` must be provided. +- Constraints: keys and values must be 3–63 characters, alphanumeric with `-`, `_`, `.` allowed, must start and end with alphanumeric. Reserved key prefixes (`vks-`, `vng.vks.`, `vng.vpc.`, `vng.billing.`, `vks-mgmt-`) are not allowed. +- Syntax: `team=platform,cost-center=123` + +**`--taints`** (list<string>) + +Kubernetes node taints as comma-separated `key=value:effect` entries. Replaces the existing taint set. + +- Required: Conditional — at least one of `--labels`, `--tags`, or `--taints` must be provided. +- Constraints: maximum 50 entries. +- Syntax: `dedicated=gpu:NoSchedule` + +**`--dry-run`** (boolean) + +Print the metadata patch payload without sending the request. + +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -55,3 +90,13 @@ grn vks update-nodegroup-metadata \ --tags team=platform \ --taints dedicated=gpu:NoSchedule ``` + +Preview the metadata patch (dry run): + +```bash +grn vks update-nodegroup-metadata \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ + --nodegroup-id ng-abc12345-6789-def0-1234-abcdef012345 \ + --labels env=staging \ + --dry-run +``` diff --git a/docs/commands/vks/update-nodegroup.md b/docs/commands/vks/update-nodegroup.md index b9db248..1bf8a10 100644 --- a/docs/commands/vks/update-nodegroup.md +++ b/docs/commands/vks/update-nodegroup.md @@ -2,11 +2,11 @@ ## Description -Update a node group's node count, security groups, auto-scaling configuration, and upgrade configuration. +Update a node group's desired node count, security groups, auto-scaling configuration, and upgrade configuration. At least one of `--num-nodes`, `--security-groups`, `--auto-scale`, or `--upgrade-config` must be provided. -To update labels, tags, or taints, use `grn vks update-nodegroup-metadata` — those fields are deprecated on `update-nodegroup`. +To update labels, tags, or taints, use [update-nodegroup-metadata](update-nodegroup-metadata.md) — those fields are deprecated on this command. -Use `--dry-run` to preview the update payload without executing it. +Use `--dry-run` to preview the update payload without executing the request. ## Synopsis @@ -23,26 +23,86 @@ grn vks update-nodegroup ## Options -`--cluster-id` (required) -: ID of the cluster that owns the node group. +**`--cluster-id`** (string) -`--nodegroup-id` (required) -: ID of the node group to update. +ID of the cluster that owns the node group. -`--num-nodes` (optional) -: New desired number of nodes for the node group. +- Required: Yes -`--security-groups` (optional) -: Comma-separated list of security group IDs to replace the current set. +**`--nodegroup-id`** (string) -`--auto-scale` (optional) -: Auto-scale configuration. Shorthand `minSize=2,maxSize=10` or JSON `{"minSize":2,"maxSize":10}`. +ID of the node group to update. -`--upgrade-config` (optional) -: Upgrade configuration. Shorthand `maxSurge=1,maxUnavailable=0,strategy=SURGE` or JSON `{"maxSurge":1,"maxUnavailable":0,"strategy":"SURGE"}`. +- Required: Yes -`--dry-run` (optional) -: Print the update payload without sending the request. +**`--num-nodes`** (string) + +New desired number of nodes. Parsed as an integer by the CLI. + +- Required: Conditional — at least one of `--num-nodes`, `--security-groups`, `--auto-scale`, or `--upgrade-config` must be provided. +- Constraints: 0–10. When `--auto-scale` is also set, must be within `[minSize, maxSize]`. + +**`--security-groups`** (list<string>) + +Security group IDs to replace the current set, comma-separated. + +- Required: Conditional — at least one update flag must be provided. +- Constraints: 1–50 entries. +- Syntax: `secg-aaa111,secg-bbb222` + +**`--auto-scale`** (structure) + +Auto-scaling configuration for the node group. Accepts shorthand or JSON. + +- Required: Conditional — at least one update flag must be provided. +- Members: + - `minSize` (integer) — minimum number of nodes; minimum value `0` + - `maxSize` (integer) — maximum number of nodes; minimum value `1` + +Shorthand syntax: + +``` +minSize=2,maxSize=10 +``` + +JSON syntax: + +```json +{"minSize": 2, "maxSize": 10} +``` + +**`--upgrade-config`** (structure) + +Upgrade strategy configuration for the node group. Accepts shorthand or JSON. + +- Required: Conditional — at least one update flag must be provided. +- Members: + - `strategy` (string) — upgrade strategy; currently only `SURGE` is supported + - `maxSurge` (integer) — maximum number of extra nodes added during upgrade; range 1–100 + - `maxUnavailable` (integer) — maximum number of nodes that may be unavailable during upgrade; range 0–100 + +Shorthand syntax: + +``` +maxSurge=1,maxUnavailable=0,strategy=SURGE +``` + +JSON syntax: + +```json +{"maxSurge": 1, "maxUnavailable": 0, "strategy": "SURGE"} +``` + +**`--dry-run`** (boolean) + +Print the update payload without sending the request. + +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -55,7 +115,7 @@ grn vks update-nodegroup \ --num-nodes 5 ``` -Set auto-scaling limits (shorthand or JSON): +Enable auto-scaling with min/max limits: ```bash grn vks update-nodegroup \ @@ -64,7 +124,7 @@ grn vks update-nodegroup \ --auto-scale minSize=2,maxSize=10 ``` -Set the upgrade configuration: +Set the upgrade configuration using JSON: ```bash grn vks update-nodegroup \ @@ -73,16 +133,6 @@ grn vks update-nodegroup \ --upgrade-config '{"maxSurge":2,"maxUnavailable":1,"strategy":"SURGE"}' ``` -To update labels, tags, or taints, use `update-nodegroup-metadata` (those fields are deprecated on `update-nodegroup`): - -```bash -grn vks update-nodegroup-metadata \ - --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ - --nodegroup-id ng-abc12345-6789-def0-1234-abcdef012345 \ - --labels env=prod,tier=app \ - --taints dedicated=gpu:NoSchedule -``` - Preview the update payload (dry run): ```bash diff --git a/docs/commands/vks/upgrade-nodegroup-version.md b/docs/commands/vks/upgrade-nodegroup-version.md index e6cf48c..ed9b0ba 100644 --- a/docs/commands/vks/upgrade-nodegroup-version.md +++ b/docs/commands/vks/upgrade-nodegroup-version.md @@ -2,9 +2,11 @@ ## Description -Upgrade the Kubernetes version of a node group within a cluster. +Upgrade the Kubernetes version of a node group within a cluster. The target version must be compatible with the cluster's current control-plane version. -Use `grn vks list-cluster-versions` to find the valid Kubernetes versions before running this command. +Use [list-cluster-versions](list-cluster-versions.md) to find valid Kubernetes versions before running this command. + +Use `--dry-run` to preview the upgrade payload without executing the request. ## Synopsis @@ -13,18 +15,40 @@ grn vks upgrade-nodegroup-version --cluster-id --nodegroup-id --k8s-version + [--dry-run] ``` ## Options -`--cluster-id` (required) -: The ID of the cluster. +**`--cluster-id`** (string) + +ID of the cluster that owns the node group. + +- Required: Yes + +**`--nodegroup-id`** (string) + +ID of the node group to upgrade. + +- Required: Yes + +**`--k8s-version`** (string) + +Target Kubernetes version for the node group (e.g. `v1.29.13-vks.1740045600`). + +- Required: Yes +- See available versions with [list-cluster-versions](list-cluster-versions.md). + +**`--dry-run`** (boolean) -`--nodegroup-id` (required) -: The ID of the node group to upgrade. +Print the upgrade payload without sending the request. -`--k8s-version` (required) -: The target Kubernetes version. Use `grn vks list-cluster-versions` to find valid versions. +- Required: No +- Default: `false` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples @@ -34,5 +58,15 @@ Upgrade a node group to a specific Kubernetes version: grn vks upgrade-nodegroup-version \ --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ --nodegroup-id ng-abc12345-6789-def0-1234-abcdef012345 \ - --k8s-version v1.29.0 + --k8s-version v1.29.13-vks.1740045600 +``` + +Preview the upgrade payload (dry run): + +```bash +grn vks upgrade-nodegroup-version \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ + --nodegroup-id ng-abc12345-6789-def0-1234-abcdef012345 \ + --k8s-version v1.29.13-vks.1740045600 \ + --dry-run ``` diff --git a/docs/commands/vks/wait.md b/docs/commands/vks/wait.md index a0c1191..790983c 100644 --- a/docs/commands/vks/wait.md +++ b/docs/commands/vks/wait.md @@ -2,55 +2,197 @@ ## Description -Poll until a VKS cluster or node group reaches a desired state. Exits with code `255` if the resource reaches a terminal failure state (`ERROR`/`FAILED`) or the wait times out. Use after asynchronous operations like create or delete. +Poll until a VKS cluster or node group reaches a desired state. Exits with code `255` if the resource reaches a terminal failure state (`ERROR` or `FAILED`) or the wait times out. Use after asynchronous operations such as create or delete. -## Synopsis +`wait` is a parent command. Invoke one of its four subcommands depending on the resource type and desired state: + +| Subcommand | Waits until | +|---|---| +| `cluster-active` | Cluster status is `ACTIVE` | +| `cluster-deleted` | Cluster no longer exists (HTTP 404) | +| `nodegroup-active` | Node group status is `ACTIVE` | +| `nodegroup-deleted` | Node group no longer exists (HTTP 404) | + +## cluster-active + +### Synopsis + +``` +grn vks wait cluster-active + --cluster-id + [--delay ] + [--max-attempts ] +``` + +### Options + +**`--cluster-id`** (string) + +ID of the cluster to poll. + +- Required: Yes + +**`--delay`** (integer) + +Seconds to wait between poll attempts. + +- Required: No +- Default: `30` + +**`--max-attempts`** (integer) + +Maximum number of poll attempts before the waiter times out. + +- Required: No +- Default: `40` + +## cluster-deleted + +### Synopsis ``` -grn vks wait cluster-active --cluster-id [--delay ] [--max-attempts ] -grn vks wait cluster-deleted --cluster-id [--delay ] [--max-attempts ] -grn vks wait nodegroup-active --cluster-id --nodegroup-id [--delay ] [--max-attempts ] -grn vks wait nodegroup-deleted --cluster-id --nodegroup-id [--delay ] [--max-attempts ] +grn vks wait cluster-deleted + --cluster-id + [--delay ] + [--max-attempts ] ``` -## Options +### Options + +**`--cluster-id`** (string) + +ID of the cluster to poll. + +- Required: Yes + +**`--delay`** (integer) + +Seconds to wait between poll attempts. + +- Required: No +- Default: `30` + +**`--max-attempts`** (integer) + +Maximum number of poll attempts before the waiter times out. + +- Required: No +- Default: `40` + +## nodegroup-active + +### Synopsis + +``` +grn vks wait nodegroup-active + --cluster-id + --nodegroup-id + [--delay ] + [--max-attempts ] +``` -`--cluster-id` (required) -: The ID of the cluster. +### Options -`--nodegroup-id` (required for `nodegroup-active` and `nodegroup-deleted`) -: The ID of the node group. +**`--cluster-id`** (string) -`--delay` (optional) -: Seconds between polls. Default: `30`. +ID of the cluster that owns the node group. -`--max-attempts` (optional) -: Maximum poll attempts before the waiter times out. Default: `40` for `cluster-active`, `cluster-deleted`, and `nodegroup-deleted`; `80` for `nodegroup-active`. +- Required: Yes -## Exit Codes +**`--nodegroup-id`** (string) -| Code | Meaning | -|------|---------| -| `0` | Resource reached the desired state | -| `255` | Resource reached `ERROR` or `FAILED` status, or waiter timed out | +ID of the node group to poll. + +- Required: Yes + +**`--delay`** (integer) + +Seconds to wait between poll attempts. + +- Required: No +- Default: `30` + +**`--max-attempts`** (integer) + +Maximum number of poll attempts before the waiter times out. + +- Required: No +- Default: `80` + +## nodegroup-deleted + +### Synopsis + +``` +grn vks wait nodegroup-deleted + --cluster-id + --nodegroup-id + [--delay ] + [--max-attempts ] +``` + +### Options + +**`--cluster-id`** (string) + +ID of the cluster that owns the node group. + +- Required: Yes + +**`--nodegroup-id`** (string) + +ID of the node group to poll. + +- Required: Yes + +**`--delay`** (integer) + +Seconds to wait between poll attempts. + +- Required: No +- Default: `30` + +**`--max-attempts`** (integer) + +Maximum number of poll attempts before the waiter times out. + +- Required: No +- Default: `40` + +## Global options + +This command also accepts the global options (`--profile`, `--region`, `--output`, `--query`, `--endpoint-url`, `--debug`, …). ## Examples -Wait for a cluster to become active: +Wait for a cluster to become active after creation: + +```bash +grn vks wait cluster-active \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 +``` + +Wait for a cluster to be fully deleted: ```bash -grn vks wait cluster-active --cluster-id k8s-xxxxx +grn vks delete-cluster --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 --force +grn vks wait cluster-deleted \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 ``` -Wait for a cluster to be fully deleted after `delete-cluster`: +Wait for a node group to become active, polling every 15 seconds: ```bash -grn vks delete-cluster --cluster-id k8s-xxxxx --force -grn vks wait cluster-deleted --cluster-id k8s-xxxxx +grn vks wait nodegroup-active \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ + --nodegroup-id ng-abc12345-6789-def0-1234-abcdef012345 \ + --delay 15 ``` Wait for a node group to be deleted: ```bash -grn vks wait nodegroup-deleted --cluster-id k8s-xxxxx --nodegroup-id ng-xxxxx +grn vks wait nodegroup-deleted \ + --cluster-id cls-abc12345-6789-def0-1234-abcdef012345 \ + --nodegroup-id ng-abc12345-6789-def0-1234-abcdef012345 ```