= 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 Openshift Cluster Manager offline access token which you can get below:

https://cloud.redhat.com/openshift/token[https://cloud.redhat.com/openshift/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 sso.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 expire (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 access token to use it with some other tool, you can use the token command:

.... $ uhc token ....

That will print the raw OpenID access 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 access token, in JSON format, can be displayed using the --payload option:

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

That will JSON representation of the access 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 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.

=== Config

The configuration variables can be read and set via the get and set commands. These settings will be persisted in the .uhc.json file in your home directory.

.... $ uhc config get url ....

.... $ uhc config set url https://api.openshift.com ....

=== Releasing Requirements:

https://goreleaser.com/install/[GoRelease]

https://github.com/settings/tokens[GitHub Token] (More below)

Steps:

• Generate a new GitHub https://github.com/settings/tokens[GitHub token] with repo scope. Make sure to copy and save your new personal access token now. You won’t be able to see it again!
• Declare token: GITHUB_TOKEN=<token>
• GoReleaser will use the latest Git tag of your repository. Create a tag and push it to GitHub:

$ git tag -a <version> -m "Release Message"
$ git push origin <version>

• Now you can run GoReleaser at the root of the repository goreleaser --rm-dist