Extended information on API parameters

Rustem_Kasyanov · May 5, 2020, 3:56pm

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.

stgraber · May 5, 2020, 10:54pm

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

Rustem_Kasyanov · May 6, 2020, 5:20pm

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.

stgraber · May 6, 2020, 5:24pm

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.

Rustem_Kasyanov · May 6, 2020, 5:30pm

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?

stgraber · May 6, 2020, 5:33pm

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).

Rustem_Kasyanov · May 6, 2020, 5:34pm

Oh, thanks a lot!

Rustem_Kasyanov · May 7, 2020, 9:34am

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 Linux Containers - LXD - Has been moved to Canonical 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 Linux Containers - LXD - Has been moved to Canonical?

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

stgraber · May 7, 2020, 6:14pm

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

Rustem_Kasyanov · May 7, 2020, 6:39pm

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.

stgraber · May 7, 2020, 6:41pm

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.

Rustem_Kasyanov · May 7, 2020, 7:10pm

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…

stgraber · May 8, 2020, 1:37am

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

Rustem_Kasyanov · May 8, 2020, 10:22am

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”: {}
}
}
}

stgraber · May 8, 2020, 1:29pm

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

Rustem_Kasyanov · May 8, 2020, 1:39pm

Thanks a lot!
Again)

Rustem_Kasyanov · May 19, 2020, 3:42pm

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:

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

turtle0x1 · May 19, 2020, 4:55pm

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

Everything (Im fairly certain) happens via the API