feat: introduce @Workflow annotation

[csviri]

No description provided.

[metacosm]

This will crash if there is no workflow annotation.

[csviri]

There is a default workflow annotation, with empty dependents. To my understanding that never happens.

[metacosm]

TBH, I'm not convinced that this improves anything. This is more verbose and will require quite a bit of change in lots of places for non-obvious benefits.

[csviri]

This is required also for this issue:
#1898

That is why it is not just a simple rename.

[metacosm]

I don't follow how this is required for explicit invocation of workflows. There's an implicit workflow being created already so adding an annotation doesn't bring much unless we would like to have data specifically associated with the workflow. That said, even workflow data could be added to the ControllerConfiguration annotation. Adding a new annotation would only make sense if we envisioned to have lots of data associated with workflows and/or if we wanted to have several workflows with different data set, which I don't think we should in either cases.

[csviri]

There are multiple aspects of this, why I think this is really beneficial:

1. what is probably less important is just better domain language, when talking to devs usually they don't get that in the background there is this Workflow that is executes the Dependent resources, so would be nice to have both in the domain language.

2. Features like this:

@ControllerConfiguration(
    workflow = @Workflow( 
          explicitInvocation = true,
          dependents = {
              @Dependent(...),
              @Dependent(...)}
    )

In the mentioned link, this is closely related to the workflow, and how it is invoked. It is much nicer to have such configs / feature options put there since its is coupled with the workflow not the controller configuration directly.
I expect that more of such will come in the future, so it is kinda future compatibility also.

[csviri]

I don't follow how this is required for explicit invocation of workflows.

So if there is no flag like mentioned how can the controller know if the workflow should be executed before reconcile method is invoked or it will be invoked manually / explicitly.

[metacosm]

I don't follow how this is required for explicit invocation of workflows.

So if there is no flag like mentioned how can the controller know if the workflow should be executed before reconcile method is invoked or it will be invoked manually / explicitly.

By simply having an explicitWorkflowInvocation attribute on the ControllerConfiguration annotation without the need for an intermediate annotation.

[metacosm]

There are multiple aspects of this, why I think this is really beneficial:

1. what is probably less important is just better domain language, when talking to devs usually they don't get that in the background there is this Workflow that is executes the Dependent resources, so would be nice to have both in the domain language.

Sure but this could be addressed by better documentation 😄

2. Features like [this](https://github.com/operator-framework/java-operator-sdk/issues/1898):

@ControllerConfiguration(
    workflow = @Workflow( 
          explicitInvocation = true,
          dependents = {
              @Dependent(...),
              @Dependent(...)}
    )

In the mentioned link, this is closely related to the workflow, and how it is invoked. It is much nicer to have such configs / feature options put there since its is coupled with the workflow not the controller configuration directly. I expect that more of such will come in the future, so it is kinda future compatibility also.

What other attributes would we be adding to the workflow configuration? I don't think that we should be adding complexity just for the sake of potential future features which might never materialize.

[csviri]

see also: #2238 (comment)

It is much nicer and descriptive to have these coupled.

Not sure what is wrong with an intermediate annotation. It is much nicer domain modeling, if we have hierachical structure.

[csviri]

Sure but this could be addressed by better documentation 😄

I think we all agree if it is much better if the user does not have to dive into docs, just understands the code based how it is structured.

[csviri]

What other attributes would we be adding to the workflow configuration? I don't think that we should be adding complexity just for the sake of potential future features which might never materialize.

So the explicit domain objects reduce cognitive burden imo, as mentioned, users will create a @Workflow and will see what are the related properties and config options. So they don't have to search for (and potintially miss it) in @ControllerConfiguratio

[openshift-merge-robot]

PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[csviri]

replaced by: #2274