I’ve invested alot of time writing a tutorial about relations this and the experience ends me up in that we need to do address a serious situation about juju and its current state of learning how to produce good charms (not only with relations).
On a higher perspective: "How to bring juju to casual programmers?"
The following discussion takes place on the IRC channel #juju on Freenode.
<elox> Look at the bottom of this official documentation: https://juju.is/docs/charm-writing/relations (For a new user, its telling that there exist a single interface in the juju eco-system "mysql".
<elox> A new user would think that juju is really not ready.
<stickupkid> Probably should be "mysql" is another interface example
<elox> I would really love some place where to find a more consistent and comprehensive place where to easily browse interfaces that exists.
<elox> I had a hard time writing this tutorial and got this as a comment from a user. That he had no clue on where to find interfances that exists and how to use them. https://discourse.charmhub.io/t/tutorial-relations-with-juju/3632
<elox> ... so I started to look, and realized that I couldn't find any information except in random places on github and launchpad etc. with little or no consistent documentation.
<stickupkid> https://jaas.ai/search?provides=elasticsearch
<stickupkid> that'll find everything that provides an elasticsearch interface
<elox> A new user will hit a wall here.
<stickupkid> that'll find everything that requires an elasticsearch interface https://jaas.ai/search?requires=elasticsearch
<stickupkid> I really don't think we document that well at all and I agree
<elox> Thats nice, but its not the way people would go ahead and find information and understand what is possible really.
<stickupkid> I wonder if juju find (new command comming for searching charms) should offer that...
<stickupkid> so is the problem understanding an interface or finding other charms that provide/require the interface?
<stickupkid> I think we should do both better
<elox> I think that juju needs some kind of inventory which has a consistent presentation for things like "interfaces" to that any two different interfaces can be understood equally. The format of that information needs to be defined and presented in such a way that it can be replicated easily.
<elox> If every interface is "different", the level of repetition will be low and cumbersome. A user then needs to "re-learn" every relation from what ever documentation is available or most likely by studying someone elses code. This is a very user-unfriendly path forward learning and using relations.
<stickupkid> elox, I really think this discourse or bug worthy, it's really valid criticism that I don't want to loose
<elox> It might be enough for expert level programmers, but for casual programmers, such as myself - I'm hitting a hurdle I have a very hard time getting over and most likely will produce bad code from.
<elox> @stupidkid what do you propose?
<stickupkid> this discussion in discourse, explain what you've hit, what's wrong.
Thank you for the discussion here! I made a bug to track the task of improving the documentation for interfaces, and dropped it into the 3.0.0 milestone, as I’d like to see us write this sometime in the next cycle.
@pengale@cory_fu … I’m trying to learn and figure our how to approach the interface-parts of charming with operator and I’m stuck here from lack of understanding how to use/reuse/reimplement/refactor interfaces.
I’ve set out to convert my nextcloud charm written in reactive and I would like to have some kind of path forward here but I don’t have a good strategy in place here except from collecting random bits and pieces from all over github and launchpad.
Sorry for the slow reply. Unfortunately, the answer at this point is that we’re still working on sorting out the best patterns for implementing interface API components, and I was actively working with @dominik.f on the k8s-service interface (and the charms which use it) trying to come up with a good basic example to start from, but we ran into some things that we’re still uncertain about that we want to discuss with the charmcraft team to get direction on (see some discussion in PR#1 on that repo).
There were definitely some patterns and anti-patterns that developed in handling interfaces in reactive that we want to fix or improve upon going forward. Some of the key ideas that I want to promote are:
Interfaces are actually API protocols, and need to be designed with that in mind, following best practices for APIs (including my current personal bugaboo: versioning the protocol from the start, so that it can evolve in a coherent way).
Interface API components are API client libraries and the framework should provide patterns / bases to encourage good practices across the board and make it easy to implement those practices, which means they need to be well thought-through.
Interface API components’ primary role is to provide a distilled view of a subset of the model which is a more semantic representation of what’s on the other side of the relation, and useful attributes or methods for interactive with that.
limit and optional are two new attributes of relation endpoints which have a lot of potential and which we should encourage the use of.
It’s worth noting that the use-cases for relations in K8s charms are almost always much less complex than for charms on machines, so that’s generally the best place to get started. On the other hand, the general philosophy for communicating between applications in K8s (advertising info via annotations and hoping someone can see and understand it) is fundamentally different than Juju’s (explicit logical connections between components, with state), so there can be some friction there at times.
Anyway, I hope that helps some, and I’ll certainly update this when further discussion happens.
I’m glad you are thinking about this topic. I just hope you consider in your work the ‘casual’ developer to be able to implement a relation since it otherwise alienate those members of the community and make everyone dependent on a few expert developers that can (have the skills to) implement relations. That would not be a good position for the whole of juju in my opinion.
