OpenShift v3 REST API usage

Time for a quick v3 api trial. The REST api is completely changed. First notable thing is authentication. Basic auth is no longer supported. Now the only supported auth types are oauth token and client SSL certificate.

Lets see how we can get an oauth token. First method is to go with a browser to https://your.openshift.master.server.example.com:8443/oauth/token/request

That will present you with a nice page explaining you how to use your newly acquired token. But we want to perform this in a more machine friendly manner so let's do with openshift-challenging-client via curl:

curl -u joe -kv -H "X-CSRF-Token: xxx" 'https://master.cluster.local:8443/oauth/authorize?client_id=openshift-challenging-client&response_type=token'

Keys here are:

• use client_id=openshift-challenging-client, otherwise 400 Bad Request is returned
• use response_type=token
• set X-CSRF-Token header to some non-empty value, otherwise error is returned
• actual token is returned in the Location header of the 302 response per the OAuth spec as access_token=VO4dAgNGLnX5MGYu_wXau8au2Rw0QAqnwq8AtrLkMfU

See partial curl output:

< HTTP/1.1 302 Found
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Location: https://master.cluster.local:8443/oauth/token/display#access_token=VO4dAgNGLnX5MGYu_wXau8au2Rw0QAqnwq8AtrLkMfU&expires_in=86400&token_type=bearer
< Pragma: no-cache
< Set-Cookie: ssn=MTQzNjM3NzI4NXxDSkxSTl8yb0ZjUmZaSDZwNG51UjNDZEx1M29xRldQNGtGZTMwbnhfYlNRV2FuVmYxVHlKSWhWazVKWjR2RDc3X056ZVpqZXl6VWN4T0Nqc1dyX01raDhiUlNSdXFpdkhDalAwWDQzNWdyWExlTmNTUURjN3pQeW9HT1RpVmRtQ1JBPT18qi62Db0PolIHaMmAjtdKPejhCGRY-EUEruT6W_Du2bg=; Path=/; Expires=Wed, 08 Jul 2015 18:41:25 UTC; Max-Age=3600; HttpOnly; Secure
< Date: Wed, 08 Jul 2015 17:41:25 GMT
< Content-Length: 0
< Content-Type: text/plain; charset=utf-8

Now lets perform a real API call to remove the token we just obtained:

curl -vk -H "Authorization: Bearer VO4dAgNGLnX5MGYu_wXau8au2Rw0QAqnwq8AtrLkMfU" https://master.cluster.local:8443/oapi/v1/oauthaccesstokens/VO4dAgNGLnX5MGYu_wXau8au2Rw0QAqnwq8AtrLkMfU -X DELETE

Well done!

Notice how we pass the token - using header: 

"Authorization: Bearer VO4dAgNGLnX5MGYu_wXau8au2Rw0QAqnwq8AtrLkMfU"

You might have noticed API endpoint is /oapi/v1/something, where "v1" is the version of the API. How do we get server supported API versions? 2 ways so far:

$ curl -k https://master.cluster.local:8443/
{
  "paths": [
    "/api",
    "/api/v1beta3",
    "/api/v1",
    "/controllers",
    "/healthz",
    "/healthz/ping",
    "/logs/",
    "/metrics",
    "/ready",
    "/osapi",
    "/osapi/v1beta3",
    "/oapi",
    "/oapi/v1",
    "/swaggerapi/"
  ]

Looking specifically at kubernetes API endpoint:

$ curl -vk https://master.cluster.local:8443/api
{
  "versions": [
    "v1beta3",
    "v1"
  ]

Well forgot to mention. OpenShift v3 does give you access to the plain kubernetes REST API as well to the OpenShift REST API, because OpenShift is built atop of kubernetes. Not sure if versions of those two will be in sync forever but for the time being supported kubernetes and OpenShift API versions do match.

I'm planning to go through most interesting API calls in another post. So far you can try looking at existing documentation:

• https://docs.openshift.org/latest/rest_api/openshift_v1.html - OpenShift Rest API documentation
• https://docs.openshift.org/latest/rest_api/kubernetes_v1.html - Kubernetes API documentation
• https://docs.openshift.org/latest/architecture/additional_concepts/authentication.html - authentication documentation
• https://docs.openshift.com/enterprise/3.0/architecture/additional_concepts/other_api_objects.html - you can read here about OAuth objects

Update (June 2016): You can run `oc ... --loglevel=8` to see exact calls made by the oc utility. It's priceless to understand how an API call works. Keep in mind the output exposes your token.

Thanks a lot to @liggit, without whom I wouldn't be able to write the above!