Third-party template discovery

[jandubois]

We have rejected several submissions of additional templates to be bundled with Lima. The main concern is ongoing maintenance:

• We don't want to get bug reports for the templates
• We don't want to update image references
• We don't want to endorse the templates because we don't want to review them

Unfortunately this makes it hard for template authors to advertise their templates, and for users to find them.

---

I propose to create a "self-managing" registry for third-party templates:

Registry location

The registry will be in the https://github.com/lima-vm/lima.yaml repo.

It will have a templates.json file in the root directory which contains the URLs of all known templates and their metadata.

There may be additional GitHub Pages for human consumption.

Template discovery

Any repo owner can add the lima.yaml tag to their repo, promising that the repo contains a lima.yaml file in the root directory.

A GitHub action will once per day query GitHub for a list of all repositories with the lima.yaml tag. It will verify that the promised lima.yaml at the root directory exists. If it does, it will collect metadata (repo description, other repo tags, last modified date for lima.yaml). Archived repos are ignored.

A commit with the new templates.json will replace the previous version. This automatically takes care of finding new templates and pruning ones that have been renamed or deleted.

We can implement a block-list filter if people start abusing this mechanism to publish misleading or malicious templates. But otherwise the mechanism is fully autonomous.

User experience

The templates.json file will be cached on the user's system. If GitHub supports using ETag or similar, then we can always check; otherwise we can update the cached version once per day (as needed).

Similar to limactl create --list-templates we can provide a limactl create --list-external-templates.

The menu displayed by limactl start can be extended with another entry:

 Choose another template (docker, podman, archlinux, fedora, ...)
 Choose an external template

We can even extend tab completion for the github: scheme (once that is supported).

[jandubois]

This proposal could be extended to support e.g. a .lima-templates file that can list multiple lima.yaml files, so one GitHub repo could provide multiple templates.

But I think this would be a bad idea because we don't want the registry to contain too many similar templates; it just makes it less useful because things become harder to find. So requiring an additional GitHub repo for each additional template creates a natural barrier to spamming the registry with lots of variations of the same template.

We should rather encourage template authors to write templates in such a way that they can be used as base templates, with further customization by the user.

Of course the basic mechanism above can always be extended later to allow additional discovery mechanisms if we think they become necessary.

[AkihiroSuda]

Sorry, this proposal seems to make the situation even worse.

We can implement a block-list filter if people start abusing this mechanism to publish misleading or malicious templates. But otherwise the mechanism is fully autonomous.

Regardless to our intention, people will expect the contents linked from our repo to be reviewed by us.
Anyway, we will have to begin actually reviewing all third-party templates to see if somebody has begun to distribute malicious templates.

Let's rather promote github:ORG/REPO schema:

• Add a plugin mechanism to provide custom locator URL schemes #3937

In this way it is obvious that the template is purely owned by a third-party, and not reviewed/endorsed by us.

[AkihiroSuda]

We may also have limactl search command that searches third-party repos with the lima.yaml tag

[jandubois]

Regardless to our intention, people will expect the contents linked from our repo to be reviewed by us.

It would be a separate repo just for the directory/registry.

But this also means we can't even have a list of external template URLs in our docs.

Anyway, we will have to begin actually reviewing all third-party templates to see if somebody has begun to distribute malicious templates.

Maybe. But it would be no different from GitHub removing malicious repos when they are alerted to them. They are not proactively reviewing all repos. This would be the same: we would have a mechanism to block content from the directory once people report abuse.

Let's rather promote github:ORG/REPO schema:

• Add a plugin mechanism to provide custom locator URL schemes #3937

In this way it is obvious that the template is purely owned by a third-party, and not reviewed/endorsed by us.

Oh, absolutely. And this should make it into Lima 2.0, whereas the registry is just a proposal.

But they serve different purposes: the URL scheme makes it easier to reference the templates, but doesn't help with discovery.

The registry would essentially just be like a search engine cache. And can potentially group things by categories or whatever if people are using meaningful tags.

The registry would still leverage the github: URL scheme because all external templates would use it.

[jandubois]

We may also have limactl search command that searches third-party repos with the lima.yaml tag

That already exists: gh search repos --topic lima-yaml.

I just noticed that tags/topics are not allowed to have dots. 😞

[nirs]

• We don't want to endorse the templates because we don't want to review them

This is not a great way to run an open source project. We want to get more contributors to make the project better. The cost is reviewing the contribution and maintaining it. Hopefully new contributors can take care of part of the projects so we can work on other parts that we care more about.

We want to make contribution easier, limiting maintenance. This can be done by introducing a templates/contrib directory with contributed templates that we don't test. "contrib" is an old convention I know from other projects. This can also be "community", "sandbox", or just "unsupported".

The limactl tool can notify users that templates from the contrib directory are not "supported". But maybe the name of the template is good enough to explain the status of the template:

limactl create template://unsupported/foo

In a product using lima you can choose to make the contrib templates optional or not available to minimize maintenance, but the upstream can include it since it is not really supported.

It we take this as example:
#2633

We use this template for ramen, since the existing k8s template is not useful for running multiple clusters. In this case you want an ip address for every cluster since managing port forwarding for multiple cluster is a nightmare, and configuring rbd mirroring is probably impossible.

The current state it that we maintain this template in ramen, and other users are not able to find it. When they try the existing template they either have to reinvent the changes we made for ramen, or they just drop lima since it does not support well multiple k8s clusters. If this was part of lima, even in untested contrib directory, I could take care of it, and other users would be able to use it or even contribute back.

Creating a new repo for this template as part of this suggested global template registry seems too complicated, and I already maintain too much repositories. I hope we can have a much simpler way.

[AkihiroSuda]

We want to get more contributors to make the project better.

Right.

The cost is reviewing the contribution and maintaining it. Hopefully new contributors can take care of part of the projects so we can work on other parts that we care more about.

It is practically impossible to review the content of disk image binaries

We want to make contribution easier, limiting maintenance. This can be done by introducing a templates/contrib directory with contributed templates that we don't test. "contrib" is an old convention I know from other projects. This can also be "community", "sandbox", or just "unsupported".

I still feel uncomfortable to accept potential malware, even in (contrib|community|sandbox|unsupported) directory,

What is the problem of limactl create github:ORG/REPO and limactl search ?

#2633

Slightly off-topic here, but we should be able to extend the upstream k8s.yaml to include what was proposed in #2633.

• Flannel can be unconditionally enabled even for a single-node cluster
• vmnet (or user-v2, in case of non-macOS) should be specified via limactl create --network
• Port forwards can be disabled via --set. We may also consider having --port-forward-none as an alias of it
• The PR does not seem to have kubeadm join, but it can be supported with .param that distinguish the worker nodes from the control planes

[jandubois]

This is not a great way to run an open source project. We want to get more contributors to make the project better. The cost is reviewing the contribution and maintaining it. Hopefully new contributors can take care of part of the projects so we can work on other parts that we care more about.

We do want to encourage people to contribute to Lima, but we also have to define the boundaries of the project.

If you look at scripting languages, they do bundle a set of "core" libraries ("batteries included"), but they do not accept every library written in that language into their core repo. They have set up external repositories, pioneered by Perl with CPAN, and then copied by virtually every other scripting language. Every user can publish their libraries to these repos, and other users can then discover them from this place.

My proposal is borrowing the same concept.

We do not want to ship 500 different templates with Lima itself. We build the extension mechanisms to allow users to extend the ecosystem around it, but not everything needs to be in the core repo.

The recent work on external driver support is another example of moving extension work out of the core repo. While the API is still maturing we may temporarily add more drivers to lima.git, but eventually only the core drivers (qemu, vz, and wsl2) will remain there and other drivers will have their own repos.

We don't want release cycles tied together too closely: why should you have to wait for the next Lima release to fix a bug in your template, or release an update?

We want to make contribution easier, limiting maintenance. This can be done by introducing a templates/contrib directory with contributed templates that we don't test. "contrib" is an old convention I know from other projects. This can also be "community", "sandbox", or just "unsupported".

Yes, but that model doesn't scale. And ties release cycles. And brings bug reports to the wrong place. Contrib versions are perpetually out of date. Having an external repository is so much more flexible.

The limactl tool can notify users that templates from the contrib directory are not "supported". But maybe the name of the template is good enough to explain the status of the template:

limactl create template://unsupported/foo

With this proposal all the external templates would use a github:foo URL, which makes it explicit already.

It we take this as example: #2633
[...]
Creating a new repo for this template as part of this suggested global template registry seems too complicated, and I already maintain too much repositories. I hope we can have a much simpler way.

You don't need to create a new repo for it, you would just set a tag (topic) on the repo and put the template in the root directory.

We can still bike-shed the exact "well known location" where the template should be stored. Maybe we can make it a hidden file in the root directory, and allow it to be a symlink?

The main challenge so far is that @AkihiroSuda seems to believe we should not have any kind of directory at all. I disagree, and hope we can eventually change his mind, but of course it also depends on what others think, so please share your feedback!

[AkihiroSuda]

The main challenge so far is that @AkihiroSuda seems to believe we should not have any kind of directory at all. I disagree, and hope we can eventually change his mind, but of course it also depends on what others think, so please share your feedback!

Can we just recommend people to show their own templates in https://github.com/lima-vm/lima/discussions/categories/show-and-tell ?
There is still a risk that we may get malicious posts, but this risk is not new, so the situation isn't getting worse.

[jandubois]

I still feel uncomfortable to accept potential malware, even in (contrib|community|sandbox|unsupported) directory,

Please note that this proposal is about a separate repo, not about including anything in lima.git.

It would be the equivalent of NPM, Ruby Gems, PyPI, etc, except it would just be an index and not even host the templates.

[nirs]

You don't need to create a new repo for it, you would just set a tag (topic) on the repo and put the template in the root directory.

We can still bike-shed the exact "well known location" where the template should be stored. Maybe we can make it a hidden file in the root directory, and allow it to be a symlink?

Just as a test case for this idea, the ramen template does not belong in the root directory, or even in the test directory. It is part or the drenv tool which is using lima only for macOS. Even if we extract the drenv tool to its own repo, putting the template in the root directory does not make sense.

A symlink can work but it really does not belong to the root directory of the project. So practically you want to create a new repo for one or more templates that should be part of the virtual template registry.

[jandubois]

A symlink can work but it really does not belong to the root directory of the project. So practically you want to create a new repo for one or more templates that should be part of the virtual template registry.

Yes, I intentionally want to create a bit of a barrier, so people "publish" their templates, which hopefully will improve quality a bit.

I don't want to have a directory of all Lima templates anywhere on GitHub. I only want to see templates where people are proud enough to publish them under their name, and where they have put some thought into them being reusable (e.g. having some documentation).

Otherwise you'll end up having to create a curated set of templates from the directory, and we are back at where we started from.

If you want all Lima templates on GitHub, just start from here:

https://github.com/search?type=code&q=minimumLimaVersion+language%3AYAML

If you publish your code to NPM, you have to create metadata for it, package it, and publish it to NPM, for which you need to maintain an account.

So requiring a well-known location for the template, and adding a tag doesn't seem too onerous. If this is too much work, then the template probably is not in a shape to be shared widely anyways.