CLI tool to easily spin up and control compute instances in various cloud environments.
Cloudy
Cloudy is a CLI tool to easily spin up and control compute instances in various cloud environments. You can think of it as an alternative to cloud-specific CLI tools, like aws
for AWS, or scw
for Scaleway.
Cloudy focuses on easily controlling compute instances (as opposed to the full functionality provided by cloud vendors). Cloudy's goal is to make it easy to run one-off cloud-based compute instances from the command line. It is somewhat similar to docker
or vagrant
, but for running instances in the Cloud instead of locally.
Cloudy is a good fit for things like the following:
- Spinning up a webserver in the cloud in order to show a friend or coworker a tech demo.
- Creating a temporary VPN in order to work around location restrictions.
- Creating a cloud-based environment to test a tool that you don't want to install locally.
Cloudy makes both spinning up and destroying an instance just a single command, as well as providing nice Bash completion. It is quite lightweight and quick to use.
For instance, creating a new instance on Scaleway with a 150 gb disk is as simple as:
$ cloudy scaleway create --volume-size 150
You can then SSH to the instance with the command:
$ cloudy ssh
When you're finished, you can destroy the instance (and all related resources) with the command:
$ cloudy destroy
Supported Cloud Providers
Cloudy currently supports the following cloud providers:
PRs providing support for additional cloud providers are always welcome!
Installation
Cloudy provides a single CLI tool, cloudy
.
This section lists installation instructions for various distros.
Generic Linux
There is a statically-linked x86_64 Linux ELF binary for cloudy
available on each of the GitHub Releases.
Nix / NixOS
Cloudy can be built with Nix by using the .nix
files in this repo:
$ nix-build
You can find the cloudy
binary in ./result/bin/cloudy
.
You can also install Cloudy from Nixpkgs by using the haskellPackages.cloudy
derivation:
$ nix-build '<nixpkgs>' -A haskellPackages.cloudy
Other Distros
PRs are welcome adding instructions for installing Cloudy on other Linux distributions!
Setup
Cloudy requires some setup before first use. The required setup is different depending on which cloud providers you want to use.
You must create a config file in ~/.config/cloudy/cloudy.yaml
. The following sections explain what options need to be set in the config file for each cloud provider.
Setup for Scaleway
You need to add things like your Scaleway access key and secret key to the ~/.config/cloudy/cloudy.yaml
config file.
You can find these values by generating a new API key on the Scaleway website at https://console.scaleway.com/iam/api-keys:
scaleway:
# (required) Scaleway key, secret, and default org and project. You can get these
# values from the Scaleway website by generating a new API key.
access_key: "SCWXIH85IR279KUH0X2I"
secret_key: "4985bead-91a4-4e96-9e8e-5d88280cf26b"
default_organization_id: "074712d9-c5e9-454c-b909-7a6be0c92cf0"
default_project_id: "074712d9-c5e9-454c-b909-7a6be0c92cf0"
# (optional) The default zone to use. You can find all zones listed in
# https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/guides/regions_and_zones
#
# If you don't specify this, then you'll need to pass it on the command line
# to all commands that require it.
default_zone: "nl-ams-1"
# (optional) The default instance type to use when creating instances.
# You can find all instance types in the output of the
# `cloudy scaleway list-instance-types` command.
#
# If you don't specify this, then you'll need to pass it on the command line
# to all commands that require it.
default_instance_type: "PLAY2-PICO"
# (optional) The default image to use. You can find other image IDs in the
# output of the `cloudy scaleway list-images` command.
#
# If you don't specify this, then you'll need to pass it on the command line
# to all commands that require it.
default_image_id: "ubuntu_noble"
Setup for AWS
(AWS support has not yet been added.)
Usage
This section explains how to use Cloudy, assuming you've gone through the setup above.
Create a Cloud Instance
The commands for creating a cloud instance differ between cloud providers. The commands for each cloud provider are explained below.
Note that if you experience an error when running a command to create a cloud instance, you must go to the cloud provider management UI and manually delete all resources that Cloudy has created.
Create a Scaleway Instance
A Scaleway instance can be created with a command like the following:
$ cloudy scaleway create \
--zone nl-ams-1 \
--instance-type PLAY2-NANO \
--volume-size 75 \
--image-id "1ec31ce3-bec3-4866-81fc-08d4b6966f9f"
This creates a PLAY2-NANO
Scaleway instance in zone nl-ams-1
with a 75 GB root disk, using an Ubuntu 24.04 disk image.
Here's the meaning of each of these arguments:
--zone
: A Scaleway zone. You can find all available values in https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/guides/regions_and_zones.--instance-type
: The Scaleway instance type. You can find all available instance types with the commandcloudy scaleway list-instance-types
.--volume-size
: The size in GB of the root disk. Some instance types have minimum / maximum root disk sizes that they support. You can find this information in the output of thecloudy scaleway list-instance-types
command.Cloudy provides no way to add additional disks to an instance.
--image-id
: The ID of the image. You can find all available image IDs with the commandcloudy scaleway list-images
. There are images available for many popular Linux distros.
See cloudy scaleway create --help
for more information.
Create an AWS EC2 Instance
(AWS support has not yet been added.)
List all Cloud Instances
You can see all your active Cloud Instances with the cloudy list
command:
$ cloudy list
|---------------------------------------------------------------------------------------------------------|
| instance id | instance name | created date | cloud | zone | ip | instance setup |
|=============|================|==================|==========|==========|================|================|
| 7 | belief-example | 2024-09-22 18:23 | scaleway | nl-ams-1 | 61.252.131.123 | nginx |
| 10 | land-secretary | 2024-09-22 18:24 | scaleway | fr-par-3 | 73.128.200.201 | (none) |
|---------------------------------------------------------------------------------------------------------|
SSH to Cloud Instance
You can SSH to an instance with the cloudy ssh
command:
$ cloudy ssh --name belief-example
You can pick which instance to SSH to with either the --name
or --id
argument. If you have only a single instance available, then you don't need to specify either the --name
or --id
argument.
Copy Files to/from Cloud Instance
You can copy files to an instance with a command like the following:
$ cloudy copy-file --to-instance ./my-local-file my-remote-file
This copies the local file my-local-file
to the cloud instance with the name my-remote-file
.
See cloudy copy-file --help
for more examples of copying files.
Destroy Cloud Instance
You can destroy a cloud instance with a command like the following:
$ cloudy destroy --name belief-example
You can pick which instance to SSH to with either the --name
or --id
argument. If you have only a single instance available, then you don't need to specify either the --name
or --id
argument.
After destroying the instance, you likely want to double check the cloud provider's management UI to confirm that all the related resources have been deleted.
Instance Setup Scripts
TODO
Moving Past Cloudy
Cloudy is meant to be simple and easy to use from the command line. If you want to change many additional settings when creating an instance, or you want to create multiple instances at once, you likely want a more flexible solution than Cloudy.
I recommend you look into either directly calling the CLI tool for a given cloud provider, or using a tool like Terraform to create cloud resources.
WARNING
Cloudy is still beta software. It is possible that cloud resources are not correctly created or deleted. You should make sure to manually check your cloud provider's management UI to confirm that all expected resources have been deleted after running commands like cloudy destroy
.
You should also make sure to check the cloud provider's management UI if any Cloudy commands fail, like cloudy PROVIDER create
.
Cloudy is provided as-is, without any warranty of any kind. You are solely responsible for all charges incurred due to Cloudy usage, even in the face of Cloudy-related bugs or mistakes.