About otc-tools
===============
This is the otc tool for using the Open Telekom Cloud APIs.  It is a simple
demonstrator using shell/curl/jq to use the OpenTelekomCloud's OpenStack and
OTC specific REST interfaces.  It is used for testing by the OTC engineering
team and can be used as a blueprint for own tooling. Unlike the more
extensive tools, this one does not pull in a load of dependencies.

Prefix any command by debug to observe the REST calls being made.

For production use, we recommend using the native OpenStack python client tools
(python-novaclient etc or the newer python-openstackclient), complemented by
the python-otcctools for specific OTC functions.  Or of course higher level
tools, such as ansible with python-shade or terraform.

Usage
-----
Set your OpenStack environment (OS_ variables) just like you do for the native
OpenStack clients (typically by sourcing a ~/.ostackrc or ~/novarc or ~/.openrc
file). The minimum set is OS_USERNAME, OS_USER_DOMAIN_NAME (could be derived from
OS_USERNAME for MyWorkplace users), OS_PASSWORD, OS_PROJECT_NAME (eu-de), and
OS_AUTH_URL (https://iam.eu-de.otc.t-systems.com/v3).

Optionally, you can also set some additional defaults on otc_env.sh by editing
it and copying it into your home as ~/.otc_env.sh.

When managing multipe OTC domains, you may create ~/.ostackrc.SUFFIX and
~/.s3rc.SUFFIX and set OTC_DOMAIN=SUFFIX to make otc read these files.

Please have a look the otc_env.sh file and look at the output from otc help --
this provides sufficient information to get doing.

otc.sh relies on a GNU date, so if you are running it on MacOS X, please install
GNU date by running `brew install gdate` and make it first in the PATH:
`ln -sf /usr/local/bin/gdate /usr/local/bin/date`

Limitations
-----------
This tool does not try to cover all functionality of OTC. Rather it tries to
be a demo and test tool for many functions; it however does fill in some gaps
where the OTC API is extended or different from the standard OpenStack API,
so feel free to use it here and contribute to fill gaps you care about. There
is a small, but active community on github.com/OpenTelekomCloud/.

The OpenStack REST API has paginated interfaces to allow the consumers to
control how large a response may get. Since 0.7.6, otc-tools ist using this
feature to avoid exceeding the maximum response sizes on OTC. (The API gateway
limits responses to a few hundred kB).
So otc-tools ends up doing a few REST calls in case you request large amounts
of data, such as otc.sh ecs list when you have hundreds of VMs.

You can control API limits using --limit= and --marker= options if you want
to manually control the amount of information. You can also use --maxgetkb=
to override the default API response limit (250kiB) when relying on
autopagination.

The command line parser is not overly smart.
The general syntax is:
  otc.sh [GLOBALOPTS] maincmd subcmd [LOCALOPTS] [POSPARAMS]
See otc.sh help for full help and otc.sh maincmd help for help on a specific
set of commands.

Note that for most commands that have positional parameters, the command
specific options (LOCALOPTS) need to precede the positional parameters.

otc.sh does not do any kind of version discovery, but just assumes support
for all commands that public OTC offers. This reduces complexity and
increases performance, and is a deliberate choice.

Some of otc.sh's functions will work with other OpenStack clouds; for
testing, even some keystonev2 support has been added. But this is not at
all meant to have production quality for any non-FusionSphere clouds.


Output formatting
-----------------
otc tools tries to output things in a human readable format. It has three basic
formats:

* The list format: It creates a table with columns that are separated by 3 spaces.
  Several values in a field are separated by one space (or a colon for ip:port
  and for vmid:device). The first three columns are standardized, first is the
  ID of the resource, second the name, third the status (if reported), then
  further information (size, AZ, relations, ...) is appended.
  There can be an optional header (explaining the column contents) which starts
  with a '#'.
  This format is returned by list and details subcommands and is supposed to be 
  parsed by humans.
  (Exception: When new services are implemented, I may just output JSON before
   I decide on a good list format.)
* The JSON format: The REST calls return JSON objects of course and jq is used
  to present a nicely formatted represntation of the object. The JSON can be
  further passed.
* The long running requests report the TASKID. With --nowait, this is the
  last output. Otherwise, the resource ID will be output last. By default the 
  task status will onlybe queried until the resource ID is known; with --wait,
  otc.sh will wait for the task to complete. There are some intermediate
  task status updates and waiting dots in between.

This has been tidied up for otc-tools-0.7 and should be more usable and less
fragile now. Nevertheless, this tool is not yet mature enough that we commit
to not break the output format here yet -- a future version might well provide
switches to control the output. Pull requests are welcome :-)

Custom commands
---------------
New in otc-tools-0.7.0, we support custom commands using
  otc custom GET|PUT|POST|DELETE|HEAD URL JSON
You can reference variables by using \$BASEURL \$CINDER_URL \$OS_PROJECT_ID.
These are not standardized and well-documented yet (except for the OS_ ones
which are the normal OpenStack environment). You'll need to check the source
code. But the most important ones you already know now ...
If you start the URL with a / (instead of http[s], \$BASEURL will be prepended.
There is an optional --jqfilter FILTERSTRING.
By default, the output from the REST call is passed through jq -r '.'.
You can replace this with --jqfilter '' which results in no processing.
Or you pass a string like --jqfilter '.servers[] | .id+\"   \"+.name'.
Note the quoting for \".

Return codes
------------
Some work has been done in the 0.7.x series to tidy up the return of response
codes; so otc.sh should really have a non-zero exit code if there were serious
failures.

Token cache
-----------
otc.sh does cache tokens (and the service catalog) in
~/tmp/.otc.cache.$OS_USERNAME.$OS_USER_DOMAIN_NAME.$OS_PROJECT_NAME
(for project-scoped tokens; domain-scoped tokens are without .$OS_PROJECT_NAME).
otc.sh ensures these files have safe permission (0600), but if your home
directory gets shared or backed up in unsafe ways, you might need to take
addtitional caution. Note that tokens are normally valid for 24hrs on OTC.
You can use the --nocache global option to not use the token cache.
If you have trouble with existing cache entries you might also
use --discardcache to force otc.sh to retrieve a new token (and store it).

Note that you can force the usage of domain-scoped tokens using --domainscope,
project-scoped tokens using --projectscope and unscoped using --unscoped.
otc.sh normally knows what kind of token is needed for which command, but
for the custom functions the default (project scoped tokens) may not always
fit.


Packages
--------
Packages (RPMs/DEBs) on open Build Service home:garloff:OTC
https://build.opensuse.org/package/show/home:garloff:OTC/otc-tools

A docker container image 
[tsiotc/otc-client](https://hub.docker.com/r/tsiotc/otc-client)
is available on dockerhub.

You can of course also just grab this script from github; please install
curl and jq to make it work; optionally also s3 (libs3/libs3-2).