Skip to content
Permalink
master
Switch branches/tags

sdc-napi/docs/index.md

Go to file
 
 
Cannot retrieve contributors at this time
Networking API (NAPI) Introduction to the Networking API What is NAPI? IP and Nic Provisioning Ping NAPI Ping (GET /ping) Example Nic Tags Nic Tag Concepts Nic Tag MTUs ListNicTags (GET /nic_tags) Inputs Example GetNicTag (GET /nic_tags/:name) Example CreateNicTag (POST /nic_tags) Inputs Example UpdateNicTag (PUT /nic_tags/:name) Inputs Example DeleteNicTag (DELETE /nic_tags/:name) Inputs Returns Networks ListNetworks (GET /networks) Inputs Example CreateNetwork (POST /networks) Inputs Routes object Example UpdateNetwork (PUT /networks/:network_uuid) Inputs Example GetNetwork (GET /networks/:network_uuid) Inputs Example DeleteNetwork (DELETE /networks/:network_uuid) Inputs Returns ProvisionNic (POST /networks/:network_uuid/nics) Inputs Example IPs ListIPs (GET /networks/:network_uuid/ips) Inputs Example GetIP (GET /networks/:network_uuid/ips/:ip_address) Example UpdateIP (PUT /networks/:network_uuid/ips/:ip_address) Inputs Reserved IPs Example: reserving an IP Fabrics Overview Interaction with Portolan Fabric VLANs Fabric VLAN fields ListFabricVLANs (GET /fabrics/:owner_uuid/vlans) Inputs Example CreateFabricVLAN (POST /fabrics/:owner_uuid/vlans) Inputs Example GetFabricVLAN (GET /fabrics/:owner_uuid/vlans/:vlan_id) Inputs Example UpdateFabricVLAN (PUT /fabrics/:owner_uuid/vlans/:vlan_id) Inputs Example DeleteFabricVLAN (DELETE /fabrics/:owner_uuid/vlans/:vlan_id) Example Fabric Networks Fabric Network fields ListFabricNetworks (GET /fabrics/:owner_uuid/vlans/:vlan_id/networks) Inputs Example CreateFabricNetwork (POST /fabrics/:owner_uuid/vlans/:vlan_id/networks) Inputs Example GetFabricNetwork (GET /fabrics/:owner_uuid/vlans/:vlan_id/networks/:network_uuid) Inputs Example UpdateFabricNetwork (PUT /fabrics/:owner_uuid/vlans/:vlan_id/networks/:network_uuid) Inputs Example DeleteFabricNetwork (DELETE /fabrics/:owner_uuid/vlans/:vlan_id/networks/:network_uuid) Example NICs ListNics (GET /nics) Inputs Example: list all NICs Example: list all nics with a nic tag of external or admin Example: list all nics belonging to servers that provide an admin or external nic tag CreateNic (POST /nics) Example GetNic (GET /nics/:mac_address) Example UpdateNic (PUT /nics/:mac_address) Example DeleteNic (DELETE /nics/:mac_address) Inputs Returns Network Pools ListNetworkPools (GET /network_pools) Inputs Example CreateNetworkPool (POST /network_pools) Inputs Example GetNetworkPool (GET /network_pools/:uuid) Example UpdateNetworkPool (PUT /network_pools/:uuid) Inputs Example DeleteNetworkPool (DELETE /network_pools/:uuid) Inputs Returns Search SearchIPs (GET /search/ips) Inputs Example Link Aggregations ListAggregations (GET /aggregations) Inputs Example GetAggregation (GET /aggregations/:id) Example CreateAggregation (POST /aggregations) Inputs Example UpdateAggregation (PUT /aggregations/:id) Inputs Example DeleteAggregation (DELETE /aggregations/:id) Inputs Example Returns Enabling on a Compute Node Internal Endpoints RunGC (GET /manage/gc) Pagination Metrics Changelog 2012-07-04 2012-08-20 2012-09-12 2013-02-07 2013-04-17 2013-05-01 2013-05-14 2014-02-18 2015-03-17 2015-03-31 2015-05-01 2015-05-07 2015-06-30
1864 lines (1394 sloc) 68.2 KB
Raw Blame
title apisections markdown2extras
Networking API (NAPI)
Nic Tags, Networks, IPs, Fabrics, Fabric VLANs, Fabric Networks, Nics, Network Pools, Search, Link Aggregations
tables, code-friendly, fenced-code-blocks

Networking API (NAPI)

Introduction to the Networking API

What is NAPI?

The Networking API allows for administering the following:

  • Nic Tags
  • Logical Networks
  • Logical Network Pools
  • Fabrics
  • IPs
  • Nics
  • Link Aggregations

NAPI itself is just a directory of the above - it does not handle communicating these changes to servers, which is the domain of VMAPI and CNAPI.

IP and Nic Provisioning

When you create a nic in NAPI, you can specify a MAC address and IP address. If you do not pick a MAC address, one will be generated at random for the new nic. If you do not pick an IP address, the next available address on the logical network will be used. The next available address is chosen in the following way:

  • If there are IPs in the network that have never been used, pick the lowest one that doesn't have belongs_to_uuid set and is unreserved.
  • If all IPs in the network have been used before, pick the least recently used unreserved IP.

Based on the above, setting the reserved property on an IP removes it from the automatic selection process. It can still be used by specifying it as ip when creating a nic. Setting the free property on an IP removes all other properties from the IP (including reserved, belongs_to_uuid, and belongs_to_type). This therefore makes the IP available for automatic provisioning again.

Ping NAPI

Ping (GET /ping)

This endpoint gives us a general status report from NAPI. It indicates if NAPI is fully initialized, and if so, which features are enabled.

Example

GET /ping
{
  "config": {
      "fabrics_enabled": true,
      "subnet_alloc_enabled": false
  },
  "healthy": true,
  "services": {
    "moray": "online"
  },
  "status": "OK"
}

Nic Tags

Nic Tag Concepts

These endpoints manage nic tags. Nic tags are intended to represent physical network connectivity of nics. There are two components to this: physical server nics that provide the nic tags, and VM virtual nics that attach to a nic tag.

For physical server nics, you can specify that a server's nic has a nic tag (using the nic_tags_provided property - see Nics below). This indicates that this nic is able to reach all other server nics attached to the same nic tag. For example, if you add "external" to the nic_tags_provided of one of Server A's nics, that nic should have Layer 2 connectivity with all other nics that are also tagged with the "external" tag. You can also tag link aggregations with tags in nic_tags_provided, since they also provide Layer 2 connectivity.

For VM virtual nics, you do not set nic_tags_provided - instead, each nic has a nic_tag property (either set manually, or inherited from its Logical Network). This allows the rest of the SDC provisioning stack to not have to worry about how networks are physically connected - when provisioning or migrating a VM, you only need to confirm that the destination server has nics that provide the tags required.

If you provision a nic on the "external" nic tag (for example), when the VM provision request is sent to the Compute Node, it looks for a physical nic that provides the "external" nic tag, and creates a Virtual Nic (vnic) over that physical interface. You can inspect the nic tags provided on a Compute Node using the nictagadm (1m) and sysinfo (1m) tools. You can inspect the nic tags of a VM on a Compute Node using the vmadm (1m) tool.

Nic Tag MTUs

Setting the MTU of nic tags allows you to set the MTU of physical nics on Compute Nodes that have that tag. When a Compute Node reboots, it gets the MTU of all nic tags for a physical nic, and sets the MTU of that nic to the maximum of all of those MTUs.

MTUs for nic tags have a minimum value of 1500 and a maximum value of 9000. Networks created on a nic tag cannot have an MTU higher than the MTU of the nic tag they're created on.

ListNicTags (GET /nic_tags)

Returns a list of all nic tags.

Inputs

Field Type Description
offset Integer Starting offset, see Pagination
limit Integer Maximum number of responses, see Pagination

Example

GET /nic_tags
[
  {
    "mtu": 1500,
    "uuid": "bc7e140a-f1fe-49fd-8b70-26379fa04492",
    "name": "admin"
  },
  {
    "mtu": 1500,
    "uuid": "99ec3b5a-4291-4a40-ba0d-abf7ba1e6e4f",
    "name": "external"
  }
]

GetNicTag (GET /nic_tags/:name)

Returns the named nic tag.

Example

GET /nic_tags/admin
{
  "uuid": "bc7e140a-f1fe-49fd-8b70-26379fa04492",
  "name": "admin",
  "mtu": 1500
}

CreateNicTag (POST /nic_tags)

Creates a nic tag.

Inputs

Field Type Description
name String nic tag name
mtu Number MTU of underlying physical network

Example

POST /nic_tags
    -d name=internal
{
  "uuid": "856e77b0-c0b2-4a6a-8c17-4ec1017360af",
  "name": "internal"
}

UpdateNicTag (PUT /nic_tags/:name)

Updates a nic tag.

Inputs

Field Type Description
name String new nic tag name
mtu Number MTU of underlying physical network

Example

PUT /nic_tags/internal
    -d name=private
{
  "uuid": "df4c1682-a77d-11e2-aafc-5354b5c883c7",
  "name": "private"
}

DeleteNicTag (DELETE /nic_tags/:name)

Deletes a nic tag.

Inputs

None.

Returns

No response payload, only a "204 No Content" response status.

Networks

These endpoints manage logical networks.

ListNetworks (GET /networks)

Returns a list of all logical networks.

Inputs

All parameters are optional filters on the list. A network will be listed if it matches all of the input parameters.

Field Type Description
fabric Boolean Whether the network is on a fabric or not
family String Return networks of the given family (one of 'ipv4' or 'ipv6')
name String or Array Network name
vlan_id Integer VLAN ID
nic_tag String or Array Nic Tag name
owner_uuid UUID Return networks that are owned by this owner_uuid
provisionable_by UUID Return networks that are provisionable by this owner_uuid
offset Integer Starting offset, see Pagination
limit Integer Maximum number of responses, see Pagination

Notes:

  • Both the name and nic_tag arguments allow for arrays of network names and network tags to be provided respectively. When multiple names or nic tags are provided, if a name or nic tag matches any one of the entries, then it will be included in the results. One can think of an array of entries as being equivalent to a logical OR.

  • provisionable_by is intended to list networks that a UFDS user can provision on. This includes both networks that contain that user in its owner_uuids and networks with owner_uuids unset. Filtering by owner_uuid, on the other hand, will only return networks with that owner in owner_uuids (not networks with owner_uuids unset).

Example

GET /networks
[
  {
    "uuid": "1275886f-3fdf-456e-bba6-28e0e2eab58f",
    "name": "admin",
    "vlan_id": 0,
    "family": "ipv4",
    "subnet": "10.99.99.0/24",
    "netmask": "255.255.255.0",
    "provision_start_ip": "10.99.99.189",
    "provision_end_ip": "10.99.99.250",
    "resolvers": [
      "8.8.4.4",
      "8.8.8.8"
    ],
    "gateway": "10.99.99.7"
  },
  {
    "uuid": "c9306c59-f0d6-4aa0-aa0c-17d22a6a3f0f",
    "name": "external",
    "vlan_id": 128,
    "family": "ipv4",
    "subnet": "10.88.88.0/24",
    "netmask": "255.255.255.0",
    "provision_start_ip": "10.88.88.189",
    "provision_end_ip": "10.88.88.250",
    "resolvers": [
      "8.8.4.4",
      "8.8.8.8"
    ],
    "gateway": "10.88.88.2"
  }
]

CreateNetwork (POST /networks)

Creates a new logical network

Inputs

Field Type Description
name String network name
vlan_id Number VLAN ID (0 if no VLAN ID)
subnet CIDR Subnet
provision_start_ip IP First IP address to allow provisioning on
provision_end_ip IP Last IP address to allow provisioning on
nic_tag String Name of the nic tag that this logical network is over
gateway IP Gateway IP address (Optional)
resolvers Array of IPs Resolver IP addresses (Optional)
routes Routes Object Static routes for hosts on this network (Optional)
owner_uuids Array of UUIDs UFDS user UUIDs allowed to provision on this network (Optional)
description String Description (Optional)

Notes:

  • The provisioning range of provision_start_ip to provision_end_ip is inclusive.
  • Specifying owner_uuids for a network limits the owner_uuid of nics and IPs created on the network to those owner_uuids or the UFDS admin UUID.

Routes object

The routes object is a JSON object where the keys are the IP or subnet destinations, and the values are the gateways for those destinations. For example:

{
    "10.88.88.0/24": "10.99.99.7",
    "10.77.77.2": "10.99.99.254"
}

This sets two static routes:

  • subnet 10.88.88.0/24 through the gateway 10.99.99.7
  • host 10.77.77.2 through the gateway 10.99.99.254

Example

POST /networks
    name=internal
    vlan_id=401
    subnet=10.0.2.0/24
    provision_start_ip=10.0.2.5
    provision_end_ip=10.0.2.250
    nic_tag=internal
    gateway=10.0.2.1
{
  "uuid": "dcb499bd-1caf-4ff6-8d70-4e6d5c02dff3",
  "name": "internal",
  "vlan_id": 401,
  "family": "ipv4",
  "subnet": "10.0.2.0/24",
  "netmask": "255.255.255.0",
  "provision_start_ip": "10.0.2.5",
  "provision_end_ip": "10.0.2.250",
  "nic_tag": "internal",
  "resolvers": [],
  "gateway": "10.0.2.1"
}

UpdateNetwork (PUT /networks/:network_uuid)

Updates a logical network.

Inputs

All fields are optional. At least one must be specified. Only the parameters specified in the update are changed, leaving all others unchanged.

Field Type Description
name String network name
gateway IP Gateway IP address
provision_start_ip IP First IP address to allow provisioning on
provision_end_ip IP Last IP address to allow provisioning on
resolvers Array of IPs Resolver IP addresses
routes Routes Object Static routes for hosts on this network (See the Routes Object description above)
owner_uuids Array of UUIDs UFDS user UUIDs allowed to provision on this network
description String Description

Notes:

  • The provisioning range of provision_start_ip to provision_end_ip is inclusive.
  • Specifying owner_uuids for a network limits the owner_uuid of nics and IPs created on the network to those owner_uuids or the UFDS admin UUID.
  • If one of the parameters causing a workflow to run is changed, the response will include a job_uuid field that can be used to obtain the job details from the workflow API.

Example

PUT /networks/2c670e67-bcd1-44c8-b59c-aaf7d8cfa17b
    description="Admin network"
    routes={ "10.88.88.0/24": "10.99.99.7" }

{
  "uuid": "2c670e67-bcd1-44c8-b59c-aaf7d8cfa17b",
  "name": "admin",
  "vlan_id": 0,
  "family": "ipv4",
  "subnet": "10.99.99.0/24",
  "netmask": "255.255.255.0",
  "provision_start_ip": "10.99.99.37",
  "provision_end_ip": "10.99.99.253",
  "nic_tag": "admin",
  "resolvers": [
    "10.99.99.11"
  ],
  "routes": {
    "10.88.88.0/24": "10.99.99.7"
  },
  "owner_uuids": [
    "930896af-bf8c-48d4-885c-6573a94b1853"
  ],
  "description": "Admin network",
  "job_uuid": "fdeb7f1a-24ee-40a0-899f-736e68ffae39"
}

GetNetwork (GET /networks/:network_uuid)

Gets a logical network by UUID.

Inputs

All fields are optional.

Field Type Description
provisionable_by UUID Check whether network is allowed to be provisioned by an owner UUID

Example

GET /networks/dcb499bd-1caf-4ff6-8d70-4e6d5c02dff3
{
  "uuid": "dcb499bd-1caf-4ff6-8d70-4e6d5c02dff3",
  "name": "internal",
  "vlan_id": 401,
  "family": "ipv4",
  "subnet": "10.0.2.0/24",
  "netmask": "255.255.255.0",
  "provision_start_ip": "10.0.2.5",
  "provision_end_ip": "10.0.2.250",
  "nic_tag": "internal",
  "resolvers": [],
  "gateway": "10.0.2.1"
}

DeleteNetwork (DELETE /networks/:network_uuid)

Deletes a network.

Inputs

None.

Returns

No response payload, only a "204 No Content" response status.

ProvisionNic (POST /networks/:network_uuid/nics)

Creates a new NIC, provisioning an IP and MAC address in the process. The :network_uuid can refer to a Network or a Network Pool.

Inputs

Field Type Description
owner_uuid UUID Nic Owner
cn_uuid UUID The UUID of the CN this NIC is on (optional, unless on fabric)
belongs_to_uuid UUID The UUID of what this Nic belongs to
belongs_to_type String The type that this belongs to (eg: 'zone', 'server')
ip String IP address to assign to the nic
reserved Boolean Whether the IP address should be reserved
nic_tags_provided Array of nic tag names Nic tags this nic provides
check_owner Boolean If set to false, skips network ownership checks (optional)
state String Set state nic starts in (one of 'provisioning', 'stopped', 'running') (optional)

Notes:

Example

POST /networks/1275886f-3fdf-456e-bba6-28e0e2eab58f/nics
    -d owner_uuid=930896af-bf8c-48d4-885c-6573a94b1853
    -d belongs_to_uuid=a112b8aa-eb39-4f84-8257-17a705880773
    -d belongs_to_type=zone

{
  "ip": "10.99.99.240",
  "netmask": "255.255.255.0",
  "vlan_id": 0,
  "nic_tag": "admin",
  "mac": "90:b8:d0:f3:f8:8b",
  "primary": false,
  "owner_uuid": "930896af-bf8c-48d4-885c-6573a94b1853",
  "belongs_to_uuid": "a112b8aa-eb39-4f84-8257-17a705880773",
  "belongs_to_type": "zone",
  "gateway": "10.99.99.7",
  "state": "running",
  "resolvers": [
    "8.8.4.4",
    "8.8.8.8"
  ]
}

IPs

These endpoints manage IPs on a logical network.

ListIPs (GET /networks/:network_uuid/ips)

Gets all of the IPs in use on that Logical Network.

Inputs

Field Type Description
belongs_to_type String The type that this belongs to (eg: 'zone', 'server', 'other')
belongs_to_uuid UUID The UUID of what this IP belongs to
owner_uuid UUID The UUID of the owner this IP belongs to
offset Integer Starting offset, see Pagination
limit Integer Maximum number of responses, see Pagination

Example

GET /networks/1275886f-3fdf-456e-bba6-28e0e2eab58f/ips

[
  {
    "ip": "10.99.99.9",
    "network_uuid": "1275886f-3fdf-456e-bba6-28e0e2eab58f",
    "reserved": false,
    "belongs_to_type": "zone",
    "belongs_to_uuid": "d66d8047-5c23-42a1-a26a-60ee806f7edb",
    "owner_uuid": "930896af-bf8c-48d4-885c-6573a94b1853"
  },
  {
    "ip": "10.99.99.10",
    "network_uuid": "1275886f-3fdf-456e-bba6-28e0e2eab58f",
    "reserved": false,
    "belongs_to_uuid": "671819b2-5017-4337-8c85-e5658e632955",
    "belongs_to_type": "zone",
    "owner_uuid": "930896af-bf8c-48d4-885c-6573a94b1853"
  }
]

GetIP (GET /networks/:network_uuid/ips/:ip_address)

Gets a specific IP on a Logical Network.

Example

GET /networks/b330e2a1-6260-41a8-8567-a8a011f202f1/ips/10.88.88.106

{
  "ip": "10.88.88.106",
  "network_uuid": "b330e2a1-6260-41a8-8567-a8a011f202f1",
  "reserved": false,
  "belongs_to_uuid": "0e56fe34-39a3-42d5-86c7-d719487f892b",
  "belongs_to_type": "zone",
  "owner_uuid": "930896af-bf8c-48d4-885c-6573a94b1853"
}

UpdateIP (PUT /networks/:network_uuid/ips/:ip_address)

Modifies a specific IP on a Logical Network.

Inputs

Field Type Description
owner_uuid UUID IP Owner
belongs_to_uuid UUID The UUID of what this IP belongs to
belongs_to_type String The type that this belongs to (eg: 'zone', 'server', 'other')
reserved Boolean Whether the IP address should be reserved
unassign Boolean When set, removes belongs_to_uuid and belongs_to_type, ignoring all other parameters in the request
check_owner Boolean If set to false, skips network ownership checks (optional)

Reserved IPs

Reserving an IP removes an IP address from the provisioning pool, which means that IPs provisioned on that network will not get that address. Note that you can still provision a nic with this IP address, but you must specify the IP when provisioning.

In addition, when you delete a nic with a reserved IP, the IP keeps its owner_uuid, but its belongs_to_uuid and belongs_to_type are removed (similar to the unassign option above).

Example: reserving an IP

PUT /networks/91daaada-4c62-4b80-9de8-0bd09895f86e/ips/10.99.99.77
    reserved=true

{
  "ip": "10.99.99.77",
  "reserved": true,
  "free": false
}

Fabrics

Overview

These endpoints manage fabrics. Fabrics are per-owner overlay networks: each account gets a fabric that's isolated from all other fabrics in the datacenter. VMs in account can only connect to machines on their own fabric, but not the fabrics of other users.

To use fabrics, users create VLANs on their fabric, and then create networks on that VLAN. See the Fabric VLANs and Fabric Networks sections for API endpoints.

Interaction with Portolan

For fabric networks to work, the packets from each fabric network (the overlay network) are encapsulated by a Compute Node and sent over the underlay network to other Compute Nodes. In order to send a packet on an overlay network from one Compute Node to another, we therefore need to lookup the following pieces of data:

  1. What Compute Node the destination MAC or IP address is on, and then
  2. The IP address of that Compute Node on the underlay network

These lookups are handled by the portolan service, which looks up the data in moray buckets. NAPI populates these tables.

To cover item #1 above, set the cn_uuid property when calling the CreateNic or UpdateNic endpoints. This is currently done by the provision workflow in VMAPI, and kept up to date by net-agent on the Compute Node.

To cover item #2 above, set the underlay property on a server's vnic when calling the CreateNic or UpdateNic endpoints.

Fabric VLANs

These endpoints manage a user's fabric VLANs.

Fabric VLAN fields

All endpoints take an optional fields parameter, which is an array specifying the properties that will be returned in the response body. The properties supported are:

  • description
  • name
  • owner_uuid
  • vlan_id
  • vnet_id

ListFabricVLANs (GET /fabrics/:owner_uuid/vlans)

List VLANs owned by a user.

Inputs

Field Type Description
offset Integer Starting offset, see Pagination
limit Integer Maximum number of responses, see Pagination

Example

GET /fabrics/2ee96b00-2bd6-4eda-9fc1-84b56a1059ad/vlans

[
  {
    "name": "default",
    "owner_uuid": "2ee96b00-2bd6-4eda-9fc1-84b56a1059ad",
    "vlan_id": 2,
    "vnet_id": 3688662
  }
]

CreateFabricVLAN (POST /fabrics/:owner_uuid/vlans)

Create a new fabric VLAN.

Inputs

Field Type Description
name String VLAN name
description String VLAN description (Optional)
fields Array of Strings Properties to return - see Fields above for the list (Optional)
vlan_id Number VLAN ID (0 if no VLAN ID)

Example

POST /fabrics/cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11/vlans
    vlan_id=44
    name=production

{
  "name": "production",
  "owner_uuid": "cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11",
  "vlan_id": 44,
  "vnet_id": 7757106
}

The vnet_id property is unique to an owner_uuid - each account has their own unique ID that's shared by all of their Fabric VLANs and networks.

GetFabricVLAN (GET /fabrics/:owner_uuid/vlans/:vlan_id)

Get a VLAN by its VLAN ID.

Inputs

All inputs are optional.

Field Type Description
fields Array of Strings Properties to return - see Fields above for the list

Example

GET /fabrics/cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11/vlans/44

{
  "name": "production",
  "owner_uuid": "cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11",
  "vlan_id": 44,
  "vnet_id": 7757106
}

UpdateFabricVLAN (PUT /fabrics/:owner_uuid/vlans/:vlan_id)

Update a fabric VLAN.

Inputs

All inputs are optional.

Field Type Description
name String VLAN name
description String VLAN description
fields Array of Strings Properties to return - see Fields above for the list

Example

PUT /fabrics/cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11/vlans/44
    name=qa

{
  "name": "qa",
  "owner_uuid": "cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11",
  "vlan_id": 44,
  "vnet_id": 7757106
}

DeleteFabricVLAN (DELETE /fabrics/:owner_uuid/vlans/:vlan_id)

Delete a fabric VLAN.

Example

DELETE /fabrics/cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11/vlans/44

{}

Fabric Networks

These endpoints manage a user's fabric networks.

Fabric Network fields

All endpoints take an optional fields parameter, which is an array specifying the properties that will be returned in the response body. The properties supported are:

  • description
  • fabric
  • gateway
  • internet_nat
  • mtu
  • name
  • nic_tag
  • owner_uuid
  • owner_uuids
  • provision_end_ip
  • provision_start_ip
  • resolvers
  • routes
  • subnet
  • uuid
  • vlan_id

ListFabricNetworks (GET /fabrics/:owner_uuid/vlans/:vlan_id/networks)

List a user's networks on a VLAN.

Inputs

All parameters are optional.

Field Type Description
fields Array of Strings Properties to return - see Fields above for the list (Optional)

Example

GET /fabrics/2ee96b00-2bd6-4eda-9fc1-84b56a1059ad/vlans/44

[
  {
    "mtu": 1400,
    "nic_tag": "sdc_overlay",
    "name": "web",
    "provision_end_ip": "10.0.1.254",
    "provision_start_ip": "10.0.1.2",
    "vlan_id": 44,
    "family": "ipv4",
    "subnet": "10.0.1.0/24",
    "uuid": "4944e6d9-d3ee-462c-b5a6-1c953551ffcf",
    "fabric": true,
    "vnet_id": 7757106,
    "gateway_provisioned": false,
    "resolvers": [
      "8.8.8.8"
    ],
    "gateway": "10.0.1.1",
    "owner_uuid": "cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11",
    "netmask": "255.255.255.0"
  }
]

CreateFabricNetwork (POST /fabrics/:owner_uuid/vlans/:vlan_id/networks)

Create a new fabric network on a VLAN.

Inputs

The parameters to this endpoint are the same as to CreateNetwork, but with some fields removed, and others added. Note that for fabrics, a user can manually specify a subnet or ask NAPI to automatically choose one for them. This means that there are two separate sets of parameters that are mutually exclusive. The following are the allocation params: [subnet, provision_start_ip, provision_end_ip]. And these are the manual params: [subnet_alloc, family, subnet_prefix].

Field Type Description
name String Network name
vlan_id Number Network ID
subnet CIDR Subnet
provision_start_ip IP First IP address to allow provisioning on
provision_end_ip IP Last IP address to allow provisioning on
subnet_alloc Boolean Automatically choose subnet
family String Address family: only 'ipv4' supported
subnet_prefix Number Number of prefix bits (only 24-bit prefixes supported)
gateway IP Gateway IP address (Optional)
internet_nat Boolean Provision a NAT zone on the gateway address (Optional) (default: true)
resolvers Array of IPs Resolver IP addresses (Optional)
routes Routes Object Static routes for hosts on this network (Optional)
description String Description (Optional)
fields Array of Strings Properties to return - see Fields above for the list (Optional)

Example

POST /fabrics/cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11/vlans/44/networks
    name=web
    subnet=10.0.1.0/24
    provision_start_ip=10.0.1.2
    provision_end_ip=10.0.1.254
    gateway=10.0.1.1
    resolvers=8.8.8.8

{
  "mtu": 1400,
  "nic_tag": "sdc_overlay",
  "name": "web",
  "provision_end_ip": "10.0.1.254",
  "provision_start_ip": "10.0.1.2",
  "vlan_id": 44,
  "family": "ipv4",
  "subnet": "10.0.1.0/24",
  "uuid": "4944e6d9-d3ee-462c-b5a6-1c953551ffcf",
  "fabric": true,
  "vnet_id": 7757106,
  "gateway_provisioned": false,
  "resolvers": [
    "8.8.8.8"
  ],
  "gateway": "10.0.1.1",
  "owner_uuid": "cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11",
  "netmask": "255.255.255.0"
}

There are several read-only properties of the network:

  • fabric: Always set to true
  • gateway_provisioned: If there is a gateway for this network, and a NAT zone has not been provisioned, this will be set to false.
  • mtu: Taken from fabric_cfg.default_overlay_mtu in the SDC SAPI config.
  • netmask: derived from subnet
  • nic_tag: Set to overlay.overlayNicTag in the NAPI config.
  • owner_uuid: the owner of the fabric
  • vnet_id: per-owner virtual network ID - see Fabric VLANs above.

GetFabricNetwork (GET /fabrics/:owner_uuid/vlans/:vlan_id/networks/:network_uuid)

Get a Network by its Network ID.

Inputs

All parameters are optional.

Field Type Description
fields Array of Strings Properties to return - see Fields above for the list (Optional)

Example

GET /fabrics/cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11/vlans/44/networks/4944e6d9-d3ee-462c-b5a6-1c953551ffcf

{
  "mtu": 1400,
  "nic_tag": "sdc_overlay",
  "name": "web",
  "provision_end_ip": "10.0.1.254",
  "provision_start_ip": "10.0.1.2",
  "vlan_id": 44,
  "family": "ipv4",
  "subnet": "10.0.1.0/24",
  "uuid": "4944e6d9-d3ee-462c-b5a6-1c953551ffcf",
  "fabric": true,
  "vnet_id": 7757106,
  "gateway_provisioned": false,
  "resolvers": [
    "8.8.8.8"
  ],
  "gateway": "10.0.1.1",
  "owner_uuid": "cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11",
  "netmask": "255.255.255.0"
}

UpdateFabricNetwork (PUT /fabrics/:owner_uuid/vlans/:vlan_id/networks/:network_uuid)

Update a fabric network.

Inputs

All parameters are optional. Note that gateway and vlan_id are immutable fields.

Field Type Description
name String Network name
vlan_id Number Network ID (immutable)
provision_start_ip IP First IP address to allow provisioning on
provision_end_ip IP Last IP address to allow provisioning on
gateway IP Gateway IP address (immutable)
internet_nat Boolean Provision a NAT zone on the gateway address (default: true)
resolvers Array of IPs Resolver IP addresses
routes Routes Object Static routes for hosts on this network
description String Description
fields Array of Strings Properties to return - see Fields above for the list

Example

PUT /fabrics/cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11/vlans/44/networks/4944e6d9-d3ee-462c-b5a6-1c953551ffcf
    description='Updated fabric network description'

{
  "mtu": 1400,
  "nic_tag": "sdc_overlay",
  "name": "web",
  "provision_end_ip": "10.0.1.254",
  "provision_start_ip": "10.0.1.2",
  "vlan_id": 44,
  "family": "ipv4",
  "subnet": "10.0.1.0/24",
  "uuid": "4944e6d9-d3ee-462c-b5a6-1c953551ffcf",
  "fabric": true,
  "vnet_id": 7757106,
  "gateway_provisioned": false,
  "resolvers": [
    "8.8.8.8"
  ],
  "gateway": "10.0.1.1",
  "description": "Updated fabric network description",
  "owner_uuid": "cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11",
  "netmask": "255.255.255.0"
}

DeleteFabricNetwork (DELETE /fabrics/:owner_uuid/vlans/:vlan_id/networks/:network_uuid)

Delete a fabric network.

Example

DELETE /fabrics/cd1cc2a9-e6ad-4c1c-a6bc-acd14e0d4d11/vlans/44/networks/4944e6d9-d3ee-462c-b5a6-1c953551ffcf

{}

NICs

These endpoints manage NICs.

ListNics (GET /nics)

Returns a list of all NICs.

Inputs

All parameters are optional filters on the list. A NIC is output in the list if it matches all of the input parameters.

Field Type Description
owner_uuid UUID NIC Owner
belongs_to_uuid UUID The UUID of what this NIC belongs to
belongs_to_type String The type that the NIC belongs to (e.g., 'zone', 'server')
allow_dhcp_spoofing Boolean Whether the NIC is allowed to function as a DHCP server
allow_ip_spoofing Boolean Whether the NIC is allowed to spoof IP addresses
allow_mac_spoofing Boolean Whether the NIC is allowed to spoof MAC addresses
allow_restricted_traffic Boolean Whether the NIC is allowed to send non-IP, non-ICMP, non-ARP traffic
allow_unfiltered_promisc Boolean Whether the NIC is allowed to listen promiscuously to traffic on different VLANs
cn_uuid String The UUID of the Compute Node that the NIC is on
network_uuid String The UUID of the network the NIC is on
nic_tag String The NIC tag that this NIC is on
nic_tags_provided Array of NIC tag names NIC tags provided by the NIC
state String What state the NIC is in (e.g., 'running', 'stopped', 'provisioning')
underlay Boolean Whether the NIC is being used to service overlay networks
offset Integer Starting offset, see Pagination
limit Integer Maximum number of responses, see Pagination

Note: all filter fields above can have multiple comma-separated values to search on (like a logical OR), excepting offset and limit.

Example: list all NICs

GET /nics

[
  {
    "ip": "10.88.88.190",
    "netmask": "255.255.255.0",
    "vlan_id": 0,
    "nic_tag": "external",
    "mac": "90:b8:d0:b6:a2:86",
    "primary": false,
    "owner_uuid": "930896af-bf8c-48d4-885c-6573a94b1853",
    "belongs_to_uuid": "27391a96-9fb5-4896-975a-85f948d9c509",
    "belongs_to_type": "zone",
    "gateway": "10.88.88.2",
    "state": "running",
    "resolvers": [
      "8.8.4.4",
      "8.8.8.8"
    ]
  },
  {
    "ip": "10.88.88.220",
    "netmask": "255.255.255.0",
    "vlan_id": 0,
    "nic_tag": "external",
    "mac": "90:b8:d0:bb:28:8b",
    "primary": false,
    "owner_uuid": "930896af-bf8c-48d4-885c-6573a94b1853",
    "belongs_to_uuid": "27391a96-9fb5-4896-975a-85f948d9c509",
    "belongs_to_type": "zone",
    "gateway": "10.88.88.2",
    "state": "running",
    "resolvers": [
      "8.8.4.4",
      "8.8.8.8"
    ]
  },
  ...
]

Example: list all nics with a nic tag of external or admin

GET /nics?nic_tag=external,admin

[
  {
    "mac": "c2:e0:09:bb:a5:3b",
    "primary": false,
    "owner_uuid": "930896af-bf8c-48d4-885c-6573a94b1853",
    "belongs_to_uuid": "0e56fe34-39a3-42d5-86c7-d719487f892b",
    "belongs_to_type": "zone",
    "ip": "10.99.99.19",
    "netmask": "255.255.255.0",
    "vlan_id": 0,
    "nic_tag": "admin",
    "gateway": "10.99.99.7",
    "state": "running",
    "resolvers": [
      "8.8.8.8",
      "8.8.4.4"
    ]
  },
  {
    "mac": "90:b8:d0:b0:e6:d0",
    "primary": false,
    "owner_uuid": "930896af-bf8c-48d4-885c-6573a94b1853",
    "belongs_to_uuid": "7896fd2d-0b6b-4e96-9e92-c3c7247bfe71",
    "belongs_to_type": "zone",
    "ip": "10.88.88.120",
    "netmask": "255.255.255.0",
    "vlan_id": 0,
    "nic_tag": "external",
    "gateway": "10.88.88.2",
    "state": "running",
    "resolvers": [
      "8.8.8.8",
      "8.8.4.4"
    ]
  },
  ...
]

Example: list all nics belonging to servers that provide an admin or external nic tag

GET /nics?belongs_to_type=server&nic_tags_provided=admin,external | json -Hamac nic_tags_provided

00:50:56:3d:a7:95 [
  "external"
]
00:50:56:34:60:4c [
  "admin"
]

CreateNic (POST /nics)

Creates a new nic.

Field Type Description
mac String MAC address
owner_uuid UUID Nic Owner
belongs_to_uuid UUID The UUID of what this Nic belongs to
belongs_to_type String The type that this belongs to (eg: 'zone', 'server')
cn_uuid UUID The UUID of the CN this NIC is on (optional, unless on fabric)
ip String IP address to assign to the nic
network_uuid UUID UUID of the network or network pool to provision an IP on
nic_tag String Nic tag (required if IP specified)
vlan_id Number VLAN ID (required if IP specified)
primary Boolean Whether this is the VM's primary nic (optional, default false)
reserved Boolean Whether the IP address should be reserved
nic_tags_provided Array of nic tag names Nic tags this nic provides
model String Nic model for KVM VMs (optional for other VM types)
check_owner Boolean If set to false, skips network ownership checks (optional)
state String Set state nic starts in (one of 'provisioning', 'stopped', 'running') (optional)
allow_dhcp_spoofing Boolean Allow operating a DHCP server on this nic
allow_ip_spoofing Boolean Allow sending and receiving packets that don't match the nic's IP
allow_mac_spoofing Boolean Allow sending and receiving packets that don't match the nic's MAC address
allow_restricted_traffic Boolean Allow sending restricted network traffic (packets that are not IPv4, IPv6 or ARP)
allow_unfiltered_promisc Boolean Allow this VM to have multiple MAC addresses
underlay Boolean Indicates this vnic is to be used as a server's underlay nic (optional)

A VM can only have one primary NIC, and will set its default gateway and nameservers to the values obtained from the network attached to the primary NIC. Adding a new primary NIC will remove the primary flag from the old one.

Example

POST /nics
    -d mac=00:50:56:34:60:4c
    -d owner_uuid=930896af-bf8c-48d4-885c-6573a94b1853
    -d belongs_to_uuid=564da1dd-cea7-9cc6-1059-cca75970c802
    -d belongs_to_type=server
{
  "mac": "00:50:56:34:60:4c",
  "primary": false,
  "owner_uuid": "930896af-bf8c-48d4-885c-6573a94b1853",
  "belongs_to_uuid": "564da1dd-cea7-9cc6-1059-cca75970c802",
  "belongs_to_type": "server"
}

GetNic (GET /nics/:mac_address)

Returns the nic with the given MAC address.

Note: Older NAPI instances require the MAC address with all colons removed. When writing software that needs to work with older NAPIs, make sure to remove the colons. (sdc-clients will handle this for you.)

Example

GET /nics/90b8d0575370

{
  "ip": "10.88.88.198",
  "netmask": "255.255.255.0",
  "vlan_id": 0,
  "nic_tag": "external",
  "mac": "90:b8:d0:57:53:70",
  "primary": false,
  "owner_uuid": "aaaaaaaf-bf8c-48d4-885c-6573a94b1853",
  "belongs_to_uuid": "27391a96-bbbb-bbbb-bbbb-85f948d9c509",
  "belongs_to_type": "zone",
  "gateway": "10.88.88.2",
  "state": "running",
  "resolvers": [
    "8.8.4.4",
    "8.8.8.8"
  ],
  "created_timestamp": "2017-04-01T01:02:03.456Z",
  "modified_timestamp": "2017-05-12T11:22:33.777Z"
}

The meaning of the fields are the same as in the CreateNic call.

NOTE: The created and modified timestamps are read-only. They may also return "1970-01-01T00:00:00.000Z" (epoch) if the creation or last modification of the nic occurred prior to NAPI implementing support for the timestamps.

UpdateNic (PUT /nics/:mac_address)

Changes properties of the nic with the given MAC address.

Field Type Description
owner_uuid UUID Nic Owner
belongs_to_uuid UUID The UUID of what this Nic belongs to
belongs_to_type String The type that this belongs to (eg: 'zone', 'server')
cn_uuid UUID The UUID of the Compute Node a VM's nic is provisioned on (optional)
ip String IP address to assign to the nic
network_uuid UUID The network UUID the nic's IP should be on
primary Boolean Whether this is the VM's primary nic
nic_tags_provided Array of nic tag names Nic tags this nic provides
model String Nic model for KVM VMs (optional for other VM types)
check_owner Boolean If set to false, skips network ownership checks (optional)
allow_dhcp_spoofing Boolean Allow operating a DHCP server on this nic
allow_ip_spoofing Boolean Allow sending and receiving packets that don't match the nic's IP
allow_mac_spoofing Boolean Allow sending and receiving packets that don't match the nic's MAC address
allow_restricted_traffic Boolean Allow sending restricted network traffic (packets that are not IPv4, IPv6 or ARP)
allow_unfiltered_promisc Boolean Allow this VM to have multiple MAC addresses
underlay Boolean Indicates this vnic is to be used as a server's underlay nic (optional)

Note: software consumers should use the MAC address with all colons removed.

Example

PUT /nics/90b8d0575370
    -d belongs_to_uuid=27391a96-bbbb-bbbb-bbbb-888888888888
    -d belongs_to_type=server
    -d state=stopped

{
  "ip": "10.88.88.198",
  "netmask": "255.255.255.0",
  "vlan_id": 0,
  "nic_tag": "external",
  "mac": "90:b8:d0:57:53:70",
  "primary": false,
  "owner_uuid": "aaaaaaaf-bf8c-48d4-885c-6573a94b1853",
  "belongs_to_uuid": "27391a96-bbbb-bbbb-bbbb-888888888888",
  "belongs_to_type": "server",
  "gateway": "10.88.88.2",
  "state": "stopped",
  "resolvers": [
    "8.8.4.4",
    "8.8.8.8"
  ]
}

DeleteNic (DELETE /nics/:mac_address)

Deletes the nic with the given MAC address, freeing any IPs that belong to that nic in the process. If the IP address is reserved, its reserved and owner_uuid properties will be preserved.

Note: software consumers should use the MAC address with all colons removed.

Inputs

None.

Returns

No response payload, only a "204 No Content" response status.

Network Pools

These endpoints manage logical network provisioning pools. These are collections of logical networks that can be used when provisioning a nic. The ordering of the networks property of a pool is significant: NAPI will go try to provision an IP on each network in this list in succession, until it succeeds or runs out of networks.

ListNetworkPools (GET /network_pools)

Returns a list of all logical network pools.

Inputs

All parameters are optional filters on the list. A network pool will be listed if it matches all of the input parameters.

Field Type Description
name String Return network pools that match the pool name
family String Return network pools containing networks of the given family (one of 'ipv4' or 'ipv6')
networks Array of UUIDs Return network pools that contain the given network UUID (only one can be given for now)
provisionable_by UUID Return network pools that are provisionable by this owner_uuid
offset Integer Starting offset, see Pagination
limit Integer Maximum number of responses, see Pagination

Example

GET /network_pools
[
  {
    "uuid": "3b5913ec-42e6-4803-9c0b-c9b1c5603520",
    "name": "internal networks",
    "nic_tag": "internal",
    "nic_tags_present": [ "internal" ],
    "family": "ipv4",
    "networks": [
      "0e70de36-a40b-4ac0-9429-819f5ff822bd",
      "9f2eada0-529b-4673-a377-c249f9240a12"
    ]
  },
  {
    "uuid": "e967a42b-312d-490c-b753-c4768d9f2091",
    "name": "external v6 networks",
    "description": "Logical pool of public IPv6 addresses",
    "nic_tag": "external",
    "nic_tags_present": [ "external" ],
    "family": "ipv6",
    "networks": [
      "57a83e2b-527c-41c1-983c-be9b792011dc",
      "8ba8a35f-3eb3-496b-8103-8238eb40f9d0"
    ]
  }
]

CreateNetworkPool (POST /network_pools)

Creates a new logical network provisioning pool.

Inputs

Field Type Description
name String Network provisioning pool name
description String Description of the new network pool
networks Array of UUIDs Logical Network UUIDs
owner_uuids Array of UUIDs UFDS user UUIDs allowed to provision on this network pool (Optional)

Notes:

  • Specifying owner_uuids for a pool limits the networks in that pool to those with either no owner_uuid or matching one of the owner_uuids. You can therefore only provision nics or IPs on a network in the pool according to its owner_uuid limitations.

Example

POST /network_pools
    name=internal%20networks
    networks=0e70de36-a40b-4ac0-9429-819f5ff822bd,9f2eada0-529b-4673-a377-c249f9240a12
{
  "uuid": "3b5913ec-42e6-4803-9c0b-c9b1c5603520",
  "name": "internal networks",
  "nic_tag": "internal",
  "nic_tags_present": [ "internal" ],
  "family": "ipv4",
  "networks": [
    "0e70de36-a40b-4ac0-9429-819f5ff822bd",
    "9f2eada0-529b-4673-a377-c249f9240a12"
  ]
}

GetNetworkPool (GET /network_pools/:uuid)

Gets a logical network provisioning pool by UUID.

Example

GET /network_pools/3b5913ec-42e6-4803-9c0b-c9b1c5603520
{
  "uuid": "3b5913ec-42e6-4803-9c0b-c9b1c5603520",
  "name": "internal networks",
  "nic_tag": "internal",
  "nic_tags_present": [ "internal" ],
  "family": "ipv4",
  "networks": [
    "0e70de36-a40b-4ac0-9429-819f5ff822bd",
    "9f2eada0-529b-4673-a377-c249f9240a12"
  ]
}

UpdateNetworkPool (PUT /network_pools/:uuid)

Changes a logical network provisioning pool.

Inputs

Must specify at least one of:

Field Type Description
name String Network provisioning pool name
description String Description of the new network pool
networks Array of UUIDs Logical Network UUIDs
owner_uuids Array of UUIDs UFDS user UUIDs allowed to provision on this network pool

Example

PUT /network_pools/3b5913ec-42e6-4803-9c0b-c9b1c5603520
    name=internal-pool
{
  "uuid": "3b5913ec-42e6-4803-9c0b-c9b1c5603520",
  "name": "internal-pool",
  "nic_tag": "internal",
  "nic_tags_present": [ "internal" ],
  "family": "ipv4",
  "networks": [
    "0e70de36-a40b-4ac0-9429-819f5ff822bd",
    "9f2eada0-529b-4673-a377-c249f9240a12"
  ]
}

DeleteNetworkPool (DELETE /network_pools/:uuid)

Deletes a network pool.

Inputs

None.

Returns

No response payload, only a "204 No Content" response status.

Search

These endpoints are for searching the various components of NAPI.

SearchIPs (GET /search/ips)

Searches IPs across all logical networks.

Inputs

Field Type Description
ip IP address IP address to search for (required)

The following are optional inputs which may be used to filter the search:

Field Type Description
belongs_to_type String The type that this belongs to (eg: 'zone', 'server')
belongs_to_uuid UUID The UUID of what this IP belongs to
fabric Boolean Whether the network is on a fabric or not
owner_uuid UUID Returns IPs owned by the specified uuid

Example

GET /search/ips?ip=10.77.77.1
[
  {
    "ip": "10.77.77.1",
    "reserved": false,
    "free": false,
    "belongs_to_type": "zone",
    "belongs_to_uuid": "807223ae-bcc7-11e2-841a-3bf662b0a0c3",
    "owner_uuid": "8d40ace0-bcc7-11e2-9bae-575fff7de171",
    "network_uuid": "1d0dd3de-1d8b-4f31-a58a-284eb2d9335f"
  },
  {
    "ip": "10.77.77.1",
    "reserved": false,
    "free": true,
    "network_uuid": "210ed836-737a-4dfe-97f9-a9f5f6811581"
  }
]

Link Aggregations

These endpoints manage link aggregations.

ListAggregations (GET /aggregations)

Returns a list of aggregations, optionally filtered by parameters.

Inputs

All parameters are optional filters on the list.

Field Type Description
belongs_to_uuid UUID The UUID of the Compute Node the aggregation belongs to
macs Array of MAC addresses MAC addresses of nics in the aggregation
nic_tags_provided Array of nic tag names Nic tags provided by the nic
offset Integer Starting offset, see Pagination
limit Integer Maximum number of responses, see Pagination

Example

GET /aggregations
[
    {
      "belongs_to_uuid": "564d4d2c-ddd0-7be7-40ae-bae473a1d53e",
      "id": "564d4d2c-ddd0-7be7-40ae-bae473a1d53e-aggr0",
      "lacp_mode": "active",
      "name": "aggr0",
      "macs": [
        "00:0c:29:a1:d5:48",
        "00:0c:29:a1:d5:52"
      ],
      "nic_tags_provided": [
        "admin",
        "internal"
      ]
    }
]

GetAggregation (GET /aggregations/:id)

Returns an aggregation.

Example

GET /aggregations/564d4d2c-ddd0-7be7-40ae-bae473a1d53e-aggr0
{
  "belongs_to_uuid": "564d4d2c-ddd0-7be7-40ae-bae473a1d53e",
  "id": "564d4d2c-ddd0-7be7-40ae-bae473a1d53e-aggr0",
  "lacp_mode": "active",
  "name": "aggr0",
  "macs": [
    "00:0c:29:a1:d5:48",
    "00:0c:29:a1:d5:52"
  ],
  "nic_tags_provided": [
    "admin",
    "internal"
  ]
}

CreateAggregation (POST /aggregations)

Creates an aggregation.

Inputs

Field Type Description
name String aggregation name (required)
lacp_mode String aggregation LACP mode: can be active, passive or off (default: off)
macs Array of Strings MAC addresses of links in the aggregation (required)
nic_tags_provided Array of nic tag names nic tags that this aggregation provides (same parameter as in CreateNic)

Example

POST /aggregations
    name=aggr0
    macs=00:0c:29:a1:d5:48,00:0c:29:a1:d5:52
    lacp_mode=active
    nic_tags_provided=admin,internal

{
  "belongs_to_uuid": "564d4d2c-ddd0-7be7-40ae-bae473a1d53e",
  "id": "564d4d2c-ddd0-7be7-40ae-bae473a1d53e-aggr0",
  "lacp_mode": "active",
  "name": "aggr0",
  "macs": [
    "00:0c:29:a1:d5:48",
    "00:0c:29:a1:d5:52"
  ],
  "nic_tags_provided": [
    "admin",
    "internal"
  ]
}

UpdateAggregation (PUT /aggregations/:id)

Updates an aggregation.

Inputs

Field Type Description
lacp_mode String aggregation LACP mode: can be active, passive or off (default: off)
macs Array of Strings MAC addresses of links in the aggregation
nic_tags_provided Array of nic tag names nic tags that this aggregation provides (same parameter as in CreateNic)

Example

PUT /aggregations/564d4d2c-ddd0-7be7-40ae-bae473a1d53e-aggr0
    lacp_mode=off

{
  "belongs_to_uuid": "564d4d2c-ddd0-7be7-40ae-bae473a1d53e",
  "id": "564d4d2c-ddd0-7be7-40ae-bae473a1d53e-aggr0",
  "lacp_mode": "off",
  "name": "aggr0",
  "macs": [
    "00:0c:29:a1:d5:48",
    "00:0c:29:a1:d5:52"
  ],
  "nic_tags_provided": [
    "admin",
    "internal"
  ]
}

DeleteAggregation (DELETE /aggregations/:id)

Deletes an aggregation.

Inputs

None.

Example

DELETE /aggregations/564d4d2c-ddd0-7be7-40ae-bae473a1d53e-aggr0
{ }

Returns

No response payload, only a "204 No Content" response status.

Enabling on a Compute Node

To link aggregation for a compute node, you must perform the following steps:

  • Create a link aggregation with the macs property set to MAC addresses of nics on that Compute Node
  • Reboot the Compute Node

Before rebooting the Compute Node, you can confirm that it will get the correct bootparams on its next boot by using the "booter" command in the dhcpd zone, like so:

booter bootparams 00:0c:29:a1:d5:3e | json kernel_args | grep -v rabbit
{
  "hostname": "00-0c-29-a1-d5-3e",
  "admin_nic": "00:0c:29:a1:d5:3e",
  "internal_nic": "aggr0",
  "aggr0_aggr": "\"00:0c:29:a1:d5:48,00:0c:29:a1:d5:52\"",
  "aggr0_lacp_mode": "off"
}

In the example above, the node will boot with one aggregation, aggr0, with 2 physical nics in the aggregation.

Note: changes to aggregations will only take effect at the next reboot of the Compute Node that hosts them.

Internal Endpoints

These endpoints are intended for use by developers and/or other internal components of the Triton stack.

RunGC (GET /manage/gc)

If NAPI has been executed with the correct CLI options, a developer can use this endpoint to tell the node.js runtime to garbage collect allocated objects. If NAPI does not have access to the node GC, it will return an error. Otherwise it will run the GC and return heap usage statistics from before and after the GC run. This endpoint is usually used for getting memory usage information or forcing a GC run to help determine whether there's a memory leak.

Pagination

Each of the list endpoints is a paginated resource, i.e.:

Being paginated means that not all queries will be provided in a single call to these APIs. To control the pagination there are two different query parameters which may be specified:

  • limit
  • offset

The limit property controls how many entries will be retrieved in a single request. By default, if limit is not specified, then the default limit, 1000 entries, will be returned. limit may range between 1 and 1000, inclusive.

The offset property controls which entry the query should start with. By default, if offset is not specified, then the default offset used is 0.

These primitives may be combined to obtain all of the results. For example, if there are 2300 networks, then to obtain all of them, one would make the three following calls to ListNetworks:

GET /networks
GET /networks?offset=1000
GET /networks?offset=2000

The general rule of thumb is that if you get a number of entries equal to your limit, then you should make another query, adding the limit amount to the offset. Once a number of entries less than limit has been returned, then there is no more need to call the API.

If an invalid limit or offset is specified, then a 400-series error will be generated with a detailed message describing the error.

Metrics

NAPI exposes metrics via node-triton-metrics on http://<ADMIN_IP>:8881/metrics.

Changelog

2012-07-04

  • Can now pass reserved to CreateNic and ProvisionNic(#ProvisionNic)
  • UpdateIP can now change the IP's reserved property

2012-08-20

  • gateway and netmask properties no longer required when calling CreateNic with an IP address
  • Adding and updating nics now takes an optional nic_tags_provided parameter

2012-09-12

2013-02-07

2013-04-17

  • Added network owner_uuid parameter
  • Added provisionable_by parameter to ListNetworks endpoint

2013-05-01

  • Changed network and network pool owner_uuid parameter to owner_uuids

2013-05-14

2014-02-18

2015-03-17

  • Nic tag endpoints now support the mtu property

2015-03-31

2015-05-01

2015-05-07

  • ListNetworks now supports filtering by the fabric property. Filtering by owner_uuid now returns only networks owned by that owner, rather than having identical behaviour to the provisionable_by filter.

2015-06-30

  • All list endpoints now support the limit and offset properties to enable pagination of results. See Pagination for more information.
  • The list endpoints are now strict about checking for unknown query parameters and will respond with an error about unknown query parameters if encountered.
  • ListNics now supports filtering on the network_uuid property.
  • ListNetworks now supports name and nic_tag being arrays.
  • ListNetworkPools now supports filtering on the name property.
  • ListIPs now supports filtering on the belongs_to_uuid and belongs_to_type properties.