Upclapi/README.md

# Upclapi

<img style="margin-top: 1em;width: 500px;border: 0" alt="Fork me on GitHub" src="logo/upclapi.svg?sanitize=true">

## Declarative [UpCloud](https://upcloud.com) Go API with YAML

This was created to:

- create,delete,start,stop [UpCloud servers](https://upcloud.com/products/cloud-servers/).
- modify, delete [UpCloud storages](https://upcloud.com/products/maxiops-storage/).
- Run commands with **ssh** in [UpCloud servers](https://upcloud.com/products/cloud-servers/). 
- create servers [Ansible inventories](https://docs.ansible.com/ansible/latest/index.html)

 > TskSrvcs can be <u>declared</u> and <u>grouped together</u> in [YAML](https://en.wikipedia.org/wiki/YAML) files, some of them can use target resource UUID 

 All in a [GO](https://golang.org/) binary program thanks to [Official UpCloudLtd GO API](https://github.com/UpCloudLtd/upcloud-go-api)

It clearly does not try to replace tools like [Terraform](https://www.terraform.io/) or [Ansible](https://docs.ansible.com/),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](https://docs.ansible.com/ansible/latest/index.html)
- resources lists in **json**
- prototyping
...

## Requirements for build

- Go `1.11+`
- Go Modules

## Build from source

- Clone this repository and go to folder:

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

- Build:

```bash
make
```

- Install ($GOPATH/bin):

```bash
make install
```

#### Run examples 

- [UpCloud](https://upcloud.com) Credentilas
Use evironment variables like this:

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

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

```txt
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

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

```txt
  -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

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

- Info Server

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

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

- Move a Float IP

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

- Get attached IP to Float IP

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

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

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

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

- Create Servers [Ansible Inventory](https://docs.ansible.com/ansible/latest/index.html)
  (yaml-config-file has to include **cluster** config section)

```bash
./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):

```bash
make show_coverage
```

- That's all! 🎉

## YAML Config Example

```yaml
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](https://developers.upcloud.com) 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](https://github.com/jesusperez).

## Article assistance

If you want to say «thank you»:

1. Twit about article [on your Twitter](https://twitter.com/intent/tweet?text=Let%27s%20write%20config%20for%20your%20Golang%20web%20app%20on%20right%20way%20%E2%80%94%20YAML%20%F0%9F%91%8C%20https%3A%2F%2Fdev.to%2Fkoddr%2Flet-s-write-config-for-your-golang-web-app-on-right-way-yaml-5ggp).
2. Add a GitHub Star and make Fork to this repository.
3. Donate some money to project author via PayPal: [@paypal.me/](https://paypal.me/).
4. Join UpCloud at my [referral link](https://upcloud.com/signup/?promo=CVR337) (your profit is **\$25** credits and I will receive \$50 worth of free credits).

Thanks for your support! 😘

## References

[UpCloudLtd go API](https://github.com/UpCloudLtd/upcloud-go-api)

[Let's write config for your Golang web app on right way — YAML 👌](https://dev.to/koddr/let-s-write-config-for-your-golang-web-app-on-right-way-yaml-5ggp). Published @ 13 Feb 2020.

[Go language: crypto / SSH executes remote commands](https://developpaper.com/go-language-crypto-ssh-executes-remote-commands/)

[golang-enter-ssh-sudo-password-on-prompt-or-exit](https://gist.github.com/boyzhujian/73b5ecd37efd6f8dd38f56e7588f1b58)

## License

MIT