This project contains the uhc
command line tool that simplifies the use
of the UHC API available in api.openshift.com
.
To install the tool run this command:
$ go get -u github.com/openshift-online/uhc-cli/cmd/uhc
The first step to use the tool is to log-in with your
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 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.
|
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 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.
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.
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 result of that will be a JSON document containing the description of those clusters, for example:
{
"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 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 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 reference documentation.
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:
{
"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 Route53 domain. See the 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
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.