diff --git a/cmd/pouet/main.go b/cmd/pouet/main.go new file mode 100644 index 0000000000..af40442e7f --- /dev/null +++ b/cmd/pouet/main.go @@ -0,0 +1,17 @@ +package main + +import ( + "fmt" + + "github.com/scaleway/scaleway-cli/internal/namespaces" +) + +// This command is used to generate markdown documentation for each commands (custom or generated) of the CLI +func main() { + commands := namespaces.GetCommands() + for _, c := range commands.GetAll() { + if c.Namespace == "instance" { + fmt.Printf("%s %s %s | %s\n", c.Namespace, c.Resource, c.Verb, c.Short) + } + } +} diff --git a/cmd/scw-doc-gen/main.go b/cmd/scw-doc-gen/main.go new file mode 100644 index 0000000000..051a7a3086 --- /dev/null +++ b/cmd/scw-doc-gen/main.go @@ -0,0 +1,32 @@ +package main + +import ( + "flag" + "fmt" + "os" + + "github.com/scaleway/scaleway-cli/internal/docgen" + "github.com/scaleway/scaleway-cli/internal/namespaces" +) + +// This command is used to generate markdown documentation for each commands (custom or generated) of the CLI +func main() { + commands := namespaces.GetCommands() + + outDir := flag.String("outdir", "./docs/commands", "Directory where markdown will be created") + flag.Parse() + + stats, err := os.Stat(*outDir) + if err != nil { + panic(err) + } + + if !stats.IsDir() { + panic(fmt.Errorf("outdir %s must be a valid directory", *outDir)) + } + + err = docgen.GenerateDocs(commands, *outDir) + if err != nil { + panic(err) + } +} diff --git a/cmd/scw/main_test.go b/cmd/scw/main_test.go index 942bb1a52f..6d58c4dcd5 100644 --- a/cmd/scw/main_test.go +++ b/cmd/scw/main_test.go @@ -1,6 +1,7 @@ package main import ( + "strings" "testing" "github.com/scaleway/scaleway-cli/internal/core" @@ -27,7 +28,8 @@ func Test_AllUsage(t *testing.T) { } for _, cmd := range namespaces.GetCommands().GetAll() { - commandLine := cmd.GetCommandLine() + commandLine := cmd.GetCommandLine("scw") + commandLine = strings.TrimPrefix(commandLine, "scw ") if _, exists := excludedCommands[commandLine]; exists || cmd.Hidden { continue } diff --git a/cmd/scw/testdata/test-all-usage-autocomplete-usage.golden b/cmd/scw/testdata/test-all-usage-autocomplete-usage.golden new file mode 100644 index 0000000000..b0b8014642 --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-autocomplete-usage.golden @@ -0,0 +1,21 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +🟥🟥🟥 STDERR️️ 🟥🟥🟥️ +Autocomplete related commands + +USAGE: + scw autocomplete + +AVAILABLE COMMANDS: + install Install autocomplete script + script Show autocomplete script for current shell + +FLAGS: + -h, --help help for autocomplete + +GLOBAL FLAGS: + -c, --config string The path to the config file + -D, --debug Enable debug mode + -o, --output string Output format: json or human, see 'scw help output' for more info (default "human") + -p, --profile string The config profile to use + +Use "scw autocomplete [command] --help" for more information about a command. diff --git a/cmd/scw/testdata/test-main-usage-usage.golden b/cmd/scw/testdata/test-main-usage-usage.golden index 962e3a3548..6ef5e6b855 100644 --- a/cmd/scw/testdata/test-main-usage-usage.golden +++ b/cmd/scw/testdata/test-main-usage-usage.golden @@ -5,6 +5,7 @@ USAGE: AVAILABLE COMMANDS: account Account API + autocomplete Autocomplete related commands baremetal Baremetal API config Config file management feedback Send feedback to the Scaleway CLI Team! diff --git a/docs/commands/account.md b/docs/commands/account.md new file mode 100644 index 0000000000..6fd838893a --- /dev/null +++ b/docs/commands/account.md @@ -0,0 +1,152 @@ + +# Documentation for `scw account` +Account API + +- [SSH keys management commands](#ssh-keys-management-commands) + - [Add a SSH key to your organization](#add-a-ssh-key-to-your-organization) + - [Get a SSH key from your organization](#get-a-ssh-key-from-your-organization) + - [Initialize SSH key](#initialize-ssh-key) + - [List all SSH keys of your organization](#list-all-ssh-keys-of-your-organization) + - [Remove a SSH key from your organization](#remove-a-ssh-key-from-your-organization) + - [Update a SSH key on your organization](#update-a-ssh-key-on-your-organization) + + +## SSH keys management commands + +SSH keys management commands. + + +### Add a SSH key to your organization + +Add a SSH key to your organization. + +**Usage:** + +``` +scw account ssh-key add [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | | The name of the SSH key | +| public-key | Required | SSH public key. Currently ssh-rsa, ssh-dss (DSA), ssh-ed25519 and ecdsa keys with NIST curves are supported | +| project-id | | Project owning the resource | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | + + +**Examples:** + + +Add a given ssh key +``` +scw account ssh-key add name=foobar public_key="$(cat )" +``` + + + + +### Get a SSH key from your organization + +Get a SSH key from your organization. + +**Usage:** + +``` +scw account ssh-key get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| ssh-key-id | Required | The ID of the SSH key | + + + +### Initialize SSH key + +Initialize SSH key. + +**Usage:** + +``` +scw account ssh-key init +``` + + + +### List all SSH keys of your organization + +List all SSH keys of your organization. + +**Usage:** + +``` +scw account ssh-key list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| order-by | One of: `created_at_asc`, `created_at_desc`, `updated_at_asc`, `updated_at_desc`, `name_asc`, `name_desc` | | +| name | | | +| project-id | | | +| organization-id | | | + + + +### Remove a SSH key from your organization + +Remove a SSH key from your organization. + +**Usage:** + +``` +scw account ssh-key remove [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| ssh-key-id | Required | | + + +**Examples:** + + +Remove a given SSH key +``` +scw account ssh-key remove 11111111-1111-1111-1111-111111111111 +``` + + + + +### Update a SSH key on your organization + +Update a SSH key on your organization. + +**Usage:** + +``` +scw account ssh-key update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| ssh-key-id | Required | | +| name | | | + + + diff --git a/docs/commands/autocomplete.md b/docs/commands/autocomplete.md new file mode 100644 index 0000000000..4225c882f8 --- /dev/null +++ b/docs/commands/autocomplete.md @@ -0,0 +1,50 @@ + +# Documentation for `scw autocomplete` +Autocomplete related commands + +- [Install autocomplete script](#install-autocomplete-script) +- [Show autocomplete script for current shell](#show-autocomplete-script-for-current-shell) + + +## Install autocomplete script + +Install autocomplete script for a given shell and OS. + +Install autocomplete script for a given shell and OS. + +**Usage:** + +``` +scw autocomplete install [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| shell | | | + + + +## Show autocomplete script for current shell + +Show autocomplete script for current shell. + +Show autocomplete script for current shell. + +**Usage:** + +``` +scw autocomplete script [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| shell | Default: `/bin/zsh` | | + + + diff --git a/docs/commands/baremetal.md b/docs/commands/baremetal.md new file mode 100644 index 0000000000..a6bb7f6256 --- /dev/null +++ b/docs/commands/baremetal.md @@ -0,0 +1,396 @@ + +# Documentation for `scw baremetal` +Baremetal API + +- [Operating System (OS) management commands](#operating-system-(os)-management-commands) + - [Get an OS with a given ID](#get-an-os-with-a-given-id) + - [List all available OS that can be install on a baremetal server](#list-all-available-os-that-can-be-install-on-a-baremetal-server) +- [Server management commands](#server-management-commands) + - [Create a baremetal server](#create-a-baremetal-server) + - [Delete a baremetal server](#delete-a-baremetal-server) + - [Get a specific baremetal server](#get-a-specific-baremetal-server) + - [Install a baremetal server](#install-a-baremetal-server) + - [List baremetal servers](#list-baremetal-servers) + - [Reboot a baremetal server](#reboot-a-baremetal-server) + - [Start a baremetal server](#start-a-baremetal-server) + - [Stop a baremetal server](#stop-a-baremetal-server) + - [Update a baremetal server](#update-a-baremetal-server) + - [Wait for a server to reach a stable state (delivery and installation)](#wait-for-a-server-to-reach-a-stable-state-(delivery-and-installation)) + + +## Operating System (OS) management commands + +An Operating System (OS) is the underlying software installed on your server + + +### Get an OS with a given ID + +Return specific OS for the given ID. + +**Usage:** + +``` +scw baremetal os get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| os-id | Required | ID of the OS | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Get a specific OS ID +``` +scw baremetal os get +``` + + + + +### List all available OS that can be install on a baremetal server + +List all available OS that can be install on a baremetal server. + +**Usage:** + +``` +scw baremetal os list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| offer-id | | Filter OS by offer ID | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + + +## Server management commands + +A server is a denomination of a type of instances provided by Scaleway + + +### Create a baremetal server + +Create a new baremetal server. Once the server is created, you probably want to install an OS. + +**Usage:** + +``` +scw baremetal server create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | Required
Default: `` | Name of the server (≠hostname) | +| description | | Description associated to the server, max 255 characters | +| type | Default: `GP-BM1-S`
One of: `GP-BM1-L`, `GP-BM1-M`, `GP-BM1-S`, `HC-BM1-L`, `HC-BM1-S`, `HM-BM1-XL`, `HM-BM1-M` | Server commercial type | +| tags.{index} | | Tags to associate to the server | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Create instance +``` +scw baremetal server create +``` + +Create a GP-BM1-M instance, give it a name and add tags +``` +scw baremetal server create name=foo tags.0=prod tags.1=blue type=GP-BM1-M +``` + + + + +### Delete a baremetal server + +Delete the server associated with the given ID. + +**Usage:** + +``` +scw baremetal server delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server to delete | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Delete a baremetal server +``` +scw baremetal server delete 11111111-1111-1111-1111-111111111111 +``` + + + + +### Get a specific baremetal server + +Get the server associated with the given ID. + +**Usage:** + +``` +scw baremetal server get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Get a given server +``` +scw baremetal server get 11111111-1111-1111-1111-111111111111 +``` + + + + +### Install a baremetal server + +Install an OS on the server associated with the given ID. + +**Usage:** + +``` +scw baremetal server install [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | Server ID to install | +| os-id | Required | ID of the OS to install on the server | +| hostname | Required | Hostname of the server | +| all-ssh-keys | | Add all SSH keys on your baremetal instance (cannot be used with ssh-key-ids) | +| ssh-key-ids.{index} | Required | SSH key IDs authorized on the server (cannot be used with all-ssh-keys) | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Install an OS on a given server with a particular SSH key ID +``` +scw baremetal server install 11111111-1111-1111-1111-111111111111 os-id=11111111-1111-1111-1111-111111111111 ssh-key-ids.0=11111111-1111-1111-1111-111111111111 +``` + + + + +### List baremetal servers + +List baremetal servers. + +**Usage:** + +``` +scw baremetal server list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| order-by | One of: `created_at_asc`, `created_at_desc` | Order of the servers | +| tags.{index} | | Filter servers by tags | +| status.{index} | | Filter servers by status | +| name | | Filter servers by name | +| organization-id | | Filter servers by organization ID | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +List all servers on your default zone +``` +scw baremetal server list +``` + + + + +### Reboot a baremetal server + +Reboot the server associated with the given ID, use boot param to reboot in rescue. + +**Usage:** + +``` +scw baremetal server reboot [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server to reboot | +| boot-type | Default: `normal`
One of: `unknown_boot_type`, `normal`, `rescue` | The type of boot | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Reboot a server using the same os +``` +scw baremetal server reboot 11111111-1111-1111-1111-111111111111 +``` + +Reboot a server in rescue mode +``` +scw baremetal server reboot 11111111-1111-1111-1111-111111111111 boot-type=rescue +``` + + + + +### Start a baremetal server + +Start the server associated with the given ID. + +**Usage:** + +``` +scw baremetal server start [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server to start | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Start a baremetal server +``` +scw baremetal server start 11111111-1111-1111-1111-111111111111 +``` + + + + +### Stop a baremetal server + +Stop the server associated with the given ID. + +**Usage:** + +``` +scw baremetal server stop [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server to stop | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Stop a baremetal server +``` +scw baremetal server stop 11111111-1111-1111-1111-111111111111 +``` + + + + +### Update a baremetal server + +Update the server associated with the given ID. + +**Usage:** + +``` +scw baremetal server update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server to update | +| name | | Name of the server (≠hostname), not updated if null | +| description | | Description associated to the server, max 255 characters, not updated if null | +| tags.{index} | | Tags associated to the server, not updated if null | +| zone | Default: `fr-par-1`
One of: `fr-par-2` | Zone to target. If none is passed will use default zone from the config | + + + +### Wait for a server to reach a stable state (delivery and installation) + +Wait for a server to reach a stable state. This is similar to using --wait flag on other action commands, but without requiring a new action on the server. + +**Usage:** + +``` +scw baremetal server wait [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server affected by the action. | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Wait for a server to reach a stable state +``` +scw baremetal server wait 11111111-1111-1111-1111-111111111111 +``` + + + + diff --git a/docs/commands/config.md b/docs/commands/config.md new file mode 100644 index 0000000000..b840a0211c --- /dev/null +++ b/docs/commands/config.md @@ -0,0 +1,187 @@ + +# Documentation for `scw config` +Config management engine is common across all Scaleway developer tools (CLI, terraform, SDK, ... ). It allows to handle Scaleway config through two ways: environment variables and/or config file. + +Scaleway config file is self-documented. We recommend you to have a look at it at least once before using Scaleway developer tools: /Users/sieben/.config/scw/config.yaml + +In this CLI, environment variables have priority over the configuration file. + +The following environment variables are supported: + +|Environment Variable|Description| +|--|--| +|SCW_ACCESS_KEY|The access key of a token (create a token at https://console.scaleway.com/account/credentials)| +|SCW_SECRET_KEY|The secret key of a token (create a token at https://console.scaleway.com/account/credentials)| +|SCW_DEFAULT_ORGANIZATION_ID|The default organization ID (get your organization ID at https://console.scaleway.com/account/credentials)| +|SCW_DEFAULT_REGION|The default region| +|SCW_DEFAULT_ZONE|The default availability zone| +|SCW_API_URL|URL of the API| +|SCW_INSECURE|Set this to true to enable the insecure mode| +|SCW_PROFILE|Set the config profile to use| + +Read more about the config management engine at https://github.com/scaleway/scaleway-sdk-go/tree/master/scw#scaleway-config + +- [Dump the config file](#dump-the-config-file) +- [Get a value from the config file](#get-a-value-from-the-config-file) +- [Allows the deletion of a profile from the config file](#allows-the-deletion-of-a-profile-from-the-config-file) + - [Delete a profile from the config file](#delete-a-profile-from-the-config-file) +- [Reset the config](#reset-the-config) +- [Set a line from the config file](#set-a-line-from-the-config-file) +- [Unset a line from the config file](#unset-a-line-from-the-config-file) + + +## Dump the config file + + + + + +**Usage:** + +``` +scw config dump +``` + + + +## Get a value from the config file + + + + + +**Usage:** + +``` +scw config get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| key | Required
One of: `access-key`, `secret-key`, `api-url`, `insecure`, `default-organization-id`, `default-project-id`, `default-region`, `default-zone`, `send-telemetry` | the key to get from the configt | + + +**Examples:** + + +Get the default organization ID +``` +scw config get default_organization_id +``` + +Get the default region of the profile 'prod' +``` +scw -p prod config get default_region +``` + + + + +## Allows the deletion of a profile from the config file + + + + +### Delete a profile from the config file + + + +**Usage:** + +``` +scw config profile delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | Required | | + + + +## Reset the config + + + + + +**Usage:** + +``` +scw config reset +``` + + + +## Set a line from the config file + +This commands overwrites the configuration file parameters with user input. +The only allowed attributes are access_key, secret_key, default_organization_id, default_region, default_zone, api_url, insecure + +This commands overwrites the configuration file parameters with user input. +The only allowed attributes are access_key, secret_key, default_organization_id, default_region, default_zone, api_url, insecure + +**Usage:** + +``` +scw config set [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| access-key | | A Scaleway access key | +| secret-key | | A Scaleway secret key | +| api-url | | Scaleway API URL | +| insecure | | Set to true to allow insecure HTTPS connections | +| default-organization-id | | A default Scaleway organization id | +| default-project-id | | A default Scaleway project id | +| default-region | One of: `fr-par`, `nl-ams` | A default Scaleway region | +| default-zone | One of: `fr-par-1`, `fr-par-2`, `nl-ams-1` | A default Scaleway zone | +| send-telemetry | | Set to false to disable telemetry | + + +**Examples:** + + +Update the default organization ID +``` +scw config set default_organization_id=12903058-d0e8-4366-89c3-6e666abe1f6f +``` + +Update the default region of the profile 'prod' +``` +scw -p prod config set default_region=nl-ams +``` + + + + +## Unset a line from the config file + + + + + +**Usage:** + +``` +scw config unset [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| key | Required
One of: `access-key`, `secret-key`, `api-url`, `insecure`, `default-organization-id`, `default-project-id`, `default-region`, `default-zone`, `send-telemetry` | the config config key name to unset | + + + diff --git a/docs/commands/feedback.md b/docs/commands/feedback.md new file mode 100644 index 0000000000..f0b7b37d20 --- /dev/null +++ b/docs/commands/feedback.md @@ -0,0 +1,36 @@ + +# Documentation for `scw feedback` +Send feedback to the Scaleway CLI Team! + +- [Send a bug-report](#send-a-bug-report) +- [Send a feature request](#send-a-feature-request) + + +## Send a bug-report + +Send a bug-report to the Scaleway CLI team. + +Send a bug-report to the Scaleway CLI team. + +**Usage:** + +``` +scw feedback bug +``` + + + +## Send a feature request + +Send a feature request to the Scaleway CLI team. + +Send a feature request to the Scaleway CLI team. + +**Usage:** + +``` +scw feedback feature +``` + + + diff --git a/docs/commands/info.md b/docs/commands/info.md new file mode 100644 index 0000000000..105de22ad0 --- /dev/null +++ b/docs/commands/info.md @@ -0,0 +1,6 @@ + +# Documentation for `scw info` +Get info about current settings + + + diff --git a/docs/commands/init.md b/docs/commands/init.md new file mode 100644 index 0000000000..bc2f6c2d16 --- /dev/null +++ b/docs/commands/init.md @@ -0,0 +1,6 @@ + +# Documentation for `scw init` +Initialize the active profile of the config located in /Users/sieben/.config/scw/config.yaml + + + diff --git a/docs/commands/instance.md b/docs/commands/instance.md new file mode 100644 index 0000000000..20a240d153 --- /dev/null +++ b/docs/commands/instance.md @@ -0,0 +1,2181 @@ + +# Documentation for `scw instance` +Instance API + +- [Image management commands](#image-management-commands) + - [Create an instance image](#create-an-instance-image) + - [Delete an instance image](#delete-an-instance-image) + - [Get an instance image](#get-an-instance-image) + - [List instance images](#list-instance-images) + - [Wait for image to reach a stable state](#wait-for-image-to-reach-a-stable-state) +- [IP management commands](#ip-management-commands) + - [Reserve a flexible IP](#reserve-a-flexible-ip) + - [Delete a flexible IP](#delete-a-flexible-ip) + - [Get a flexible IP](#get-a-flexible-ip) + - [List all flexible IPs](#list-all-flexible-ips) + - [Update a flexible IP](#update-a-flexible-ip) +- [Placement group management commands](#placement-group-management-commands) + - [Create a placement group](#create-a-placement-group) + - [Delete the given placement group](#delete-the-given-placement-group) + - [Get a placement group](#get-a-placement-group) + - [List placement groups](#list-placement-groups) + - [Update a placement group](#update-a-placement-group) +- [Security group management commands](#security-group-management-commands) + - [Remove all rules of a security group](#remove-all-rules-of-a-security-group) + - [Create a security group](#create-a-security-group) + - [Delete a security group](#delete-a-security-group) + - [Get a security group](#get-a-security-group) + - [List security groups](#list-security-groups) + - [Update security group](#update-security-group) +- [Server management commands](#server-management-commands) + - [Attach a volume to a server](#attach-a-volume-to-a-server) + - [Backup server](#backup-server) + - [Connect to the serial console of an instance](#connect-to-the-serial-console-of-an-instance) + - [Create server](#create-server) + - [Delete server](#delete-server) + - [Detach a volume from its server](#detach-a-volume-from-its-server) + - [Get a server](#get-a-server) + - [List all servers](#list-all-servers) + - [Reboot server](#reboot-server) + - [SSH into a server](#ssh-into-a-server) + - [Put server in standby mode](#put-server-in-standby-mode) + - [Power on server](#power-on-server) + - [Power off server](#power-off-server) + - [Terminate server](#terminate-server) + - [Update a server](#update-a-server) + - [Wait for server to reach a stable state](#wait-for-server-to-reach-a-stable-state) +- [Server type management commands](#server-type-management-commands) + - [List server types](#list-server-types) +- [Snapshot management commands](#snapshot-management-commands) + - [Create a snapshot from a given volume](#create-a-snapshot-from-a-given-volume) + - [Delete a snapshot](#delete-a-snapshot) + - [Get a snapshot](#get-a-snapshot) + - [List snapshots](#list-snapshots) + - [Wait for snapshot to reach a stable state](#wait-for-snapshot-to-reach-a-stable-state) +- [User data management commands](#user-data-management-commands) + - [Delete user data](#delete-user-data) + - [Get user data](#get-user-data) + - [List user data](#list-user-data) + - [Add/Set user data](#addset-user-data) +- [Volume management commands](#volume-management-commands) + - [Create a volume](#create-a-volume) + - [Delete a volume](#delete-a-volume) + - [Get a volume](#get-a-volume) + - [List volumes](#list-volumes) + - [Update a volume](#update-a-volume) +- [Volume type management commands](#volume-type-management-commands) + - [List volumes types](#list-volumes-types) + + +## Image management commands + +Images are backups of your instances. +You can reuse that image to restore your data or create a series of instances with a predefined configuration. + +An image is a complete backup of your server including all volumes. + + + +### Create an instance image + +Create an instance image. + +**Usage:** + +``` +scw instance image create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | Default: `` | Name of the image | +| snapshot-id | Required | UUID of the snapshot that will be used as root volume in the image | +| arch | Required
One of: `x86_64`, `arm` | Architecture of the image | +| default-bootscript | | Default bootscript of the image | +| additional-snapshots.{key}.id | | UUID of the snapshot to add | +| additional-snapshots.{key}.name | | Name of the additional snapshot | +| additional-snapshots.{key}.size | | Size of the additional snapshot | +| additional-snapshots.{key}.volume-type | One of: `l_ssd`, `b_ssd` | Underlying volume type of the additional snapshot | +| additional-snapshots.{key}.organization-id | | Organization ID that own the additional snapshot | +| public | | True to create a public image | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Create an image named 'foobar' for x86_64 instances from the given root_volume ID (root_volume ID needs to be a snapshot UUID) +``` +scw instance image create name=foobar root-volume=11111111-1111-1111-1111-111111111111 arch=x86_64 +``` + + + + +### Delete an instance image + +Delete the image with the given ID. + +**Usage:** + +``` +scw instance image delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| image-id | Required | | +| with-snapshots | | Delete the snapshots attached to this image | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Delete an image in the default zone with the given ID +``` +scw instance image delete 11111111-1111-1111-1111-111111111111 +``` + +Delete an image in fr-par-1 zone with the given ID +``` +scw instance image delete 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + + + + +### Get an instance image + +Get details of an image with the given ID. + +**Usage:** + +``` +scw instance image get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| image-id | Required | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Get an image in the default zone with the given ID +``` +scw instance image get 11111111-1111-1111-1111-111111111111 +``` + +Get an image in fr-par-1 zone with the given ID +``` +scw instance image get 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + + + + +### List instance images + +List all images available in an account. + +**Usage:** + +``` +scw instance image list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | | | +| public | | | +| arch | | | +| organization-id | | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +List all public images in the default zone +``` +scw instance image list +``` + + + + +### Wait for image to reach a stable state + +Wait for image to reach a stable state. This is similar to using --wait flag on other action commands, but without requiring a new action on the image. + +**Usage:** + +``` +scw instance image wait [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| image-id | Required | ID of the image. | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Wait for a image to reach a stable state +``` +scw instance image wait 11111111-1111-1111-1111-111111111111 +``` + + + + +## IP management commands + +A flexible IP address is an IP address which you hold independently of any server. +You can attach it to any of your servers and do live migration of the IP address between your servers. + +Be aware that attaching a flexible IP address to a server will remove the previous public IP address of the server and cut any ongoing public connection to the server. + + + +### Reserve a flexible IP + +Reserve a flexible IP. + +**Usage:** + +``` +scw instance ip create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| project-id | | The project ID the IP is reserved in | +| server | | UUID of the server you want to attach the IP to | +| tags.{index} | | An array of keywords you want to tag this IP with | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Create an IP in the default zone +``` +scw instance ip create +``` + +Create an IP in fr-par-1 zone +``` +scw instance ip create zone=fr-par-1 +``` + +Create an IP and attach it to the given server +``` +scw instance ip create server=11111111-1111-1111-1111-111111111111 +``` + + + + +### Delete a flexible IP + +Delete the IP with the given ID. + +**Usage:** + +``` +scw instance ip delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| ip | Required | The ID or the address of the IP to delete | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Delete an IP in the default zone with the given ID +``` +scw instance ip delete 11111111-1111-1111-1111-111111111111 +``` + +Delete an IP in fr-par-1 zone with the given ID +``` +scw instance ip delete 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + +Delete an IP using directly the given IP address +``` +scw instance ip delete 51.15.253.183 +``` + + + + +### Get a flexible IP + +Get details of an IP with the given ID or address. + +**Usage:** + +``` +scw instance ip get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| ip | Required | The IP ID or address to get | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Get an IP in the default zone with the given ID +``` +scw instance ip get 11111111-1111-1111-1111-111111111111 +``` + +Get an IP in fr-par-1 zone with the given ID +``` +scw instance ip get 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + +Get an IP using directly the given IP address +``` +scw instance ip get +``` + + + + +### List all flexible IPs + +List all flexible IPs. + +**Usage:** + +``` +scw instance ip list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| project | | The project ID the IPs are reserved in | +| name | | Filter on the IP address (Works as a LIKE operation on the IP address) | +| organization-id | | The organization ID the IPs are reserved in | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +List all IPs in the default zone +``` +scw instance ip list +``` + +List all IPs in fr-par-1 zone +``` +scw instance ip list zone=fr-par-1 +``` + + + + +### Update a flexible IP + +Update a flexible IP. + +**Usage:** + +``` +scw instance ip update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| ip | Required | IP ID or IP address | +| reverse | | Reverse domain name | +| tags.{index} | | An array of keywords you want to tag this IP with | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Update an IP in the default zone with the given ID +``` +scw instance ip update 11111111-1111-1111-1111-111111111111 reverse=example.com +``` + +Update an IP in fr-par-1 zone with the given ID +``` +scw instance ip update 11111111-1111-1111-1111-111111111111 zone=fr-par-1 reverse=example.com +``` + +Update an IP using directly the given IP address +``` +scw instance ip update 51.15.253.183 reverse=example.com +``` + + + + +## Placement group management commands + +Placement groups allow the user to express a preference regarding +the physical position of a group of instances. It'll let the user +choose to either group instances on the same physical hardware for +best network throughput and low latency or to spread instances on +far away hardware to reduce the risk of physical failure. + +The operating mode is selected by a `policy_type`. Two policy +types are available: + - `low_latency` will group instances on the same hypervisors + - `max_availability` will spread instances on far away hypervisors + +The `policy_type` is set by default to `max_availability`. + +For each policy types, one of the two `policy_mode` may be selected: + - `optional` will start your instances even if the constraint is not respected + - `enforced` guarantee that if the instance starts, the constraint is respected + +The `policy_mode` is set by default to `optional`. + + + +### Create a placement group + +Create a new placement group. + +**Usage:** + +``` +scw instance placement-group create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | Default: `` | Name of the placement group | +| policy-mode | One of: `optional`, `enforced` | | +| policy-type | One of: `max_availability`, `low_latency` | | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Create a placement group with default name +``` +scw instance placement-group create +``` + +Create a placement group with the given name +``` +scw instance placement-group create name=foobar +``` + +Create an enforced placement group +``` +scw instance placement-group create policy-mode=enforced +``` + +Create an optional placement group +``` +scw instance placement-group create policy-mode=optional +``` + +Create an optional low latency placement group +``` +scw instance placement-group create policy-mode=optional policy-type=low_latency +``` + +Create an enforced low latency placement group +``` +scw instance placement-group create policy-mode=enforced policy-type=low_latency +``` + + + + +### Delete the given placement group + +Delete the given placement group. + +**Usage:** + +``` +scw instance placement-group delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| placement-group-id | Required | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Delete a placement group in the default zone with the given ID +``` +scw instance placement-group delete 11111111-1111-1111-1111-111111111111 +``` + +Delete a placement group in fr-par-1 zone with the given ID +``` +scw instance placement-group delete 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + + + + +### Get a placement group + +Get the given placement group. + +**Usage:** + +``` +scw instance placement-group get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| placement-group-id | Required | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Get a placement group with the given ID +``` +scw instance placement-group get 6c15f411-3b6f-402d-8eba-ae24ef9254e9 +``` + + + + +### List placement groups + +List all placement groups. + +**Usage:** + +``` +scw instance placement-group list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | | Filter placement groups by name (for eg. "cluster1" will return "cluster100" and "cluster1" but not "foo") | +| organization-id | | List only placement groups of this organization | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +List all placement groups in the default zone +``` +scw instance placement-group list +``` + +List placement groups that match a given name ('cluster1' will return 'cluster100' and 'cluster1' but not 'foo') +``` +scw instance placement-group list name=cluster1 +``` + + + + +### Update a placement group + +Update one or more parameter of the given placement group. + +**Usage:** + +``` +scw instance placement-group update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| placement-group-id | Required | UUID of the placement group | +| name | | Name of the placement group | +| policy-mode | One of: `optional`, `enforced` | | +| policy-type | One of: `max_availability`, `low_latency` | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Update the name of a placement group +``` +scw instance placement-group update 95053f33-cd3c-4cdc-b2b0-57d2dda97b13 name=foobar +``` + +Update the policy mode of a placement group (All instances in your placement group MUST be shutdown) +``` +scw instance placement-group update 1f883434-8c2d-40f0-b686-d0754b3a7bc0 policy-mode=enforced +``` + +Update the policy type of a placement group (All instances in your placement group MUST be shutdown) +``` +scw instance placement-group update 0954ec26-9917-47b6-8c5c-7bc81d7bb9d2 policy-type=low_latency +``` + + + + +## Security group management commands + +A security group is a set of firewall rules on a set of instances. +Security groups enable to create rules that either drop or allow incoming traffic from certain ports of your instances. + +Security Groups are stateful by default which means return traffic is automatically allowed, regardless of any rules. +As a contrary, you have to switch in a stateless mode to define explicitly allowed. + + + +### Remove all rules of a security group + + + +**Usage:** + +``` +scw instance security-group clear [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| security-group-id | Required | ID of the security group to reset. | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Remove all rules of the given security group +``` +scw instance security-group clear security-group-id=11111111-1111-1111-1111-111111111111 +``` + + + + +### Create a security group + +Create a security group. + +**Usage:** + +``` +scw instance security-group create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | Required
Default: `` | Name of the security group | +| description | | Description of the security group | +| organization-default | Default: `false` | Whether this security group becomes the default security group for new instances | +| stateful | Default: `true` | Whether the security group is stateful or not | +| inbound-default-policy | Default: `accept`
One of: `accept`, `drop` | Default policy for inbound rules | +| outbound-default-policy | Default: `accept`
One of: `accept`, `drop` | Default policy for outbound rules | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Create a Security Group with the given name and description +``` +scw instance security-group create name=foobar description=foobar foobar +``` + +Create a Security Group that will be applied as a default on instances of your organization +``` +scw instance security-group create organization-default=true +``` + +Create a Security Group that will have a default drop inbound policy (Traffic your instance receive) +``` +scw instance security-group create inbound-default-policy=drop +``` + +Create a Security Group that will have a default drop outbound policy (Traffic your instance transmit) +``` +scw instance security-group create outbound-default-policy=drop +``` + +Create a stateless Security Group +``` +scw instance security-group create +``` + + + + +### Delete a security group + +Delete a security group. + +**Usage:** + +``` +scw instance security-group delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| security-group-id | Required | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Delete a security group with the given ID +``` +scw instance security-group delete 69e17c83-9945-47ac-8b29-8c1ad050ee83 +``` + + + + +### Get a security group + +Get the details of a Security Group with the given ID. + +**Usage:** + +``` +scw instance security-group get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| security-group-id | Required | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Get a security group with the given ID +``` +scw instance security-group get a3244331-5d32-4e36-9bf9-b60233e201c7 +``` + + + + +### List security groups + +List all security groups available in an account. + +**Usage:** + +``` +scw instance security-group list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | | Name of the security group | +| organization-id | | The security group organization ID | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +List all security groups that match the given name +``` +scw instance security-group list name=foobar +``` + + + + +### Update security group + +Update security group. + +**Usage:** + +``` +scw instance security-group update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| security-group-id | Required | ID of the security group to update | +| name | | | +| description | | | +| stateful | | | +| inbound-default-policy | One of: `accept`, `drop` | | +| outbound-default-policy | One of: `accept`, `drop` | | +| organization-default | | | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Set the default outbound policy as drop +``` +scw instance security-group update security-group-id=11111111-1111-1111-1111-111111111111 outbound-default-policy=drop +``` + +Set the given security group as the default for the organization +``` +scw instance security-group update security-group-id=11111111-1111-1111-1111-111111111111 organization-default=true +``` + +Change the name of the given security group +``` +scw instance security-group update security-group-id=11111111-1111-1111-1111-111111111111 name=foobar +``` + +Change the description of the given security group +``` +scw instance security-group update security-group-id=11111111-1111-1111-1111-111111111111 description=foobar +``` + +Enable stateful security group +``` +scw instance security-group update security-group-id=11111111-1111-1111-1111-111111111111 stateful=true +``` + +Set the default inbound policy as drop +``` +scw instance security-group update security-group-id=11111111-1111-1111-1111-111111111111 inbound-default-policy=drop +``` + + + + +## Server management commands + +Server types are denomination of the different instances we provide. +Scaleway offers **Virtual Cloud** and **dedicated GPU** instances. + +**Virtual Cloud Instances** + +Virtual cloud instances are offering the best performance/price ratio for most workloads. Different CPU architectures are proposed: The **Development** and **General Purpose** ranges are based on AMD EPYC CPUs. The **ARM64** range is based on Cavium Thunder X ARM CPUs. + +* The **Development** instances range provides stable and consistent performance for development needs. + Spin up a development or test environment within seconds. + Refer to the [Development Instance offer details](https://www.scaleway.com/en/development-instances/) for more information. + +* The **General Purpose** instances range is the solution for demanding workloads. + Powerful AMD EPYC CPUs back those instances and offer up to 48 Cores, 256GB of RAM and 600GB of replicated local NVMe SSD storage. + Refer to the [General Purpose offer details](https://www.scaleway.com/en/general-purpose-instances/) for more information. + +* The **ARM** instances range is based on Cavium ThunderX SoCs and provides up to 64 Cores ARM 64bit, 128GB of RAM and 1TB SSD storage. + Refer to the [ARM offer details](https://www.scaleway.com/en/arm-instances) for more information. + +**Dedicated GPU Instances** + +GPU instances are very powerful compute instances, providing lots of RAM, vCPU, and storage. + +They are equipped with Nvidia Tesla P100 GPUs, which are designed for handling rapidly, a massive amount of data. +They are useful for heavy data processing, artificial intelligence and machine learning, video encoding, rendering, and so on. +The GPU is dedicated to each instance and directly exposed through PCI-e. +For more information, refer to [GPU Instances](https://www.scaleway.com/en/gpu-instances/). + + + +### Attach a volume to a server + + + +**Usage:** + +``` +scw instance server attach-volume [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server | +| volume-id | Required | ID of the volume to attach | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Attach a volume to a server +``` +scw instance server attach-volume server-id=11111111-1111-1111-1111-111111111111 volume-id=22222222-1111-5555-2222-666666111111 +``` + + + + +### Backup server + +Create a new image based on the server. + +This command: + - creates a snapshot of all attached volumes. + - creates an image based on all these snapshots. + +Once your image is ready you will be able to create a new server based on this image. + + +**Usage:** + +``` +scw instance server backup [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server to backup. | +| name | Default: `` | Name of your backup. | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Create a new image based on a server +``` +scw instance server backup 11111111-1111-1111-1111-111111111111 +``` + + + + +### Connect to the serial console of an instance + + + +**Usage:** + +``` +scw instance server console [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | Server ID to connect to | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + + +### Create server + +Create an instance server. + +**Usage:** + +``` +scw instance server create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| image | Required | Image ID or label of the server | +| type | Default: `DEV1-S`
One of: `GP1-XS`, `GP1-S`, `GP1-M`, `GP1-L`, `GP1-XL`, `DEV1-S`, `DEV1-M`, `DEV1-L`, `DEV1-XL`, `RENDER-S` | Server commercial type | +| name | Default: `` | Server name | +| root-volume | | Local root volume of the server | +| additional-volumes.{index} | | Additional local and block volumes attached to your server | +| ip | Default: `new` | Either an IP, an IP ID, 'new' to create a new IP, 'dynamic' to use a dynamic IP or 'none' for no public IP (new | dynamic | none | |
) | +| tags.{index} | | Server tags | +| ipv6 | | Enable IPv6 | +| stopped | | Do not start server after its creation | +| security-group-id | | The security group ID it use for this server | +| placement-group-id | | The placement group ID in witch the server has to be created | +| bootscript-id | | The bootscript ID to use, if empty the local boot will be used | +| cloud-init | | The cloud-init script to use | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Create and start an instance on Ubuntu Focal +``` +scw instance server create image=ubuntu_focal +``` + +Create a GP1-XS instance, give it a name and add tags +``` +scw instance server create image=ubuntu_focal type=GP1-XS name=foo tags.0=prod tags.1=blue +``` + +Create an instance with 2 additional block volumes (50GB and 100GB) +``` +scw instance server create image=ubuntu_focal additional-volumes.0=block:50GB additional-volumes.1=block:100GB +``` + +Create an instance with 2 local volumes (10GB and 10GB) +``` +scw instance server create image=ubuntu_focal root-volume=local:10GB additional-volumes.0=local:10GB +``` + +Use an existing IP +``` +ip=$(scw instance ip create | grep id | awk '{ print $2 }') +scw instance server create image=ubuntu_focal ip=$ip +``` + + + + +### Delete server + +Delete a server with the given ID. + +**Usage:** + +``` +scw instance server delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | | +| with-volumes | Default: `none`
One of: `none`, `local`, `block`, `root`, `all` | Delete the volumes attached to the server | +| with-ip | | Delete the IP attached to the server | +| force-shutdown | | Force shutdown of the instance server before deleting it | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Delete a server in the default zone with a given id +``` +scw instance server delete 11111111-1111-1111-1111-111111111111 +``` + +Delete a server in fr-par-1 zone with a given id +``` +scw instance server delete 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + + + + +### Detach a volume from its server + + + +**Usage:** + +``` +scw instance server detach-volume [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| volume-id | Required | ID of the volume to detach | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Detach a volume from its server +``` +scw instance server detach-volume volume-id=22222222-1111-5555-2222-666666111111 +``` + + + + +### Get a server + +Get the details of a specified Server. + +**Usage:** + +``` +scw instance server get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Get a server with the given ID +``` +scw instance server get 94ededdf-358d-4019-9886-d754f8a2e78d +``` + + + + +### List all servers + +List all servers. + +**Usage:** + +``` +scw instance server list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | | Filter servers by name (for eg. "server1" will return "server100" and "server1" but not "foo") | +| private-ip | | List servers by private_ip | +| without-ip | | List servers that are not attached to a public IP | +| commercial-type | | List servers of this commercial type | +| state | One of: `running`, `stopped`, `stopped in place`, `starting`, `stopping`, `locked` | List servers in this state | +| tags.{index} | | List servers with these exact tags | +| organization-id | | List only servers of this organization | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +List all servers on your default zone +``` +scw instance server list +``` + +List servers of this commercial type +``` +scw instance server list commercial-type=DEV1-S +``` + +List servers that are not attached to a public IP +``` +scw instance server list without-ip=true +``` + +List servers that match the given name ('server1' will return 'server100' and 'server1' but not 'foo') +``` +scw instance server list name=server1 +``` + + + + +### Reboot server + + + +**Usage:** + +``` +scw instance server reboot [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server affected by the action. | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Reboot a server in the default zone with a given id +``` +scw instance server reboot 11111111-1111-1111-1111-111111111111 +``` + +Reboot a server in fr-par-1 zone with a given id +``` +scw instance server reboot 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + + + + +### SSH into a server + +Connect to distant server via the SSH protocol. + +**Usage:** + +``` +scw instance server ssh [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | Server ID to SSH into | +| username | Default: `root` | Username used for the SSH connection | +| port | Default: `22` | Port used for the SSH connection | +| command | | Command to execute on the remote server | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + + +### Put server in standby mode + + + +**Usage:** + +``` +scw instance server standby [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server affected by the action. | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Put in standby a server in the default zone with a given id +``` +scw instance server standby 11111111-1111-1111-1111-111111111111 +``` + +Put in standby a server in fr-par-1 zone with a given id +``` +scw instance server standby 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + + + + +### Power on server + + + +**Usage:** + +``` +scw instance server start [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server affected by the action. | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Start a server in the default zone with a given id +``` +scw instance server start 11111111-1111-1111-1111-111111111111 +``` + +Start a server in fr-par-1 zone with a given id +``` +scw instance server start 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + + + + +### Power off server + + + +**Usage:** + +``` +scw instance server stop [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server affected by the action. | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Stop a server in the default zone with a given id +``` +scw instance server stop 11111111-1111-1111-1111-111111111111 +``` + +Stop a server in fr-par-1 zone with a given id +``` +scw instance server stop 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + + + + +### Terminate server + +Terminates a server with the given ID and all of its volumes. + +**Usage:** + +``` +scw instance server terminate [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | | +| with-ip | | Delete the IP attached to the server | +| with-block | Default: `prompt`
One of: `prompt`, `true`, `false` | Delete the Block Storage volumes attached to the server | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Terminate a server in the default zone with a given id +``` +scw instance server terminate 11111111-1111-1111-1111-111111111111 +``` + +Terminate a server in fr-par-1 zone with a given id +``` +scw instance server terminate 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + +Terminate a server and also delete its flexible IPs +``` +scw instance server terminate 11111111-1111-1111-1111-111111111111 with-ip=true +``` + + + + +### Update a server + +Update a server. + +**Usage:** + +``` +scw instance server update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | UUID of the server | +| name | | Name of the server | +| ip | | IP that should be attached to the server (use ip=none to detach) | +| cloud-init | | The cloud-init script to use | +| boot-type | One of: `local`, `bootscript`, `rescue` | | +| tags.{index} | | Tags of the server | +| bootscript | | | +| dynamic-ip-required | | | +| enable-ipv6 | | | +| protected | | | +| security-group-id | | | +| volume-ids.{index} | | Will update ALL volume IDs at once, including the root volume of the server (use volume-ids=none to detach all volumes) | +| placement-group-id | | Placement group ID if server must be part of a placement group | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Update the name of a given server +``` +scw instance server update 11111111-1111-1111-1111-111111111111 name=foobar +``` + +Put a given instance in rescue mode (reboot is required to access rescue mode) +``` +scw instance server update 11111111-1111-1111-1111-111111111111 boot-type=rescue +``` + +Overwrite tags of a given server +``` +scw instance server update 11111111-1111-1111-1111-111111111111 tags.0=foo tags.1=bar +``` + +Enable IPv6 on a given server +``` +scw instance server update 11111111-1111-1111-1111-111111111111 enable-ipv6=true +``` + +Apply the given security group to a given server +``` +scw instance server update +``` + +Put a given server in the given placement group. Server must be off +``` +scw instance server update +``` + + + + +### Wait for server to reach a stable state + +Wait for server to reach a stable state. This is similar to using --wait flag on other action commands, but without requiring a new action on the server. + +**Usage:** + +``` +scw instance server wait [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | ID of the server affected by the action. | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Wait for a server to reach a stable state +``` +scw instance server wait 11111111-1111-1111-1111-111111111111 +``` + + + + +## Server type management commands + +Server types will answer with all instance types available in a given zone. +Each of these types will contains all the features of the instance (CPU, RAM, Storage) with their associated pricing. + + + +### List server types + +Get server types technical details. + +**Usage:** + +``` +scw instance server-type list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +List all server-types in the default zone +``` +scw instance server-type list +``` + +List all server-types in fr-par-1 zone +``` +scw instance server-type list zone=fr-par-1 +``` + + + + +## Snapshot management commands + +Snapshots contain the data of a specific volume at a particular point in time. +The data can include the instance's operating system, +configuration information or files stored on the volume. + +A snapshot can be done from a specific volume (for example you +have a server with a volume containing the OS and another one +containing the application data, and you want to use different +snapshot strategies on both volumes). + +Snapshots only work on `l_ssd` volume type at the moment. `b_ssd` +snapshots will be available starting 2020. + + + +### Create a snapshot from a given volume + +Create a snapshot from a given volume. + +**Usage:** + +``` +scw instance snapshot create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | Default: `` | Name of the snapshot | +| volume-id | Required | UUID of the volume | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Create a snapshot in the default zone from the given volume ID +``` +scw instance snapshot create volume-id=11111111-1111-1111-1111-111111111111 +``` + +Create a snapshot in fr-par-1 zone from the given volume ID +``` +scw instance snapshot create zone=fr-par-1 volume-id=11111111-1111-1111-1111-111111111111 +``` + +Create a named snapshot from the given volume ID +``` +scw instance snapshot create name=foobar volume-id=11111111-1111-1111-1111-111111111111 +``` + + + + +### Delete a snapshot + +Delete the snapshot with the given ID. + +**Usage:** + +``` +scw instance snapshot delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| snapshot-id | Required | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Delete a snapshot in the default zone with the given ID +``` +scw instance snapshot delete 11111111-1111-1111-1111-111111111111 +``` + +Delete a snapshot in fr-par-1 zone with the given ID +``` +scw instance snapshot delete 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + + + + +### Get a snapshot + +Get details of a snapshot with the given ID. + +**Usage:** + +``` +scw instance snapshot get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| snapshot-id | Required | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Get a snapshot in the default zone with the given ID +``` +scw instance snapshot get 11111111-1111-1111-1111-111111111111 +``` + +Get a snapshot in fr-par-1 zone with the given ID +``` +scw instance snapshot get 11111111-1111-1111-1111-111111111111 zone=fr-par-1 +``` + + + + +### List snapshots + +List snapshots. + +**Usage:** + +``` +scw instance snapshot list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | | | +| organization-id | | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +List all snapshots in the default zone +``` +scw instance snapshot list +``` + +List all snapshots in fr-par-1 zone +``` +scw instance snapshot list zone=fr-par-1 +``` + + + + +### Wait for snapshot to reach a stable state + +Wait for snapshot to reach a stable state. This is similar to using --wait flag on other action commands, but without requiring a new action on the snapshot. + +**Usage:** + +``` +scw instance snapshot wait [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| snapshot-id | Required | ID of the snapshot. | +| zone | Default: `fr-par-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Wait for a snapshot to reach a stable state +``` +scw instance snapshot wait 11111111-1111-1111-1111-111111111111 +``` + + + + +## User data management commands + +User data is a key value store API you can use to provide data from and to your server without authentication. + +As an example of use, Scaleway images contain the script scw-generate-ssh-keys which generates SSH server’s host keys then stores their fingerprints as user data under the key “ssh-host-fingerprints”. +This way, we ensure they are really connecting to their Scaleway instance and they are not victim of a man-in-the-middle attack. + +There are two endpoints to access user data: + - **From a running instance**, by using the metadata API at http://169.254.42.42/user_data. + To enhance security, we only allow user data viewing and editing as root. + To know if the query is issued by the root user, we only accept queries made from a local port below 1024 (by default, non-root users can’t bind ports below 1024). + To specify the local port with cURL, use `curl --local-port 1-1024 http://169.254.42.42/user_data` + - **From the instance API** at using methods described bellow. + + + +### Delete user data + +Delete the given key from a server user data. + +**Usage:** + +``` +scw instance user-data delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | UUID of the server | +| key | Required | Key of the user data to delete | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + + +### Get user data + +Get the content of a user data with the given key on a server. + +**Usage:** + +``` +scw instance user-data get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | UUID of the server | +| key | Required | Key of the user data to get | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + + +### List user data + +List all user data keys registered on a given server. + +**Usage:** + +``` +scw instance user-data list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | UUID of the server | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + + +### Add/Set user data + +Add or update a user data with the given key on a server. + +**Usage:** + +``` +scw instance user-data set [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| server-id | Required | UUID of the server | +| key | Required | Key of the user data to set | +| content | Required | Content of the user data | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + + +## Volume management commands + +A volume is where you store your data inside your instance. It +appears as a block device on Linux that you can use to create +a filesystem and mount it. + +We have two different types of volume (`volume_type`): + - `l_ssd` is a local block storage: your data is downloaded on + the hypervisor and you need to power off your instance to attach + or detach a volume. + - `b_ssd` is a remote block storage: your data is stored on a + centralised cluster. You can plug and unplug a volume while + your instance is running. As of today, `b_ssd` is only available + for `DEV1`, `GP1` and `RENDER` offers. + +Minimum and maximum volume sizes for each volume types can be queried +from the zone `/products/volumes` API endpoint. _I.e_ for: + - `fr-par-1` use https://api.scaleway.com/instance/v1/zones/fr-par-1/products/volumes + - `nl-ams-1` use https://api.scaleway.com/instance/v1/zones/nl-ams-1/products/volumes + +Each types of volumes is also subject to a global quota for the sum of all the +volumes. This quota depends of the level of support and may be +changed on demand. + +Be wary that when terminating an instance, if you want to keep +your block storage volume, **you must** detach it beforehand you +issue the `terminate` call. + +When using multiple block devices, it's advised to mount them by +using their UUID instead of their device name. A device name is +subject to change depending on the volumes order. Block devices +UUIDs can be found in `/dev/disk/by-id/`. + + + +### Create a volume + +Create a volume. + +**Usage:** + +``` +scw instance volume create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | | | +| volume-type | One of: `l_ssd`, `b_ssd` | | +| size | | | +| base-volume | | | +| base-snapshot | | | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Create a volume called 'my-volume' +``` +scw instance volume create name=my-volume +``` + +Create a volume with a size of 50GB +``` +scw instance volume create size=50GB +``` + +Create a volume of type 'l_ssd', based on volume '00112233-4455-6677-8899-aabbccddeeff' +``` +scw instance volume create volume-type=l_ssd base-volume=00112233-4455-6677-8899-aabbccddeeff +``` + + + + +### Delete a volume + +Delete the volume with the given ID. + +**Usage:** + +``` +scw instance volume delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| volume-id | Required | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Delete a volume with the given ID +``` +scw instance volume delete af136619-bc59-4b48-a0ed-ed7dceaad9a6 +``` + + + + +### Get a volume + +Get details of a volume with the given ID. + +**Usage:** + +``` +scw instance volume get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| volume-id | Required | | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Get a volume with the given ID +``` +scw instance volume get b70e9a0e-28b1-4542-bb9b-06d2d6debc0f +``` + + + + +### List volumes + +List volumes. + +**Usage:** + +``` +scw instance volume list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| volume-type | One of: `l_ssd`, `b_ssd` | Filter by volume type | +| name | | Filter volume by name (for eg. "vol" will return "myvolume" but not "data") | +| organization-id | | Filter volume by organization | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +List all volumes +``` +scw instance volume list +``` + +List all block storage volumes +``` +scw instance volume list volume-type=b_ssd +``` + +List all local storage volumes +``` +scw instance volume list volume-type=l_ssd +``` + +List all volumes that match a name +``` +scw instance volume list name=foobar +``` + +List all block storage volumes that match a name +``` +scw instance volume list volume-type=b_ssd name=foobar +``` + + + + +### Update a volume + +Replace name and/or size properties of given ID volume with the given value(s). Any volume name can be changed while, for now, only `b_ssd` volume growing is supported. + +**Usage:** + +``` +scw instance volume update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| volume-id | Required | UUID of the volume | +| name | | The volume name | +| size | | The volume disk size | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +Change the volume name +``` +scw instance volume update 11111111-1111-1111-1111-111111111111 name=my-new-name +``` + +Change the volume disk size (bytes) +``` +scw instance volume update 11111111-1111-1111-1111-111111111111 size=60GB +``` + +Change the volume name and disk size +``` +scw instance volume update 11111111-1111-1111-1111-111111111111 name=a-new-name size=70GB +``` + + + + +## Volume type management commands + +Volume types will answer with all volume types available in a given zone. +Each of these types will contains all the capabilities and constraints of the volume (min size, max size, snapshot). + + + +### List volumes types + +Get volumes technical details. + +**Usage:** + +``` +scw instance volume-type list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `nl-ams-1` | Zone to target. If none is passed will use default zone from the config | + + +**Examples:** + + +List all volume-types in the default zone +``` +scw instance volume-type list +``` + +List all volume-types in fr-par-1 zone +``` +scw instance volume-type list zone=fr-par-1 +``` + + + + diff --git a/docs/commands/k8s.md b/docs/commands/k8s.md new file mode 100644 index 0000000000..067c3c9e0f --- /dev/null +++ b/docs/commands/k8s.md @@ -0,0 +1,996 @@ + +# Documentation for `scw k8s` +Kapsule API + +- [Kapsule cluster management commands](#kapsule-cluster-management-commands) + - [Create a new cluster](#create-a-new-cluster) + - [Delete a cluster](#delete-a-cluster) + - [Get a cluster](#get-a-cluster) + - [List all the clusters](#list-all-the-clusters) + - [List available versions for a cluster](#list-available-versions-for-a-cluster) + - [Reset the admin token of a cluster](#reset-the-admin-token-of-a-cluster) + - [Update a cluster](#update-a-cluster) + - [Upgrade a cluster](#upgrade-a-cluster) + - [Wait for a cluster to reach a stable state](#wait-for-a-cluster-to-reach-a-stable-state) +- [Manage your Kubernetes Kapsule cluster's kubeconfig files](#manage-your-kubernetes-kapsule-cluster's-kubeconfig-files) + - [Retrieve a kubeconfig](#retrieve-a-kubeconfig) + - [Install a kubeconfig](#install-a-kubeconfig) + - [Uninstall a kubeconfig](#uninstall-a-kubeconfig) +- [Kapsule node management commands](#kapsule-node-management-commands) + - [Get a node in a cluster](#get-a-node-in-a-cluster) + - [List all the nodes in a cluster](#list-all-the-nodes-in-a-cluster) + - [Reboot a node in a cluster](#reboot-a-node-in-a-cluster) + - [Replace a node in a cluster](#replace-a-node-in-a-cluster) + - [Wait for a node to reach a stable state](#wait-for-a-node-to-reach-a-stable-state) +- [Kapsule pool management commands](#kapsule-pool-management-commands) + - [Create a new pool in a cluster](#create-a-new-pool-in-a-cluster) + - [Delete a pool in a cluster](#delete-a-pool-in-a-cluster) + - [Get a pool in a cluster](#get-a-pool-in-a-cluster) + - [List all the pools in a cluster](#list-all-the-pools-in-a-cluster) + - [Update a pool in a cluster](#update-a-pool-in-a-cluster) + - [Upgrade a pool in a cluster](#upgrade-a-pool-in-a-cluster) + - [Wait for a pool to reach a stable state](#wait-for-a-pool-to-reach-a-stable-state) +- [Available Kubernetes version commands](#available-kubernetes-version-commands) + - [Get details about a specific version](#get-details-about-a-specific-version) + - [List all available versions](#list-all-available-versions) + + +## Kapsule cluster management commands + +A cluster is a fully managed Kubernetes cluster. + +It is composed of different pools, each pool containing the same kind of nodes. + + + +### Create a new cluster + +This method allows to create a new Kubernetes cluster on an account. + +**Usage:** + +``` +scw k8s cluster create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | Required | The name of the cluster | +| description | | The description of the cluster | +| tags.{index} | | The tags associated with the cluster | +| version | Required | The Kubernetes version of the cluster | +| cni | Required
One of: `unknown_cni`, `cilium`, `calico`, `weave`, `flannel` | The Container Network Interface (CNI) plugin that will run in the cluster | +| enable-dashboard | | The enablement of the Kubernetes Dashboard in the cluster | +| ingress | One of: `unknown_ingress`, `none`, `nginx`, `traefik`, `traefik2` | The Ingress Controller that will run in the cluster | +| pools.{index}.name | | | +| pools.{index}.node-type | Required | 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 | Required | The size (number of nodes) of the pool | +| pools.{index}.min-size | | The minimun size of the pool | +| pools.{index}.max-size | | The maximum size of the pool | +| pools.{index}.container-runtime | One of: `unknown_runtime`, `docker`, `containerd`, `crio` | The container runtime for the nodes of the pool | +| pools.{index}.autohealing | | The enablement of the autohealing feature for the pool | +| pools.{index}.tags.{index} | | The tags associated with the pool | +| 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 | One of: `unknown_estimator`, `binpacking` | Type of resource estimator to be used in scale up | +| autoscaler-config.expander | One of: `unknown_expander`, `random`, `most_pods`, `least_waste`, `priority` | Type of node group expander to be used in scale up | +| autoscaler-config.ignore-daemonsets-utilization | | Ignore DaemonSet pods when calculating resource utilization for scaling down | +| autoscaler-config.balance-similar-node-groups | | Detect similar node groups and balance the number of nodes between them | +| autoscaler-config.expendable-pods-priority-cutoff | | Pods with priority below cutoff will be expendable | +| autoscaler-config.scale-down-unneeded-time | | How long a node should be unneeded before it is eligible for scale down | +| 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 | One of: `any`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday` | The day of the week for the maintenance window | +| feature-gates.{index} | | List of feature gates to enable | +| admission-plugins.{index} | | List of admission plugins to enable | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Create a Kubernetes cluster named foo with cilium as CNI, in version 1.17.4 and with a pool named default composed of 3 DEV1-M +``` +scw k8s cluster create name=foo version=1.17.4 pools.0.size=3 pools.0.node-type=DEV1-M pools.0.name=default +``` + +Create a Kubernetes cluster named bar, tagged, calico as CNI, in version 1.17.4 and with a tagged pool named default composed of 2 RENDER-S and autohealing and autoscaling enabled (between 1 and 10 nodes) +``` +scw k8s cluster create name=bar version=1.17.4 tags.0=tag1 tags.1=tag2 cni=cilium pools.0.size=2 pools.0.node-type=RENDER-S pools.0.min-size=1 pools.0.max-size=10 pools.0.autohealing=true pools.0.autoscaling=true pools.0.tags.0=pooltag1 pools.0.tags.1=pooltag2 pools.0.name=default +``` + + + + +### Delete a cluster + +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. + +**Usage:** + +``` +scw k8s cluster delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | The 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 | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Delete a given cluster +``` +scw k8s cluster delete 11111111-1111-1111-111111111111 +``` + + + + +### Get a cluster + +This method allows to get details about a specific Kubernetes cluster. + +**Usage:** + +``` +scw k8s cluster get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | The ID of the requested cluster | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Get a given cluster +``` +scw k8s cluster get 11111111-1111-1111-111111111111 +``` + + + + +### List all the clusters + +This method allows to list all the existing Kubernetes clusters in an account. + +**Usage:** + +``` +scw k8s cluster list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| order-by | One of: `created_at_asc`, `created_at_desc`, `updated_at_asc`, `updated_at_desc`, `name_asc`, `name_desc`, `status_asc`, `status_desc`, `version_asc`, `version_desc` | The sort order of the returned clusters | +| name | | The name on which to filter the returned clusters | +| status | One of: `unknown`, `creating`, `ready`, `deleting`, `deleted`, `updating`, `locked`, `pool_required` | The status on which to filter the returned clusters | +| organization-id | | The organization ID on which to filter the returned clusters | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +List all the clusters on your default region +``` +scw k8s cluster list +``` + +List the ready clusters on your default region +``` +scw k8s cluster list status=ready +``` + +List the clusters that match the given name on fr-par ('cluster1' will return 'cluster100' and 'cluster1' but not 'foo') +``` +scw k8s cluster list region=fr-par name=cluster1 +``` + + + + +### List available versions for a cluster + +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. + +**Usage:** + +``` +scw k8s cluster list-available-versions [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | The ID of the cluster which the available Kuberentes versions will be listed from | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +List all available versions for a given cluster to upgrade to +``` +scw k8s cluster list-available-versions 11111111-1111-1111-111111111111 +``` + + + + +### Reset the admin token of a cluster + +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). + +**Usage:** + +``` +scw k8s cluster reset-admin-token [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | The ID of the cluster of which the admin token will be renewed | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Reset the admin token for a given cluster +``` +scw k8s cluster reset-admin-token 11111111-1111-1111-111111111111 +``` + + + + +### Update a cluster + +This method allows to update a specific Kubernetes cluster. Note that this method is not made to upgrade a Kubernetes cluster. + +**Usage:** + +``` +scw k8s cluster update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | 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 | +| 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 | One of: `unknown_estimator`, `binpacking` | Type of resource estimator to be used in scale up | +| autoscaler-config.expander | One of: `unknown_expander`, `random`, `most_pods`, `least_waste`, `priority` | Type of node group expander to be used in scale up | +| autoscaler-config.ignore-daemonsets-utilization | | Ignore DaemonSet pods when calculating resource utilization for scaling down | +| autoscaler-config.balance-similar-node-groups | | Detect similar node groups and balance the number of nodes between them | +| autoscaler-config.expendable-pods-priority-cutoff | | Pods with priority below cutoff will be expendable | +| autoscaler-config.scale-down-unneeded-time | | How long a node should be unneeded before it is eligible for scale down | +| enable-dashboard | | The new value of the Kubernetes Dashboard enablement | +| ingress | One of: `unknown_ingress`, `none`, `nginx`, `traefik`, `traefik2` | The new Ingress Controller for the cluster | +| 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 | One of: `any`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday` | The day of the week for the maintenance window | +| feature-gates.{index} | | List of feature gates to enable | +| admission-plugins.{index} | | List of admission plugins to enable | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Enable dashboard on a given cluster +``` +scw k8s cluster update 11111111-1111-1111-111111111111 enable-dashboard=true +``` + +Add TTLAfterFinished and ServiceNodeExclusion as feature gates on a given cluster +``` +scw k8s cluster update 11111111-1111-1111-111111111111 feature-gates.0=TTLAfterFinished feature-gates.1=ServiceNodeExclusion +``` + + + + +### Upgrade a cluster + +This method allows to upgrade a specific Kubernetes cluster and/or its associated pools to a specific and supported Kubernetes version. + +**Usage:** + +``` +scw k8s cluster upgrade [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | The ID of the cluster to upgrade | +| version | Required | The new Kubernetes version of the cluster | +| upgrade-pools | | The enablement of the pools upgrade | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Upgrade a given cluster to Kubernetes version 1.17.4 (without upgrading the pools) +``` +scw k8s cluster upgrade 11111111-1111-1111-111111111111 version=1.17.4 +``` + +Upgrade a given cluster to Kubernetes version 1.17.4 (and upgrade the pools) +``` +scw k8s cluster upgrade 11111111-1111-1111-111111111111 version=1.17.4 upgrade-pools=true +``` + + + + +### Wait for a cluster to reach a stable state + +Wait for server to reach a stable state. This is similar to using --wait flag on other action commands, but without requiring a new action on the server. + +**Usage:** + +``` +scw k8s cluster wait [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | ID of the cluster. | +| wait-for-pools | | Wait for pools to be ready. | +| region | Default: `fr-par` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Wait for a cluster to reach a stable state +``` +scw k8s cluster wait 11111111-1111-1111-1111-111111111111 +``` + + + + +## Manage your Kubernetes Kapsule cluster's kubeconfig files + + + + +### Retrieve a kubeconfig + +Retrieve the kubeconfig for a specified cluster. + +**Usage:** + +``` +scw k8s kubeconfig get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | Cluster ID from which to retrieve the kubeconfig | +| region | Default: `fr-par` | Region to target. If none is passed will use default region from the config | + + + +### Install a kubeconfig + +Retrieve the kubeconfig for a specified cluster and write it on disk. +It will merge the new kubeconfig in the file pointed by the KUBECONFIG variable. If empty it will default to $HOME/.kube/config. + +**Usage:** + +``` +scw k8s kubeconfig install [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | Cluster ID from which to retrieve the kubeconfig | +| keep-current-context | | Whether or not to keep the current kubeconfig context unmodified | +| region | Default: `fr-par` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Install the kubeconfig for a given cluster and using the new context +``` +scw k8s kubeconfig install 11111111-1111-1111-1111-111111111111 +``` + + + + +### Uninstall a kubeconfig + +Remove specified cluster from kubeconfig file specified by the KUBECONFIG env, if empty it will default to $HOME/.kube/config. +If the current context points to this cluster, it will be set to an empty context. + +**Usage:** + +``` +scw k8s kubeconfig uninstall [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | Cluster ID from which to uninstall the kubeconfig | + + +**Examples:** + + +Uninstall the kubeconfig for a given cluster +``` +scw k8s kubeconfig uninstall 11111111-1111-1111-1111-111111111111 +``` + + + + +## Kapsule node management commands + +A node (short for worker node) is an abstraction for a Scaleway Instance. +It is part of a pool and is instantiated by Scaleway, making Kubernetes software installed and configured automatically on it. +Please note that Kubernetes nodes cannot be accessed with ssh. + + + +### Get a node in a cluster + +This method allows to get details about a specific Kubernetes node. + +**Usage:** + +``` +scw k8s node get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| node-id | Required | The ID of the requested node | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Get a given node +``` +scw k8s node get 11111111-1111-1111-111111111111 +``` + + + + +### List all the nodes in a cluster + +This method allows to list all the existing nodes for a specific Kubernetes cluster. + +**Usage:** + +``` +scw k8s node list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | The cluster ID from which the nodes will be listed from | +| pool-id | | The pool ID on which to filter the returned nodes | +| order-by | One of: `created_at_asc`, `created_at_desc` | The sort order of the returned nodes | +| name | | The name on which to filter the returned nodes | +| status | One of: `unknown`, `creating`, `not_ready`, `ready`, `deleting`, `deleted`, `locked`, `rebooting`, `creation_error` | The status on which to filter the returned nodes | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +List all the nodes in the given cluster +``` +scw k8s node list 11111111-1111-1111-111111111111 +``` + +List all the nodes in the pool 2222222222222-2222-222222222222 in the given cluster +``` +scw k8s node list 11111111-1111-1111-111111111111 pool-id=2222222222222-2222-222222222222 +``` + +List all ready nodes in the given cluster +``` +scw k8s node list 11111111-1111-1111-111111111111 status=ready +``` + + + + +### Reboot a node in a cluster + +This method allows to reboot a specific node. This node will frist be cordoned, meaning that scheduling will be disabled. Then the existing pods on the node will be drained and reschedule onto another schedulable node. Note that when there is not enough space to reschedule all the pods (in a one node cluster for instance), you may experience some disruption of your applications. + +**Usage:** + +``` +scw k8s node reboot [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| node-id | Required | The ID of the node to reboot | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Reboot a given node +``` +scw k8s node reboot 11111111-1111-1111-111111111111 +``` + + + + +### Replace a node in a cluster + +This method allows to replace a specific node. The node will be set cordoned, meaning that scheduling will be disabled. Then the existing pods on the node will be drained and reschedule onto another schedulable node. Then the node will be deleted, and a new one will be created after the deletion. Note that when there is not enough space to reschedule all the pods (in a one node cluster for instance), you may experience some disruption of your applications. + +**Usage:** + +``` +scw k8s node replace [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| node-id | Required | The ID of the node to replace | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Replace a given node +``` +scw k8s node replace 11111111-1111-1111-111111111111 +``` + + + + +### Wait for a node to reach a stable state + +Wait for a node to reach a stable state. This is similar to using --wait flag on other action commands, but without requiring a new action on the node. + +**Usage:** + +``` +scw k8s node wait [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| node-id | Required | ID of the node. | +| region | Default: `fr-par` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Wait for a node to reach a stable state +``` +scw k8s node wait 11111111-1111-1111-1111-111111111111 +``` + + + + +## Kapsule pool management commands + +A pool is a set of identical Nodes. A pool has a name, a size (its current number of nodes), nodes number limits (min, max) and a Scaleway instance type. +Changing those limits increases/decreases the size of a pool. Thus, when autoscaling is enabled, the pool will grow or shrink inside those limits, depending on its load. +A "default pool" is automatically created with every cluster. + + + +### Create a new pool in a cluster + +This method allows to create a new pool in a specific Kubernetes cluster. + +**Usage:** + +``` +scw k8s pool create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | The ID of the cluster in which the pool will be created | +| name | Required | The name of the pool | +| node-type | Required | The node type is the type of Scaleway Instance wanted for the pool | +| placement-group-id | | The placement group ID in which all the nodes of the pool will be created | +| autoscaling | | The enablement of the autoscaling feature for the pool | +| size | Required | The size (number of nodes) of the pool | +| min-size | | The minimun size of the pool | +| max-size | | The maximum size of the pool | +| container-runtime | One of: `unknown_runtime`, `docker`, `containerd`, `crio` | The container runtime for the nodes of the pool | +| autohealing | | The enablement of the autohealing feature for the pool | +| tags.{index} | | The tags associated with the pool | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Create a pool named bar with 2 DEV1-XL on a given cluster +``` +scw k8s pool create 11111111-1111-1111-111111111111 name=bar node-type=DEV1-XL size=2 +``` + +Create a pool named fish with 5 GP1-L with autoscaling enabled within 0 and 10 nodes, autohealing enabled, and containerd as the container runtime on a given cluster +``` +scw k8s pool create 11111111-1111-1111-111111111111 name=fish node-type=GP1-L size=5 min-size=0 max-size=10 autoscaling=true autohealing=true container-runtime=containerd +``` + +Create a tagged pool named turtle with 1 GP1-S which is using the already created placement group 2222222222222-2222-222222222222 for all the nodes in the pool on a given cluster +``` +scw k8s pool create 11111111-1111-1111-111111111111 name=turtle node-type=GP1-S size=1 placement-group-id=2222222222222-2222-222222222222 tags.0=turtle tags.1=placement-group +``` + + + + +### Delete a pool in a cluster + +This method allows to delete a specific pool from a cluster, deleting all the nodes associated with it. + +**Usage:** + +``` +scw k8s pool delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| pool-id | Required | The ID of the pool to delete | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Delete a given pool +``` +scw k8s pool delete 11111111-1111-1111-111111111111 +``` + + + + +### Get a pool in a cluster + +This method allows to get details about a specific pool. + +**Usage:** + +``` +scw k8s pool get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| pool-id | Required | The ID of the requested pool | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Get a given pool +``` +scw k8s pool get 11111111-1111-1111-111111111111 +``` + + + + +### List all the pools in a cluster + +This method allows to list all the existing pools for a specific Kubernetes cluster. + +**Usage:** + +``` +scw k8s pool list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| cluster-id | Required | The ID of the cluster from which the pools will be listed from | +| order-by | One of: `created_at_asc`, `created_at_desc`, `updated_at_asc`, `updated_at_desc`, `name_asc`, `name_desc`, `status_asc`, `status_desc`, `version_asc`, `version_desc` | The sort order of the returned pools | +| name | | The name on which to filter the returned pools | +| status | One of: `unknown`, `ready`, `deleting`, `deleted`, `scaling`, `warning`, `locked`, `upgrading` | The status on which to filter the returned pools | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +List all pools for a given cluster +``` +scw k8s pool list 11111111-1111-1111-111111111111 +``` + +List all scaling pools for a given cluster +``` +scw k8s pool list 11111111-1111-1111-111111111111 status=scaling +``` + +List all pools for a given cluster that contain the word foo in the pool name +``` +scw k8s pool list 11111111-1111-1111-111111111111 name=foo +``` + +List all pools for a given cluster and order them by ascending creation date +``` +scw k8s pool list 11111111-1111-1111-111111111111 order-by=created_at_asc +``` + + + + +### Update a pool in a cluster + +This method allows to update some attributes of a specific pool such as the size, the autoscaling enablement, the tags, ... + +**Usage:** + +``` +scw k8s pool update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| pool-id | Required | The ID of the pool to update | +| autoscaling | | The new value for the enablement of autoscaling for the pool | +| size | | The new size for the pool | +| min-size | | The new minimun size for the pool | +| max-size | | The new maximum size for the pool | +| autohealing | | The new value for the enablement of autohealing for the pool | +| tags.{index} | | The new tags associated with the pool | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Enable autoscaling on a given pool +``` +scw k8s pool update 11111111-1111-1111-111111111111 autoscaling=true +``` + +Reduce the size and max size of a given pool to 4 +``` +scw k8s pool update 11111111-1111-1111-111111111111 size=4 max-size=4 +``` + +Change the tags of the given pool +``` +scw k8s pool update 11111111-1111-1111-111111111111 tags.0=my tags.1=new tags.2=pool +``` + + + + +### Upgrade a pool in a cluster + +This method allows to upgrade the Kubernetes version of a specific pool. Note that this will work when the targeted version is the same than the version of the cluster. + +**Usage:** + +``` +scw k8s pool upgrade [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| pool-id | Required | The ID of the pool to upgrade | +| version | Required | The new Kubernetes version for the pool | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Upgrade a given pool to the Kubernetes version 1.17.4 +``` +scw k8s pool upgrade 11111111-1111-1111-111111111111 version=1.17.4 +``` + + + + +### Wait for a pool to reach a stable state + +Wait for a pool to reach a stable state. This is similar to using --wait flag on other action commands, but without requiring a new action on the node. + +**Usage:** + +``` +scw k8s pool wait [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| pool-id | Required | ID of the pool. | +| region | Default: `fr-par` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Wait for a pool to reach a stable state +``` +scw k8s pool wait 11111111-1111-1111-1111-111111111111 +``` + + + + +## Available Kubernetes version commands + +A version is a vanilla Kubernetes version like `x.y.z`. +It is composed of a major version x, a minor version y and a patch version z. +Scaleway's managed Kubernetes, Kapsule, will at least support the last patch version for the last three minor release. + +Also each version have a different set of container runtimes, CNIs, ingresses, feature gates and admission plugins available. + + + +### Get details about a specific version + +This method allows to get a specific Kubernetes version and the details about the version. + +**Usage:** + +``` +scw k8s version get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| version-name | Required | The requested version name | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Get the Kubernetes version 1.18.0 +``` +scw k8s version get 1.18.0 +``` + + + + +### List all available versions + +This method allows to list all available versions for the creation of a new Kubernetes cluster. + +**Usage:** + +``` +scw k8s version list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +List all available Kubernetes version in Kapsule +``` +scw k8s version list +``` + + + + diff --git a/docs/commands/marketplace.md b/docs/commands/marketplace.md new file mode 100644 index 0000000000..fa1c11c214 --- /dev/null +++ b/docs/commands/marketplace.md @@ -0,0 +1,45 @@ + +# Documentation for `scw marketplace` +Marketplace API + +- [Marketplace images management commands](#marketplace-images-management-commands) + - [Get a specific marketplace image](#get-a-specific-marketplace-image) + - [List marketplace images](#list-marketplace-images) + + +## Marketplace images management commands + +Marketplace images management commands. + + +### Get a specific marketplace image + +Get a specific marketplace image. + +**Usage:** + +``` +scw marketplace image get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| label | Required | | + + + +### List marketplace images + +List marketplace images. + +**Usage:** + +``` +scw marketplace image list +``` + + + diff --git a/docs/commands/object.md b/docs/commands/object.md new file mode 100644 index 0000000000..c63d09ad2d --- /dev/null +++ b/docs/commands/object.md @@ -0,0 +1,96 @@ + +# Documentation for `scw object` +Object-storage utils + +- [Manage configuration files for popular S3 tools](#manage-configuration-files-for-popular-s3-tools) + - [Generate a S3 tool configuration file](#generate-a-s3-tool-configuration-file) + - [Install a S3 tool configuration file to its default location](#install-a-s3-tool-configuration-file-to-its-default-location) + + +## Manage configuration files for popular S3 tools + +Configuration generation for S3 tools. + + +### Generate a S3 tool configuration file + +Generate a S3 tool configuration file. + +**Usage:** + +``` +scw object config get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| type | Required
One of: `rclone`, `s3cmd`, `mc` | Type of S3 tool you want to generate a config for | +| name | Default: `scaleway` | Name of the s3 remote you want to generate | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Generate a s3cmd config file for Paris region +``` +scw object config get region=fr-par type=s3cmd +``` + +Generate a rclone config file for default region +``` +scw object config get type=rclone +``` + +Generate a mc (minio) config file for default region +``` +scw object config get type=mc +``` + + + + +### Install a S3 tool configuration file to its default location + +Install a S3 tool configuration file to its default location. + +**Usage:** + +``` +scw object config install [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| type | Required
One of: `rclone`, `s3cmd`, `mc` | Type of S3 tool you want to generate a config for | +| name | Default: `scaleway` | Name of the s3 remote you want to generate | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Install a s3cmd config file for Paris region +``` +scw object config install region=fr-par type=s3cmd +``` + +Install a rclone config file for default region +``` +scw object config install type=rclone +``` + +Install a mc (minio) config file for default region +``` +scw object config install type=mc +``` + + + + diff --git a/docs/commands/rdb.md b/docs/commands/rdb.md new file mode 100644 index 0000000000..cb1acc0ca3 --- /dev/null +++ b/docs/commands/rdb.md @@ -0,0 +1,888 @@ + +# Documentation for `scw rdb` +Database RDB API + +- [Access Control List (ACL) management commands](#access-control-list-(acl)-management-commands) + - [Add an ACL instance to a given instance](#add-an-acl-instance-to-a-given-instance) + - [Delete ACL rules of a given instance](#delete-acl-rules-of-a-given-instance) + - [List ACL rules of a given instance](#list-acl-rules-of-a-given-instance) +- [Backup management commands](#backup-management-commands) + - [Create a database backup](#create-a-database-backup) + - [Delete a database backup](#delete-a-database-backup) + - [Export a database backup](#export-a-database-backup) + - [Get a database backup](#get-a-database-backup) + - [List database backups](#list-database-backups) + - [Restore a database backup](#restore-a-database-backup) + - [Update a database backup](#update-a-database-backup) +- [Instance TLS certificate management commands](#instance-tls-certificate-management-commands) + - [Get the TLS certificate of an instance](#get-the-tls-certificate-of-an-instance) +- [Database management commands](#database-management-commands) + - [Create a database in a given instance](#create-a-database-in-a-given-instance) + - [Delete a database in a given instance](#delete-a-database-in-a-given-instance) + - [List all database in a given instance](#list-all-database-in-a-given-instance) +- [Database engines commands](#database-engines-commands) + - [List available database engines](#list-available-database-engines) +- [Instance management commands](#instance-management-commands) + - [Clone an instance](#clone-an-instance) + - [Create an instance](#create-an-instance) + - [Delete an instance](#delete-an-instance) + - [Get an instance](#get-an-instance) + - [List instances](#list-instances) + - [Get instance metrics](#get-instance-metrics) + - [Update an instance](#update-an-instance) + - [Upgrade an instance to an higher instance type](#upgrade-an-instance-to-an-higher-instance-type) + - [Wait for an instance to reach a stable state](#wait-for-an-instance-to-reach-a-stable-state) +- [Instance logs management commands](#instance-logs-management-commands) + - [List available logs of a given instance](#list-available-logs-of-a-given-instance) + - [Prepare logs of a given instance](#prepare-logs-of-a-given-instance) +- [Node types management commands](#node-types-management-commands) + - [List available node types](#list-available-node-types) +- [User privileges management commands](#user-privileges-management-commands) + - [List privileges of a given user in a given database in a given instance](#list-privileges-of-a-given-user-in-a-given-database-in-a-given-instance) + - [Set privileges of a given user in a given database in a given instance](#set-privileges-of-a-given-user-in-a-given-database-in-a-given-instance) +- [Settings management commands](#settings-management-commands) + - [Add an instance setting](#add-an-instance-setting) + - [Delete an instance setting](#delete-an-instance-setting) +- [User management commands](#user-management-commands) + - [Create an user in a given instance](#create-an-user-in-a-given-instance) + - [Delete an user in a given instance](#delete-an-user-in-a-given-instance) + - [List users of a given instance](#list-users-of-a-given-instance) + - [Update an user in a given instance](#update-an-user-in-a-given-instance) + + +## Access Control List (ACL) management commands + +Network Access Control List allows to control network in and out traffic by setting up ACL rules. + + + +### Add an ACL instance to a given instance + +Add an ACL instance to a given instance. + +**Usage:** + +``` +scw rdb acl add [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance you want to add acl rules to | +| rules.{index}.ip | | | +| rules.{index}.description | | | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Delete ACL rules of a given instance + +Delete ACL rules of a given instance. + +**Usage:** + +``` +scw rdb acl delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance you want to delete an ACL rules from | +| acl-rule-ips.{index} | | ACL rules IP present on the instance | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### List ACL rules of a given instance + +List ACL rules of a given instance. + +**Usage:** + +``` +scw rdb acl list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## Backup management commands + +Save and restore backups of your database instance. + + + +### Create a database backup + +Create a database backup. + +**Usage:** + +``` +scw rdb backup create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | | UUID of the instance | +| database-name | | Name of the database you want to make a backup of | +| name | | Name of the backup | +| expires-at | | Expiration date (Format ISO 8601) | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Delete a database backup + +Delete a database backup. + +**Usage:** + +``` +scw rdb backup delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| database-backup-id | Required | UUID of the database backup to delete | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Export a database backup + +Export a database backup. + +**Usage:** + +``` +scw rdb backup export [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| database-backup-id | Required | | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Get a database backup + +Get a database backup. + +**Usage:** + +``` +scw rdb backup get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| database-backup-id | Required | UUID of the database backup | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### List database backups + +List database backups. + +**Usage:** + +``` +scw rdb backup list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | | Name of the database backups | +| order-by | One of: `created_at_asc`, `created_at_desc`, `name_asc`, `name_desc`, `status_asc`, `status_desc` | Criteria to use when ordering database backups listing | +| instance-id | | UUID of the instance | +| organization-id | | Organization ID the database backups belongs to | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Restore a database backup + +Restore a database backup. + +**Usage:** + +``` +scw rdb backup restore [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| database-name | | Defines the destination database in order to restore into a specified database, the default destination is set to the origin database of the backup | +| database-backup-id | Required | Backup of a logical database | +| instance-id | Required | Defines the rdb instance where the backup has to be restored | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Update a database backup + +Update a database backup. + +**Usage:** + +``` +scw rdb backup update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| database-backup-id | Required | UUID of the database backup to update | +| name | | Name of the Database Backup | +| expires-at | | Expiration date (Format ISO 8601) | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## Instance TLS certificate management commands + +Instance TLS certificate management commands. + + +### Get the TLS certificate of an instance + +Get the TLS certificate of an instance. + +**Usage:** + +``` +scw rdb certificate get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## Database management commands + +Manage logical databases on your instance + + + +### Create a database in a given instance + +Create a database in a given instance. + +**Usage:** + +``` +scw rdb database create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance where to create the database | +| name | | Name of the database | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Delete a database in a given instance + +Delete a database in a given instance. + +**Usage:** + +``` +scw rdb database delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance where to delete the database | +| name | Required | Name of the database to delete | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### List all database in a given instance + +List all database in a given instance. + +**Usage:** + +``` +scw rdb database list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | | Name of the database | +| managed | | Whether or not the database is managed | +| owner | | User that owns this database | +| order-by | One of: `name_asc`, `name_desc`, `size_asc`, `size_desc` | Criteria to use when ordering database listing | +| instance-id | Required | UUID of the instance to list database of | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## Database engines commands + +Software that stores and retrieves data from a database. Each database engine has a name and versions. + + + +### List available database engines + +List available database engines. + +**Usage:** + +``` +scw rdb engine list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## Instance management commands + +A Database Instance is composed of one or more Nodes, depending of the is_ha_cluster setting. Autohealing is enabled by default for HA clusters. Database automated backup is enabled by default in order to prevent data loss. + + + +### Clone an instance + +Clone an instance. + +**Usage:** + +``` +scw rdb instance clone [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance you want to clone | +| name | | Name of the clone instance | +| node-type | | Node type of the clone | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Create an instance + +Create an instance. + +**Usage:** + +``` +scw rdb instance create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | Required | Name of the instance | +| engine | Required | Database engine of the database (PostgreSQL, MySQL, ...) | +| user-name | Required | Name of the user created when the instance is created | +| password | Required | Password of the user | +| node-type | Required
Default: `DB-DEV-S`
One of: `DB-DEV-S`, `DB-DEV-M`, `DB-DEV-L`, `DB-DEV-XL`, `DB-GP-XS`, `DB-GP-S`, `DB-GP-M`, `DB-GP-L`, `DB-GP-XL` | Type of node to use for the instance | +| is-ha-cluster | | Whether or not High-Availability is enabled | +| disable-backup | | Whether or not backups are disabled | +| tags.{index} | | Tags to apply to the instance | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Delete an instance + +Delete an instance. + +**Usage:** + +``` +scw rdb instance delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance to delete | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Get an instance + +Get an instance. + +**Usage:** + +``` +scw rdb instance get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### List instances + +List instances. + +**Usage:** + +``` +scw rdb instance list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| tags.{index} | | List instance that have a given tags | +| name | | List instance that match a given name pattern | +| order-by | One of: `created_at_asc`, `created_at_desc`, `name_asc`, `name_desc`, `region`, `status_asc`, `status_desc` | Criteria to use when ordering instance listing | +| organization-id | | Organization ID to list the instance of | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Get instance metrics + +Get database instance metrics. + +**Usage:** + +``` +scw rdb instance metrics [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance | +| start-date | | Start date to gather metrics from | +| end-date | | End date to gather metrics from | +| metric-name | | Name of the metric to gather | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Update an instance + +Update an instance. + +**Usage:** + +``` +scw rdb instance update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| backup-schedule-frequency | | In hours | +| backup-schedule-retention | | In days | +| is-backup-schedule-disabled | | Whether or not the backup schedule is disabled | +| name | | Name of the instance | +| instance-id | Required | UUID of the instance to update | +| tags.{index} | | Tags of a given instance | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Upgrade an instance to an higher instance type + +Upgrade your current `node_type` or enable high availability on your standalone database instance. + +**Usage:** + +``` +scw rdb instance upgrade [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | | +| node-type | One of: `DB-DEV-S`, `DB-DEV-M`, `DB-DEV-L`, `DB-DEV-XL`, `DB-GP-XS`, `DB-GP-S`, `DB-GP-M`, `DB-GP-L`, `DB-GP-XL` | | +| enable-ha | | | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Wait for an instance to reach a stable state + +Wait for an instance to reach a stable state. This is similar to using --wait flag. + +**Usage:** + +``` +scw rdb instance wait [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | ID of the instance you want to wait for. | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + +**Examples:** + + +Wait for an instance to reach a stable state +``` +scw rdb instance wait 11111111-1111-1111-1111-111111111111 +``` + + + + +## Instance logs management commands + +Instance logs management commands. + + +### List available logs of a given instance + +List available logs of a given instance. + +**Usage:** + +``` +scw rdb log list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | | +| order-by | One of: `created_at_asc`, `created_at_desc` | | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Prepare logs of a given instance + +Prepare your instance logs. Logs will be grouped on a minimum interval of a day. + +**Usage:** + +``` +scw rdb log prepare [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance you want logs of | +| start-date | | Start datetime of your log. Format: `{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z` | +| end-date | | End datetime of your log. Format: `{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z` | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## Node types management commands + +Node types powering your instance + + + +### List available node types + +List available node types. + +**Usage:** + +``` +scw rdb node-type list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| include-disabled-types | | Whether or not to include disabled types | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## User privileges management commands + +Define some privileges to a user on a specific database. + + + +### List privileges of a given user in a given database in a given instance + +List privileges of a given user in a given database in a given instance. + +**Usage:** + +``` +scw rdb privilege list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| order-by | One of: `user_name_asc`, `user_name_desc`, `database_name_asc`, `database_name_desc` | Criteria to use when ordering privileges listing | +| database-name | | Name of the database | +| instance-id | Required | UUID of the instance | +| user-name | | Name of the user | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Set privileges of a given user in a given database in a given instance + +Set privileges of a given user in a given database in a given instance. + +**Usage:** + +``` +scw rdb privilege set [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance | +| database-name | | Name of the database | +| user-name | | Name of the user | +| permission | One of: `readonly`, `readwrite`, `all`, `custom`, `none` | Permission to set (Read, Read/Write, All, Custom) | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## Settings management commands + +Instance Settings are tunables of Database Engines. Available settings depend on the database engine and its version. + + + +### Add an instance setting + +Add an instance setting. + +**Usage:** + +``` +scw rdb settings add [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance you want to add settings to | +| settings.{index}.name | | | +| settings.{index}.value | | | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Delete an instance setting + +Delete an instance setting. + +**Usage:** + +``` +scw rdb settings delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance to delete settings from | +| setting-names.{index} | | Settings names to delete | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## User management commands + +Manage users on your instance + + + +### Create an user in a given instance + +Create an user in a given instance. + +**Usage:** + +``` +scw rdb user create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance you want to create a user in | +| name | | Name of the user you want to create | +| password | | Password of the user you want to create | +| is-admin | | Whether the user you want to create will have administrative privileges | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Delete an user in a given instance + +Delete an user in a given instance. + +**Usage:** + +``` +scw rdb user delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance to delete a user from | +| name | Required | Name of the user | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### List users of a given instance + +List users of a given instance. + +**Usage:** + +``` +scw rdb user list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | | Name of the user | +| order-by | One of: `name_asc`, `name_desc`, `is_admin_asc`, `is_admin_desc` | Criteria to use when ordering users listing | +| instance-id | Required | UUID of the instance | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Update an user in a given instance + +Update an user in a given instance. + +**Usage:** + +``` +scw rdb user update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| instance-id | Required | UUID of the instance the user belongs to | +| name | Required | Name of the database user | +| password | | Password of the database user | +| is-admin | | Whether or not this user got administrative privileges | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + diff --git a/docs/commands/registry.md b/docs/commands/registry.md new file mode 100644 index 0000000000..5692694483 --- /dev/null +++ b/docs/commands/registry.md @@ -0,0 +1,387 @@ + +# Documentation for `scw registry` +Container registry API + +- [Image management commands](#image-management-commands) + - [Delete an image](#delete-an-image) + - [Get a image](#get-a-image) + - [List all your images](#list-all-your-images) + - [Update an existing image](#update-an-existing-image) +- [Install a local Docker credential helper](#install-a-local-docker-credential-helper) +- [Login to a registry](#login-to-a-registry) +- [Logout of a registry](#logout-of-a-registry) +- [Namespace management commands](#namespace-management-commands) + - [Create a new namespace](#create-a-new-namespace) + - [Delete an existing namespace](#delete-an-existing-namespace) + - [Get a namespace](#get-a-namespace) + - [List all your namespaces](#list-all-your-namespaces) + - [Update an existing namespace](#update-an-existing-namespace) +- [Tag management commands](#tag-management-commands) + - [Delete a tag](#delete-a-tag) + - [Get a tag](#get-a-tag) + - [List all your tags](#list-all-your-tags) + + +## Image management commands + +An image represents a container image. + +The visibility of an image can be public (everyone can pull it), private (only your organization can pull it) or inherit from the namespace visibility (default) +It can be changed with an update on the image via the registry API. + + + +### Delete an image + +Delete the image associated with the given id. + +**Usage:** + +``` +scw registry image delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| image-id | Required | The unique ID of the Image | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Get a image + +Get the image associated with the given id. + +**Usage:** + +``` +scw registry image get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| image-id | Required | The unique ID of the Image | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### List all your images + +List all your images. + +**Usage:** + +``` +scw registry image list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| order-by | One of: `created_at_asc`, `created_at_desc`, `name_asc`, `name_desc` | Field by which to order the display of Images | +| namespace-id | | Filter by the Namespace ID | +| name | | Filter by the Image name (exact match) | +| organization-id | | Filter by Organization ID | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Update an existing image + +Update the image associated with the given id. + +**Usage:** + +``` +scw registry image update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| image-id | Required | Image ID to update | +| visibility | One of: `visibility_unknown`, `inherit`, `public`, `private` | A `public` image is pullable from internet without authentication, opposed to a `private` image. `inherit` will use the namespace `is_public` parameter | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## Install a local Docker credential helper + +This command will install the Docker credential helper for your account. + +It will create a new script named docker-credential-scw. +This script will be called each time Docker needs the credentials and will return the correct credentials. +It avoid running docker login commands. + + +This command will install the Docker credential helper for your account. + +It will create a new script named docker-credential-scw. +This script will be called each time Docker needs the credentials and will return the correct credentials. +It avoid running docker login commands. + + +**Usage:** + +``` +scw registry install-docker-helper [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| path | Default: `/usr/local/bin` | Directory in which the Docker helper will be installed. This directory should be in your $PATH | + + + +## Login to a registry + +This command will run the correct command in order to log you in on the registry with the chosen program. +You will need to have the chosen binary installed on your system and in your PATH. + +This command will run the correct command in order to log you in on the registry with the chosen program. +You will need to have the chosen binary installed on your system and in your PATH. + +**Usage:** + +``` +scw registry login [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| program | Default: `docker`
One of: `docker`, `podman` | Program used to log in to the namespace | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## Logout of a registry + +This command will run the correct command in order to log you out of the registry with the chosen program. +You will need to have the chosen binary installed on your system and in your PATH. + +This command will run the correct command in order to log you out of the registry with the chosen program. +You will need to have the chosen binary installed on your system and in your PATH. + +**Usage:** + +``` +scw registry logout [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| program | Default: `docker`
One of: `docker`, `podman` | Program used to log in to the namespace | +| region | Default: `fr-par` | Region to target. If none is passed will use default region from the config | + + + +## Namespace management commands + +A namespace is for images what a folder is for files + +To use our services, the first step is to create a namespace. + +A namespace is for images what a folder is for files. Every push or pull must mention the namespace : +```docker pull rg.nl-ams.scw.cloud//:``` + +Note that a namespace name is unique on a region. Thus, if another client already has created "test", you can't have it as a namespace + +A namespace can be either public or private (default), which determines who can pull images. + + + +### Create a new namespace + +Create a new namespace. + +**Usage:** + +``` +scw registry namespace create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | Required | Define a namespace name | +| description | | Define a description | +| is-public | | Define the default visibility policy | +| organization-id | | Organization ID to use. If none is passed will use default organization ID from the config | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Delete an existing namespace + +Delete the namespace associated with the given id. + +**Usage:** + +``` +scw registry namespace delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| namespace-id | Required | The unique ID of the Namespace | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Get a namespace + +Get the namespace associated with the given id. + +**Usage:** + +``` +scw registry namespace get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| namespace-id | Required | The unique ID of the Namespace | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### List all your namespaces + +List all your namespaces. + +**Usage:** + +``` +scw registry namespace list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| order-by | One of: `created_at_asc`, `created_at_desc`, `description_asc`, `description_desc`, `name_asc`, `name_desc` | Field by which to order the display of Images | +| name | | Filter by the namespace name (exact match) | +| organization-id | | Filter by the namespace owner | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Update an existing namespace + +Update the namespace associated with the given id. + +**Usage:** + +``` +scw registry namespace update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| namespace-id | Required | Namespace ID to update | +| description | | Define a description | +| is-public | | Define the default visibility policy | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +## Tag management commands + +A tag represents a container tag of an image. + + + +### Delete a tag + +Delete the tag associated with the given id. + +**Usage:** + +``` +scw registry tag delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| tag-id | Required | The unique ID of the tag | +| force | | If two tags share the same digest the deletion will fail unless this parameter is set to true | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### Get a tag + +Get the tag associated with the given id. + +**Usage:** + +``` +scw registry tag get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| tag-id | Required | The unique ID of the Tag | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + +### List all your tags + +List all your tags. + +**Usage:** + +``` +scw registry tag list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| order-by | One of: `created_at_asc`, `created_at_desc`, `name_asc`, `name_desc` | Field by which to order the display of Images | +| image-id | Required | The unique ID of the image | +| name | | Filter by the tag name (exact match) | +| region | Default: `fr-par`
One of: `fr-par`, `nl-ams` | Region to target. If none is passed will use default region from the config | + + + diff --git a/docs/commands/version.md b/docs/commands/version.md new file mode 100644 index 0000000000..d4bfc94a81 --- /dev/null +++ b/docs/commands/version.md @@ -0,0 +1,6 @@ + +# Documentation for `scw version` +Display cli version + + + diff --git a/docs/styleguide.md b/docs/styleguide.md new file mode 100644 index 0000000000..cd3c8736bd --- /dev/null +++ b/docs/styleguide.md @@ -0,0 +1,52 @@ +# Styleguide + +## CLI + +This guide is used by contributors and documentation team to populate the long and short for each CLI commands. + +!! Warning !! If you wish to contribute to the documentation of a generated command, just open an issue for it. +A Scaleway team member will take into account your feedback to fix it across all our products. + +### Namespace style guide + +#### `short` + +Mostly a place holder: + +- `scw k8s` Kapsule management commands +- `scw object` Object storage management commands + +#### `long` + +Description about how the different resources can be combined. + +### Resource style guide + +#### `short` + +Mostly a placeholder: + +- `scw rdb user`: User management commands + +#### `long` + +- Complete explanation about what this resource is about +- what it does +- How this particular resource interact with other resources whether in this namespace or not +- What is the lifecycle of this command + +### Verb style guide + +#### `short` + +Mostly an english sentence that describe the action that will occur when this command run. +If you are with sub resources, mention the parent resource to help user grasp the scope of this action. + +##### Examples: + +- `scw rdb acl delete` Delete ACL rules for a given instance + +#### `long` + +Describe what will happen when this command in run. +How it could affect other resources whether in this namespace or outside of it. diff --git a/internal/core/cobra_builder.go b/internal/core/cobra_builder.go index b4f8a96591..64241f6470 100644 --- a/internal/core/cobra_builder.go +++ b/internal/core/cobra_builder.go @@ -126,16 +126,7 @@ func (b *cobraBuilder) hydrateCobra(cobraCmd *cobra.Command, cmd *Command) { cobraCmd.PersistentFlags().BoolP("wait", "w", false, "wait until the "+cmd.Resource+" is ready") } - cobraCmd.Annotations["CommandUsage"] = cobraCmd.CommandPath() - if cobraCmd.HasAvailableSubCommands() || len(cobraCmd.Commands()) > 0 { - cobraCmd.Annotations["CommandUsage"] += " " - } - if positionalArg := cmd.ArgSpecs.GetPositionalArg(); positionalArg != nil { - cobraCmd.Annotations["CommandUsage"] += " <" + positionalArg.Name + " ...>" - } - if len(cmd.ArgSpecs) > 0 { - cobraCmd.Annotations["CommandUsage"] += " [arg=value ...]" - } + cobraCmd.Annotations["CommandUsage"] = cmd.GetUsage(ExtractBinaryName(b.ctx), NewCommands(b.commands...)) } const usageTemplate = `USAGE: diff --git a/internal/core/cobra_usage_builder.go b/internal/core/cobra_usage_builder.go index e0d0d915a2..9051d1323d 100644 --- a/internal/core/cobra_usage_builder.go +++ b/internal/core/cobra_usage_builder.go @@ -3,13 +3,11 @@ package core import ( "bytes" "context" - "encoding/json" "fmt" "io" "strings" "text/tabwriter" - "github.com/scaleway/scaleway-cli/internal/args" "github.com/scaleway/scaleway-cli/internal/interactive" "github.com/scaleway/scaleway-sdk-go/logger" ) @@ -78,49 +76,7 @@ func buildExamples(binaryName string, cmd *Command) string { for _, cmdExample := range cmd.Examples { // Build title. title := fmt.Sprintf(" %s", cmdExample.Short) - commandLine := "" - switch { - case cmdExample.Raw != "": - commandLine = cmdExample.Raw - commandLine = strings.Trim(commandLine, "\n") - commandLine = interactive.RemoveIndent(commandLine) - case cmdExample.ArgsJSON != "": - // Query and path parameters don't have json tag, - // so we need to enforce a JSON tag on every field to make this work. - var cmdArgs = newObjectWithForcedJSONTags(cmd.ArgsType) - if err := json.Unmarshal([]byte(cmdExample.ArgsJSON), cmdArgs); err != nil { - panic(fmt.Errorf("in command '%s', example '%s': %w", cmd.getPath(), cmdExample.Short, err)) - } - var cmdArgsAsStrings, err = args.MarshalStruct(cmdArgs) - positionalArg := cmd.ArgSpecs.GetPositionalArg() - if positionalArg != nil { - for i, cmdArg := range cmdArgsAsStrings { - if !strings.HasPrefix(cmdArg, positionalArg.Prefix()) { - continue - } - cmdArgsAsStrings[i] = strings.TrimLeft(cmdArg, positionalArg.Prefix()) - // Switch the positional args with args at position 0 to make sure it is always at the beginning - cmdArgsAsStrings[0], cmdArgsAsStrings[i] = cmdArgsAsStrings[i], cmdArgsAsStrings[0] - break - } - } - - if err != nil { - panic(fmt.Errorf("in command '%s', example '%s': %w", cmd.getPath(), cmdExample.Short, err)) - } - - // Build command line example. - commandParts := []string{ - binaryName, - cmd.Namespace, - cmd.Resource, - cmd.Verb, - } - commandParts = append(commandParts, cmdArgsAsStrings...) - commandLine = strings.Join(commandParts, " ") - default: - panic(fmt.Errorf("in command '%s' invalid example '%s', it should either have a ArgsJSON or a Raw", cmd.getPath(), cmdExample.Short)) - } + commandLine := cmdExample.GetCommandLine(binaryName, cmd) commandLine = interactive.Indent(commandLine, 4) commandLine = strings.Trim(commandLine, "\n") diff --git a/internal/core/cobra_utils.go b/internal/core/cobra_utils.go index f22260ed45..0a83376056 100644 --- a/internal/core/cobra_utils.go +++ b/internal/core/cobra_utils.go @@ -168,7 +168,7 @@ func positionalArgHint(binaryName string, cmd *Command, hintValue string, otherA // Suggest to use the other arguments. suggestedArgs = append(suggestedArgs, otherArgs...) - suggestedCommand := append([]string{binaryName, cmd.GetCommandLine()}, suggestedArgs...) + suggestedCommand := append([]string{cmd.GetCommandLine(binaryName)}, suggestedArgs...) return "Try running: " + strings.Join(suggestedCommand, " ") } diff --git a/internal/core/command.go b/internal/core/command.go index ba3080a984..b524ecf588 100644 --- a/internal/core/command.go +++ b/internal/core/command.go @@ -108,8 +108,25 @@ func (c *Command) getPath() string { return strings.Join(path, indexCommandSeparator) } -func (c *Command) GetCommandLine() string { - return strings.ReplaceAll(c.getPath(), indexCommandSeparator, " ") +func (c *Command) GetCommandLine(binaryName string) string { + return strings.Trim(binaryName+" "+strings.ReplaceAll(c.getPath(), indexCommandSeparator, " "), " ") +} + +func (c *Command) GetUsage(binaryName string, commands *Commands) string { + parts := []string{ + c.GetCommandLine(binaryName), + } + + if commands.HasSubCommands(c) { + parts = append(parts, "") + } + if positionalArg := c.ArgSpecs.GetPositionalArg(); positionalArg != nil { + parts = append(parts, "<"+positionalArg.Name+" ...>") + } + if len(c.ArgSpecs) > 0 { + parts = append(parts, "[arg=value ...]") + } + return strings.Join(parts, " ") } // seeAlsosAsStr returns all See Alsos as a single string @@ -200,6 +217,27 @@ func (c *Commands) GetSortedCommand() []*Command { return commands } +func (c *Commands) HasSubCommands(cmd *Command) bool { + if cmd.Namespace != "" && cmd.Resource != "" && cmd.Verb != "" { + return false + } + if cmd.Namespace == "" && cmd.Resource == "" && cmd.Verb == "" { + return true + } + for _, command := range c.commands { + if command == cmd { + continue + } + if cmd.Resource == "" && cmd.Namespace == command.Namespace { + return true + } + if cmd.Verb == "" && cmd.Namespace == command.Namespace && cmd.Resource == command.Resource { + return true + } + } + return false +} + func (c *Command) getHumanMarshalerOpt() *human.MarshalOpt { if c.View != nil { return c.View.getHumanMarshalerOpt() diff --git a/internal/core/context.go b/internal/core/context.go index 5467aac1ed..a6db594a71 100644 --- a/internal/core/context.go +++ b/internal/core/context.go @@ -150,3 +150,15 @@ func ExtractConfigPathFlag(ctx context.Context) string { func ExtractProfileFlag(ctx context.Context) string { return extractMeta(ctx).ProfileFlag } + +// GetDocGenContext reuturn a minimal context that can be used by scw-doc-gen +func GetDocGenContext() context.Context { + ctx := context.Background() + client, _ := scw.NewClient( + scw.WithDefaultZone(scw.ZoneFrPar1), + scw.WithDefaultRegion(scw.RegionFrPar), + ) + return injectMeta(ctx, &meta{ + Client: client, + }) +} diff --git a/internal/core/example.go b/internal/core/example.go index 98b00f3d80..8c00bb1cf6 100644 --- a/internal/core/example.go +++ b/internal/core/example.go @@ -1,5 +1,14 @@ package core +import ( + "encoding/json" + "fmt" + "strings" + + "github.com/scaleway/scaleway-cli/internal/args" + "github.com/scaleway/scaleway-cli/internal/interactive" +) + // Example represents an example for the usage of a CLI command. type Example struct { @@ -12,3 +21,49 @@ type Example struct { // Raw is a raw example. Only one of ArgsJSON or Raw should be provided. Raw string } + +func (e *Example) GetCommandLine(binaryName string, cmd *Command) string { + switch { + case e.Raw != "": + res := e.Raw + res = strings.Trim(res, "\n") + res = interactive.RemoveIndent(res) + return res + case e.ArgsJSON != "": + // Query and path parameters don't have json tag, + // so we need to enforce a JSON tag on every field to make this work. + var cmdArgs = newObjectWithForcedJSONTags(cmd.ArgsType) + if err := json.Unmarshal([]byte(e.ArgsJSON), cmdArgs); err != nil { + panic(fmt.Errorf("in command '%s', example '%s': %w", cmd.getPath(), cmd.Short, err)) + } + var cmdArgsAsStrings, err = args.MarshalStruct(cmdArgs) + positionalArg := cmd.ArgSpecs.GetPositionalArg() + if positionalArg != nil { + for i, cmdArg := range cmdArgsAsStrings { + if !strings.HasPrefix(cmdArg, positionalArg.Prefix()) { + continue + } + cmdArgsAsStrings[i] = strings.TrimLeft(cmdArg, positionalArg.Prefix()) + // Switch the positional args with args at position 0 to make sure it is always at the beginning + cmdArgsAsStrings[0], cmdArgsAsStrings[i] = cmdArgsAsStrings[i], cmdArgsAsStrings[0] + break + } + } + + if err != nil { + panic(fmt.Errorf("in command '%s', example '%s': %w", cmd.getPath(), cmd.Short, err)) + } + + // Build command line example. + commandParts := []string{ + binaryName, + cmd.Namespace, + cmd.Resource, + cmd.Verb, + } + commandParts = append(commandParts, cmdArgsAsStrings...) + return strings.Join(commandParts, " ") + default: + panic(fmt.Errorf("in command '%s' invalid example '%s', it should either have a ArgsJSON or a Raw", cmd.getPath(), cmd.Short)) + } +} diff --git a/internal/docgen/docgen.go b/internal/docgen/docgen.go new file mode 100644 index 0000000000..2f499b0540 --- /dev/null +++ b/internal/docgen/docgen.go @@ -0,0 +1,148 @@ +package docgen + +import ( + "bytes" + "fmt" + "io/ioutil" + "path" + "regexp" + "strings" + "text/template" + + "github.com/scaleway/scaleway-cli/internal/core" +) + +type tplData struct { + Namespaces map[string]*tplNamespace +} + +type tplNamespace struct { + Cmd *core.Command + Commands *core.Commands + Resources map[string]*tplResource +} + +type tplResource struct { + Cmd *core.Command + Verbs map[string]*core.Command +} + +const ansi = "[\u001B\u009B][[\\]()#;?]*(?:(?:(?:[a-zA-Z\\d]*(?:;[a-zA-Z\\d]*)*)?\u0007)|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PRZcf-ntqry=><~]))" + +// Generate markdown documentation for a given list of commands +func GenerateDocs(commands *core.Commands, outDir string) error { + // Prepare data that will be sent to template engine + data := &tplData{ + Namespaces: map[string]*tplNamespace{}, + } + + for _, c := range commands.GetAll() { + if c.Hidden { + continue + } + + if data.Namespaces[c.Namespace] == nil { + data.Namespaces[c.Namespace] = &tplNamespace{ + Commands: commands, + Resources: map[string]*tplResource{}, + } + } + namespace := data.Namespaces[c.Namespace] + + // If we have no resource command is the namespace command + if c.Resource == "" { + namespace.Cmd = c + continue + } + + if namespace.Resources[c.Resource] == nil { + namespace.Resources[c.Resource] = &tplResource{ + Verbs: map[string]*core.Command{}, + } + } + resource := namespace.Resources[c.Resource] + + // If we have no verb command is the resource command + if c.Verb == "" { + resource.Cmd = c + continue + } + + resource.Verbs[c.Verb] = c + } + + for name, namespace := range data.Namespaces { + fmt.Println("Generating namespace", name) + namespaceDoc, err := renderNamespace(namespace) + if err != nil { + return err + } + err = ioutil.WriteFile(path.Join(outDir, name+".md"), []byte(namespaceDoc), 0600) + if err != nil { + return err + } + } + + return nil +} + +func renderNamespace(data *tplNamespace) (string, error) { + buffer := bytes.Buffer{} + err := newTemplate().ExecuteTemplate(&buffer, "namespace", data) + if err != nil { + return "", err + } + str := buffer.String() + return str, nil +} + +func newTemplate() *template.Template { + tpl := template.New("index") + tpl = tpl.Funcs(map[string]interface{}{ + "bq": func(count ...int) string { + return "`" + }, + "bbq": func(count ...int) string { + return "```" + }, + "map": func(args ...interface{}) map[string]interface{} { + res := map[string]interface{}{} + for i := 0; i < len(args); i += 2 { + res[args[i].(string)] = args[i+1] + } + return res + }, + "anchor": func(short string) string { + res := strings.ToLower(short) + res = strings.ReplaceAll(res, " ", "-") + res = strings.ReplaceAll(res, "/", "") + return res + }, + "remove_escape_sequence": func(s string) string { + re := regexp.MustCompile(ansi) + return re.ReplaceAllString(s, "") + }, + "arg_spec_flag": func(arg *core.ArgSpec) string { + parts := []string(nil) + if arg.Required { + parts = append(parts, "Required") + } + if arg.Default != nil { + _, doc := arg.Default(core.GetDocGenContext()) + parts = append(parts, fmt.Sprintf("Default: `%s`", doc)) + } + if len(arg.EnumValues) > 0 { + parts = append(parts, fmt.Sprintf("One of: `%s`", strings.Join(arg.EnumValues, "`, `"))) + } + return strings.Join(parts, "
") + }, + "default": func(defaultValue string, value string) string { + if value == "" { + return defaultValue + } + return value + }, + }) + tpl = template.Must(tpl.Parse(tplStr)) + return tpl +} diff --git a/internal/docgen/tpl.go b/internal/docgen/tpl.go new file mode 100644 index 0000000000..e47daea8c0 --- /dev/null +++ b/internal/docgen/tpl.go @@ -0,0 +1,72 @@ +package docgen + +const tplStr = ` + + +{{- define "namespace" -}} +{{ template "do_not_edit" }} +# Documentation for {{ bq }}scw {{ .Cmd.Namespace }}{{ bq }} +{{ remove_escape_sequence (.Cmd.Long | default .Cmd.Short) }} + +{{ range $resourceName, $resource := .Resources -}} +- [{{ $resource.Cmd.Short }}](#{{ anchor $resource.Cmd.Short }}) +{{- range $verbName, $cmd := $resource.Verbs }} + - [{{ $cmd.Short }}](#{{ anchor $cmd.Short }}) +{{- end }} +{{ end }} + +{{ range $resourceName, $resource := .Resources -}} +## {{ $resource.Cmd.Short }} + +{{ $resource.Cmd.Long }} + +{{ if $resource.Verbs | len -}} +{{ range $verbName, $cmd := $resource.Verbs }} +### {{ $cmd.Short }} + +{{ template "cmd" (map "Cmd" $cmd "Data" $) }} + +{{ end -}} +{{- else -}} +{{ template "cmd" (map "Cmd" $resource.Cmd "Data" $) }} + +{{ end }} +{{ end }} +{{- end -}} + +{{- define "cmd" -}} +{{ .Cmd.Long }} + +**Usage:** + +{{ bbq }} +{{ .Cmd.GetUsage "scw" .Data.Commands }} +{{ bbq }} +{{ if .Cmd.ArgSpecs }} + +**Args:** + +| Name | | Description | +|------|---|-------------| +{{ range $arg := .Cmd.ArgSpecs -}} +| {{ $arg.Name }} | {{ arg_spec_flag $arg }} | {{ $arg.Short }} | +{{ end -}} +{{- end -}} +{{- if .Cmd.Examples }} + +**Examples:** + +{{ range $example := .Cmd.Examples }} +{{ $example.Short }} +{{ bbq }} +{{ $example.GetCommandLine "scw" $.Cmd }} +{{ bbq }} +{{ end }} +{{ end }} +{{- end -}} + +{{- define "do_not_edit" -}} + +{{- end -}} + +` diff --git a/internal/namespaces/autocomplete/autocomplete.go b/internal/namespaces/autocomplete/autocomplete.go index da65fac972..1164f6dfc2 100644 --- a/internal/namespaces/autocomplete/autocomplete.go +++ b/internal/namespaces/autocomplete/autocomplete.go @@ -20,6 +20,7 @@ import ( func GetCommands() *core.Commands { return core.NewCommands( + autocompleteRootCommand(), autocompleteInstallCommand(), autocompleteCompleteBashCommand(), autocompleteCompleteFishCommand(), @@ -28,6 +29,14 @@ func GetCommands() *core.Commands { ) } +func autocompleteRootCommand() *core.Command { + return &core.Command{ + Short: `Autocomplete related commands`, + Long: ``, + Namespace: "autocomplete", + } +} + type autocompleteScript struct { CompleteScript string CompleteFunc string diff --git a/internal/namespaces/config/commands.go b/internal/namespaces/config/commands.go index b93bb2816b..142faaaa3d 100644 --- a/internal/namespaces/config/commands.go +++ b/internal/namespaces/config/commands.go @@ -35,17 +35,19 @@ func configRoot() *core.Command { configPath := scw.GetConfigPath() envVarTable := bytes.Buffer{} w := tabwriter.NewWriter(&envVarTable, 5, 1, 2, ' ', tabwriter.ANSIGraphicsRendition) - for _, envVar := range [][2]string{ - {"SCW_ACCESS_KEY", "The access key of a token (create a token at https://console.scaleway.com/account/credentials)"}, - {"SCW_SECRET_KEY", "The secret key of a token (create a token at https://console.scaleway.com/account/credentials)"}, - {"SCW_DEFAULT_ORGANIZATION_ID", "The default organization ID (get your organization ID at https://console.scaleway.com/account/credentials)"}, - {"SCW_DEFAULT_REGION", "The default region"}, - {"SCW_DEFAULT_ZONE", "The default availability zone"}, - {"SCW_API_URL", "URL of the API"}, - {"SCW_INSECURE", "Set this to true to enable the insecure mode"}, - {"SCW_PROFILE", "Set the config profile to use"}, + for _, envVar := range [][5]string{ + {"|", "Environment Variable", "|", "Description", "|"}, + {"|", "--", "|", "--", "|"}, + {"|", scw.ScwAccessKeyEnv, "|", "The access key of a token (create a token at https://console.scaleway.com/account/credentials)", "|"}, + {"|", scw.ScwSecretKeyEnv, "|", "The secret key of a token (create a token at https://console.scaleway.com/account/credentials)", "|"}, + {"|", scw.ScwDefaultOrganizationIDEnv, "|", "The default organization ID (get your organization ID at https://console.scaleway.com/account/credentials)", "|"}, + {"|", scw.ScwDefaultRegionEnv, "|", "The default region", "|"}, + {"|", scw.ScwDefaultZoneEnv, "|", "The default availability zone", "|"}, + {"|", scw.ScwAPIURLEnv, "|", "URL of the API", "|"}, + {"|", scw.ScwInsecureEnv, "|", "Set this to true to enable the insecure mode", "|"}, + {"|", scw.ScwActiveProfileEnv, "|", "Set the config profile to use", "|"}, } { - fmt.Fprintf(w, " %s\t%s\n", terminal.Style(envVar[0], color.Bold, color.FgBlue), envVar[1]) + fmt.Fprintf(w, " %s%s%s%s%s\n", envVar[0], terminal.Style(envVar[1], color.Bold, color.FgBlue), envVar[2], envVar[3], envVar[4]) } w.Flush() return &core.Command{ @@ -58,6 +60,7 @@ func configRoot() *core.Command { In this CLI, ` + terminal.Style(`environment variables have priority over the configuration file`, color.Bold) + `. The following environment variables are supported: + ` + envVarTable.String() + ` Read more about the config management engine at https://github.com/scaleway/scaleway-sdk-go/tree/master/scw#scaleway-config `), diff --git a/internal/qa/qa.go b/internal/qa/qa.go index b1003da475..86b6ab9eb5 100644 --- a/internal/qa/qa.go +++ b/internal/qa/qa.go @@ -29,7 +29,7 @@ type ShortMustNotEndWithDotError struct { } func (err ShortMustNotEndWithDotError) Error() string { - return "short must not end with '.' for command '" + err.Command.GetCommandLine() + "'" + return "short must not end with '.' for command '" + err.Command.GetCommandLine("scw") + "'" } func testShortEndWithDotError(commands *core.Commands) []error { @@ -49,7 +49,7 @@ type ShortMustBePresentError struct { } func (err ShortMustBePresentError) Error() string { - return "short must be present for command '" + err.Command.GetCommandLine() + "'" + return "short must be present for command '" + err.Command.GetCommandLine("scw") + "'" } func testShortIsNotPresentError(commands *core.Commands) []error { @@ -70,7 +70,7 @@ type WellKnownArgOrderError struct { } func (err WellKnownArgOrderError) Error() string { - return "well-known arg order must be respected '" + err.Command.GetCommandLine() + "', arg '" + err.Argspec.Name + "'" + return "well-known arg order must be respected '" + err.Command.GetCommandLine("scw") + "', arg '" + err.Argspec.Name + "'" } type WellKnownArgAtTheEndError struct { @@ -79,7 +79,7 @@ type WellKnownArgAtTheEndError struct { } func (err WellKnownArgAtTheEndError) Error() string { - return "well-known arg must be at the end'" + err.Command.GetCommandLine() + "', arg '" + err.Argspec.Name + "'" + return "well-known arg must be at the end'" + err.Command.GetCommandLine("scw") + "', arg '" + err.Argspec.Name + "'" } const ( @@ -148,7 +148,7 @@ type ArgMustUseDashError struct { } func (err ArgMustUseDashError) Error() string { - return "arg must use dash for command '" + err.Command.GetCommandLine() + "', arg '" + err.Argspec.Name + "'" + return "arg must use dash for command '" + err.Command.GetCommandLine("scw") + "', arg '" + err.Argspec.Name + "'" } func testArgMustUseDashError(commands *core.Commands) []error { @@ -172,7 +172,7 @@ type PositionalArgMustBeRequiredError struct { } func (err PositionalArgMustBeRequiredError) Error() string { - return "positional argument must be required '" + err.Command.GetCommandLine() + "', arg '" + err.Argspec.Name + "'" + return "positional argument must be required '" + err.Command.GetCommandLine("scw") + "', arg '" + err.Argspec.Name + "'" } func testPositionalArgMustBeRequiredError(commands *core.Commands) []error { @@ -196,7 +196,7 @@ type ExampleCanHaveOnlyOneTypeOfExampleError struct { } func (err ExampleCanHaveOnlyOneTypeOfExampleError) Error() string { - return "arg must use dash for command '" + err.Command.GetCommandLine() + "', example #" + strconv.Itoa(err.ExampleIndex) + return "arg must use dash for command '" + err.Command.GetCommandLine("scw") + "', example #" + strconv.Itoa(err.ExampleIndex) } func testExampleCanHaveOnlyOneTypeOfExampleError(commands *core.Commands) []error { @@ -224,7 +224,7 @@ type DifferentLocalizationForNamespaceError struct { func (err DifferentLocalizationForNamespaceError) Error() string { return fmt.Sprintf("different localization for commands '%v', '%v': %v, %v", - err.Command1.GetCommandLine(), err.Command2.GetCommandLine(), err.ArgNames1, err.ArgNames2) + err.Command1.GetCommandLine("scw"), err.Command2.GetCommandLine("scw"), err.ArgNames1, err.ArgNames2) } func testDifferentLocalizationForNamespaceError(commands *core.Commands) []error { @@ -235,7 +235,7 @@ func testDifferentLocalizationForNamespaceError(commands *core.Commands) []error continue } - samePathLength := strings.Count(command1.GetCommandLine(), " ") == strings.Count(command2.GetCommandLine(), " ") + samePathLength := strings.Count(command1.GetCommandLine("scw"), " ") == strings.Count(command2.GetCommandLine("scw"), " ") sameNamespace := command1.Namespace == command2.Namespace @@ -297,7 +297,7 @@ type DuplicatedCommandError struct { } func (err DuplicatedCommandError) Error() string { - return fmt.Sprintf("duplicated command '%s'", err.Command.GetCommandLine()) + return fmt.Sprintf("duplicated command '%s'", err.Command.GetCommandLine("scw")) } // testDuplicatedCommandError testes that there is no duplicate command. @@ -306,7 +306,7 @@ func testDuplicatedCommandError(commands *core.Commands) []error { uniqueness := make(map[string]bool) for _, command := range commands.GetAll() { - key := command.GetCommandLine() + key := command.GetCommandLine("scw") if uniqueness[key] { errors = append(errors, &DuplicatedCommandError{Command: command})