-
Notifications
You must be signed in to change notification settings - Fork 7
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add the operator folder to the template #44
Conversation
@@ -0,0 +1,8 @@ | |||
# {Component/Service Name} - Troubleshooting | |||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Again, is it supposed to be just one doc? If so, should we add the information here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
||
## Prerequisites | ||
|
||
<!--Describe the prerequisites for installing your service (if there are some).--> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
@@ -0,0 +1,15 @@ | |||
# Updating {Component Name} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I proposed a section called "What's Changed". PTAL.
docs/operator/cn/03-10-operations.md
Outdated
@@ -0,0 +1,5 @@ | |||
# {Component/Service Name} - Operations | |||
|
|||
<!--Please create only one single document for your Operations documentation. Our goal is to display all Operations content for a service on a single page so that the operators can quickly search for information using the search function.--> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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!
Yes, configuration is important. Could the |
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... |
|
||
<!--Please create only one single document with multiple sections for your Operations documentation. Our goal is to display all Operations content for a service on a single page so that the operators can quickly search for information using the search function.--> | ||
|
||
<!--Recommended sections: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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:
Related issue(s)