upcloud-cli

UpCloud CLI - upctl

upctl provides a command-line interface to UpCloud services. It allows you to control your resources from the command line or any compatible interface.

UpCloud command line client

Usage:
upctl [command]

Available Commands:
account     Manage account
completion  Generate shell completion code
defaults    Generate defaults
ip-address  Manage ip address
network     Manage network
router      Manage router
server      Manage servers
storage     Manage storages

Use "upctl [command] --help" for more information about a command.

Installation

As upctl is currently in beta, we aren't yet offering it through different packaging managers. Expect this to change once we hit version 1.0.0.

To use upctl, download the upctl binary from the Releases page. After downloading, verify that the client works.

macOS

sudo curl -o /usr/local/bin/upctl https://github.com/UpCloudLtd/upcloud-cli/releases/download/v<VERSION>/upctl-v<VERSION>-darwin-amd64
sudo chmod +x /usr/local/bin/upctl
upctl -h

Setting up bash completion requires a few commands more.

brew install bash-completion
sudo upctl completion bash > /usr/local/etc/bash_completion.d/upctl
echo "[ -f /usr/local/etc/bash_completion ] && . /usr/local/etc/bash_completion" >> ~/.bash_profile
. /usr/local/etc/bash_completion

Linux

sudo curl -o /usr/local/bin/upctl https://github.com/UpCloudLtd/upcloud-cli/releases/download/v<VERSION>/upctl-v<VERSION>-linux-amd64
sudo chmod +x /usr/local/bin/upctl
upctl -h

Bash completion can also be set up with some extra commands. You should adapt this for your package manager.

sudo apt install bash-completion
sudo upctl completion bash > /etc/bash_completion.d/upctl
echo "[ -f /etc/bash_completion ] && . /etc/bash_completion" >> ~/.bash_profile
. /etc/bash_completion

Windows

Invoke-WebRequest -Uri "https://github.com/UpCloudLtd/upcloud-cli/releases/download/v<VERSION>/upctl-v<VERSION>-windows-amd64" -OutFile "upctl.exe"
upctl.exe -h

Quick Start

Create a upctl.yaml config file with user credentials into your home directory's .config dir ($HOME/.config/upctl.yaml) or the current directory.

username: your_upcloud_username
password: your_upcloud_password

Credentials can also be stored at environment variables UPCLOUD_USERNAME and UPCLOUD_PASSWORD. If variables are set, matching config file items are ignored.

Run something to test that the credentials are working.

$ upctl server list
 UUID                                   Hostname             Plan        Zone      State   
────────────────────────────────────── ──────────────────── ─────────── ───────── ─────────
 00229ddf-0e46-45b5-a8f7-cad2c8d11f6a   server1              2xCPU-4GB   de-fra1   stopped 
 003c9d77-0237-4ee7-b3a1-306efba456dc   server2              1xCPU-2GB   sg-sin1   started

Examples

Every command has a help included and you can find all its options by adding -h at the end of the command, like upctl network list -h. Below, you'll find a few common commands that have many other available options as well.

Create a new server

upctl server create --hostname test-server.io --zone es-mad1 --ssh-keys ~/.ssh/id_rsa.pub

NOTE: You will have to specify a method for authentication by

• ssh-keys --ssh-keys id_rsa.pub
• or password delivery --password-delivery sms

Note: If you have a custom operating system template, these don't work by default. Use --os your-custom-img with --metadata to make the keys available through the metadata service.

Server title defaults to hostname. To set a different title, add --title "Test server"

Create storage

upctl storage create --size 25 --title test-storage --zone es-mad1

Note: Storage size is in GB.

Attach storage to server

upctl server storage attach <SERVER-UUID> --storage <STORAGE-UUID>

Contributing

Contributions from the community are much appreciated! Please note that all features using our API should be implemented with UpCloud Golang API SDK. If something is missing from there, add an issue or PR in that repository instead before implementing it here.

• Check GitHub issues and pull requests before creating new ones
  • If the issue isn't yet reported, you can create a new issue.
• Besides bug reports, all improvement ideas and feature requests are more than welcome and can be submitted through GitHub issues.
  • New features and enhancements can be submitted by first forking the repository and then sending your changes back as a pull request.
• Following semantic versioning, we won't accept breaking changes within the major version (1.x.x, 2.x.x etc).
  • Such PRs can be open for some time and are only accepted when the next major version is being created.

Development

• upctl uses UpCloud Golang API SDK
• upctl is built on Cobra

You need a Golang version 1.11+ installed on your development machine. Use make to build and test the CLI. Makefile help can be found:

$ make help
build             Build program binary for current os/arch
build-all         Build all targets
build-linux       Build program binary for linux x86_64
build-darwin      Build program binary for darwin x86_64
build-windows     Build program binary for windows x86_64
test              Run tests
fmt               Run gofmt on all source files
clean             Cleanup everything

Requirements

This repository uses pre-commit and go-critic for maintaining code quality. Installing them is not mandatory, but it helps in avoiding the problems you'd otherwise encounter after opening a pull request as they are run by automated tests for all PRs.

Development quickstart

To begin development, first fork the repository to your own account, clone it and begin making changes.

git clone git@github.com/username/upcloud-cli.git
cd upcloud-cli
pre-commit install

Make the changes with your favorite editor. Once you're done, create a new branch and push it back to Github.

git checkout -b <branch-name>
<add your changes, "git status" helps>
git commit -m "New feature: create a new server in the nearest zone if not specified"
git push --set-upstream <branch-name>

After pushing the new branch, browse to your fork of the repository in GitHub and create a pull request from there. Once the pull request is created, please make changes to your branch based on the comments & discussion in the PR.

Releasing for beta versions

Current release process:

• Update CHANGELOG.md
• Tag a commit with the version you want to release e.g. v1.2.3
• Push the tag & commit to GitHub
  • GitHub actions will automatically set the version based on the tag, create a GitHub release, build the project, and upload binaries & SHA sum to the GitHub release
• Edit the new release in GitHub and add the changelog for this release
• Done!

License

MIT license