Upclapi

Declarative UpCloud Go API with YAML

This was created to:

• create,delete,start,stop UpCloud servers.
• modify, delete UpCloud storages.
• Run commands with ssh in UpCloud servers.
• create servers Ansible inventories

TskSrvcs can be declared and grouped together in YAML files, some of them can use target resource UUID

All in a GO binary program thanks to Official UpCloudLtd GO API

It clearly does not try to replace tools like Terraform or Ansible,etc to manage Infraestructure rather as an alternative for some cases, like:

• simple servers provisioning
• servers tsksrvcs: start, stop, delete
• modify network interfaces
• float ip management
• modify storage
• automatic resources scale
• run commands on servers via ssh (output is captured)
• create Ansible inventories
• resources lists in json
• prototyping ...

Requirements for build

• Go 1.11+
• Go Modules

Build from source

• Clone this repository and go to folder:

git clone https://github.com/JesusPerez/upclapi.git
cd upclapi

• Build:

make

• Install ($GOPATH/bin):

make install

Run examples

• UpCloud Credentilas Use evironment variables like this:

export UPCLOUD_USERNAME="api-username"
export UPCLOUD_PASSWORD="api-password"

If creadentials are not found, this message will be displayed:

Auth info: Username must be specified
or
Auth info: Password must be specified

As an option it is possible to encrypt sensitive informations like:

• Credentials (username/password)

• Data config file in yaml

• Help

# Getting help 
go run ./... --help 

  -c string
    command to run [
    createserver, infoserver, restartserver, startserver, stopserver, deleteserver,
    infofloatip, movefloatip, modifyip,
    infotags, addtags, deletetags
    deletestorage, modifystorage,
    inventory, pubhosts, prvhosts
    runssh, runcmd
    ] (default "infoserver")
  -cmd string
    run [ssh] command
  -f string
    path to data file (default "datacfg.yaml")
  -id string
    server uuid
  -kdr string
    use coder
  -o string
    output format

• Create Server

./build/upclapi  -c createserver -f [yaml-config-file]

• Info Server

./build/upclapi  -c infoserver -f [yaml-config-file] 

./build/upclapi  -c infoserver -id server-hostname

• Move a Float IP

./build/upclapi  -c movefloatip -f [yaml-config-file]

• Get attached IP to Float IP

./build/upclapi  -c infofloatip -id float-ip ( or -f [yaml-config-file] ) -o attached

./build/upclapi  -c movefloatip -id float-ip-address::target-hostname

• Run SSH on Server (yaml-config-file has to include ssh* config section)

./build/upclapi  -c runssh -f [yaml-config-file] -ssh remote-command-to-execute

• Create Servers Ansible Inventory (yaml-config-file has to include cluster config section)

./build/upclapi  -c inventory -f [yaml-config-file] 

User account persmissions may not allow some tsksrvcs to create or deleted To fully manage, UpCloud owner account is mandatory

• To show info about coverage (will open in browser):

make show_coverage

• That's all! 🎉

YAML Config Example

floatIP: float-ip-for-servers
# "hostname" should start with hostPrefix or comment/remove this setting
hostPrefix: prefix-for-severs
# Could be same as hostPrefix, like "server" for server01, server02, etc
mainName: main-global/cluster/floatIP-name
servers:
# Repeat this section for each host 
  - hostname: test.example.com
    title: "Host title"
    # Cluster definition for this server not mandatory
    cluster: 
      role: master # role in ansible inventory
    ## SSH credentials to run commands not mandatory
    ssh:
      host: hostName-or-ip
      user: root
      password: ""
      type: key # can use password 
      keyPath: path-to-id_rsa-key-file
      port: 22
    # List of Tags (management can be restricted for user account)
    tags:     
    - server  
    loginUser:
      sshKeys:  # ssh-rsa public keys to add
        - ssh-rsa ....

    plan:  "1xCPU-1GB" # UpCloud Plan if is using an UpCloud "Simple Plan"
    metaData: 1
    timeZone: "UTC"
    userData: ""
    zone:   nl-ams1 # UpCloud Zone

    # List of Storage Devices, at least one
    storageDevices: 
     -  action: clone # UpCloud Storage Action
        title:   "Ubuntu Server 20.04 LTS (Focal Fossa)" 
        storage: "01000000-0000-4000-8000-000030200200" # UpCloud Storage UUID 
        size:    25  # Volume Size in GB 
        tier:    maxiops
    # If this sever can use floatIP set to 1 
    useFloatIP: 1 
    # List of Networks, at least one
    networks: 
      - access: utility # only if is need it
        family: IPv4
      - access: public  # only if is need it
        family: IPv4
      - access: private # if is going to use SDN
        family: IPv4
        network: UUID-SDN-NETWORK
        ipaddress: SDN-ip-address-or-use-SDN-DHCP

Environment

Main vars:

UpCloud API connetions

• UPCLOUD_USERNAME with username

• UPCLOUD_PASSWORD with password

• KUPCLAPI includes user + password encrypted

Use to preset settings:

Arg	Env. var
-c	UPCLAPI_COMMAND
-f	UPCLAPI_DATACFG
-id	UPCLAPI_ID
-cmd	UPCLAPI_RUNCMD
-kdr	UPCLAPI_ENCODER
-o	UPCLAPI_OUT

Coders and encoders

It is possible to encrypt sensitive informations like:

• Credentials (username/password)
• Data config file in yaml

Coders are called using operating system command (exec)

Tecoder from ZTerton backend developments is fully supported

Coder definition to be used:

var	content
cmd	command-path
abbrv	abbreviation
decoder	decoder-args
fdecoder	file-decoder-args
encoder	encoder-args
fencoder	file-encoder-args

Author

• Jesús Pérez.

Article assistance

If you want to say «thank you»:

1. Twit about article on your Twitter.
2. Add a GitHub Star and make Fork to this repository.
3. Donate some money to project author via PayPal: @paypal.me/.
4. Join UpCloud at my referral link (your profit is $25 credits and I will receive $50 worth of free credits).

Thanks for your support! 😘

References

UpCloudLtd go API

Let's write config for your Golang web app on right way — YAML 👌. Published @ 13 Feb 2020.

Go language: crypto / SSH executes remote commands

golang-enter-ssh-sudo-password-on-prompt-or-exit

License

MIT