DR-000020 - Teams must document deployment requirements in a clear & consistent way

Owned by Radhakrishnan Gopalakrishnan
Last updated: May 06, 2024 by Jenn Colt
2 min read
Submitted Date

 

Approved Date

 

StatusACCEPTED
ImpactLOW

 

Overrides/Supersedes 

This decision was migrated from the Tech Leads Decision Log as part of a consolidation process.  The original decision record can be found here. 

RFC 

N/A

Stakeholders

  • All developers, SysOps, Hosting providers

Contributors

Craig McNally 

Approvers

This decision was made by the Tech Leads group prior to the adoption of current decision making processes within the FOLIO project.

Background/Context

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

Assumptions

N/A

Constraints

N/A

Rationale

  • Environment variables must be specified in the LaunchDescriptor  section of the ModuleDescriptor . 
    • Adding a description  field 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 
  • 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.

Decision

Teams must document deployment requirements in a clear & consistent way

Implications

  • Pros
    • N/A
  • Cons
    • N/A

Other Related Resources

  • OKAPI-1019 - Add a description field to ModuleDescriptor/LaunchDescriptor env. vars CLOSED