Service registry
This page serves as a documentation on what the service registry does and how it works.
Design
Purpose
Provide authentication keys for microservices (as opposed to user-based authentication keys)
This allows microservices to communicate between each other without the approval of a user (action). This is useful (needed) for things such as cron tasks.
Categorize microservices together
Provides ways to register and query as such a category
This allows things such as front-ends to know which services are available and only show those in the user interface. TODO discuss this
In the case of the application microservice, this allows for several microservice of the category "application" to be grouped together and used interchangeably for the same thing within oms-events
In the case of the notification pipeline, we will also have several microservices of the category "notification" which either send notifications via mail or push or smoke signals or whatever
Query for frontend modules/pages
Each microservice can register modules/pages/whatever-we-call-them to be displayed additionally in the menu bar and also be loaded upon frontend load. The registry gathers these by a registered getModules.json (the path to this file is set with a label, see "Use"
Currently it uses a hack to register these pages to the core
In the future it might take over the modules functionality from the core, doing effectively the same thing TODO discuss this
Use
You can add different labels on a container that the registry will read and that can be queried through the api
Label | Default | Description |
|---|---|---|
registry.port | traefik.port or 80 | The port which the service exposes as the main endpoint |
registry.frontend | traefik.frontend.rule parsed | The frontend url under which this service is reachable |
registry.enable | traefik.enable or false | Whether the service is reachable through the frontend |
registry.categories | [ ] | An array of strings and priorities which determines the categories this microservice belongs to Example: "registry.categories=(events, 10);(notifications, 10)" |
registry.description | "" | A description for this service |
| servicename | The servicename is parsed directly from what is set as a servicename in docker-compose.yml and cannot be altered |
registry.modules | "" | If this service wants to register frontend pages, this should be the relative path where it serves a getModules.json. Do not prepend http://<servicename>:<port> this will be added automatically from the above fields Example: /frontend/getModules.json → registry queries http://omsevents-frontend:8083/frontend/getModules.json How to use getModules.json is described here |
registry.status | "/status" | An endpoint that upon a GET request delivers whether the service is up and healthy or not. Connection refused is interpreted as a no. Extra information can be delivered, but the success field is indicating the actual status response {success: 1, data: <extra information>} |
Code
API
Questions
I (@Derk Snijders) read Micro service - communication, went through the code and looked at the API, yet still had some questions. Answering these should provide solid documentation as to how to use the registry.
Why seperate authentication for microservices and users?
I would propose splitting Users and Members. This way you can have Members being a User, but also services being a User and do all authentication for Users the same.
Answer Nico: I love that idea, this would solve it in a more elegant fashion!
Doesn't docker already offer the ability to categorize services using labels?
Still might need someway to query this, but...
Answer Nico: Still needs some way to query it. Effectively the registry does query docker for it and then provides a nicer interface. But we could also rationalize it away and maybe provide a code snippet which queries docker and parses the response but somehow having a small service for it feels nicer.
Doesn't traefik already gives you the ability to query services using categories?
Isn't this feature taken directly from the traefik website what we need? '* Round Robin, rebalancer load-balancers'
Answer Nico: The loadbalancing only happens for instances of the same service, traefik has no notion of category in our sense where different services provide somewhat same functionalities.
What are categories?
Are multiple instances of the same service (image) a category? Or are multiple services that do approximately the same, but not exactly, a category?
I believe Traefik (or even docker?) can handle the first case, I do not see the use case / priority of the second case.
Answer Nico: The second case, for examples see Purpose -> 2.a.ii. and 2.a.iii. above
Isn't it solely up to the frontend to decide which pages to show? (since we dropped the concept of modules)
Meaning integration with the service registry for backend-only services would solely be for authentication?
Answer Nico: We should rediscuss this, I had some insights when splitting off the frontend.
Comments
On way I could, however, see this function is maybe using approximately similar behaviour as a fallback, to achieve at least sort of what you want? But then I would think there might be better options to achieve that, for example by explicitly linking service A as service B's fallback service.
Thought of another possible use case:
Services within the same service have the same outcome + response, but can differ in side effects.
This would allow A/B testing
but also for example have some of the services do some advanced analytic stuff which would be CPU heavy or something which is why we do not want all of the services to do this
This again would mean there would be an order / priority for the service and therefor would act similarily to a fallback mechanism, which as described in my other comment I would presume to have better implementation techniques.
Okay, I will explain both use-cases a bit more.
Application microservices: The events module will query the registry for all microservice which hold the category "application". It assumes that each of these services implements an API which we have to define somewhere, having endpoints to communicate user applications but leaving the implementation to that microservice. We need it because the application is wholly different for statutory events (delegate/visitor and other things), summer universities (global matching system) and normal events (custom-made forms per event). For this we decided it would be impossible finding one implementation which serves all 3 purposes, so we decided to instead create an interface behind which a microservice can do all this logic. To not hardcode the implementing microservices into oms-events we need categories.
Notification pipeline: We will have several kinds of notification channels, which of course are active depending on the user. However, as described here I believe it is a good solution to leave this filtering to seperate microservices and from the origin of the message always forward everything. In example that means the following: a microservice, let's say oms-events, has registered an action that needs a notification, someone has applied to an event. It will send a notification down a pipeline holding the name of the applied person, one or more recipients (like all organizers of the event or the incoming responsible), the type of action that triggered the notification and some kind of message. This should run down a pipe of several microservices which all accept this very format of notification and forward it through email, push, on-screen notification, smoke signal or whatever. Each of these services has a part in the settings page and knows per user, which kind of actions it should forward and which not. So again we have a set of microservices which implement the same api and again it feels cleaner to not hardcode which services are loaded in the system but add them to a category. (footnote: I don't think oms-events will actually send the notification to all of those services itself but we could again implement a slim microservices which does the forwarding)
Ah, so in a way categories are interfaces for services. That makes a bit more sense. I will think about this
Yes, each category is always linked to an interface. I imagine a nice confluence page where all the categories and their respective API is listed in a neat table =)
Okay, I think you managed to convince me on the service registry
The magic word for me really was interface, so magic that I am considering if that would be a better name then category, but I'd say category also makes sense now that I understand the idea behind it.
The thing I am still, however, not so sure about it is the implementation timeline, we should not tackle all of this (and other outstanding issues) at once and instead do it the incremental way (yay!)
User/Member split (and allowing to have a User→Service)
This for sure should be postponed imo, I understand a hack was in place and I think we should stick to that until most of the other things are figured out, this would require a sizeable core refactor (and might lead the way for having an authentication service outside of the core)
Bonus for this is that this approach would likely require little code in the service registry, so that can remain as it is for a while
Categorizing microservices
If I understand correctly this already works on the service registry side, core simply has to integrate with it (events already integrated?)
Provide modules registering/querying
As of right now I am still against modules (I would leave this to the frontend solely), I would appreciate you elaborating on why you would like to reopen this discussion @Nico
Then there are the other outstanding issues/PRs:
Docker structure rework
Core permissions
Core Auth/JWT
'fixing' service registry and events
Several small fixess
I would suggest the following overall timeline:
Finish the docker structure rework
This would mean merging it into 'dev' without oms-events/serviceregistry
Merging the several small fixes
Should be easily done, most QoL changes, if turns out to be a bigger deal postpone them
'fixing' service registry and events
As of this point I believe there were some issues (like log spam) with these service but I am not 100% sure of what right now
Includes integrating core with the other services
When the fixes are done we can merge this into oms-docker/dev
Finish a beta/limited implementation of the permissions
Let's say clean up what the current branch is attempting right now
Split Users/Members
And add Microservice users
This should include the removal of the hack in place in the service registry
Finish up the Auth/JWT rework
Finish up the permissions
I know you said on #31 that you would not approve of merging that PR into dev without the service registry and oms-events, I would like to ask you to rethink this stance as I realize these should be in the stable oms-docker branch but this PR includes such a rework of the docker structure that I really feel we need to merge this ASAP in order to have stabilized/locked the docker structure, preventing merge conflicts further down the line (as currently there are already quite some issues like this in several PRs)
Curious to your opinion on this!
Yes that seems like a good plan. I want to add that I should finish the core-frontend, but somehow I would like the permission system to be in place for this. Also I am curious on how it works now internally.
Regarding docker, I also commented on github that with using -f instead of cd-ing to folders I know it works because I have implemented it that way in my version, so I would approve it with this. If you want I/you can rework that, it's really just the oms.sh which I would like to see changed a bit. But yes I also agree we should lock this soon, as it's preventing others to effectively work on the system
Regarding service-registry yes I can try to clean the code a bit, I think it's a good idea. But oms-events will need some more refactoring, as the core API is not yet fully integrated and will need more effort until things work again. However it can already serve as an example microservice to check if the modules system works.
Regarding modules, I will prepare some arguments, I am myself not 100% sure how I would like to see it going.
Awesome page, answers all the questions I had.
I am, however, still not sold on the need for categories. The way I see it you always need a specific API endpoint, with a specific purpose and specific return value. How do you see this becoming an 'approximate purpose' and 'approximate return value' when you query a category as opposed to a set service?
I mean, even for the notifications, I cannot even really think of a case where you do not want/care about the way of notifications (let's say email or sms). This would in my opinion be a user-setting and can therefore not be randomly determined by serving a (~random) service within a category.