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

**URL:** <https://forums.suse.com/t/is-there-a-way-to-create-a-digital-ocean-host-programmatically/114>\
**Category:** Rancher 1.x\
**Created:** [July 17, 2015, 10:14am UTC](https://forums.suse.com/t/is-there-a-way-to-create-a-digital-ocean-host-programmatically/114 "2015-07-17T10:14:14Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![NlightNFotis](https://sea2.discourse-cdn.com/flex022/user_avatar/forums.suse.com/nlightnfotis/32/47_2.png) [@NlightNFotis](https://forums.suse.com/u/NlightNFotis)\
**Post date:** [July 17, 2015, 10:14am UTC](https://forums.suse.com/t/is-there-a-way-to-create-a-digital-ocean-host-programmatically/114/1 "2015-07-17T10:14:14Z")

</div>

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,

---

<div class="post-metadata">

**Author:** ![vincent](https://sea2.discourse-cdn.com/flex022/user_avatar/forums.suse.com/vincent/32/7156_2.png) [@vincent](https://forums.suse.com/u/vincent)\
**Post date:** [July 17, 2015, 5:12pm UTC](https://forums.suse.com/t/is-there-a-way-to-create-a-digital-ocean-host-programmatically/114/2 "2015-07-17T17:12:06Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![ebuildy](https://sea2.discourse-cdn.com/flex022/user_avatar/forums.suse.com/ebuildy/32/53_2.png) [@ebuildy](https://forums.suse.com/u/ebuildy)\
**Post date:** [July 21, 2015, 7:20pm UTC](https://forums.suse.com/t/is-there-a-way-to-create-a-digital-ocean-host-programmatically/114/3 "2015-07-21T19:20:35Z")

</div>

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](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

---

<div class="post-metadata">

**Author:** ![vincent](https://sea2.discourse-cdn.com/flex022/user_avatar/forums.suse.com/vincent/32/7156_2.png) [@vincent](https://forums.suse.com/u/vincent)\
**Post date:** [July 21, 2015, 8:22pm UTC](https://forums.suse.com/t/is-there-a-way-to-create-a-digital-ocean-host-programmatically/114/4 "2015-07-21T20:22:36Z")

</div>

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 😄. There is a lot of boring documentation about the [specification of the API](https://github.com/rancher/api-spec) 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](https://github.com/rancher/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](https://github.com/rancher/rancher/issues/1052) and [rancher/rancher#384](https://github.com/rancher/rancher/issues/384) in particular.

---

<div class="post-metadata">

**Author:** ![ebuildy](https://sea2.discourse-cdn.com/flex022/user_avatar/forums.suse.com/ebuildy/32/53_2.png) [@ebuildy](https://forums.suse.com/u/ebuildy)\
**Post date:** [July 22, 2015, 9:56am UTC](https://forums.suse.com/t/is-there-a-way-to-create-a-digital-ocean-host-programmatically/114/5 "2015-07-22T09:56:51Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![denise](https://avatars.discourse-cdn.com/v4/letter/d/82dd89/32.png) [@denise](https://forums.suse.com/u/denise)\
**Post date:** [July 23, 2015, 4:17pm UTC](https://forums.suse.com/t/is-there-a-way-to-create-a-digital-ocean-host-programmatically/114/6 "2015-07-23T16:17:06Z")

</div>