Documentation of Mixin architecture

[richbai90]

I need to develop a Mixin for Packer by Hashicorp. I'm looking at the aws cli Mixin as a guide, since my Mixin will be very simple, just execute a few commands during build, and a couple more during install. I can't figure out by reading the documentation or looking at examples, where the logic actually happens. My understanding is that the aws Mixin just defers to the exec Mixin, but even searching the entire repository of the aws Mixin, the only text containing ec2 is in a test file. Where does the actual aws command get invoked?

[carolynvs]

Sorry, we really are lacking any good docs on how to implement a mixin.

All the mixins right now act as wrappers for a CLI installed in the bundle's container. The pkg/exec/builder package contains common logic that they all share to handle calling the CLI. The mixin is mostly responsible for the following:

1. Defining its schema, so that people using an editor can get autocomplete, and so that porter can (eventually) validate the porter.yaml during build.
2. Defining an Action struct that matches your supported yaml syntax in the porter.yaml file. This struct should contain fields for the data the user is setting in the porter.yaml (for example, the exec mixin's Action has fields for "command", "arguments" and "flags".
3. Have the Action struct implement relevant interfaces used by the pkg/exec/builder package. These interfaces tell Porter how to execute your command, what the command is, the arguments to pass, flags, the current working directory, and if your mixin supports collection output from the command (which again is assisted by that builder package).

Here is the line in the aws mixin's code that tells the builder package how to call aws (i.e. what is the name of the cli that is wrapped by the mixin)

https://github.com/getporter/aws-mixin/blob/5fd791685a6d4c5dab98fa1d3dad98104039c5b6/pkg/aws/action.go#L68-L70

You mentioned that you looked for the term "ec2" in the mixin and I wanted to explain quick why you won't find that in the aws mixin. Most of the public mixins just wrap existing commands, and use concepts such as "arguments" and "flags" to support calling any aws command supported by the CLI without having to maintain and keep up to date a mixin that has explicit understanding of each sub-command the aws CLI supports.

A mixin could choose to be more than a wrapper for a CLI (the helm3 mixin is more opinionated, same with the arm mixin). I don't have public examples of this, but some mixins don't wrap a CLI at all and execute internal logic instead, or call an API, etc.

Feel free to ask more follow-up questions, I realize that at the moment writing a mixin mostly relies upon using the skeletor template repository and then reading the code to figure out what's going on.

[richbai90]

I see. That makes a lot of sense. I appreciate your willingness to answer questions so quickly. Seeing your the last CNAB shop still in active maintenance, I appreciate your dedication to project and hope this sticks around. It's a great tool.

[carolynvs]

Don't worry, Porter isn't going anywhere. 😄 We are getting more users and contributors all the time. But yeah we still have a ways to go on both content and libraries to help people extend porter.