[proposal] Documentation for olm command workflows#2834
[proposal] Documentation for olm command workflows#2834varshaprasad96 wants to merge 1 commit intooperator-framework:masterfrom
Conversation
This PR provides documentation explaining the workflows for proposed olm commands and a README describing the deployment of operator by following suggested workflows.
varshaprasad96
changed the title
|
This can probably go in operator-framework/enhancements since it enhances OLM and registry tooling. |
jmrodri
left a comment
jmrodri
left a comment
There was a problem hiding this comment.
some questions and some typos.
| status: provisional | ||
| --- | ||
|
|
||
| # README describing new command workflows for olm enabled operators |
There was a problem hiding this comment.
when referring to the product or project name I think we should use capitals. olm -> OLM
|
|
||
| ## Motivation | ||
|
|
||
| Currently, the `operator-sdk generate csv` command is used for generating CSVs, which sacffolds the project and writes the csv manifest on disk. This process still requires the developers to manually edit the CSV when any of the required fields are missing. Also, with the depreciation in the use of package manifests for olm, generating CSVs and creating operator bundle image does not require two separate commands. Integrating both the functionalities and providing a single command with an interactive input for collecting the required UI metadata to generate CSV as well as for building an operator bundle image will result in a better developer experience. |
There was a problem hiding this comment.
typo: sacffolds -> scaffolds
typo: csv manifest -> CSV manifest
did you mean deprecation? instead of "depreciation"?
typo: for olm -> for OLM
|
|
||
| ## Goals | ||
|
|
||
| The proposal is aimed at expalining the resulting process of developing an olm enabled operator from scratch with the above mentioned improvements. |
There was a problem hiding this comment.
typo: expalining -> explaining
typo: olm -> OLM
|
|
||
| ## Proposal | ||
|
|
||
| ### README |
There was a problem hiding this comment.
is README the correct the subheading?
There was a problem hiding this comment.
Not sure completely. But this is a fake README to give an overview about the process.
| $ Provide DisplayName for your operator: | ||
| $ Provide version for your operator: | ||
| $ Provide minKubeVersion for CSV: |
There was a problem hiding this comment.
If these are new prompts we are asking the user, are we thinking about internationalizing the strings? We should at least call out what our plan is for i18n.
There was a problem hiding this comment.
Will there be input validation? If so, how do we ask the user to re-enter?
There was a problem hiding this comment.
These are the UI metadata fields which could asked along with the command. An exhaustive list is here: https://docs.google.com/document/d/1dP6Y9DlE3TuoVXaOdYbuKjo97Qxwqy-07A7msf6_cTQ/edit
We haven't discussed about the implementation yet. Should it be included in the doc?
dmesser
left a comment
dmesser
left a comment
There was a problem hiding this comment.
This looks good. We would create even more appeal with developers if we are able to shorten the commands by relying on reasonable defaults, given we are in a Operator-SDK project directory. If we are not or we couldn't determine the information from on-disk data we can fail fast and ask the user to set the value explicitly.
In addition this proposal would benefit from a fake man page that elaborates on the various switches. This allows for the example workflow to use the short versions whereas the fake man page provides the details about further options.
|
|
||
| # Generate kustomize base templates with UI metadata and publish operator in a bundle image | ||
| # If you would like to write the operator manifests on disk, specify the path using the flag "--output-dir" | ||
| $ operator-sdk generate bundle <IMAGE_REGISTRY>/<TAG> |
There was a problem hiding this comment.
A couple thoughts to make this command even shorter:
--package - could we derive this from the operator (project) name by default?
--kustomize-dir - it's already proposed as optional given we have a default, that's great
--output-dir - it's already optional, so we are good
Given the above, the command would be shortened to: operator-sdk generate bundle <image>:<tag> which looks really appealing in a (repetitive) workflow.
There was a problem hiding this comment.
Yes, as the package name can be derived from the operator project, have made it optional if the user wants a different package name than the project name.
|
|
||
| # Deploy and test the operator on the cluster using OLM | ||
| # If path to the kustomize base templates is not present, they are generated from scratch inside ./config folder | ||
| $ operator-sdk run --olm --kustomize-dir <Path to directory containing kustomize base templates> |
There was a problem hiding this comment.
Similar to my previous comment, I am looking for ways to make this even shorter.
--kustomize-dir - can we use the same default like we do in generate bundle?
--operator-version - can we use the the version string from CSV as a default?
If both is possible, this command would be a mere operator-sdk run --olm which is really nice.
There was a problem hiding this comment.
Have modified the operator-sdk run --olm command to:
- Deploy the operator for the version specified in the kustomize template for generating CSV.
- Use the specified
--versionif present.
| ... | ||
|
|
||
| # Cleanup | ||
| $ operator-sdk cleanup --olm --operator-version <Version of the operator> |
There was a problem hiding this comment.
We could make --operator-version optional by either taking the version string from the CSV or clean up the first operator we find by this name.
|
@dmesser - I have made the changes and updated the PR (operator-framework/enhancements#16) in the operator-framework/enhancements repository. Please provide your reviews. |
|
Closing this PR, as it has been moved to operator-framework/enhancements repository. |
4 participants
Description of the change:
This PR provides documentation explaining the workflows for proposed OLM commands and a README describing the deployment of operator by following suggested workflows.
Motivation for the change:
Improve OLM commands.