Architecture documentation

[ascheman]

I am about to write some internal documentation about Konveyor/Kantra these days.
It contains component diagrams like the following to show the composition of the tool chain.

I would like to propose a docs-as-code / diagrams-as-code approach for such documentation (e.g., using PlantUML).

With this representation there are several drawbacks

• PlantUML is somehow ugly (and does not render deterministically)
• The diagram is (yet) to large (we have to split it up)

But it also has some benefits

• We could automatically check consistency of the diagram with the Dockerfile (or perhaps even generate it from the Dockerfile with some lightweight tooling/script)
• Diagrams (as code) could be maintained close to the code (so it is easier for the responsible development staff to keep it up-to-date)

If the team would be willing to learn and further maintain such kind of documentation, we could think about contributing our work to the Konveyor project.

[ascheman]

Even more important, we should have some runtime diagram which show how the different tools interact, e.g.,

[jwmatthews]

I like the idea of capturing this kind of information and open to exploring options. As to tooling, I've seen some usage of Mermaid that could be interesting, but I don't have strong experience/preference. I'm supportive of general spirit of this, collaborating to get arch diagams/docs together sounds great!

[savitharaghunathan]

I asked collaborators/maintainers from CNCF for their thoughts on the tools they use for architecture diagrams since I have less insight in that area. The most popular reply was mermaid.js . I havent had the chance to consolidate the replies yet. If you are interested, here's the thread - https://cloud-native.slack.com/archives/C014YQ8CDCG/p1700150633917999

[ascheman]

I suggest not to focus on just one tool for diagrams. Both mermaid and plantuml have their merits and drawbacks. IMHO

• mermaid renders more nicely, though I have never tried it for larger diagrams like the Docker based component diagram shown above. Perhaps someone could try to assemble a comparable mermaid-based component diagram to see the differences?
• plantuml renders really ugly, but has way more options, i.e.,
  • diagram types,
  • symbols within one diagram type like the control, entity, etc.,
  • and the option to define ones one sprites including a large library of predefined symbols for almost all current cloud technologies (the so called stdlib).

Both could be complemented by https://diagrams.net which allow to create really powerful diagrams (though not text/DSL based). But you can store PNGs (or even better SVGs) with the model embedded. So you still have diagram source and visible representation in one file (though it's hard to perform diffs on the models).

[ascheman]

Perhaps my analysis so far is wrong, but I cannot see how/when windup-shim and kantra itself are used in the respective containers (see composition above). However, they are both copied into the kantra image, i.e.,

• https://github.com/qaware/kantra/blob/698dfaf20cc2370f5888c0ca2cdff8479c0a77f1/Dockerfile#L35 (kantra), and
• https://github.com/qaware/kantra/blob/698dfaf20cc2370f5888c0ca2cdff8479c0a77f1/Dockerfile#L38 (windup-shim).

To me, it seems as if kantra when used as CLI creates several containers (but directly calling, e.g., konveyor-analyzer), so it is never used inside of the container.
windup-shim seems to be used offline to transform WindUp rulesets (XML) to Konveyor rulesets (YAML). But is it ever used on the fly to convert rulesets?

So, why are both built/copied to the final runtime container image?

[jwmatthews]

@fabianvf would you help to share some thoughts on Monday?

[fabianvf]

I believe kantra is included in the container so that it is installable via the container image, ie

podman pull quay.io/konveyor/kantra:latest
podman run --name kantra-download quay.io/konveyor/kantra:latest 1> /dev/null 2> /dev/null
podman cp kantra-download:/usr/local/bin/kantra .
podman rm kantra-download

so you are correct, it is not used at runtime or within the container. It's only used as a method of distribution.

windup-shim is used on the fly to convert rulesets. We convert and test the rulesets that we deliver ahead of time, but there are many users that already have XML rulesets written that they use internally. Kantra is able to take those in and do a best effort conversion and run using windup-shim.

[ascheman]

Thanks for the reply, @fabianvf - The software distribution method is - let's say - interesting ;-).

Can you point me to a piece of code, where windup-shim is used? How could I make use of it when calling kantra?

[fabianvf]

Yeah it's a pretty quick and dirty distribution method.

I believe execution of windup-shim happens under the kantra transform rules subcommand

$ kantra transform rules -h
Convert XML rules to YAML

Usage:
  kantra transform rules [flags]

Flags:
  -h, --help                help for rules
  -i, --input stringArray   path to XML rule file(s) or directory
  -o, --output string       path to output directory

Global Flags:
      --log-level uint32   log level (default 4)
      --no-cleanup         do not cleanup temporary resources

The subcommand implementation is here:

https://github.com/konveyor/kantra/blob/main/cmd/shimconvert.go#L25

It does run it in a new container, but it's another quay.io/konveyor/kantra image with an overwritten entrypoint (hence the windup-shim's inclusion in the image:

https://github.com/konveyor/kantra/blob/main/cmd/shimconvert.go#L165-L173