commit 478364d47b1365ac2477faa1292aca92cdd4b144 Author: JesusPerez Date: Sat Aug 28 14:15:11 2021 +0100 init repo diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c32f48c --- /dev/null +++ b/.gitignore @@ -0,0 +1,157 @@ +build +.k +OLD +tries +tmp +test +# enviroment to load on bin/build +.env + +# where souce code is clone with git +clone + +# where tools command are found +tools + +# where pipeline templates are found +templates + +# OSX leaves these everywhere on SMB shares +._* + +# OSX trash +.DS_Store + +# Eclipse files +.classpath +.project +.settings/** + +# Files generated by JetBrains IDEs, e.g. IntelliJ IDEA +.idea/ +*.iml + +# Vscode files +.vscode + +# This is where the result of the go build goes +/output*/ +/_output*/ +/_output + +# Emacs save files +*~ +\#*\# +.\#* + +# Vim-related files +[._]*.s[a-w][a-z] +[._]s[a-w][a-z] +*.un~ +Session.vim +.netrwhist + +# cscope-related files +cscope.* + +# Go test binaries +*.test +/hack/.test-cmd-auth + +# JUnit test output from ginkgo e2e tests +/junit*.xml + +# Mercurial files +**/.hg +**/.hg* + +# Vagrant +.vagrant +network_closure.sh + +# Local cluster env variables +/cluster/env.sh + +# Compiled binaries in third_party +/third_party/pkg + +# Also ignore etcd installed by hack/install-etcd.sh +/third_party/etcd* +/default.etcd + +# User cluster configs +.kubeconfig + +.tags* + +# Version file for dockerized build +.dockerized-kube-version-defs + +# Web UI +/www/master/node_modules/ +/www/master/npm-debug.log +/www/master/shared/config/development.json + +# Karma output +/www/test_out + +# precommit temporary directories created by ./hack/verify-generated-docs.sh and ./hack/lib/util.sh +/_tmp/ +/doc_tmp/ + +# Test artifacts produced by Jenkins jobs +/_artifacts/ + +# Go dependencies installed on Jenkins +/_gopath/ + +# Config directories created by gcloud and gsutil on Jenkins +/.config/gcloud*/ +/.gsutil/ + +# CoreOS stuff +/cluster/libvirt-coreos/coreos_*.img + +# Juju Stuff +/cluster/juju/charms/* +/cluster/juju/bundles/local.yaml + +# Downloaded Kubernetes binary release +/kubernetes/ + +# direnv .envrc files +.envrc + +# Downloaded kubernetes binary release tar ball +kubernetes.tar.gz + +# generated files in any directory +# TODO(thockin): uncomment this when we stop committing the generated files. +#zz_generated.* +zz_generated.openapi.go +zz_generated_*_test.go + +# TODO(roycaihw): remove this when we stop committing the generated definition +!staging/src/k8s.io/apiextensions-apiserver/pkg/generated/openapi/zz_generated.openapi.go +# low-change blueprint in code-generator to notice changes +!staging/src/k8s.io/code-generator/_examples/apiserver/openapi/zz_generated.openapi.go +# low-change sample-apiserver spec to be compilable when published +!staging/src/k8s.io/sample-apiserver/pkg/generated/openapi/zz_generated.openapi.go + +# make-related metadata +/.make/ + +# Just in time generated data in the source, should never be committed +/test/e2e/generated/bindata.go + +# This file used by some vendor repos (e.g. github.com/go-openapi/...) to store secret variables and should not be ignored +!\.drone\.sec + +# Godeps workspace +/Godeps/_workspace + +/bazel-* +*.pyc + +# generated by verify-vendor.sh +vendordiff.patch diff --git a/README.md b/README.md new file mode 100644 index 0000000..88896bf --- /dev/null +++ b/README.md @@ -0,0 +1,296 @@ +# Upclapi + +Fork me on GitHub + +## 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 declared and grouped together 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