Is there a way to create a digital ocean host programmatically?

Hello.

I am exploring Rancher’s api, and I want to use it to deploy a digital ocean host programmatically. Unfortunatelly, the api accessible to me from /v1/hosts does not contain any actions revolving around host creation, and it seems to just present information already available in the GUI form (presumably to be consumed by other services).

My question is: is there any way in the Rancher API to programmatically create hosts in DO? Or do
I have to use docker machine to do that? Is there another, more flexible/correct way to perform such
an action?

Thanks for your time,

Yes, everything the UI does is 100% through the API. What you’re looking for is POST /v1/machines with for example:

{
    "name": "my-do-host", 
    "digitaloceanConfig": {
        "accessToken": "...",
        "backups": false,
        "image": "ubuntu-14-04-x64",
        "ipv6": false,
        "privateNetworking": false,
        "region": "nyc3",
        "size": "1gb"
    }
}

Machines create the VM in the provider with docker-machine, then get their own registrationToken to start the rancher/agent container, which registers itself with Rancher and creates the host resource. The “Custom” Add host option in the UI is just giving you the registrationToken to run the command on your own.

Side note: The API UI doesn’t support turning embedded types into a form yet, so you’ll have to put in valid JSON for the digitaloceanConfig field.
/v1/schemas/digitaloceanConfig has a resourceFields map that tells you what all the valid keys are. Generally it would have more validation info or an array of the valid values but the machine config types are fairly generic since they’re largely just wrapping docker-machine. So for any of the string values you generally want the same thing as you would give their corresponding CLI option.

This looks fantastic, I am searching to get/create the registration token with my API key in order to automate host provisionning, I can see how it created (https://github.com/rancher/cattle/blob/2face8a72d79888152749820d55b1e220a9e24f5/code/implementation/register/src/main/java/io/cattle/platform/register/util/RegistrationToken.java#L38).

I am a bit lost in the Rancher documentation, where is the doc speaking about that?

Thanks you very much,

Thomas Decaux

There is not really any documentation of the API, we consider it largely an internal implementation detail for the UI until there is user demand for it because we don’t want to take attention away from all the native docker functionality that we integrate with. The UI is 100% static content on a CDN so it is entirely driven by the API. So there is quite a bit of tooling, framework, and design that goes into it… because we do expect user demand for it eventually, but more importantly because as the UI developer I’m the main consumer of it and insist on it :smile:. There is a lot of boring documentation about the specification of the API but it is all generic and not related to the specific Containers, Services, etc that the Rancher API implements.

If you haven’t already gone to the API & Keys section of the UI (under the user icon menu in the header) and clicked on the Endpoint, go ahead and do that. We call what you’re looking at the API UI; it lets you do almost anything with the API from a browser, and will show you the equivalent HTTP request or curl command. So if you click the registrationTokens link, then the Create button in the upper-right and “Show Request” it will show you those, then you can “Send Request” to do the actual create. This is all 100% static too, and driven by schemas in the API (/v1/schemas) that describe every field, every kind of resource, properties that tell you what things can be created or what actions are available on a specific instance of a resource, etc.

There is also a machine-generated CLI based on the same schemas (cattle-cli), and there will be a more friendly human-maintained version of that coming in the nearish future.

Important Note: If you click into the API from a browser you are authenticated as your user, which has access to all your Environments (and those are called projects in the API, because…reasons…). When you use the API keys offered in the UI, they are authenticated as that specific environment and have access only to it. So in the browser you want to be in /v1/projects/{id} to scope it to a particular environment for almost anything. With API keys you don’t need the /projects/{id} part because we already know what environment it is, so /v1/projects/1a5/registrationTokens in the user context is the same as /v1/registrationTokens in an environment API key context (though the other URL works too).

Registration Token is POST /v1/registrationTokens. Almost everything in the API is created asynchronously, including tokens, so this will give you back a token with state=registering and transitioning=yes. It will not contain the string you want yet. So you need to poll the links.self URL a little bit later until it becomes state=active (or subscribe to the WebSocket that will tell you when anything changes… this is how the UI works).

One the token is active it will have a registrationUrl property that’s the raw URL, and a command that is the full “sudo docker run …” string. You should use the command if possible because it includes the right agent version and the required flags, which may change from time to time.

The friendly CLI will have something like a --wait-for-it flag that will automatically do the waiting for the transition to finish stuff instead of you having to write code; cattle-cli does not currently have that.

If you’re going to use the API, be aware that we do not guarantee compatibility between versions yet. We generally are because it’s a pain for everyone to have to synchronize incompatible changes, but there will be things someday before a 1.0/GA release in some areas that will require changes (e.g. renaming projects and environments to match the UI terms). Watch rancher/rancher#1052 and rancher/rancher#384 in particular.

1 Like

Yes I am seeing this, you are right, the API is documented itself! Fantastic, I am using also the socket stuff to watch events … woa !! amazing job.

As always, thanks you for a so detailed answer.