Extended information on API parameters

Dear developers and forum members!

First, I want to thank Stéphane Graber and a LXD community for creating and supporting such an awesome technology as Linux containers. I find it quit flexible and easy to use. This is really, really awesome!

Now, let’s get to the point of my topic. I’m a system(s) engineer and currently exploring a LXD API’s documentation. My goal is to sort out available HTTP methods and configuration parameters, i.e.:

  • certificates
  • instances
  • events
  • images
  • networks
  • operations
  • profiles
  • projects
  • storage-pools
  • resources
  • cluster
    There are some examples of using configuration parameters via such HTTP methods as PUT and PATCH in a current API documentation.
Input (replaces any existing config with the provided one):

{
“config”: {
“core.trust_password”: “my-new-password”,
“core.https_address”: “1.2.3.4:8443”
}
}
But the full list has not been found, unfortunately.

Could you please help me with that?

Thanks in advance.

All the API endpoints and methods are listed at https://linuxcontainers.org/lxd/docs/master/rest-api
All the valid config options are listed in their relevant docs (instances, network, storage, …).

If we’re missing some struct fields, we should fix that, the full list can be found here https://github.com/lxc/lxd/tree/master/shared/api

Well, thanks for a reply!
I saw those docs. Yeah, there are lots of useful information. But some parameters are not described.

For example. I’m working on /1.0/instances API element and POST HTTP method.
In API docs said:

{
“ephemeral”: true, // Whether to destroy the instance on shutdown

But I could not find “ephemeral” parameter in relevant docs (instances, network, storage, …).
How can I deal with that?

Thanks in advance.

What else do you need to know about ephemeral?

If it’s set to the true, the instance will be destroy on shutdown.
It’s not a config key, it’s a property which is why you see it in /1.0/instances. It’s visible in GET and can be set in PUT/PATCH.

The CLI lets you change it with lxc config edit or by passing --ephemeral at creation time.

Note that you can always pass --debug to the CLI to see what’s sent to the server.

Oh, probably my fault. Confused “parameters” and “property” terms, sry.
Then, how can I get the whole available list of “properties”?
By only exploring them via GET method?

All the struct attributes should be listed in the API doc under their respective endpoints in the example along with a comment explaining what they are, just like you found for ephemeral above.

The config keys, devices, … which some attributes take, those are listed under their respective docs (such as the valid options for config or devices in the case of instances).

Oh, thanks a lot!

Oh sry me again for bothering but I would like to make clear some moments.

I’m exploring “devices”: property in /1.0/instances. And kinda confused with config keys and parameters in there.
In API docs said:

"devices": {                                                        // Optional list of devices the instance should have
    "kvm": {
        "path": "/dev/kvm",
        "type": "unix-char"
    },
},

Cannot found a describtion of “kvm” property in https://linuxcontainers.org/lxd/docs/master/ there.
What additional properties are available besides “kvm”?

And how to use Device types via API:

  • none
  • nic
  •    physical
    
  •    bridged:
    
  •    macvlan: 
    
  •    ipvlan: 
    
  •    p2p: 
    
  •    sriov:
    
  •    routed: 
    
  • disk
  •    Ceph-rbd:
    
  •    Ceph-fs:
    
  • unix-cha
  • unix-block
  • usb
  • gpu
  • infiniband
  •    physical:
    
  •    sriov:
    
  • proxy
  • unix-hotplug

with available parameters described in that doc https://linuxcontainers.org/lxd/docs/master/instances#device-types?

I used GET method to one of my instance and got this:

    "expanded_devices": {
        "eth0": {
            "name": "eth0",
            "network": "lxdbr0",
            "type": "nic"
        },
        "root": {
            "path": "/",
            "pool": "localpool",
            "type": "disk"
        }
    },

But I didn’t find such properties in POST /1.0/instances.

Sry for maybe such “stupid” questions, but I need to sort out with API.
Currently, I need to understand:

  • how network devices are described via POST /1.0/instances
  • how storage devices are described via POST /1.0/instances

type refers to the device type listed in the doc, the other keys are specific to that device type also listed in the doc.

Alright, It’s clear. But what about API’s properties used with the device type listed in the doc?

Yeah, this doc https://linuxcontainers.org/lxd/docs/master/configuration is really, really useful. Unfortunately, the API doc is not structured like that. It seems to me that API’s properties are written just for examples.

So I’m currently trying to create a structured API documentation for future use.

Again, sry, if it seems to you that I’m making a fuss.

expanded_devices and expanded_config are read-only representation, that’s why you won’t see them in POST/PUT.

They represent the addition of all the profiles and the instance specific config.

In the most common case, devices will be empty and expanded_devices will contain a root and eth0 devices which both come from the default profile.

It’s clear.
Then, if I understood right the JSON in an example of using type:nic will be the following:

"devices": {                                                        // Optional list of devices the instance should have
    "nic": {
        "nictype": "bridged",
        "config": {
                    "parent": "br0",
                    "mtu" : "9000",
                    "name": "eth0",
                    "host_name": "demo",
                    "ipv4.address": "10.0.0.254",
                    "ipv4.routes": "10.10.0.0/24,10.20.0.0/24,10.30.0.0/24"
       },
    },
},

Sure that I misunderstood that moment…

Close but not quite, it would be something like:

"devices": {
  "eth0": {
    "type": "nic",
    "nictype": "bridged",
    "name": "eth0",
    "parent": "br0",
    "mtu": "9000",
  }
}

This effectively matches what you’d see in YAML form when you see under devices in lxc config edit or lxc profile edit

Okay, that’s clear. Thanks a lot!

Came to /1.0/instances/<name>/metadata.
How can I get the description of properties and available parameters?
Cannot understand what is changable and what is not. Couldn’t find info(

{
“architecture”: “x86_64”,
“creation_date”: 1477146654,
“expiry_date”: 0,
“properties”: {
“architecture”: “x86_64”,
“description”: “BusyBox x86_64”,
“name”: “busybox-x86_64”,
“os”: “BusyBox”
},
“templates”: {
“/template”: {
“when”: [
“”
],
“create_only”: false,
“template”: “template.tpl”,
“properties”: {}
}
}
}

Properties are free for all, every image can set what they want, they don’t have any particular meaning and LXD doesn’t care about them other than showing them back to the user.

The rest is covered in https://linuxcontainers.org/lxd/docs/master/image-handling

Thanks a lot!
Again)

Hi!
Can join a node to an existing cluster via API?

As far I understood there are only two ways to join a node to and existing cluster:

  1. interactively
  2. via YAML file
    https://lxd.readthedocs.io/en/latest/clustering/

https://lxd.readthedocs.io/en/latest/rest-api/#10cluster

Everything (Im fairly certain) happens via the API