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 command
cloudy 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 the
cloudy 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 command cloudy 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.
