Doc unclear / TOI doc doesn't mention toiExecutor actions field

[dee0]

What happened:

Here there
is a field Actions []string on the Executor struct.

And here there is an assertion that that the user specified action is in the toiExecutor's list of actions.

The documentation here doesn't cover the above Actions field.

Perhaps this is by design, since not specifying any Actions on the toiExecutor seems to make it applicable for any user specified action. So maybe the field is actually deprecated or not ready for user adoption yet. Or maybe the doc above is just failing to describe the field.

In any case, the doc is unclear. I am looking at the code because the doc doesn't make it clear how the various config, template, scheme, credential request and parameters of toiPackage and toiExecutor are used to make the input for the the install program that will ultimately be run.

For sure part of the problem is the reliance on spiff++. Not many people are familiar with this and the docs for spiff++ aren't great.

I guess what I am saying is that there are possibly two doc defects here :

1. For sure the doc should be clear enough so that I don't feel the need to resort to reading the code, and
2. Perhaps the doc needs to describe the Actions field

What you expected to happen:

Head shouldn't hurt after trying to figure out how this stuff all works :)

How to reproduce it (as minimally and precisely as possible):

See above

Anything else we need to know:

Nope

Environment:

OCM and doc site as of 2024-12-16.

[dee0]

Was just getting back to the task I was at when I felt motivated to look into the code.

toiPackage has executors []ExecutorSpecification and ExecutorSpecification has actions []string.

So I was wondering what happens if multiple ExecutorSpecification contain the same action in the there actions []string. Do all of those executors run? Or just the first one? Or maybe this is an error condition?

From the code, I believe it is the case that only the first runs. But then in that case I would think it would be better if somehow a map from action to executor was used.

[jakobmoellerdev]

Hey @dee0 thanks for reaching out. The main issue is that the TOI executor was not publicly documented mainly because it is an alpha grade implementation. As such we are discussing in the team of even deprecating it alltogether (basically putting it EOL) as we are barely able to support it as it stands. Do you rely on its functionality for your use cases? If so we will have to think about adding additional documentation but this might take a while before it hits the repos.

[dee0]

Thanks for looking at the ticket @jakobmoellerdev

In our current project to move to Kyma we are looking to lean heavily on OCM for CD and for supporting sovereign cloud.

For the latter, we need something like OCM TOI in order to streamline the bootstrapping of our applications. Since anyway we expect the operators of the private cloud to be using the OCM cli for transport it of course makes sense to use TOI for bootstrapping.

Obviously if we have set things up so that TOI can be used for sovereign cloud then we may as well use it for ourselves.

Given the above, it should be no surprise that it would be very disappointing for us if TOI were to be deprecated as then we would have to go back to the drawing board when it comes to the bootstrapping of our application. And as some folks are on the bubble wrt OCM usage, they question the value of its usage overall, those of us in support of using OCM will have to again make the case for it.

Regarding support, my manager has no problem with his team contributing fixes to OCM. So if TOI is basically working, or nearly working, for our use case I think we would really rather see TOI left in place as opposed to be deprecated.

That said, as we are just in the process of implementing a 'hello world' installer, followed by a POC installer of our stuff, we can't say yet what gaps there may be.

[dee0]

Hey @mandelsoft and @jakobmoellerdev

Would you please take a look at the readme here in this TOI helloworld project I created and let me know what you think?

Btw, while at the moment the project doesn't actually define an installer it does attempt to document the install process + simulate the spiff operations.

I intend to actually implement the installer once I have some feedback on what is present so far. i.e. I want to confirm I am on the right track first.

And once the installer is done I would like to open a PR for the OCM doc to improve the TOI documentation.

[jakobmoellerdev]

Thanks for looking at the ticket @jakobmoellerdev

In our current project to move to Kyma we are looking to lean heavily on OCM for CD and for supporting sovereign cloud.

For the latter, we need something like OCM TOI in order to streamline the bootstrapping of our applications. Since anyway we expect the operators of the private cloud to be using the OCM cli for transport it of course makes sense to use TOI for bootstrapping.

I agree that you will need something like TOI, however TOI as it is now is simply not battle proven enough to be agreed upon. Call it a POC of sorts.

Obviously if we have set things up so that TOI can be used for sovereign cloud then we may as well use it for ourselves.

Agreed.

Given the above, it should be no surprise that it would be very disappointing for us if TOI were to be deprecated as then we would have to go back to the drawing board when it comes to the bootstrapping of our application. And as some folks are on the bubble wrt OCM usage, they question the value of its usage overall, those of us in support of using OCM will have to again make the case for it.

I understand the issues regarding the value add OCM alone brings. However the team doesn't want to do early commitments on TOI because we have our hands full with rethinking the core of OCM due to maintainability concerns. Similarly, I am afraid that TOI cannot be maintained by us actively right now.

Regarding support, my manager has no problem with his team contributing fixes to OCM. So if TOI is basically working, or nearly working, for our use case I think we would really rather see TOI left in place as opposed to be deprecated.

We cannot guarantee that TOI is working except for @mandelsoft's manual tests and setups (which most of the team has no insight into). We can provide support to establish a common working model or even agree to develop a standard based on TOI together that you can either lead or contribute on however, bringing TOI from POC stage to an actually wanted value add.

That said, as we are just in the process of implementing a 'hello world' installer, followed by a POC installer of our stuff, we can't say yet what gaps there may be.

You're in the same boat as us, so one here should expect the roads to a production grade TOI like tool to be clear. We are happy for any contribution will in that regard and am willing to setup community calls, issues or subprojects, but the core of OCM and its library is on too loose feet right now to focus on this. (even though it pains me to admit this)

Hey @mandelsoft and @jakobmoellerdev

In the future, you can address @open-component-model/maintainers if you want the attention of the team. @mandelsoft in particular does not work actively on OCM anymore starting this year.

Would you please take a look at the readme here in this TOI helloworld project I created and let me know what you think?

I went through your project and this is a great effort to make sense of the existing TOI. I would love to channel that energy into making the entirety of a potential "TOI v2" a possibility. Your practical feedback and ideas as well as a bit of technical guidance should allow us to make TOI a much more applicable concept. Concretely, I think I want to avoid any mandatory interaction points with spiff++ in the future. The structure looks okay to me and does not immediately break patterns (but due to my lack of history with TOI, take that with a grain of salt).

Btw, while at the moment the project doesn't actually define an installer it does attempt to document the install process + simulate the spiff operations.

I am thinking that the spiff stuff is the most contentious point of it all :D

I intend to actually implement the installer once I have some feedback on what is present so far. i.e. I want to confirm I am on the right track first.

Again, hard to say for me without deep diving myself. Youre probably deeper into the TOI infrastructure at this point than me.

And once the installer is done I would like to open a PR for the OCM doc to improve the TOI documentation.

I love the enthusiasm and am waiting anxiously :D