An interface tutorial?

docs

#1

Hello folks,

I jump in and out of charm writing when I have the time, and the thing that absolutely kills me every time is the loose definition and styling of the interfaces.

The new(ish) endpoint style I’ve not yet wrapped my head around, and the metadata that is available by default is a complete mystery unless you log object outputs or happen to see information in another interface.

Is there any chance, someone who knows better than me, could spend a few minutes documenting a very simple “standard” interface. Something that demonstrates what metadata is available over the interfaces by default and how to add your own bits and pieces.

Charm writing I can handle, interface writing is a black art and when I do it often enough I can remember it but when I don’t I forget, and figuring it out is complete guesswork.

Apologies if somethings already been written, cause I can’t find it!


#2

:100:

If we can make interfaces understandable, then charming becomes about 10x simpler.

Related - we are thinking of creating a dedicated interface reference that describes what each side of the relation expects to make it easy to bolt things together.


Simple relations for simple people
#3

Tom, is there something that drives you to implement the raw interface, rather than use a pre-written layer?

I’m sceptical about encouraging re-implementations of interface handshaking. Instead, it makes more sense to me that both halves of the interface are implemented in Python by the same person, and charms use that Python. The new charm tech approach we sketched out moved layers to be closer to standard Python library imports to get this to feel a lot nicer. It’s still early but I feel good about that direction.

That said, better debugging capabilities make a lot of sense regardless.


#4

Sure Mark, the charms I’m building don’t have layers that are compatible so I don’t have much choice. But in reality the interfaces are just pushing metadata up and down the pipes, which is why then I mulled over this type of option to make life easier rather than having to write a bunch of code. Either way, if I’m writing charms, generally speaking there isn’t a compatilble interface or layer to go with them, so it usually starts from scratch.


#5

The emphasis I would like is on demystifying relations and interfaces. I hope that teaching the primitives will make it easier for more people to trust the abstractions.

Relations are intentionally abstract. And they’re also somewhat opaque. Speaking from personal anecdote, “juju relate a b” was almost too magical when I was trying to understand Juju. Once I understood that they’re exchanging data via a protocol facilitated via the Juju controller, but that there’s no actual network connection being established between a and b, things fell into place mentally for me.

Perhaps there’s 2 documents:

  • Implementing interfaces for people who have bought into charming, such as @magicaltrout and @jamesbeedy
  • Explaining interfaces for people who are experimenting with charms and want to know how to trust them

#6

Also just to come back on this point slightly… take something like MySQL, Zookeeper etc… you can’t have the same developer implement both ends, outside of the fact that they’ve probably got an initial charm subject, mediawiki or whatever. I then want to use MySQL, either I reuse their interface, or write my own… if every user wrote both ends of the interface, you’d end up in the same place we are with charms, where there are 20 different versions of the same thing and its unclear what you use.

I’d much rather have a self documenting, stricter interface that made it easy to write the interfaces and have them easy for people to understand, then one for each service being provided.


#7

Good points, thanks Tom.

It’s very common for an interface to be shared across many charms. If you think about the benefits of code reuse, when there is shared functionality we should have shared code. All the charms which connect to MySQL should share as much code for that as possible.

Here’s how I’m thinking about it.

First, the base abstractions need to do a much better job of fitting (and reinforcing) the actual Juju model. It is intended that there will be nice base classes for things like Endpoint and Application, as well as the core data that represents the state of the relation (the interface is really an agreement to a particular protocol of changes to that data).

Second, there need to be a bunch of high quality charms that implement things in a way which is very understandable. At the moment, your experience varies wildly depending on what you look at and in what order.

Third, the piece that implements a particular interface should be a pure Python library, that gives you normal Python classes. Now a charm can reuse interface implementations just by importing the right library. We missed out on this previously because we were still trying to let people use any language to write charms. Screw it, we all like Python, let’s optimise for that. So interface layers become much simpler.

To you point about reuse - yes, each charm developer writes their own charm. But the interfaces in that charm could mostly be reusable libraries, to the extent that there are already charms that speak that interface. The charm is unique (mediawiki talks to MySQL like many other things do but it’s the only thing which does mediawiki).


#8

I think your third point is spot on. As a developer being able to use them like any normal bit of code is key. IDE’s can make use of the code imports for completion etc to make life easier.

It still diverges from my original point though that as a developer, who wants to be able to improve and extend the charm ecosystem, so tutorial about how to write interfaces, especially if there is a new style coming, would be like gold dust for us part time charmers who would like to be able to write interfaces that are both useful, understandable and extendable.

Tom


#9

Yes, could not agree more - the big uplift in charm tech 2.0 is to make it really easy to understand existing charms, and also really easy to write your own charms. We learned a lot from reactive charming, the next wave will be even better.

Documentation and tutorials are key to this, as is the architecture and some tactical choices like focusing purely on Python from end to end.