Hi. I want to use the Rancher API to create a Rancher environment, i.e., we want to be able to set up and tear down development and test environments automatically. Browsing the API from the UI I’ve found this URI:
v1/projects/
that seems to be the container for environments. (Am I right in thinking that “environment” in Rancher UI terminology == “project” in the API?) So there is this handy Create button that gives me a cURL command for creating an environment (project). When I run the curl command I get a 405 “method not allowed” yet when I run the HTTP request in the browser I get a 201 Created. This is the curl command and the HTTP response:
curl -v -u $RANCHER_ACCESS_KEY:$RANCHER_SECRET_KEY -H 'Accept: application/json'
-H 'Content-Type: application/json' --data '{"description":"Testing", "name":"Testing", "members":
:[]}' http://my.rancher.server:8080/v1/projects/
* Adding handle: conn: 0x7fd8b2003a00
* Adding handle: send: 0
* Adding handle: recv: 0
* Curl_addHandleToPipeline: length: 1
* - Conn 0 (0x7fd8b2003a00) send_pipe: 1, recv_pipe: 0
* About to connect() to my.rancher.server port 8080 (#0)
* Trying xx.xx.xxx.xxx...
* Connected to my.rancher.server (xx.xx.xxx.xxx) port 8080 (#0)
* Server auth using Basic with user ‘xxxxxxxxxxxxxx’
> POST /v1/projects/ HTTP/1.1
> Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
> User-Agent: curl/7.30.0
> Host: my.rancher.server:8080
> Accept: application/json
> Content-Type: application/json
> Content-Length: 57
* upload completely sent off: 57 out of 57 bytes
< HTTP/1.1 405 Method Not Allowed
< Content-Length: 170
< Content-Type: application/json; charset=utf-8
< Date: Thu, 10 Sep 2015 13:01:30 GMT
* Server Jetty(9.2.11.v20150529) is not blacklisted
< Server: Jetty(9.2.11.v20150529)
< X-Api-Account-Id: 1a5
< X-Api-Client-Ip: xxx.xxx.xxx.xxx
< X-Api-Schemas: http://my.rancher.server:8080/v1/schemas
<
* Connection #0 to host my.rancher.server left intact
{"id":"6f0fb521-f323-46cf-bf46-f06428984e92","type":"error","links":{},"actions":{},"status":405,"code":"Method not allowed","message":"Method not allowed","detail":null}
Our Rancher server is an aws instance. Are we really not allowed to create an environment (or project) via a POST to the Rancher API or do I have something wrong with the curl command? A GET via curl on /v1/projects works fine. BTW I must say you’ve done a great job making the API clear and browsable from the Rancher UI.
Yes, UI Environment => API project, and UI Stack => API Environment. We will fix the naming in the API eventually…
Basically you need an API key for your account to be able to create new projects, the one you have is for a specific project. There is not a button for these in the API, but go to it in a browser, navigate to /v1/apikeys, click create and choose the appropriate account, then show/send and save the public/secret values
The API keys created through the UI are for a specific project. with those, things like services (belonging to that project) are available at /v1/services. /v1/projects exists, but lists only the one project you are in, and projects don’t own other projects so trying to create one fails.
When you click through the browser into the API you’re authenticated as your user account. It has access to multiple projects so /v1/projects lists them all, and is allowed to create new ones (if you are an admin account…). Things like services for a particular project are underneath there in /v1/projects/${id}/services. Projects are nearly the only thing a user can manage because almost everything else belongs to a project. So /v1 should list almost only that, but it lists everything for admins due to a bug.
Thank you! That worked first time. So, in the UI, I think my user account is ‘admin’ - because I set-up access control for the first time and can control site access. Does that explain why I can see all environments when I browse to /v1/projects/ - you mentioned that this was a bug?
When I go to /v1/apikeys and look at the accountID drop-down I see quite a few items (one account for each environment as well as a system and admin account, a machineServiceAccount, and some accounts that appear to be used by rancher agents). I take it that these accounts are for authentication, hence being linked to credentials, whereas the terms ‘owner’ and ‘member’, appearing in the docs, are for authorisation? Or is ‘owner’ the same as the admin account?
Is the machineServiceAccount used for docker-machine to set up hosts? Because that will be my next task Would just like to clarify some of these things. Thanks again for the prompt response.
Yes, you are admin because you setup access control. In this week’s release you’ll be able to manage the admin flag for multiple accounts.
The bug I meant is that if you go to /v1 it shows a link for every type, instead of just “projects” and a couple others. Seeing all projects is correct, since you are an admin you can manage any of them (the UI supports that too).
API keys are tied to an account and are for authentication. Technically a project is a subclass of account internally, so apikeys for a project are in there too. Normal human users are accounts that are of kind “admin” or “user”.
Admins are authorized to anything, normal users are authorized to particular projects through a list of members. These make sense for the configured auth provider (I.e. Github org “rancher”) and are not tied directly to an account in the database (except for local auth mode…). The projectMember has a role (“owner”, “member”, or “readonly” is new this week) which determines what matching accounts can do. When a user login we look at their e.g. Github account and figure out which projectMember entries are relevant to them.
There are API keys for various internal systems to communicate with each other, like the agents that run on your hosts and the service that runs docker-machine. You see these because you’re admin, but there’s nothing very relevant for you to do with them.
Creating a host through machine is done with a post to /v1/machines containing a config for one of the providers.
Would just like to clarify some of these things. Thanks again for the prompt response.