Re: [ovirt-devel] [ATN] Introduction of RESTAPI metamodel
by Juan Hernández
On 10/26/2015 04:56 PM, Roman Mohr wrote:
> Hi Juan,
>
> The way to specify the contract look pretty clean and nice.
> I would love to read a few words about the big picture. What is the
> final scenario?
>
The motivation for this change is that currently we don't have a central
place where the RESTAPI is specified, rather we have several different
places, using several different technologies:
* XML schema for the data model.
* JAX-RS for part of the operational model (without the parameters).
* rsdl_metadata.yaml for the parameters of the operational model.
This makes it difficult to infer information about the model. For
example, the generators of the SDKs have to download the XML schema, and
the RSDL (which is generated from the JAX-RS interfaces using reflection
and combining it with the information from the rsdl_metadata.yaml file)
and then they have to do their own computations to extract what they need.
Same happens with the CLI: it has to extract the information it needs
from the Python code generated for the Python SDK, yet another level of
indirection.
We are also lacking a comprehensive reference documentation of the
RESTAPI. What we currently have has been written by hand, and gets out
of sync very quickly, and we don't even notice.
To solve these issues I intend to have the specification of the RESTAPI
only in one place, and using only one technology. I decided to use Java
interfaces for that. Note however that they are just the support for the
information, like paper is the support for ink. I decided to use Java
because it is easy to create, modify and re-factor using tools familiar
to most of us.
These source of these interfaces is analysed (using QDox, currently) and
a "model" of the RESTAPI is generated in memory. This model is
independent of the supporting Java source, and easy to consume. For
example, imagine that you want to list all the types available in the
model and for each one display its documentation:
Model model = ...;
for (Type type : model.getTypes()) {
Name name = type.getName();
String doc = type.getDoc();
System.out.println(name + ": " + doc);
}
Something like this, but more elaborate, will be part of a web
application that provides comprehensive reference documentation,
assuming that we dedicate the time to write documentation comments in
the specification.
I intend to use this model also to do simplify the generators of the
SDKs and the CLI.
In addition these are some of the things that I would like to change in
the near future (for 4.0):
* Move the specification of the parameters of operations out of the
rsdl_metadata.yaml file and into the model. For example:
@Service
public VmService {
/**
* The operation to add a virtual machine.
*/
interface Add {
/**
* The representation of the virtual machine is received
* as parameter, and the representation of the created
* virtual machine is returned as result.
*/
@In @Out Vm vm();
/**
* In the future, we will be able to specify other
* parameters here.
*/
@In Boolean force();
/**
* Even with default values.
*/
@In default Boolean force() { return true; }
/**
* And we will be able to specify constraints, which
* will replace the rsdl_metadata.yaml file.
*/
@Constraint
default boolean vmNameMustNotBeNull() {
return vm().name() != null;
}
}
}
* Enforce the constraints automatically. If the constraints are in the
model, then we can just check them and reject requests before delivering
them to the application. Currently we do this manually (and often
forget) with calls to "validate(...)" methods.
* Generate the Java classes directly from the model. Instead of Model ->
XML Schema -> Java, we can do Model -> Java. This will allow us to solve
some of the XJC compiler limitations, like the horrible way we handle
arrays today.
* Replace JAX-RS with a simpler infrastructure that supports better
streaming and CDI injection.
* Add support for multiple versions of the API, using the "Version"
header, and generating different Java classes for entities and services.
For example, if we have versions 4 and 5 of the model as separate
artifacts, then we can generate "V4Vm" and "V5Vm" entity classes, and
"V4VmService" and "V5VmService" service classes. These can be used
simultaneously in the server, so we can have in the same engine
implementations for multiple versions.
The final picture isn't completely defined yet.
Regards,
Juan Hernandez
> On Mon, Oct 26, 2015 at 4:03 PM, Juan Hernández <jhernand(a)redhat.com
> <mailto:jhernand@redhat.com>> wrote:
>
> Hello,
>
> I will soon merge the following patches that introduce a new way to
> specify the contracts of the RESTAPI:
>
> restapi: Introduce metamodel
> https://gerrit.ovirt.org/45852
>
> restapi: Use metamodel
> https://gerrit.ovirt.org/46478
>
> restapi: Generate JAX-RS interfaces from model
> https://gerrit.ovirt.org/47337
>
>
> Looks pretty much like we are replacing one way of annotating things
> with another way of specifying things.
> Could you elaborate what the benefit of that way of description is?
>
> How would I customize endpoints with e.g. @Gzip annotations? Would I at
> the end still have my JAX-RS annotates resource classes?
>
>
> These patches introduce a new "metamodel" concept, and move the current
> specification of the RESTAPI based on XML schema and JAX-RS interfaces
> to a new "model" built on the new metamodel.
>
>
> What does this mean for you in practical terms? Currently when you want
> to introduce or modify one of the data types used by the RESTAPI you
> start by modifying the XML schema. Once the patches are merged the XML
> schema will never be touched, as it will be automatically generated from
> the "model". For example, imagine that you need to add a new "color"
> attribute to the "VM" entity. To do so with the new model you will have
> to modify the following file, which is the specification of the "Vm"
> entity, written as a Java interface:
>
>
> https://gerrit.ovirt.org/#/c/46478/16/backend/manager/modules/restapi/mod...
>
> In that interface you will have to add a line like this:
>
> String color();
>
> Note that this Java interface is just the specification of the entity,
> it won't be used at all during runtime. Instead of that the XML schema
> will be generated from it, and then Java will be generated from the XML
> schema, as we do today (this will change in the future, but not yet).
>
> Same for the services. If you want to add a new "paint" action to the
> "Vm" resource then you won't modify the JAX-RS interfaces, instead of
> that you will modify the following file, which is the specification of
> the "Vm" service, written as a Java interface:
>
>
> https://gerrit.ovirt.org/#/c/47337/6/backend/manager/modules/restapi/mode...
>
> In that interface you will need to add a sub-interface representing the
> action:
>
> interface Paint {
> }
>
> The JAX-RS interface will be generated from that. Currently these
> sub-interfaces are empty. In the future they will contain the
> specifications of the parameters (currently in the rsdl_metadata.yml
> file).
>
>
>
> These changes will currently affect only the specification of the
> RESTAPI, not the implementation, so in in the "Backend*Resource" classes
> things won't change yet.
>
>
> Currently I do not really understand where we are going here. Are we
> trying to get rid of rdsl?
>
> So basically two questions:
>
> 1) What is the final goal?
> 2) What speaks agains using Hibernate validator on Daos in combination
> with JAX-RS annotated resources (and just removing all interfaces, as
> far as I can see we only have one implementation per endpoint) and
> creating all schemas and clients through SWAGGER tooling?
>
>
> If you have doubts, please let me know.
>
> Regards,
> Juan Hernandez
>
> --
> Dirección Comercial: C/Jose Bardasano Baos, 9, Edif. Gorbea 3, planta
> 3ºD, 28016 Madrid, Spain
> Inscrita en el Reg. Mercantil de Madrid – C.I.F. B82657941 - Red Hat
> S.L.
> _______________________________________________
> Devel mailing list
> Devel(a)ovirt.org <mailto:Devel@ovirt.org>
> http://lists.ovirt.org/mailman/listinfo/devel
>
>
> Thanks,
>
> Roman
--
Dirección Comercial: C/Jose Bardasano Baos, 9, Edif. Gorbea 3, planta
3ºD, 28016 Madrid, Spain
Inscrita en el Reg. Mercantil de Madrid – C.I.F. B82657941 - Red Hat S.L.
8 years, 6 months
Requiring Java 8 during runtime
by Juan Hernández
Hello,
As you probably know oVirt Engine 4 will use WildFly 10, and that
requires Java 8. The version of WildFly that we currently use is 8.2.1,
and it can work with both Java 7 and Java 8. In order to ease the
transition I'm about to merge the following patch, that will require
Java 8 during runtime:
core: Require Java 8 during runtime
https://gerrit.ovirt.org/46872
The implication of this for you is that you must make sure that you have
Java 8 installed in the machine where you run your the engine. Fedora 22
only supports Java 8, so that isn't a problem. EL6 supports both Java 7
and Java 8, so make sure that you have Java 8 installed:
yum -y install java-1.8.0-openjdk-devel
If you have objections please speak now, otherwise I will merge the
patch tomorrow.
Regards,
Juan Hernandez
--
Dirección Comercial: C/Jose Bardasano Baos, 9, Edif. Gorbea 3, planta
3ºD, 28016 Madrid, Spain
Inscrita en el Reg. Mercantil de Madrid – C.I.F. B82657941 - Red Hat S.L.
8 years, 6 months
rethinking fake-kvm and faqemu
by Martin Polednik
Hello everyone,
I've been reworking the fake_kvm and faqemu VDSM hook to make them
somewhat more usable and mostly to allow testing of ppc64le on x86_64
based hosts.
TL;DR version: checkout [1], enable fake_kvm and happy ppc64le hacking :)
Current fake_kvm isn't really a hook and is contained within 'caps'
module. This is wrong for multiple reasons, the most important one
being mixing optional with mainline code. Another issue appears when
one tries to move the fake_kvm code into a hook: the whole notion of
architectures within VDSM is contained within the 'caps' module.
The patch series, which git tip is at [1], introduces new cpuinfo
module that moves information related to architecture to 'cpuinfo'
module of the VDSM library. Intermediate benefit is that current hooks
and library code can access the information related to host's cpu.
This allows for moving fake_kvm code into a hook that I've called
fakearch. Fakearch is, in my opinion, more suitable name - there is
barely any KVM faking, but the host 'fakes' selected architecture.
Faqemu is, on the other hand, a hook. Unfortunately it wasn't really
updated and doesn't allow running VMs under fake architecture. The
series therefore try to refactor it to allow cross-arch VMs to be
started (the VM actually uses host architecture, but from engine's
point of view it's running on the faked arch).
So far tested cross-arch runs are
* x86_64->x86_64 (faqemu functionality),
* x86_64->ppc64le (the most important one),
* ppc64le->x86_64,
* ppc64le->ppc64le (faqemu for Power).
I'm interested in your reviews and comments regarding this effort!
[1] https://gerrit.ovirt.org/#/c/46962/
Best regards,
mpolednik
8 years, 6 months
[oVirt 3.6 Localization Question #36] "Network's configurations differ from"
by Yuko Katabami
Hello all,
Here is another question.
*File:* ApplicationConstants
*Resource ID:* hostOutOfSyncPreviewSentence
*String: *Network's configurations differ from
*Question:* Is this a part of an error message, followed by another string?
Could you please show an example how the final message is going to be shown
to users?
Kind regards,
Yuko Katabami
8 years, 6 months
[oVirt 3.6 Localization Question #35] "QoS Out average"
by Yuko Katabami
Hello all,
I would like to ask for your help with the following question.
*File:* ApplicationConstants
*Resource IDs:*
outAverageLinkShareOutOfSyncPopUp
outAverageRealTimeOutOfSyncPopUp
outAverageUpperLimitOutOfSyncPopUp
*Strings: *
QoS Out average link share
QoS Out average real time
QoS Out average upper limit
*Question: *Could anyone please tell us where these strings appear in the
GUI and how they are used?
Kind regards,
Yuko Katabami
8 years, 6 months
[ATN] Introduction of RESTAPI metamodel
by Juan Hernández
Hello,
I will soon merge the following patches that introduce a new way to
specify the contracts of the RESTAPI:
restapi: Introduce metamodel
https://gerrit.ovirt.org/45852
restapi: Use metamodel
https://gerrit.ovirt.org/46478
restapi: Generate JAX-RS interfaces from model
https://gerrit.ovirt.org/47337
These patches introduce a new "metamodel" concept, and move the current
specification of the RESTAPI based on XML schema and JAX-RS interfaces
to a new "model" built on the new metamodel.
What does this mean for you in practical terms? Currently when you want
to introduce or modify one of the data types used by the RESTAPI you
start by modifying the XML schema. Once the patches are merged the XML
schema will never be touched, as it will be automatically generated from
the "model". For example, imagine that you need to add a new "color"
attribute to the "VM" entity. To do so with the new model you will have
to modify the following file, which is the specification of the "Vm"
entity, written as a Java interface:
https://gerrit.ovirt.org/#/c/46478/16/backend/manager/modules/restapi/mod...
In that interface you will have to add a line like this:
String color();
Note that this Java interface is just the specification of the entity,
it won't be used at all during runtime. Instead of that the XML schema
will be generated from it, and then Java will be generated from the XML
schema, as we do today (this will change in the future, but not yet).
Same for the services. If you want to add a new "paint" action to the
"Vm" resource then you won't modify the JAX-RS interfaces, instead of
that you will modify the following file, which is the specification of
the "Vm" service, written as a Java interface:
https://gerrit.ovirt.org/#/c/47337/6/backend/manager/modules/restapi/mode...
In that interface you will need to add a sub-interface representing the
action:
interface Paint {
}
The JAX-RS interface will be generated from that. Currently these
sub-interfaces are empty. In the future they will contain the
specifications of the parameters (currently in the rsdl_metadata.yml file).
These changes will currently affect only the specification of the
RESTAPI, not the implementation, so in in the "Backend*Resource" classes
things won't change yet.
If you have doubts, please let me know.
Regards,
Juan Hernandez
--
Dirección Comercial: C/Jose Bardasano Baos, 9, Edif. Gorbea 3, planta
3ºD, 28016 Madrid, Spain
Inscrita en el Reg. Mercantil de Madrid – C.I.F. B82657941 - Red Hat S.L.
8 years, 6 months
[ANN] oVirt 3.5.5 Final Release is now available
by Sandro Bonazzola
The oVirt Project is pleased to announce the availability
of the oVirt 3.5.5 Final Release, as of October 26th, 2015.
This release is available now for
Red Hat Enterprise Linux 6.7, CentOS Linux 6.7 (or similar) and
Red Hat Enterprise Linux 7.1, CentOS Linux 7.1 (or similar).
This release supports Hypervisor Hosts running
Red Hat Enterprise Linux 6.7, CentOS Linux 6.7 (or similar),
Red Hat Enterprise Linux 7.1, CentOS Linux 7.1 (or similar) and Fedora 21.
This release of oVirt 3.5.5 includes updated packages for:
- oVirt Engine
- oVirt Hosted Engine HA
- oVirt Hosted Engine Setup
- VDSM
- oVirt Data Warehouse
- oVirt Reports
- oVirt Engine SDK
- oVirt Engine client
- QEMU KVM
See the release notes [1] for a list of fixed bugs.
Please refer to release notes [1] for Installation / Upgrade instructions.
a new oVirt Live ISO is already available [2].
Please note that mirrors[3] may need usually one day before being
synchronized.
Please refer to the release notes for known issues in this release.
[1] http://www.ovirt.org/OVirt_3.5.5_Release_Notes
[2] http://resources.ovirt.org/pub/ovirt-3.5/iso/ovirt-live/
[3] http://www.ovirt.org/Repository_mirrors#Current_mirrors
--
Sandro Bonazzola
Better technology. Faster innovation. Powered by community collaboration.
See how it works at redhat.com
8 years, 6 months
[ANN] oVirt 3.6.0 Third Release Candidate is now available for testing
by Sandro Bonazzola
[ANN] oVirt 3.6.0 Third Release Candidate is now available for testing
The oVirt Project is pleased to announce the availability
of the Third Release Candidate of oVirt 3.6 for testing, as of October
22nd, 2015.
This release is available now for Fedora 22,
Red Hat Enterprise Linux 6.7, CentOS Linux 6.7 (or similar) and
Red Hat Enterprise Linux 7.1, CentOS Linux 7.1 (or similar).
This release supports Hypervisor Hosts running
Red Hat Enterprise Linux 7.1, CentOS Linux 7.1 (or similar),
Fedora 21 and Fedora 22.
Highly experimental support for Debian 8.1 Jessie has been added too.
This release of oVirt 3.6.0 includes numerous bug fixes.
See the release notes [1] for an initial list of the new features and bugs
fixed.
Please refer to release notes [1] for Installation / Upgrade instructions.
New oVirt Node ISO and oVirt Live ISO will be available soon as well[2].
Please note that mirrors[3] may need usually one day before being
synchronized.
Please refer to the release notes for known issues in this release.
[1] http://www.ovirt.org/OVirt_3.6_Release_Notes
[2] http://plain.resources.ovirt.org/pub/ovirt-3.6-pre/iso/
[3] http://www.ovirt.org/Repository_mirrors#Current_mirrors
--
Sandro Bonazzola
Better technology. Faster innovation. Powered by community collaboration.
See how it works at redhat.com
8 years, 6 months
[ANN] oVirt 3.6.0 Third Release Candidate is now available for testing
by Sandro Bonazzola
The oVirt Project is pleased to announce the availability
of the Third Release Candidate of oVirt 3.6 for testing, as of October
22nd, 2015.
This release is available now for Fedora 22,
Red Hat Enterprise Linux 6.7, CentOS Linux 6.7 (or similar) and
Red Hat Enterprise Linux 7.1, CentOS Linux 7.1 (or similar).
This release supports Hypervisor Hosts running
Red Hat Enterprise Linux 7.1, CentOS Linux 7.1 (or similar),
Fedora 21 and Fedora 22.
Highly experimental support for Debian 8.1 Jessie has been added too.
This release of oVirt 3.6.0 includes numerous bug fixes.
See the release notes [1] for an initial list of the new features and bugs
fixed.
Please refer to release notes [1] for Installation / Upgrade instructions.
New oVirt Node ISO and oVirt Live ISO will be available soon as well[2].
Please note that mirrors[3] may need usually one day before being
synchronized.
Please refer to the release notes for known issues in this release.
[1] http://www.ovirt.org/OVirt_3.6_Release_Notes
[2] http://plain.resources.ovirt.org/pub/ovirt-3.6-pre/iso/
[3] http://www.ovirt.org/Repository_mirrors#Current_mirrors
--
Sandro Bonazzola
Better technology. Faster innovation. Powered by community collaboration.
See how it works at redhat.com
8 years, 6 months
