From a30cafb8dde854519e075238039cb12309098cca Mon Sep 17 00:00:00 2001 From: Jules Casteran Date: Wed, 22 Nov 2023 15:23:50 +0100 Subject: [PATCH 1/2] feat(block): add commands --- internal/namespaces/block/v1alpha1/custom.go | 53 ++++++++++++++++++++ internal/namespaces/get_commands.go | 2 + 2 files changed, 55 insertions(+) create mode 100644 internal/namespaces/block/v1alpha1/custom.go diff --git a/internal/namespaces/block/v1alpha1/custom.go b/internal/namespaces/block/v1alpha1/custom.go new file mode 100644 index 0000000000..8fe73b5e3b --- /dev/null +++ b/internal/namespaces/block/v1alpha1/custom.go @@ -0,0 +1,53 @@ +package block + +import ( + "github.com/fatih/color" + "github.com/scaleway/scaleway-cli/v2/internal/core" + "github.com/scaleway/scaleway-cli/v2/internal/human" + block "github.com/scaleway/scaleway-sdk-go/api/block/v1alpha1" +) + +var ( + volumeStatusMarshalSpecs = human.EnumMarshalSpecs{ + block.VolumeStatusUnknownStatus: &human.EnumMarshalSpec{Attribute: color.Faint}, + block.VolumeStatusCreating: &human.EnumMarshalSpec{Attribute: color.FgBlue}, + block.VolumeStatusAvailable: &human.EnumMarshalSpec{Attribute: color.FgGreen}, + block.VolumeStatusInUse: &human.EnumMarshalSpec{Attribute: color.FgHiGreen}, + block.VolumeStatusDeleting: &human.EnumMarshalSpec{Attribute: color.FgBlue}, + block.VolumeStatusResizing: &human.EnumMarshalSpec{Attribute: color.FgBlue}, + block.VolumeStatusError: &human.EnumMarshalSpec{Attribute: color.FgRed}, + block.VolumeStatusSnapshotting: &human.EnumMarshalSpec{Attribute: color.FgBlue}, + block.VolumeStatusLocked: &human.EnumMarshalSpec{Attribute: color.FgRed}, + } + + snapshotStatusMarshalSpecs = human.EnumMarshalSpecs{ + block.SnapshotStatusUnknownStatus: &human.EnumMarshalSpec{Attribute: color.Faint}, + block.SnapshotStatusCreating: &human.EnumMarshalSpec{Attribute: color.FgBlue}, + block.SnapshotStatusAvailable: &human.EnumMarshalSpec{Attribute: color.FgGreen}, + block.SnapshotStatusError: &human.EnumMarshalSpec{Attribute: color.FgRed}, + block.SnapshotStatusDeleting: &human.EnumMarshalSpec{Attribute: color.FgBlue}, + block.SnapshotStatusDeleted: &human.EnumMarshalSpec{Attribute: color.Faint}, + block.SnapshotStatusInUse: &human.EnumMarshalSpec{Attribute: color.FgHiGreen}, + block.SnapshotStatusLocked: &human.EnumMarshalSpec{Attribute: color.FgRed}, + } + referenceStatusMarshalSpecs = human.EnumMarshalSpecs{ + block.ReferenceStatusUnknownStatus: &human.EnumMarshalSpec{Attribute: color.Faint}, + + block.ReferenceStatusAttaching: &human.EnumMarshalSpec{Attribute: color.FgBlue}, + block.ReferenceStatusAttached: &human.EnumMarshalSpec{Attribute: color.FgHiGreen}, + block.ReferenceStatusDetaching: &human.EnumMarshalSpec{Attribute: color.FgBlue}, + block.ReferenceStatusDetached: &human.EnumMarshalSpec{Attribute: color.FgGreen}, + block.ReferenceStatusSnapshotting: &human.EnumMarshalSpec{Attribute: color.FgBlue}, + block.ReferenceStatusError: &human.EnumMarshalSpec{Attribute: color.FgRed}, + } +) + +func GetCommands() *core.Commands { + cmds := GetGeneratedCommands() + + human.RegisterMarshalerFunc(block.VolumeStatus(""), human.EnumMarshalFunc(volumeStatusMarshalSpecs)) + human.RegisterMarshalerFunc(block.SnapshotStatus(""), human.EnumMarshalFunc(snapshotStatusMarshalSpecs)) + human.RegisterMarshalerFunc(block.ReferenceStatus(""), human.EnumMarshalFunc(referenceStatusMarshalSpecs)) + + return cmds +} diff --git a/internal/namespaces/get_commands.go b/internal/namespaces/get_commands.go index 1a34f7fec3..eaf33e0310 100644 --- a/internal/namespaces/get_commands.go +++ b/internal/namespaces/get_commands.go @@ -8,6 +8,7 @@ import ( autocompleteNamespace "github.com/scaleway/scaleway-cli/v2/internal/namespaces/autocomplete" "github.com/scaleway/scaleway-cli/v2/internal/namespaces/baremetal/v1" billing "github.com/scaleway/scaleway-cli/v2/internal/namespaces/billing/v2alpha1" + block "github.com/scaleway/scaleway-cli/v2/internal/namespaces/block/v1alpha1" cockpit "github.com/scaleway/scaleway-cli/v2/internal/namespaces/cockpit/v1beta1" configNamespace "github.com/scaleway/scaleway-cli/v2/internal/namespaces/config" container "github.com/scaleway/scaleway-cli/v2/internal/namespaces/container/v1beta1" @@ -86,6 +87,7 @@ func GetCommands() *core.Commands { ipfs.GetCommands(), documentdb.GetCommands(), mnq.GetCommands(), + block.GetCommands(), ) //if beta {} From 941141da9e295a866c724f6f464cc46cbc5d43f2 Mon Sep 17 00:00:00 2001 From: Jules Casteran Date: Wed, 22 Nov 2023 15:37:16 +0100 Subject: [PATCH 2/2] update doc --- ...l-usage-block-snapshot-create-usage.golden | 23 ++ ...l-usage-block-snapshot-delete-usage.golden | 19 ++ ...-all-usage-block-snapshot-get-usage.golden | 19 ++ ...all-usage-block-snapshot-list-usage.golden | 22 ++ ...l-usage-block-snapshot-update-usage.golden | 21 ++ ...test-all-usage-block-snapshot-usage.golden | 24 ++ .../test-all-usage-block-usage.golden | 22 ++ ...all-usage-block-volume-create-usage.golden | 26 ++ ...all-usage-block-volume-delete-usage.golden | 19 ++ ...st-all-usage-block-volume-get-usage.golden | 19 ++ ...t-all-usage-block-volume-list-usage.golden | 22 ++ ...-usage-block-volume-type-list-usage.golden | 18 ++ ...t-all-usage-block-volume-type-usage.golden | 20 ++ ...all-usage-block-volume-update-usage.golden | 24 ++ .../test-all-usage-block-volume-usage.golden | 24 ++ cmd/scw/testdata/test-main-usage-usage.golden | 1 + docs/commands/block.md | 278 ++++++++++++++++++ 17 files changed, 601 insertions(+) create mode 100644 cmd/scw/testdata/test-all-usage-block-snapshot-create-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-snapshot-delete-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-snapshot-get-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-snapshot-list-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-snapshot-update-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-snapshot-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-volume-create-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-volume-delete-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-volume-get-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-volume-list-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-volume-type-list-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-volume-type-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-volume-update-usage.golden create mode 100644 cmd/scw/testdata/test-all-usage-block-volume-usage.golden create mode 100644 docs/commands/block.md diff --git a/cmd/scw/testdata/test-all-usage-block-snapshot-create-usage.golden b/cmd/scw/testdata/test-all-usage-block-snapshot-create-usage.golden new file mode 100644 index 0000000000..f9e70222e9 --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-snapshot-create-usage.golden @@ -0,0 +1,23 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +To create a snapshot, the volume must be in the `in_use` or the `available` status. +If your volume is in a transient state, you need to wait until the end of the current operation. + +USAGE: + scw block snapshot create [arg=value ...] + +ARGS: + [volume-id] UUID of the volume to snapshot + [name] Name of the snapshot + [project-id] Project ID to use. If none is passed the default project ID will be used + [tags.{index}] List of tags assigned to the snapshot + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3) + +FLAGS: + -h, --help help for create + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-snapshot-delete-usage.golden b/cmd/scw/testdata/test-all-usage-block-snapshot-delete-usage.golden new file mode 100644 index 0000000000..0d9e8ac881 --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-snapshot-delete-usage.golden @@ -0,0 +1,19 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +You must specify the `snapshot_id` of the snapshot you want to delete. The snapshot must not be in use. + +USAGE: + scw block snapshot delete [arg=value ...] + +ARGS: + snapshot-id UUID of the snapshot + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3) + +FLAGS: + -h, --help help for delete + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-snapshot-get-usage.golden b/cmd/scw/testdata/test-all-usage-block-snapshot-get-usage.golden new file mode 100644 index 0000000000..04807f6bdc --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-snapshot-get-usage.golden @@ -0,0 +1,19 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +Retrieve technical information about a specific snapshot. Details such as size, volume type, and status are returned in the response. + +USAGE: + scw block snapshot get [arg=value ...] + +ARGS: + snapshot-id UUID of the snapshot + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3) + +FLAGS: + -h, --help help for get + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-snapshot-list-usage.golden b/cmd/scw/testdata/test-all-usage-block-snapshot-list-usage.golden new file mode 100644 index 0000000000..75d1aabdd8 --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-snapshot-list-usage.golden @@ -0,0 +1,22 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +List all available snapshots in a specified zone. By default, the snapshots listed are ordered by creation date in ascending order. This can be modified via the `order_by` field. + +USAGE: + scw block snapshot list [arg=value ...] + +ARGS: + [order-by] Criteria to use when ordering the list (created_at_asc | created_at_desc | name_asc | name_desc) + [project-id] Filter by Project ID + [volume-id] Filter snapshots by the ID of the original volume + [name] Filter snapshots by their names + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3 | all) + +FLAGS: + -h, --help help for list + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-snapshot-update-usage.golden b/cmd/scw/testdata/test-all-usage-block-snapshot-update-usage.golden new file mode 100644 index 0000000000..e2791f6d85 --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-snapshot-update-usage.golden @@ -0,0 +1,21 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +Update the name or tags of the snapshot. + +USAGE: + scw block snapshot update [arg=value ...] + +ARGS: + snapshot-id UUID of the snapshot + [name] When defined, is the name of the snapshot + [tags.{index}] List of tags assigned to the snapshot + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3) + +FLAGS: + -h, --help help for update + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-snapshot-usage.golden b/cmd/scw/testdata/test-all-usage-block-snapshot-usage.golden new file mode 100644 index 0000000000..96d0c3c95d --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-snapshot-usage.golden @@ -0,0 +1,24 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +You can then revert your data to the previous snapshot. You can also create a new read/write Block volume from a previous snapshot. + +USAGE: + scw block snapshot + +AVAILABLE COMMANDS: + create Create a snapshot of a volume + delete Delete a snapshot + get Get a snapshot + list List all snapshots + update Update a snapshot + +FLAGS: + -h, --help help for snapshot + +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 block snapshot [command] --help" for more information about a command. diff --git a/cmd/scw/testdata/test-all-usage-block-usage.golden b/cmd/scw/testdata/test-all-usage-block-usage.golden new file mode 100644 index 0000000000..ae52f78437 --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-usage.golden @@ -0,0 +1,22 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +This API allows you to use and manage your Block Storage volumes. + +USAGE: + scw block + +AVAILABLE COMMANDS: + snapshot A Block Storage snapshot is a read-only picture of a Block volume, taken at a specific time + volume A Block Storage volume is a logical storage drive on a network-connected storage system. It is exposed to Instances as if it were a physical disk, and can be attached and detached like a hard drive. Several Block volumes can be attached to one Instance at a time + volume-type Block Storage volume types are determined by their storage class and their IOPS. There are two storage classes available: `bssd` and `sbs`. The IOPS can be chosen for volumes of the `sbs` storage class + +FLAGS: + -h, --help help for block + +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 block [command] --help" for more information about a command. diff --git a/cmd/scw/testdata/test-all-usage-block-volume-create-usage.golden b/cmd/scw/testdata/test-all-usage-block-volume-create-usage.golden new file mode 100644 index 0000000000..36fdbddfd8 --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-volume-create-usage.golden @@ -0,0 +1,26 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +To create a new volume from scratch, you must specify `from_empty` and the `size`. +To create a volume from an existing snapshot, specify `from_snapshot` and the `snapshot_id` in the request payload instead, size is optional and can be specified if you need to extend the original size. The volume will take on the same volume class and underlying IOPS limitations as the original snapshot. + +USAGE: + scw block volume create [arg=value ...] + +ARGS: + name Name of the volume + perf-iops The maximum IO/s expected, according to the different options available in stock (`5000 | 15000`) + [project-id] Project ID to use. If none is passed the default project ID will be used + [from-empty.size] Volume size in bytes, with a granularity of 1 GB (10^9 bytes) + [from-snapshot.size] Volume size in bytes, with a granularity of 1 GB (10^9 bytes) + [from-snapshot.snapshot-id] Source snapshot from which volume will be created + [tags.{index}] List of tags assigned to the volume + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3) + +FLAGS: + -h, --help help for create + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-volume-delete-usage.golden b/cmd/scw/testdata/test-all-usage-block-volume-delete-usage.golden new file mode 100644 index 0000000000..eb21d77dac --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-volume-delete-usage.golden @@ -0,0 +1,19 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +You must specify the `volume_id` of the volume you want to delete. The volume must not be in the `in_use` status. + +USAGE: + scw block volume delete [arg=value ...] + +ARGS: + volume-id UUID of the volume + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3) + +FLAGS: + -h, --help help for delete + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-volume-get-usage.golden b/cmd/scw/testdata/test-all-usage-block-volume-get-usage.golden new file mode 100644 index 0000000000..9f19860b48 --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-volume-get-usage.golden @@ -0,0 +1,19 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +Retrieve technical information about a specific volume. Details such as size, type, and status are returned in the response. + +USAGE: + scw block volume get [arg=value ...] + +ARGS: + volume-id UUID of the volume + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3) + +FLAGS: + -h, --help help for get + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-volume-list-usage.golden b/cmd/scw/testdata/test-all-usage-block-volume-list-usage.golden new file mode 100644 index 0000000000..5e738902a9 --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-volume-list-usage.golden @@ -0,0 +1,22 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +List all existing volumes in a specified zone. By default, the volumes listed are ordered by creation date in ascending order. This can be modified via the `order_by` field. + +USAGE: + scw block volume list [arg=value ...] + +ARGS: + [order-by] Criteria to use when ordering the list (created_at_asc | created_at_desc | name_asc | name_desc) + [project-id] Filter by Project ID + [name] Filter the return volumes by their names + [product-resource-id] Filter by a product resource ID linked to this volume (such as an Instance ID) + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3 | all) + +FLAGS: + -h, --help help for list + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-volume-type-list-usage.golden b/cmd/scw/testdata/test-all-usage-block-volume-type-list-usage.golden new file mode 100644 index 0000000000..b7f0fd7ced --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-volume-type-list-usage.golden @@ -0,0 +1,18 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +List all available volume types in a specified zone. The volume types listed are ordered by name in ascending order. + +USAGE: + scw block volume-type list [arg=value ...] + +ARGS: + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3 | all) + +FLAGS: + -h, --help help for list + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-volume-type-usage.golden b/cmd/scw/testdata/test-all-usage-block-volume-type-usage.golden new file mode 100644 index 0000000000..57ceba03df --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-volume-type-usage.golden @@ -0,0 +1,20 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +Block Storage volume types are determined by their storage class and their IOPS. There are two storage classes available: `bssd` and `sbs`. The IOPS can be chosen for volumes of the `sbs` storage class. + +USAGE: + scw block volume-type + +AVAILABLE COMMANDS: + list List volume types + +FLAGS: + -h, --help help for volume-type + +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 block volume-type [command] --help" for more information about a command. diff --git a/cmd/scw/testdata/test-all-usage-block-volume-update-usage.golden b/cmd/scw/testdata/test-all-usage-block-volume-update-usage.golden new file mode 100644 index 0000000000..88cfcac490 --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-volume-update-usage.golden @@ -0,0 +1,24 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +Update the technical details of a volume, such as its name, tags, or its new size and `volume_type` (within the same Block Storage class). +You can only resize a volume to a larger size. It is currently not possible to change your Block Storage Class. + +USAGE: + scw block volume update [arg=value ...] + +ARGS: + volume-id UUID of the volume + [name] When defined, is the new name of the volume + [size] Optional field for increasing the size of a volume (size must be equal or larger than the current one) + [tags.{index}] List of tags assigned to the volume + [perf-iops] The maximum IO/s expected, according to the different options available in stock (`5000 | 15000`) + [zone=fr-par-1] Zone to target. If none is passed will use default zone from the config (fr-par-1 | pl-waw-3) + +FLAGS: + -h, --help help for update + +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 diff --git a/cmd/scw/testdata/test-all-usage-block-volume-usage.golden b/cmd/scw/testdata/test-all-usage-block-volume-usage.golden new file mode 100644 index 0000000000..f4617f34bf --- /dev/null +++ b/cmd/scw/testdata/test-all-usage-block-volume-usage.golden @@ -0,0 +1,24 @@ +🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲 +πŸŸ₯πŸŸ₯πŸŸ₯ STDERR️️ πŸŸ₯πŸŸ₯πŸŸ₯️ +Block volumes can be snapshotted, mounted or unmounted. + +USAGE: + scw block volume + +AVAILABLE COMMANDS: + create Create a volume + delete Delete a detached volume + get Get a volume + list List volumes + update Update a volume + +FLAGS: + -h, --help help for volume + +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 block volume [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 82a481379d..778d8c2af8 100644 --- a/cmd/scw/testdata/test-main-usage-usage.golden +++ b/cmd/scw/testdata/test-main-usage-usage.golden @@ -9,6 +9,7 @@ AVAILABLE COMMANDS: autocomplete Autocomplete related commands baremetal Elastic Metal API billing This API allows you to query your consumption + block This API allows you to use and manage your Block Storage volumes cockpit Cockpit API container Container as a Service API dns Domains and DNS API diff --git a/docs/commands/block.md b/docs/commands/block.md new file mode 100644 index 0000000000..382bd83feb --- /dev/null +++ b/docs/commands/block.md @@ -0,0 +1,278 @@ + +# Documentation for `scw block` +This API allows you to use and manage your Block Storage volumes. + +- [A Block Storage snapshot is a read-only picture of a Block volume, taken at a specific time](#a-block-storage-snapshot-is-a-read-only-picture-of-a-block-volume,-taken-at-a-specific-time) + - [Create a snapshot of a volume](#create-a-snapshot-of-a-volume) + - [Delete a snapshot](#delete-a-snapshot) + - [Get a snapshot](#get-a-snapshot) + - [List all snapshots](#list-all-snapshots) + - [Update a snapshot](#update-a-snapshot) +- [A Block Storage volume is a logical storage drive on a network-connected storage system. It is exposed to Instances as if it were a physical disk, and can be attached and detached like a hard drive. Several Block volumes can be attached to one Instance at a time](#a-block-storage-volume-is-a-logical-storage-drive-on-a-network-connected-storage-system.-it-is-exposed-to-instances-as-if-it-were-a-physical-disk,-and-can-be-attached-and-detached-like-a-hard-drive.-several-block-volumes-can-be-attached-to-one-instance-at-a-time) + - [Create a volume](#create-a-volume) + - [Delete a detached volume](#delete-a-detached-volume) + - [Get a volume](#get-a-volume) + - [List volumes](#list-volumes) + - [Update a volume](#update-a-volume) +- [Block Storage volume types are determined by their storage class and their IOPS. There are two storage classes available: `bssd` and `sbs`. The IOPS can be chosen for volumes of the `sbs` storage class](#block-storage-volume-types-are-determined-by-their-storage-class-and-their-iops.-there-are-two-storage-classes-available:-`bssd`-and-`sbs`.-the-iops-can-be-chosen-for-volumes-of-the-`sbs`-storage-class) + - [List volume types](#list-volume-types) + + +## A Block Storage snapshot is a read-only picture of a Block volume, taken at a specific time + +You can then revert your data to the previous snapshot. You can also create a new read/write Block volume from a previous snapshot. + + +### Create a snapshot of a volume + +To create a snapshot, the volume must be in the `in_use` or the `available` status. +If your volume is in a transient state, you need to wait until the end of the current operation. + +**Usage:** + +``` +scw block snapshot create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| volume-id | | UUID of the volume to snapshot | +| name | | Name of the snapshot | +| project-id | | Project ID to use. If none is passed the default project ID will be used | +| tags.{index} | | List of tags assigned to the snapshot | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3` | Zone to target. If none is passed will use default zone from the config | + + + +### Delete a snapshot + +You must specify the `snapshot_id` of the snapshot you want to delete. The snapshot must not be in use. + +**Usage:** + +``` +scw block snapshot delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| snapshot-id | Required | UUID of the snapshot | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3` | Zone to target. If none is passed will use default zone from the config | + + + +### Get a snapshot + +Retrieve technical information about a specific snapshot. Details such as size, volume type, and status are returned in the response. + +**Usage:** + +``` +scw block snapshot get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| snapshot-id | Required | UUID of the snapshot | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3` | Zone to target. If none is passed will use default zone from the config | + + + +### List all snapshots + +List all available snapshots in a specified zone. By default, the snapshots listed are ordered by creation date in ascending order. This can be modified via the `order_by` field. + +**Usage:** + +``` +scw block snapshot list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| order-by | One of: `created_at_asc`, `created_at_desc`, `name_asc`, `name_desc` | Criteria to use when ordering the list | +| project-id | | Filter by Project ID | +| volume-id | | Filter snapshots by the ID of the original volume | +| name | | Filter snapshots by their names | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3`, `all` | Zone to target. If none is passed will use default zone from the config | + + + +### Update a snapshot + +Update the name or tags of the snapshot. + +**Usage:** + +``` +scw block snapshot update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| snapshot-id | Required | UUID of the snapshot | +| name | | When defined, is the name of the snapshot | +| tags.{index} | | List of tags assigned to the snapshot | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3` | Zone to target. If none is passed will use default zone from the config | + + + +## A Block Storage volume is a logical storage drive on a network-connected storage system. It is exposed to Instances as if it were a physical disk, and can be attached and detached like a hard drive. Several Block volumes can be attached to one Instance at a time + +Block volumes can be snapshotted, mounted or unmounted. + + +### Create a volume + +To create a new volume from scratch, you must specify `from_empty` and the `size`. +To create a volume from an existing snapshot, specify `from_snapshot` and the `snapshot_id` in the request payload instead, size is optional and can be specified if you need to extend the original size. The volume will take on the same volume class and underlying IOPS limitations as the original snapshot. + +**Usage:** + +``` +scw block volume create [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| name | Required | Name of the volume | +| perf-iops | Required | The maximum IO/s expected, according to the different options available in stock (`5000 | 15000`) | +| project-id | | Project ID to use. If none is passed the default project ID will be used | +| from-empty.size | | Volume size in bytes, with a granularity of 1 GB (10^9 bytes) | +| from-snapshot.size | | Volume size in bytes, with a granularity of 1 GB (10^9 bytes) | +| from-snapshot.snapshot-id | | Source snapshot from which volume will be created | +| tags.{index} | | List of tags assigned to the volume | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3` | Zone to target. If none is passed will use default zone from the config | + + + +### Delete a detached volume + +You must specify the `volume_id` of the volume you want to delete. The volume must not be in the `in_use` status. + +**Usage:** + +``` +scw block volume delete [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| volume-id | Required | UUID of the volume | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3` | Zone to target. If none is passed will use default zone from the config | + + + +### Get a volume + +Retrieve technical information about a specific volume. Details such as size, type, and status are returned in the response. + +**Usage:** + +``` +scw block volume get [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| volume-id | Required | UUID of the volume | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3` | Zone to target. If none is passed will use default zone from the config | + + + +### List volumes + +List all existing volumes in a specified zone. By default, the volumes listed are ordered by creation date in ascending order. This can be modified via the `order_by` field. + +**Usage:** + +``` +scw block volume list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| order-by | One of: `created_at_asc`, `created_at_desc`, `name_asc`, `name_desc` | Criteria to use when ordering the list | +| project-id | | Filter by Project ID | +| name | | Filter the return volumes by their names | +| product-resource-id | | Filter by a product resource ID linked to this volume (such as an Instance ID) | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3`, `all` | Zone to target. If none is passed will use default zone from the config | + + + +### Update a volume + +Update the technical details of a volume, such as its name, tags, or its new size and `volume_type` (within the same Block Storage class). +You can only resize a volume to a larger size. It is currently not possible to change your Block Storage Class. + +**Usage:** + +``` +scw block volume update [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| volume-id | Required | UUID of the volume | +| name | | When defined, is the new name of the volume | +| size | | Optional field for increasing the size of a volume (size must be equal or larger than the current one) | +| tags.{index} | | List of tags assigned to the volume | +| perf-iops | | The maximum IO/s expected, according to the different options available in stock (`5000 | 15000`) | +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3` | Zone to target. If none is passed will use default zone from the config | + + + +## Block Storage volume types are determined by their storage class and their IOPS. There are two storage classes available: `bssd` and `sbs`. The IOPS can be chosen for volumes of the `sbs` storage class + +Block Storage volume types are determined by their storage class and their IOPS. There are two storage classes available: `bssd` and `sbs`. The IOPS can be chosen for volumes of the `sbs` storage class. + + +### List volume types + +List all available volume types in a specified zone. The volume types listed are ordered by name in ascending order. + +**Usage:** + +``` +scw block volume-type list [arg=value ...] +``` + + +**Args:** + +| Name | | Description | +|------|---|-------------| +| zone | Default: `fr-par-1`
One of: `fr-par-1`, `pl-waw-3`, `all` | Zone to target. If none is passed will use default zone from the config | + + +