Add the operator folder to the template

[mmitoraj]

Description

To make it easier for the contributing teams to add content for private cloud operators, I enhanced the template repository by adding the operator folder with the template file structure.

Changes proposed in this pull request:

• Added the operator folder to the template

Related issue(s)

[IwonaLanger]

Again, is it supposed to be just one doc? If so, should we add the information here?

[gczuczy]

For components I would like to suggest adding a Configuration section. Components will ultimately be installed using helm charts, and these have a significant parameter set. The structure of the configurable values here should be enumerated and documented.

Also, if a component is expected any other injected configuration (like configmaps and/or secrets) these should be documented here as well. For secrets it is very important to document their origin (like this is the key/secret for X BTP service integration) along with their expected structure.

[gczuczy]

The following details are expected to present heres:

• [components] What other components does this one depend on
• What BTP integrations does this service is using/building upon

[gczuczy]

This should have a section for significant changes since the last release, depending on the release type. For patch updates, nothing is expected. For minor or major releases breaking changes are expected to be explained here.

This includes, but not limited to:

• Mechanics changes (something worked X way, now works Y way)
• New functionalities
• Obsolete functionalities
• Configuration changes
• Updating pitfalls

[mmitoraj]

I understood it differently. For me, this document is about the update procedure that is more or less stable. It includes the steps to update the component. What you are describing sounds more like a changelog or a release note. We can re-confirm with Aneta. BTW, Aneta, do we also provide what's new notes for the partner-managed edition?

[mmitoraj]

Aneta confirmed that "it's actually both the stable steps but also the specific for the concrete version update. As an example, you can have a look at the BAS update documentation:
https://help.sap.com/docs/OPSAWS/a57e20d1d0124a5db7cf6b68a4b60c06/51a431e8a20841e5a3c258bda526ac10.html?state=DRAFT". Also, in addition, we probably will also publish What's New.

[mmitoraj]

I proposed a section called "What's Changed". PTAL.

[gczuczy]

Disagree for components, this needs multiple sections.

I would suggest the following section for components:

• REST API references (if the component has one)
• Custom Resource documentation:
  • What is the purpose of which CR.
  • Backup requirements of the CR (regenerated or needs to be backed up)
  • The mechanics of the CR (eg for Kymas, spec syncs from SKR to KCP, while status is the other way around)
  • how to interface with them (if annotations/labels are triggering mechanics enumerate and document these)

[mmitoraj]

True, this document can or even must have multiple sections. Having them all in one file is important to make the search functionality easier.

I also included the sections you recommended. Thanks!

[mmitoraj]

For components I would like to suggest adding a Configuration section. Components will ultimately be installed using helm charts, and these have a significant parameter set. The structure of the configurable values here should be enumerated and documented.

Also, if a component is expected any other injected configuration (like configmaps and/or secrets) these should be documented here as well. For secrets it is very important to document their origin (like this is the key/secret for X BTP service integration) along with their expected structure.

Yes, configuration is important. Could the Configuration section be part of Operations or Installation?

[mmitoraj]

For components I would like to suggest adding a Configuration section. Components will ultimately be installed using helm charts, and these have a significant parameter set. The structure of the configurable values here should be enumerated and documented.
Also, if a component is expected any other injected configuration (like configmaps and/or secrets) these should be documented here as well. For secrets it is very important to document their origin (like this is the key/secret for X BTP service integration) along with their expected structure.

Yes, configuration is important. Could the Configuration section be part of Operations or Installation?

I would propose adding it to Operations. PTAL at my proposal. Could you suggest what exactly we should provide regarding Secrets? I did not get it...

[gczuczy]

One more section came to my mind we need to add here: Metrics

Each module and component needs to document the followings:

• What metrics endpoints are there, and in what format they are producing metrics (prometheus is expected here generally)
• What metrics are presented on each endpoint, and each and every of these need sufficient documentation for the reader to understand what kind of internal mechanics it is representing
• Suggested way to determine warnings and critical levels for metrics

Separately for alerting, if some important conditions are represented by a combination of metrics, then these should also be listed as suggested alerts, along with threshold mechanics.