NOTICE
This decision has been migrated to the Technical Council's Decision Log as part of a consolidation effort. See: DR-000020 - Teams must document deployment requirements in a clear & consistent way
Overview
One pain point identified during the Iris bugfest retrospective was that some modules have specific deployment requirements which were essentially undocumented. A few examples include:
- Environment variables and Java options
- Secrets that need to be provisioned in secret storage
- Dependencies on external infrastructure (Elasticsearch, Kafka, MinIO/S3, etc.)
- Load balancer requirements - some modules don't use HTTP and require a load balancer which can work w/ arbitrary TCP traffic
- Non-standard health check endpoints
Considerations
- Environment variables must be specified in the
LaunchDescriptorsection of theModuleDescriptor.- Adding a
descriptionfield would allow teams to provide context directly in the module descriptor, which is also used to generate docker hub documentation. This would give us information similar to the info captured in the README files of some module, e.g
- Adding a
- One drawback of using the wiki is that it's more or less free-form and could be difficult to find what you're looking for unless conventions are defined and strictly followed.
- Some modules have documented deployment requirements in their modules README file. This too is more or less free-form, but makes it easier to find since it's located in a standard place (top level of the module repo)
- This effort should be coordinated with SysOps SIG. It isn't surprising that they have a similar request for this type of documentation.
JIRAs
- OKAPI-1019 - Getting issue details... STATUS
4 Comments
Jason Root
However many up-votes I get, I give this all of them.
R1 has been particularly painful in this regard to stand up. There is no central place I can go to see what all of my module run-time options are and what they do, what ports things need to be running on, how they should be exposed, and what options/env vars/settings are best to set for a Prod environment, and what pieces of infrastructure are supported. (Bitnami Helm charts? Docker compose Kafka? Standalone Elasticsearch on a VM?)
To get where I'm at, I have been reading as many docs as I can on the Wikis, Jiras, Dockerhub and Github and asking as many questions as I can on Folio org's Slack to the Devops and Devs channels. There are over 60 back-end modules, not counting all of the other pieces of infra... This has been most time-consuming, and I'm sure annoying to others.
Craig McNally
If we get more of this (e.g. env. variable descriptions, etc.) formally defined in the module descriptor, OKAPI can effectively serve as that central place. That said, there will always be tidbits of important information which won't fit nicely into the module descriptor. IMO putting that stuff in the README is a simple solution, and while not ideal, it seems like a good place to start.
Jason Root
For what it’s worth, my answer to both of those would be yes [~marcjohnson]
If there is a lot of shared env vars (because they are provided by spring or raml) then that should make it even easier to disseminate.
[~cmcnally] I agree that the MD is a great place for a lot of this. Anything “extra” that might not be able to be provided in the MD should be documented in the readme.md for the module, and that can also scraped for use in Dockerhub.
Jason Root
A long while back, I started a running list of all of the back-end modules, their env vars and ports to work, and if they needed a db connection or not. It has been useful for me, to carry this forward with each release so I have a central place I can reference and disseminate.