Create tenants via API

1 Create an enterprise and users
- 1.1 Create the enterprise
- 1.2 Create an enterprise-datacenter limit for the new enterprise
- 1.3 Switch to the new enterprise
- 1.4 Create users
  - 1.4.1 Create an enterprise admin
  - 1.4.2 Create a cloud user
2 Add VM templates to the appliance library
- 2.1 Refresh the apps library
  - 2.1.1 Get the enterprise ID
  - 2.1.2 Get the enterprise repositories
  - 2.1.3 Perform the refresh
- 2.2 Retrieve a compatible template
- 2.3 Add a new template from a remote repository
  - 2.3.1 Retrieve all template definitions and select one
  - 2.3.2 Create a template from a template definition

This guide will be updated shortly

This how-to guide describes how to create an enterprise and some users, as well as how to download some templates from a remote template repository.

In this how-to guide you will perform the tasks of the cloud administrator and enterprise administrator. This how-to guide uses the Cloud Administrator default account and does not show proper authentication.

Before you begin working through this guide, you should create a datacenter (for API instructions, see API infrastructure tutorial), or a public cloud region (although be aware that some of the template management steps are different for public cloud regions)

Create an enterprise and users

When using the Abiquo API to create a tenant (Abiquo enterprise), it is important to first create the enterprise and then allow the enterprise to use datacenters or public cloud regions by creating an enterprise-datacenter limit.

Create the enterprise

The following request creates an enterprise with enterprise resource allocation limits.

cURL:

curl -X POST https://example.com/api/admin/enterprises \ 
	 -H 'Accept:application/vnd.abiquo.enterprise+json; version=4.6' \ 
	 -H 'Content-Type:application/vnd.abiquo.enterprise+json; version=4.6' \ 
	 -d @requestpayload.json \ 
	 -u user:password --verbose

Success status code: 201

Request payload:

{
  "cpuCountHardLimit": 20, 
  "diskHardLimitInMb": 20480, 
  "isReservationRestricted": false, 
  "ramSoftLimitInMb": 10240, 
  "links": [], 
  "workflow": false, 
  "vlansHard": 10, 
  "publicIpsHard": 10, 
  "publicIpsSoft": 10, 
  "ramHardLimitInMb": 20480, 
  "vlansSoft": 10, 
  "cpuCountSoftLimit": 20, 
  "diskSoftLimitInMb": 10240, 
  "name": "Tioco"
}

Response payload:

 {
    "id": 276,
    "name": "Tioco",
    "isReservationRestricted": false,
    "workflow": false,
    "twoFactorAuthenticationMandatory": false,
    "reseller": false,
    "keyNode": false,
    "diskSoftLimitInMb": 10240,
    "diskHardLimitInMb": 20480,
    "storageSoftInMb": 0,
    "storageHardInMb": 0,
    "vmsSoft": 0,
    "vmsHard": 0,
    "vlansSoft": 10,
    "vlansHard": 10,
    "publicIpsSoft": 10,
    "publicIpsHard": 10,
    "repositorySoftInMb": 0,
    "repositoryHardInMb": 0,
    "links": [
        {
            "title": "Tioco",
            "rel": "edit",
            "type": "application/vnd.abiquo.enterprise+json",
            "href": "https://example.com:443/api/admin/enterprises/276"
        },
        {
            "title": "users",
            "rel": "users",
            "type": "application/vnd.abiquo.users+json",
            "href": "https://example.com:443/api/admin/enterprises/276/users"
        },
        {
            "title": "properties",
            "rel": "properties",
            "type": "application/vnd.abiquo.enterpriseproperties+json",
            "href": "https://example.com:443/api/admin/enterprises/276/properties"
        },
        {
            "title": "Global scope",
            "rel": "scope",
            "type": "application/vnd.abiquo.scope+json",
            "href": "https://example.com:443/api/admin/scopes/1"
        },
        {
            "title": "template definitions lists",
            "rel": "appslib/templateDefinitionLists",
            "type": "application/vnd.abiquo.templatedefinitionlists+json",
            "href": "https://example.com:443/api/admin/enterprises/276/appslib/templateDefinitionLists"
        },
        {
            "title": "template defintion paths",
            "rel": "appslib/templateDefinitions",
            "type": "application/vnd.abiquo.templatedefinitions+json",
            "href": "https://example.com:443/api/admin/enterprises/276/appslib/templateDefinitions"
        },
        {
            "title": "repositories",
            "rel": "datacenterrepositories",
            "type": "application/vnd.abiquo.datacenterrepositories+json",
            "href": "https://example.com:443/api/admin/enterprises/276/datacenterrepositories"
        },
        {
            "title": "virtual machines",
            "rel": "virtualmachines",
            "type": "application/vnd.abiquo.virtualmachines+json",
            "href": "https://example.com:443/api/admin/enterprises/276/action/virtualmachines"
        },
        {
            "title": "virtual appliances",
            "rel": "virtualappliances",
            "type": "application/vnd.abiquo.virtualappliances+json",
            "href": "https://example.com:443/api/admin/enterprises/276/action/virtualappliances"
        },
        {
            "title": "ips",
            "rel": "ips",
            "type": "application/vnd.abiquo.privateips+json",
            "href": "https://example.com:443/api/admin/enterprises/276/action/ips"
        },
        {
            "title": "virtual datacenters",
            "rel": "cloud/virtualdatacenters",
            "type": "application/vnd.abiquo.virtualdatacenters+json",
            "href": "https://example.com:443/api/admin/enterprises/276/action/virtualdatacenters"
        },
        {
            "title": "reserved machines",
            "rel": "reservedmachines",
            "type": "application/vnd.abiquo.machines+json",
            "href": "https://example.com:443/api/admin/enterprises/276/reservedmachines"
        },
        {
            "title": "limits",
            "rel": "limits",
            "type": "application/vnd.abiquo.limits+json",
            "href": "https://example.com:443/api/admin/enterprises/276/limits"
        },
        {
            "title": "providerlimits",
            "rel": "providerlimits",
            "type": "application/vnd.abiquo.providerlimits+json",
            "href": "https://example.com:443/api/admin/enterprises/276/providerlimits"
        },
        {
            "title": "volumes",
            "rel": "volumes",
            "type": "application/vnd.abiquo.volumes+json",
            "href": "https://example.com:443/api/admin/enterprises/276/action/volumes"
        },
        {
            "title": "external networks",
            "rel": "externalnetworks",
            "type": "application/vnd.abiquo.vlans+json",
            "href": "https://example.com:443/api/admin/enterprises/276/action/externalnetworks"
        },
        {
            "title": "pending tasks",
            "rel": "pendingtasks",
            "type": "application/vnd.abiquo.tasks+json",
            "href": "https://example.com:443/api/admin/enterprises/276/action/pendingtasks"
        },
        {
            "title": "credentials",
            "rel": "credentials",
            "type": "application/vnd.abiquo.publiccloudcredentialslist+json",
            "href": "https://example.com:443/api/admin/enterprises/276/credentials"
        },
        {
            "title": "pricingcredentials",
            "rel": "pricingcredentials",
            "type": "application/vnd.abiquo.pricingcredentialslist+json",
            "href": "https://example.com:443/api/admin/enterprises/276/pricingcredentials"
        },
        {
            "title": "virtual appliances specs",
            "rel": "vappspecs",
            "type": "application/vnd.abiquo.virtualappliancespecs+json",
            "href": "https://example.com:443/api/admin/enterprises/276/vappspecs"
        },
        {
            "title": "bills",
            "rel": "bills",
            "type": "application/vnd.abiquo.bills+json",
            "href": "https://example.com:443/api/statistics/enterpriseresources/276/bills"
        },
        {
            "title": "billregisters",
            "rel": "billregisters",
            "type": "application/vnd.abiquo.bills+json",
            "href": "https://example.com:443/api/statistics/enterpriseresources/276/billregisters"
        },
        {
            "title": "estimation",
            "rel": "estimation",
            "type": "text/plain",
            "href": "https://example.com:443/api/statistics/enterpriseresources/276/billregisters/action/estimate"
        },
        {
            "title": "Bill providers",
            "rel": "billproviders",
            "type": "application/vnd.abiquo.billproviders+json",
            "href": "https://example.com:443/api/statistics/enterpriseresources/276/bills/action/providers"
        },
        {
            "title": "Reseller enterprise",
            "rel": "reseller",
            "type": "application/vnd.abiquo.enterprise+json",
            "href": "https://example.com:443/api/admin/enterprises/267"
        }
    ],
    "ramSoft": 0,
    "ramHard": 0,
    "cpuSoft": 0,
    "cpuHard": 0
}

Create an enterprise-datacenter limit for the new enterprise

An enterprise-datacenter limit allows an enterprise to use a datacenter or public cloud region. You can also use it to limit the allocation of resources in the datacenter. In this case, because all the limit values are set to 0, the enterprise's resource usage is not limited at this level. However, it is already limited at the enterprise level, and can also be limited at the virtual datacenters level.

cURL:

Success status code: 201

Request payload:

Response payload:

Switch to the new enterprise

To perform some operations on the new tenant, it may be convenient to switch to that tenant, as you would do in the user interface. You can do this with a PUT request to update the user that will switch.

If you are working with the main cloud admin user, get the data entity for this user (whose user ID is 1) from whichever enterprise they are in by using a query over all enterprises represented by the underscore character "_", use a query like the following.

To switch the user to the new tenant enterprise, you need to edit the user entity, and add a link to the new enterprise, then update the user. Before you perform the PUT request to update the user, add an email attribute for the user if you didn't already add one.

So for example, to switch user 10 to the new enterprise.

Make sure you remember to add the email address!

For more details and a complete example, see Switch enterprises via API.

You can check the enterprise that you are working with in the user interface.

Create users

The request to create a user is always the same but the user entity will vary depending on the user's role. To create a user you will need to know the ID of the role that you will assign to the user. And the ID of the user's scope. The following examples show how to create a tenant enterprise admin and an ordinary user.

Create an enterprise admin

The enterprise admin user can administer one or more tenant. By default, this user is allowed to create users within the tenant. The ID of the ENTERPRISE_ADMIN role is 3. The ID of the default global scope is 1. The username is given as the "nick" element. Modify and submit the following request to create an enterprise admin user.

cURL:

Success status code: 201

Request payload:

Response payload:

Create a cloud user

Modify and submit the following request to create a cloud user with the USER role.

cURL:

Success status code: 201

Request payload:

Response payload:

Add VM templates to the appliance library

The Apps library stores VM templates so that users can easily deploy VMs from these templates. Templates can be downloaded from a remote repository or uploaded from a local machine. The Apps library templates are available to the virtual datacenters. From there a user can add the VM template to a virtual appliance for deployment in the cloud.

Refresh the apps library

An Apps library belongs to your enterprise and there is one for each of the datacenters you are allowed to access. So to add templates that will only be used by one enterprise, it is best to switch to the enterprise, as described earlier in tutorial.

Get the enterprise ID

To refresh the Apps library using the API, you need to know the enterprise ID and the datacenter repository ID.

If you are working with the default Abiquo enterprise, the ID is "1". Otherwise you can retrieve the enterprise ID using https://wiki.abiquo.com/api/latest/EnterprisesResource.html#list-enterprise-identifiers-and-names

Get the enterprise repositories

Using the enterprise ID, retrieve all the repositories for your enterprise.

cURL:

Success status code: 200

Request payload:

-- none --

Response payload:

Perform the refresh

To refresh the enterprise datacenter repository, perform a put request to the "refresh" link in the datacenter repository entity shown above.

cURL:

Success status: 202

Request payload:

-- none --

Response payload:

The acceptedrequest media type is a reference to the action in progress. You can use this link to track the progress of the asynchronous refresh task.

Remember that the refresh is an asynchronous task, so you should wait until it has completed to go on to the next step.

Retrieve a compatible template

If you have already added some templates to the Apps library, you can just retrieve a template that is compatible with your hypervisor type by performing a query similar to the following one. If there are a lot of templates, you may wish to filter them using query parameters or select a specific template ID to retrieve. In this example, we filter by compatible hypervisorTypeName (VMX_04) and text in the template name and limit the number of templates returned to 1.

Remember that in Abiquo, you create a VM using only a link to a template, you do not need the full template entity.

The result of this query is a collection of templates, so if you only needed one template entity, you could remove the collection information or perform another request to retrieve just the desired template.

cURL:

Response payload:

Add a new template from a remote repository

If there are no templates in your Apps library and you would like to add some using the API, follow the steps in this section. The most convenient template to download is the m0n0wall template in the default remote repository. However, the following query uses the a remote repository available in the local Abiquo installation.

Registering a remote repository is outside the scope of this tutorial. To register a custom remote repository, either please see the TemplateDefinitionList documentation or register it in Abiquo using the UI.

Template definition lists are available at the enterprise level, so to retrieve them, you just need your enterprise ID. Before you run this query, you may need to open the Remote template repository in the UI, by clicking the + Add template button and selecting "Create from remote template repository".

Retrieve all template definitions and select one

If you wish to retrieve all the template definitions found in the remote repositories registered in your Abiquo environment and available to your enterprise, you can use the following query. Obviously this query may return a large number of results, so one strategy may be to search the result for the ID of the template you wish to use.

Note that the following link contains an uppercase letter "D" in definition.

cURL:

Success status code: 200

Request payload:

-- none --

Response payload:

This is only one template definition taken from the list of hundreds of template definitions that were returned by this query. You can search for the template name and cut and paste the required template.

Create a template from a template definition

You can create a template in the Apps library from a link to a template definition retrieved from the above query. This is equivalent to downloading a template from the remote repository to the Apps library. To create the VM template request entity, you will need the information in the "edit" link section of the template definition above. You can then use this template in a later step to create a VM. The template ID is returned in the accepted request in the task link.

cURL:

Success status code: 202

Request payload:

Response payload:

See also Appliance manager template API upload and download for information on how to upload templates from the local filesystem using the Appliance Manager API.