Instructions block in the README lacks clear direction & purpose for those new to the concept of operators

[benjaminapetersen]

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 implies HELM_CHART=/path/to/wherever. Why does tomcat-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 that docker build expects, so the output is unknown shorthand flag: 'e' in -e.
• Under section 2., if my HELM_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!

[ecordell]

@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
• 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

[benjaminapetersen]

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!

[benjaminapetersen]

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.

[alecmerdler]

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.

[benjaminapetersen]

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.