Clarification: Rename template into workflows and revisit what a workflow is today

[gianarb]

Ciao!

This is a long-standing topic we have. But I think it is time to make it happen.

Today we have templates and workflows.

A template is a reusable description of tasks and actions that we want to perform somewhere at some point. We are working around the concept of #438 and things like that.

A workflow represents the execution of a template at some point in time.

---

As far as they are designed today they are treated as resources, as long as hardware. But technically speaking a template yes, is a resource but a workflow is not.

You can create, update and delete a template. But a workflow can start, can't be edited, or removed.

---

What I am proposing is to rename template to workflow, mainly because template is really generic as a term, even workflow is but differently. it clearly set the expectation for something that can be executed multiple time.

What we know today as workflow can be renamed as execution, and it won't be a resource on its own, it will be strictly linked to a template (well... workflow 👍 I am already confusing myself)

Let me describe the interaction I have in my mind via Tink CLI

# equivalent of tink template create
tink workflow create 

# equivalent of tink workflow create
tink workflow run <workflow_id> --data device_1=mac-address...

# list the execution of specific workflows
$ tink workflow list-executions <workflow_id>

# A lot of what is now under tink workflow will be moved under the new tink workflow

[mmlb]

Yep I think this makes a lot of sense. This is about a good a place to start for the mass renaming of things for clarity.

[markjacksonfishing]

+1

[thebsdbox]

This is much clearer, although there may be some confusion between <workflow_id>

• Is it the list of actions?
• Is it the running task?

tink workflow get does this return a workflow (of actions) or does it return the running workflow?

[mmlb]

I think we'd rename to execution-id naming for that.

[gianarb]

@thebsdbox I am assuming you are speaking about the "new workflow"

tink workflow get

That command returns the list of workflows, it is almost the same you get when you do tink template get today.

if you want to get all the executions for particular workflows you will do something like:

tink workflow describe <workflow_id>

it will return details of the workflow (the YAML for example) and a list of executions (execution are just the same thing you get today when doing tink workflow get

tink workflow execution <execution_id>

Can be the command who returns the status of specific execution, with the progress for all the actions and so on... wdyt?

[gauravgahlot]

The command tink workflow status <execution_id> instead of tink workflow execution <execution_id> to return the status of specific execution.

@gianarb Corrected!

[gianarb]

hey! Instead of what @gauravgahlot ? Or for what?

[jacobweinstock]

I really like that we're moving on from template. I would like to propose we use provision instead of execution.

template -> workflow
workflow -> provision

# create a workflow
tink workflow create --file ubuntu20.04.yaml
# provision a machine
tink provision create --workflow <workflow_name or workflow_id> --hardware <hardware_name or hardware_id>

[mmlb]

# create a workflow
tink workflow create --file ubuntu20.04.yaml
# provision a machine
tink provision create --workflow <workflow_name or workflow_id> --hardware <hardware_name or hardware_id>

I don't think --hardware makes sense here either because there really isn't any enforcement that template/workflow's templating only applies to "device". --values or --data or similar really seems like the direction to go in. I can envision passing in one-time passwords/tokens via --values for example.

[jacobweinstock]

Wow! There is a lot here...

--hardware <hardware_name or hardware_id> what is this? I don't understand

In my opinion, tink provision create is wrong again because it places provision at the same level as another resource, but an execution (provisioning) is not a resource like hardware and template/workflow. Because you can't create, update, delete it.

What do you do with a workflow? You run it... I am not sure provisioning a workflow is right

tink workflow run <workflow_id>

Maybe you can provision hardware with a workflow...

tink hardware provision <template_id>

But I don't think this is true because, in theory, you can have a workflow that targets a worker that is not registered as hardware right? (I think this is what @mmlb calls privileged workflow).

Maybe we can use provision as a term to identify a workflow execution if we do not want to execution but I am not sure... And I am probably not the best candidate to be picky with it comes to naming things in a language that is not my native one!

Thanks for the feedback. It seems like I definitely have a different understanding/experience with how we interact with the stack.

fundamentally aren't we taking a hardware profile/data and combining it with a template/workflow? this gives is us what? workflow run? in this context, I don't feel this makes sense. Combining hardware with a workflow isn't still just a workflow, is it? It feels like we're creating another resource.

Especially once we are running the same workflow against multiple "devices". Then, when we're talking/reasoning about a workflow only its execution/run id matters. We can't use the workflow name/id anymore. For example, "Hey Jane, can you help troubleshoot run_id 1234" or "run_id is 70% complete". This allows us to reference a workflow and its associated hardware. The execution/run id feels like its own resource now.

Also, regardless of whether a workflow is run to provision a machine, or update firmware, or discover hardware, there is a mapping between a workflow and a piece of hardware. When a user is working with a machine and then comes to the Tinkerbell stack, the hardware doesn't feel like a first-class citizen anymore. Going from hardware data to what is being run on it (the workflow) is not a direct connection. workflow -> mac address, then mac address to hardware data.

These are some of the reasons I'm bringing up the idea of making the combination of hardware data with a workflow a first-class resource that is the direct combination of the two. My suggestion used specific words like provision but really at the moment, I'm more interested in what the thoughts are around this general idea than the names.

If I'm just way off base, please let me know. I don't want to delay or derail any forward progress to renaming template. I'm really on board with that. Thanks for the consideration.

[gianarb]

You are right! This brings me to another topic we can discuss on its own (I
introduced it to Manny a few days ago), but yes... Hardware should not be
part of the Tinkerbell stack in my opinion because Tinkerbell is a workflow
engine. It should be made of two things: "something to run", a workflow in
this context. And an execution request (that will may or may not contain
all or part of what today is known as hardware). So yes. I agree.

Even Hegel should not be part of the stack IMHO, I am not saying it should not
exist, but it is not a strict requirement when I look at Tinkerbell and the
the problem it solves.

[jacobweinstock]

This is a very interesting idea. I'm interested in learning more. Is this something you'll be discussing in an upcoming community meeting?

[gianarb]

I would really like to but I want to produce something that we can all read and look at first