Add docs on Hybrid operator

[varshaprasad96]

There are no docs related to hybrid operators. We would need docs to encourage users to start using hybrid operators which is an extension of Helm based operators.

Update:
The proposal is to have docs in a separate directory with the following high level contents:

• Overview on Hybrid Operators
• Quickstart on creating a hybrid operator
• Tutorial on creating a hybrid operator

Subsections:

• Init command
• Create api (with go and helm)
• Configuring RBACs (Scaffolding RBAC when go and helm apis are specified in the project #142)
• Customizations in helm reconciler
• Running the operator
• Configuring watches.yaml
• Quick overview on hybrid project structure (similar to https://sdk.operatorframework.io/docs/overview/project-layout/#m-docsoverviewproject-layout)
• Steps to migrate legacy helm project to hybrid (There are not any specific steps, but a few lines will help)

[jmrodri]

Transform this ticket into a meta issue for docs related items. During the Helm community meeting we brought up the issue of where to host it, for now let's focus on the content and deal with hosting later.

[varshaprasad96]

Updated this to be a meta-issue with sub sections.

[ryanm101]

Any update on this as I'm trying to make a hybrid operator and it's non-obvious.

e.g.

# Create the go modules file
go mod init example.com/m/v2

# Create the initial operator - API
operator-sdk init --plugins=helm  --domain=example.com  --kind=CMAPI  --helm-chart=../helm/cm/charts/cmapi

# Allow multiple Helm charts
echo "multigroup: true" >> ./PROJECT

# Create the UI operator
operator-sdk create api --helm-chart=../helm/cm/charts/cmui --kind=CMUI

# Add Reconciler
operator-sdk create api --group=api --kind CM --resource --controller --plugins=go/v4-alpha --version v1beta1

results in the error: FATA[0000] failed to create API: unable to run pre-scaffold tasks of "base.go.kubebuilder.io/v4-alpha": cmd/main.go file should present in the root directory

I know documentation is the bane of all things but it's rather critical to a project like this.

[varshaprasad96]

@ryanm101 Detailed docs are available here: https://github.com/operator-framework/helm-operator-plugins/blob/main/docs/tutorial.md. Also a sample project generated using these commands can be referred here: https://github.com/operator-framework/helm-operator-plugins/tree/main/testdata/hybrid/memcached-operator.

The error you are witnessing here is because of the go/v4-alpha plugin version. The hybrid helm project currently isn't modified to support go/v4 plugins yet. I would suggest to use go/v3 for now. A separate issue needs to be created to add support for the recent scaffolding changes in v4 versions of go plugin.

[ryanm101]

So a bit more playing results in

go mod init example.com/m/v2



# Create the initial operator - API
operator-sdk init --plugins=hybrid.helm.sdk.operatorframework.io  --domain=example.com

echo "multigroup: true" >> ./PROJECT

# Create the UI operator
operator-sdk create api --helm-chart=../helm/cm/charts/cmapi --kind=CMAPI --plugins helm.sdk.operatorframework.io/v1
operator-sdk create api --helm-chart=../helm/cm/charts/cmui --kind=CMUI --plugins helm.sdk.operatorframework.io/v1

then operator-sdk create api --group=api --kind CM --resource --controller --plugins=go/v3 --version=v1alpha1 results in:

go: finding module for package example.com/m/v2/api/api/v1alpha1
go: example.com/m/v2 imports
        example.com/m/v2/api/api/v1alpha1: cannot find module providing package example.com/m/v2/api/api/v1alpha1: unrecognized import path "example.com/m/v2/api/api/v1alpha1": parse https://example.com/m/v2/api/api/v1alpha1?go-get=1: no go-import meta tags ()
Error: failed to create API: unable to run post-scaffold tasks of "base.go.kubebuilder.io/v3": exit status 1
Usage:
  operator-sdk create api [flags]

with go/v4-alpha i get:

FATA[0000] failed to create API: unable to run pre-scaffold tasks of "base.go.kubebuilder.io/v4-alpha": cmd/main.go file should present in the root directory 

Following Doc here: https://docs.openshift.com/container-platform/4.14/operators/operator_sdk/helm/osdk-hybrid-helm.html

[ryanm101]

Issue seems to be in the imports in main.go

it's looking in <rootdir>/api but it's creating everything in <rootdir>/apis

it's caused by multigroup.

setting all the components to single group works.

# Create the go modules file
go mod init example.com/m/v2

# Create the initial operator - API
echo "INITIALISING OPERATOR"
operator-sdk init --plugins=hybrid.helm.sdk.operatorframework.io --project-version="3" --domain=example.com
#operator-sdk edit --multigroup=true # fails

# Create the UI operator
operator-sdk create api --helm-chart=../helm/cm-api --kind=CMAPI --plugins helm.sdk.operatorframework.io/v1  --group cm
operator-sdk create api --helm-chart=../helm/cm-ui --kind=CMUI --plugins helm.sdk.operatorframework.io/v1  --group cm

echo "Adding Custom Controller"
operator-sdk create api --group cm --kind CM --resource --controller --plugins=go/v3 --version=v1

[ryanm101]

Though now i see

make build
make: *** No rule to make target `build'.  Stop.

operator-sdk version
operator-sdk version: "v1.32.0", commit: "4dcbbe343b29d325fd8a14cc60366335298b40a3", kubernetes version: "v1.26.0", go version: "go1.21.1", GOOS: "darwin", GOARCH: "arm64"

is it because i'm on a mac M1?

[varshaprasad96]

@ryanm101 Could you share your Makefile which is scaffolded by the project?

is it because i'm on a mac M1?

It shouldn't matter, the build target should appear either ways. I see that in testdata:

helm-operator-plugins/testdata/hybrid/memcached-operator/Makefile

Line 41 in 215d1f8

build: manifests generate fmt vet ## Build manager binary.