uhc-cli

README

= UHC API Command Line Tools

This project contains the `uhc` command line tool that simplifies the use
of the _UHC_ API available in `api.openshift.com`.

== Installation

To install the tool run this command:

....
$ go get -u github.com/openshift-online/uhc-cli/cmd/uhc
....


== Log In

The first step to use the tool is to log-in with your
https://developers.redhat.com[developers.redhat.com] offline access token. To do
that use the `login` command:

....
$ uhc login --token=eyJ...
....

Alternatively, if you don't have an offline access token, you can log-in using
your https://developers.redhat.com[developers.redhat.com] user name and
password:

....
$ uhc login --user=... --password=...
....

However this option is deprecated, because it is less secure, and it will be
removed in the future.

This will use the provided token to request _OpenID_ access and refresh tokens
to _developers.redhat.com_. The tokens will be saved to the `.uhc.json` file in
your home directory, for future use.

By default the user name and password won't be saved to the `.uhc.json` file,
unless the `--persistent` option is explicitly used.

When the tokens expiry (usually after several hours) the tool will ask the user
to run the `login` command again.

The `login` command has options to log-in to other environments. For example, if
you have a service running in your local environment and you want to use the
tool to test it, you can log-in like this:

....
$ uhc login \
--token=eyJ... \
--url=https://localhost:8000 \
--insecure
....

NOTE: The `insecure` option disables verification of TLS certificates and host
names, do not use it in production environments.

== Obtaining Tokens

If you need the _OpenID_ token to use it with some other tool, you can use the
`token` command:

....
$ uhc token
....

That will print the raw _OpenID_ token, which you can then use to send requests
to the server with some other tool. For example, if you want to use
https://curl.haxx.se[curl] to retrieve your list of clusters you can do the
following:

....
$ curl \
--header "Authorization: Bearer $(uhc token)" \
https://api.openshift.com/api/clusters_mgmt/v1/clusters
....

The details of the _OpenID_ token, in JSON format, can be displayed using the
`--payload` option:

....
$ uhc token --payload
....

That will JSON representation of the token, which is useful to diagnose
authentication issues.

== Log Out

To log out run the `logout` command:

....
$ uhc logout
....

That will remove the `.uhc.json` file, so next time you want to use the tool you
will need to log-in again. You can also remove that file manually; the effect is
exactly the same.

== Retrieving Objects

Once logged in you can use the `get` command to retrieve objects. For example,
to retrieve the list of clusters with a name that starts with `my` you can use
the following command:

....
$ uhc get /api/clusters_mgmt/v1/clusters --parameter search="name like 'my%'"
....

The `--parameter` option is used to specify query parameters. It is most useful
combined with the `get` command, but it can be also used with any other command.
For detailed information about the query parameters supported by each resource
see the https://api.openshift.com[reference documentation].

The `search` query parameter is specially useful to retrieve objects from
collections that support searching. The syntax of this parameter is similar to
the syntax of the `where` clause of an SQL statement, but using the names of the
attributes of the object instead of the names of the columns of a table. For
example, in order to retrieve the clusters with a name starting with `my` and
created in a DNS domain ending with `example.com` the complete command can be
the following:

....
$ uhc get /api/clusters_mgmt/v1/clusters \
--parameter search="name like 'my%' and dns.base_domain like '%.example.com'"
....

To find the AWS regions in the US:

....
$ uhc get /api/clusters_mgmt/v1/cloud_providers/aws/regions \
--parameter search="name like 'US %'"
....

To find the clusters created after March 1st 2019:

....
$ uhc get /api/clusters_mgmt/v1/clusters \
--parameter search="creation_timestamp >= '2019-03-01'"
....

To find the clusters that are either ready or installing:

....
$ uhc get /api/clusters_mgmt/v1/clusters \
--parameter search="state in ('ready', 'installing')"
....

The result of that will be a JSON document containing the description of those
clusters, for example:

[source,json]
----
{
  "kind": "ClusterList",
  "page": 1,
  "size": 6,
  "total": 10
  "items": [
    {
      "kind": "Cluster",
      "id": "1GUAUWE3E1IS87Q99M0kxO1LpCG",
      "href": "/api/clusters_mgmt/v1/clusters/1GUAUWE3E1IS87Q99M0kxO1LpCG",
      "name": "mycluster",
      "api": {
        "url": "https://mycluster-api.example.com:6443"
      },
      "console": {
        "url": "https://console-openshift-console.apps.mycluster.example.com"
      },
      ...
    },
    ...
  ]
}
----

As the server will always return JSON documents, so it is very convenient to use
the https://stedolan.github.io/jq[jq] tool to extract that information that you
need. For example, if you want to get the list of identifiers of your clusters
you can do the following:

....
$ uhc get /api/clusters_mgmt/v1/clusters | jq -r .items[].id
....

That will return something like this:

....
1FtmglZGw2byDzO8tb2cCtWxCNf
1FtRj13Fz2DIcm4zaDrcLvKAIyf
...
....

The `get` command can also be used to retrieve information from sub-resources
associated to objects.  For example, the credentials of a cluster (SSH keys,
administrator password and _kubeconfig_) are available in a `credentials`
sub-resource. So if your cluster identifier is `123` you can retrieve the
credentials with this command:

....
$ uhc get /api/clusters_mgmt/v1/clusters/123/credentials
....

Again the https://stedolan.github.io/jq[jq] tool is very useful here. For
example, it can be used to extract the _kubeconfig_ to a file that can then be
used directly with the `oc` command:

....
$ # Get the file:
$ uhc get /api/clusters_mgmt/v1/clusters/123/credentials \
| jq -r .kubeconfig > mycluster.config

$ # Use it:
$ oc --config=mycluster.config get pods
....

For a complete definition of the types of objects, and their attributes, see the
https://api.openshift.com[reference documentation].

== Creating Objects

To create objects use the `post` command, and put the JSON representation of
the object either in the standard input or else in a file indicated by the
`--body` option. For example, to create a new cluster prepare a `mycluster.json`
file with this content:

[source,json]
----
{
  "name": "mycluster",
  "flavour": {
    "id": "4"
  },
  "region": {
    "id": "us-east-1"
  },
  "aws": {
    "access_key_id": "...",
    "secret_access_key": "..."
  },
  "dns": {
    "base_domain": "example.com"
  }
}
----

And then use the `post` command:

....
$ uhc post < mycluster.json
....

Or with the `--body` option:

....
$ uhc post --body=mycluster.json
....

That will send the request to the server, which will initiate the process of
creating the object, and will return a JSON document containing the
representation.

NOTE: In the above example the AWS credentials are empty, but they are
mandatory. Also the DNS base domain needs to be an existing
https://aws.amazon.com/route53[Route53] domain. See
the https://api.openshift.com[reference documentation] for details.

Complicated objects, like a cluster, are usually created asynchronously, so the
fact that the server returns a response doesn't mean that the object is ready to
use. Clusters, for example, have a `state` attribute to indicate that. So after
creating a cluster you will have to periodically check till the cluster is
ready. To do so first get the `id` returned by the `post` command:

....
$ uhc post /api/clusters_mgmt/v1/clusters --body=mycluster.json | jq -r .id
....

The use that identifier to check the value of the `state` attribute, till it is
`ready`:

....
$ uhc get /api/clusters_mgmt/v1/clusters/123 | jq -r .state
....

== Deleting Objects

Objects can be deleted using the `delete` command. For example to delete the
cluster with identifier `123` use the following command:

....
$ uhc delete /api/clusters_mgmt/v1/clusters/123
....

Some objects can be deleted in different ways. For example, a cluster can be
deleted completely, destroying all the virtual machines, disks and any other
resources it uses. But it can also just be deleted from the database while
preserving the virtual machines, disks, etc. To do so the server accepts a
`deprovision` parameter, which can be `true` or `false`. To use it with the tool
add the `--parameter` option. For example, to delete the cluster with identifier
`123` only from the database, use the following command:

....
$ uhc delete /api/clusters_mgmt/v1/clusters/123 --parameter "deprovision=false"
....

Deletion, like creation, is a lengthy process for complicated objects like
clusters, and it happens asynchronously. After the `delete` command finishes it
will take some time to actually delete the cluster. That can be checking using
the `get` command till it returns a `404 Not Found` response.