helm-app-operator-kit
helm-app-operator-kit copied to clipboard
Instructions block in the README lacks clear direction & purpose for those new to the concept of operators
Greetings! So confession up front, I'm new to operators. Therefore, this issue is just describing some of my personal friction trying to use helm-app-operator-kit
with a helm chart I have created. There is a lot of assumption in the directions, it would be great to clarify to improve adoption.
I'll start with this block and outline my questions:
This project is a component of the Operator Framework
Makes implies I should download a binary & run it against my helm chart (I see there is golang
here, though I am not asked to build it). However:
This repository serves as a template for easily creating...
Makes me think think this repo is more of an example/tutorial.
Run the following:
$ git checkout [email protected]:operator-framework/helm-app-operator-kit.git && cd helm-app-operator-kit
$ docker build -t quay.io/<namespace>/<chart>-operator -e HELM_CHART=/path/to/helm/chart -e API_VERSION=<group/version> -e KIND=<Kind> .
$ docker push quay.io/<namespace>/<chart>-operator
Could be greatly improved with some explanation. A few questions/suggestions:
- There is a
tomcat-operator
directory included, and the README sounds a bit like a tutorial, but impliesHELM_CHART=/path/to/wherever
. Why doestomcat-operator
appear as a top level item? -
API_VERSION=<group/version>
implies an input, but there isn't an explanation as to what this is for. Assuming someone is coming to this project who isn't super familiar with operators, this would be nice to explain. -
KIND=<kind>
also could be explained for the same reason as above, very helpful to assume people are new to the concept of operators - I ran the
docker build -t quay.io/myuser/my-new-operator -e HELM_CHART=<~/path/to/a/place/where/I/have/a/chart> -e API_VERSION=<foo/bar> -e KIND=<kind>
, but-e
is not a flag thatdocker build
expects, so the output isunknown shorthand flag: 'e' in -e
. - Under section
2.
, if myHELM_CHART=/path/to/chart
, the./deploy
directory here is strange. If my helm chart path is elsewhere, I don't quite understand why I am working with the/deploy
directory here.
Appreciate any feedback, and happy to help improve the doc via PRs if open to discussion. Thanks!
@benjaminapetersen You're absolutely correct - helm-app-operator-kit is a poor entrypoint into learning about and building operators. This is something we should fix (even if we link out to some docs somewhere else that says "Read This First")
The goal of this repo is to provide tooling to build a stateless application operator out of a helm chart. There is also an example of how to configure the tooling (this is what tomcat-operator is intended to do).
Some action items for us to clean this up (further suggestions welcome).
- [ ] Link to introductions to the operator concept and other operator tools (olm)
- [ ] Provide at least a short introduction that assumes you don't already know what an operator is
- [x] move tomcat-operator under an
examples
directory - [ ] provide step-by-step instructions for building an operator from a helm chart (as opposed to the current list of commands with fake paths)
- [ ] Be clear about what the tooling is doing; provide instructions for loading a chart into a container with the helm-app-operator-kit already installed as well as instructions for building your own container that makes use of helm-app-operator-kit
Yes, your checklist sums it up well.
New to operators, my thought was "oh, build from a helm chart, this is prob the easy entry point." Nope :) At least, not quite yet.
Appreciate the reply!
Curious, is there a good "how to make an operator for my app" guide already? Basically an operators 101 for a simple nodejs/Ruby/go app, what are the key things to manage.
I see plenty of existing operator examples, but a starter guide would be fantastic.
Curious, is there a good "how to make an operator for my app" guide already?
The Operator Framework "Getting Started" repository is the closest thing to this right now.
Right! I opened an issue or two there suggesting ways to expand the guide. Particularly the "Now, copy and paste this Handler..." section. Rather than a copy/paste, working through the function conceptually. Esp given the disclaimer Note: The provided handler implementation is only meant to demonstrate the use of the SDK APIs and is not representative of the best practices of a reconciliation loop.
I imagine many are looking for the best practices to avoid repeating known mistakes.