Add optional support for specifying digests for template locators

jandubois · jandubois · commit 3faf29335568 · 2025-02-15T23:27:00.000-08:00
Instead of `base: template.yaml` the user can write:

```yaml
base:
- url: template.yaml
  digest: decafbad
```

Same thing for `file` properties of provisoning scripts and probes.

The digest values are currently being ignored; verification will happen
in a later PR.

Signed-off-by: Jan Dubois &lt;jan.dubois@suse.com&gt;
diff --git a/cmd/limactl/template.go b/cmd/limactl/template.go
@@ -47,8 +47,9 @@ var templateCopyExample = `  Template locators are local files, file://, https:/
   # Copy default template to STDOUT
   limactl template copy template://default -
 
-  # Copy template from web location to local file
-  limactl template copy https://example.com/lima.yaml mighty-machine.yaml
+  # Copy template from web location to local file and embed all external references
+  # (this does not embed template:// references)
+  limactl template copy --embed https://example.com/lima.yaml mighty-machine.yaml
 `
 
 func newTemplateCopyCommand() *cobra.Command {
diff --git a/pkg/limatmpl/abs.go b/pkg/limatmpl/abs.go
@@ -26,7 +26,7 @@ func (tmpl *Template) useAbsLocators() error {
 		return err
 	}
 	for i, baseLocator := range tmpl.Config.Base {
-		locator, err := absPath(baseLocator, basePath)
+		locator, err := absPath(baseLocator.URL, basePath)
 		if err != nil {
 			return err
 		}
@@ -40,7 +40,7 @@ func (tmpl *Template) useAbsLocators() error {
 	}
 	for i, p := range tmpl.Config.Probes {
 		if p.File != nil {
-			locator, err := absPath(*p.File, basePath)
+			locator, err := absPath(p.File.URL, basePath)
 			if err != nil {
 				return err
 			}
@@ -49,7 +49,7 @@ func (tmpl *Template) useAbsLocators() error {
 	}
 	for i, p := range tmpl.Config.Provision {
 		if p.File != nil {
-			locator, err := absPath(*p.File, basePath)
+			locator, err := absPath(p.File.URL, basePath)
 			if err != nil {
 				return err
 			}
@@ -63,7 +63,7 @@ func (tmpl *Template) useAbsLocators() error {
 // On Windows filepath.Abs() only returns a "rooted" name, but does not add the volume name.
 // withVolume also normalizes all path separators to the platform native one.
 func withVolume(path string) (string, error) {
-	if runtime.GOOS == "windows" && len(filepath.VolumeName(path)) == 0 {
+	if runtime.GOOS == "windows" && filepath.VolumeName(path) == "" {
 		root, err := filepath.Abs("/")
 		if err != nil {
 			return "", err
diff --git a/pkg/limatmpl/abs_test.go b/pkg/limatmpl/abs_test.go
@@ -225,7 +225,7 @@ func TestAbsPath(t *testing.T) {
 			assert.ErrorContains(t, err, "volume")
 		})
 	}
-	
+
 	t.Run("", func(t *testing.T) {
 		actual, err := absPath("foo", "template://")
 		assert.NilError(t, err)
diff --git a/pkg/limatmpl/embed.go b/pkg/limatmpl/embed.go
@@ -9,6 +9,7 @@ import (
 	"sync"
 
 	"github.com/coreos/go-semver/semver"
+	"github.com/lima-vm/lima/pkg/limayaml"
 	"github.com/lima-vm/lima/pkg/store/dirnames"
 	"github.com/lima-vm/lima/pkg/store/filenames"
 	"github.com/lima-vm/lima/pkg/version/versionutil"
@@ -19,6 +20,7 @@ import (
 var warnBaseIsExperimental = sync.OnceFunc(func() {
 	logrus.Warn("`base` is experimental")
 })
+
 var warnFileIsExperimental = sync.OnceFunc(func() {
 	logrus.Warn("`provision[*].file` and `probes[*].file` are experimental")
 })
@@ -69,23 +71,23 @@ func (tmpl *Template) embedAllBases(ctx context.Context, embedAll, defaultBase b
 			break
 		}
 		baseLocator := tmpl.Config.Base[0]
-		isTemplate, _ := SeemsTemplateURL(baseLocator)
+		isTemplate, _ := SeemsTemplateURL(baseLocator.URL)
 		if isTemplate && !embedAll {
 			// Once we skip a template:// URL we can no longer embed any other base template
 			for i := 1; i < len(tmpl.Config.Base); i++ {
-				isTemplate, _ = SeemsTemplateURL(tmpl.Config.Base[i])
+				isTemplate, _ = SeemsTemplateURL(tmpl.Config.Base[i].URL)
 				if !isTemplate {
-					return fmt.Errorf("cannot embed template %q after not embedding %q", tmpl.Config.Base[i], baseLocator)
+					return fmt.Errorf("cannot embed template %q after not embedding %q", tmpl.Config.Base[i].URL, baseLocator.URL)
 				}
 			}
 			break
 			// TODO should we track embedding of template:// URLs so we can warn if we embed a non-template:// URL afterwards?
 		}
 
-		if seen[baseLocator] {
-			return fmt.Errorf("base template loop detected: template %q already included", baseLocator)
+		if seen[baseLocator.URL] {
+			return fmt.Errorf("base template loop detected: template %q already included", baseLocator.URL)
 		}
-		seen[baseLocator] = true
+		seen[baseLocator.URL] = true
 
 		// remove base[0] from template before merging
 		if err := tmpl.embedBase(ctx, baseLocator, embedAll, seen); err != nil {
@@ -101,13 +103,13 @@ func (tmpl *Template) embedAllBases(ctx context.Context, embedAll, defaultBase b
 	return nil
 }
 
-func (tmpl *Template) embedBase(ctx context.Context, baseLocator string, embedAll bool, seen map[string]bool) error {
+func (tmpl *Template) embedBase(ctx context.Context, baseLocator limayaml.LocatorWithDigest, embedAll bool, seen map[string]bool) error {
 	warnBaseIsExperimental()
-	logrus.Debugf("Embedding base %q in template %q", baseLocator, tmpl.Locator)
+	logrus.Debugf("Embedding base %q in template %q", baseLocator.URL, tmpl.Locator)
 	if err := tmpl.Unmarshal(); err != nil {
 		return err
 	}
-	base, err := Read(ctx, "", baseLocator)
+	base, err := Read(ctx, "", baseLocator.URL)
 	if err != nil {
 		return err
 	}
@@ -308,7 +310,7 @@ func (tmpl *Template) deleteListEntry(list string, idx int) {
 	tmpl.expr.WriteString(fmt.Sprintf("| del($a.%s[%d], $b.%s[%d])\n", list, idx, list, idx))
 }
 
-// upgradeListEntryStringToMapField turns list[idx] from a string to a {field: list[idx]} map
+// upgradeListEntryStringToMapField turns list[idx] from a string to a {field: list[idx]} map.
 func (tmpl *Template) upgradeListEntryStringToMapField(list string, idx int, field string) {
 	// TODO the head_comment on the string becomes duplicated as a foot_comment on the new field; could be a yq bug?
 	tmpl.expr.WriteString(fmt.Sprintf("| ($a.%s[%d] | select(type == \"!!str\")) |= {\"%s\": .}\n", list, idx, field))
@@ -557,9 +559,9 @@ func (tmpl *Template) embedAllScripts(ctx context.Context, embedAll bool) error
 		// Don't overwrite existing script. This should throw an error during validation.
 		if p.File != nil && p.Script == "" {
 			warnFileIsExperimental()
-			isTemplate, _ := SeemsTemplateURL(*p.File)
+			isTemplate, _ := SeemsTemplateURL(p.File.URL)
 			if embedAll || !isTemplate {
-				scriptTmpl, err := Read(ctx, "", *p.File)
+				scriptTmpl, err := Read(ctx, "", p.File.URL)
 				if err != nil {
 					return err
 				}
@@ -570,9 +572,9 @@ func (tmpl *Template) embedAllScripts(ctx context.Context, embedAll bool) error
 	for i, p := range tmpl.Config.Provision {
 		if p.File != nil && p.Script == "" {
 			warnFileIsExperimental()
-			isTemplate, _ := SeemsTemplateURL(*p.File)
+			isTemplate, _ := SeemsTemplateURL(p.File.URL)
 			if embedAll || !isTemplate {
-				scriptTmpl, err := Read(ctx, "", *p.File)
+				scriptTmpl, err := Read(ctx, "", p.File.URL)
 				if err != nil {
 					return err
 				}
diff --git a/pkg/limatmpl/embed_test.go b/pkg/limatmpl/embed_test.go
@@ -3,14 +3,14 @@ package limatmpl_test
 import (
 	"context"
 	"fmt"
-	"github.com/sirupsen/logrus"
 	"os"
 	"reflect"
 	"strings"
 	"testing"
 
 	"github.com/lima-vm/lima/pkg/limatmpl"
 	"github.com/lima-vm/lima/pkg/limayaml"
+	"github.com/sirupsen/logrus"
 	"gotest.tools/v3/assert"
 	"gotest.tools/v3/assert/cmp"
 )
@@ -179,13 +179,16 @@ mounts:
 	},
 	{
 		"template:// URLs are not embedded when embedAll is false",
+		// also tests file.url format
 		``,
 		`
 base: template://default
 provision:
-- file: template://provision.sh
+- file:
+    url: template://provision.sh
 probes:
-- file: template://probe.sh
+- file:
+    url: template://probe.sh
 `,
 		`
 base: template://default
@@ -228,7 +231,7 @@ base: baseX.yaml`,
 		"Bases are embedded depth-first",
 		`#`,
 		`
-base: [base1.yaml, base2.yaml]
+base: [base1.yaml, {url: base2.yaml}] # also test file.url format
 additionalDisks: [disk0]
 ---
 base: base3.yaml
diff --git a/pkg/limatmpl/locator.go b/pkg/limatmpl/locator.go
@@ -72,7 +72,7 @@ func Read(ctx context.Context, name, locator string) (*Template, error) {
 				return nil, err
 			}
 		}
-		logrus.Debugf("interpreting argument %q as a file url for instance %q", locator, tmpl.Name)
+		logrus.Debugf("interpreting argument %q as a file URL for instance %q", locator, tmpl.Name)
 		filePath := strings.TrimPrefix(locator, "file://")
 		if !filepath.IsAbs(filePath) {
 			return nil, fmt.Errorf("file URL %q is not an absolute path", locator)
diff --git a/pkg/limayaml/limayaml.go b/pkg/limayaml/limayaml.go
@@ -51,7 +51,12 @@ type LimaYAML struct {
 	User                 User           `yaml:"user,omitempty" json:"user,omitempty"`
 }
 
-type BaseTemplates []string
+type BaseTemplates []LocatorWithDigest
+
+type LocatorWithDigest struct {
+	URL    string  `yaml:"url" json:"url"`
+	Digest *string `yaml:"digest,omitempty" json:"digest,omitempty" jsonschema:"nullable"` // TODO currently unused
+}
 
 type (
 	OS        = string
@@ -216,11 +221,11 @@ const (
 )
 
 type Provision struct {
-	Mode                            ProvisionMode `yaml:"mode,omitempty" json:"mode,omitempty" jsonschema:"default=system"`
-	SkipDefaultDependencyResolution *bool         `yaml:"skipDefaultDependencyResolution,omitempty" json:"skipDefaultDependencyResolution,omitempty"`
-	Script                          string        `yaml:"script" json:"script"`
-	File                            *string       `yaml:"file,omitempty" json:"file,omitempty" jsonschema:"nullable"`
-	Playbook                        string        `yaml:"playbook,omitempty" json:"playbook,omitempty"`
+	Mode                            ProvisionMode      `yaml:"mode,omitempty" json:"mode,omitempty" jsonschema:"default=system"`
+	SkipDefaultDependencyResolution *bool              `yaml:"skipDefaultDependencyResolution,omitempty" json:"skipDefaultDependencyResolution,omitempty"`
+	Script                          string             `yaml:"script" json:"script"`
+	File                            *LocatorWithDigest `yaml:"file,omitempty" json:"file,omitempty" jsonschema:"nullable"`
+	Playbook                        string             `yaml:"playbook,omitempty" json:"playbook,omitempty"`
 }
 
 type Containerd struct {
@@ -236,11 +241,11 @@ const (
 )
 
 type Probe struct {
-	Mode        ProbeMode `yaml:"mode,omitempty" json:"mode,omitempty" jsonschema:"default=readiness"`
-	Description string    `yaml:"description,omitempty" json:"description,omitempty"`
-	Script      string    `yaml:"script,omitempty" json:"script,omitempty"`
-	File        *string   `yaml:"file,omitempty" json:"file,omitempty" jsonschema:"nullable"`
-	Hint        string    `yaml:"hint,omitempty" json:"hint,omitempty"`
+	Mode        ProbeMode          `yaml:"mode,omitempty" json:"mode,omitempty" jsonschema:"default=readiness"`
+	Description string             `yaml:"description,omitempty" json:"description,omitempty"`
+	Script      string             `yaml:"script,omitempty" json:"script,omitempty"`
+	File        *LocatorWithDigest `yaml:"file,omitempty" json:"file,omitempty" jsonschema:"nullable"`
+	Hint        string             `yaml:"hint,omitempty" json:"hint,omitempty"`
 }
 
 type Proto = string
diff --git a/pkg/limayaml/marshal.go b/pkg/limayaml/marshal.go
@@ -35,11 +35,21 @@ func unmarshalDisk(dst *Disk, b []byte) error {
 	return yaml.Unmarshal(b, dst)
 }
 
-// unmarshalBaseTemplates unmarshalls `base` which is either a string or a list of strings.
+// unmarshalBaseTemplates unmarshalls `base` which is either a string or a list of Locators.
 func unmarshalBaseTemplates(dst *BaseTemplates, b []byte) error {
 	var s string
 	if err := yaml.Unmarshal(b, &s); err == nil {
-		*dst = BaseTemplates{s}
+		*dst = BaseTemplates{LocatorWithDigest{URL: s}}
+		return nil
+	}
+	return yaml.UnmarshalWithOptions(b, dst, yaml.CustomUnmarshaler[LocatorWithDigest](unmarshalLocatorWithDigest))
+}
+
+// unmarshalLocator unmarshalls a locator which is either a string or a Locator struct.
+func unmarshalLocatorWithDigest(dst *LocatorWithDigest, b []byte) error {
+	var s string
+	if err := yaml.Unmarshal(b, &s); err == nil {
+		*dst = LocatorWithDigest{URL: s}
 		return nil
 	}
 	return yaml.Unmarshal(b, dst)
@@ -49,6 +59,7 @@ func Unmarshal(data []byte, v any, comment string) error {
 	opts := []yaml.DecodeOption{
 		yaml.CustomUnmarshaler[BaseTemplates](unmarshalBaseTemplates),
 		yaml.CustomUnmarshaler[Disk](unmarshalDisk),
+		yaml.CustomUnmarshaler[LocatorWithDigest](unmarshalLocatorWithDigest),
 	}
 	if err := yaml.UnmarshalWithOptions(data, v, opts...); err != nil {
 		return fmt.Errorf("failed to unmarshal YAML (%s): %w", comment, err)
diff --git a/pkg/limayaml/validate.go b/pkg/limayaml/validate.go
@@ -206,8 +206,8 @@ func Validate(y *LimaYAML, warn bool) error {
 	// y.Firmware.LegacyBIOS is ignored for aarch64, but not a fatal error.
 
 	for i, p := range y.Provision {
-		if p.File != nil && *p.File != "" {
-			return fmt.Errorf("field `provision[%d].file` must be empty during validation (script should already be embedded)", i)
+		if p.File != nil && p.File.URL != "" {
+			return fmt.Errorf("field `provision[%d].file.url` must be empty during validation (script should already be embedded)", i)
 		}
 		switch p.Mode {
 		case ProvisionModeSystem, ProvisionModeUser, ProvisionModeBoot:
@@ -249,8 +249,8 @@ func Validate(y *LimaYAML, warn bool) error {
 		}
 	}
 	for i, p := range y.Probes {
-		if p.File != nil && *p.File != "" {
-			return fmt.Errorf("field `probes[%d].file` must be empty during validation (script should already be embedded)", i)
+		if p.File != nil && p.File.URL != "" {
+			return fmt.Errorf("field `probes[%d].file.url` must be empty during validation (script should already be embedded)", i)
 		}
 		if !strings.HasPrefix(p.Script, "#!") {
 			return fmt.Errorf("field `probe[%d].script` must start with a '#!' line", i)
diff --git a/templates/default.yaml b/templates/default.yaml
@@ -214,6 +214,8 @@ containerd:
 #
 # EXPERIMENTAL Alternatively the script can be provided using the "file" property. This file is read when the instance
 # is created and then stored under the "script" property. When "file" is specified "script" must be empty.
+# The "file" property can either be a string (URL), or an object with a "url" and "digest" properties.
+# The "digest" property is currently unused.
 # Relative script files will be resolved relative to the location of the template file.
 # 🟢 Builtin default: []
 # provision:
@@ -226,7 +228,9 @@ containerd:
 #     apt-get install -y vim
 # # `user` is executed without root privileges
 # - mode: user
-#   file: user-provisioning.sh
+#   file:
+#     url: user-provisioning.sh
+#     digest: deadbeef
 # # `boot` is executed directly by /bin/sh as part of cloud-init-local.service's early boot process,
 # # which is why there is no hash-bang specified in the example
 # # See cloud-init docs for more info https://docs.cloud-init.io/en/latest/reference/examples.html#run-commands-on-first-boot
@@ -255,6 +259,8 @@ containerd:
 # The scripts can use the following template variables: {{.Home}}, {{.Name}}, {{.Hostname}}, {{.UID}}, {{.User}}, and {{.Param.Key}}.
 # EXPERIMENTAL Alternatively the script can be provided using the "file" property. This file is read when the instance
 # is created and then stored under the "script" property. When "file" is specified "script" must be empty.
+# The "file" property can either be a string (URL), or an object with a "url" and "digest" properties.
+# The "digest" property is currently unused.
 # Relative script files will be resolved relative to the location of the template file.
 # 🟢 Builtin default: []
 # probes:
@@ -284,7 +290,10 @@ minimumLimaVersion: null
 # EXPERIMENTAL
 # Default settings can be imported from base templates. These will be merged in when the instance
 # is created, and the combined template is stored in the instance directory.
-# This setting ca be either a single string, or a list of strings.
+# This setting ca be either a single string (URL), or a list of locators.
+# A locator is again either a string (URL), or an object with "url" and "digest" properties, e.g.
+# base: [{url: ./base.yaml, digest: decafbad}, …]
+# The "digest" property is currently unused.
 # Any relative base template name will be resolved relative to the location of the main template.
 # 🟢 Builtin default: no base template
 base: null

Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ func (tmpl *Template) useAbsLocators() error {`
`26`	`26`	`return err`
`27`	`27`	`}`
`28`	`28`	`for i, baseLocator := range tmpl.Config.Base {`
`29`		`- locator, err := absPath(baseLocator, basePath)`
	`29`	`+ locator, err := absPath(baseLocator.URL, basePath)`
`30`	`30`	`if err != nil {`
`31`	`31`	`return err`
`32`	`32`	`}`
`@@ -40,7 +40,7 @@ func (tmpl *Template) useAbsLocators() error {`
`40`	`40`	`}`
`41`	`41`	`for i, p := range tmpl.Config.Probes {`
`42`	`42`	`if p.File != nil {`
`43`		`- locator, err := absPath(*p.File, basePath)`
	`43`	`+ locator, err := absPath(p.File.URL, basePath)`
`44`	`44`	`if err != nil {`
`45`	`45`	`return err`
`46`	`46`	`}`
`@@ -49,7 +49,7 @@ func (tmpl *Template) useAbsLocators() error {`
`49`	`49`	`}`
`50`	`50`	`for i, p := range tmpl.Config.Provision {`
`51`	`51`	`if p.File != nil {`
`52`		`- locator, err := absPath(*p.File, basePath)`
	`52`	`+ locator, err := absPath(p.File.URL, basePath)`
`53`	`53`	`if err != nil {`
`54`	`54`	`return err`
`55`	`55`	`}`
`@@ -63,7 +63,7 @@ func (tmpl *Template) useAbsLocators() error {`
`63`	`63`	`// On Windows filepath.Abs() only returns a "rooted" name, but does not add the volume name.`
`64`	`64`	`// withVolume also normalizes all path separators to the platform native one.`
`65`	`65`	`func withVolume(path string) (string, error) {`
`66`		`- if runtime.GOOS == "windows" && len(filepath.VolumeName(path)) == 0 {`
	`66`	`+ if runtime.GOOS == "windows" && filepath.VolumeName(path) == "" {`
`67`	`67`	`root, err := filepath.Abs("/")`
`68`	`68`	`if err != nil {`
`69`	`69`	`return "", err`
Original file line number	Diff line number	Diff line change
`@@ -225,7 +225,7 @@ func TestAbsPath(t *testing.T) {`
`225`	`225`	`assert.ErrorContains(t, err, "volume")`
`226`	`226`	`})`
`227`	`227`	`}`
`228`		`-`
	`228`	`+`
`229`	`229`	`t.Run("", func(t *testing.T) {`
`230`	`230`	`actual, err := absPath("foo", "template://")`
`231`	`231`	`assert.NilError(t, err)`
Original file line number	Diff line number	Diff line change
`@@ -72,7 +72,7 @@ func Read(ctx context.Context, name, locator string) (*Template, error) {`
`72`	`72`	`return nil, err`
`73`	`73`	`}`
`74`	`74`	`}`
`75`		`- logrus.Debugf("interpreting argument %q as a file url for instance %q", locator, tmpl.Name)`
	`75`	`+ logrus.Debugf("interpreting argument %q as a file URL for instance %q", locator, tmpl.Name)`
`76`	`76`	`filePath := strings.TrimPrefix(locator, "file://")`
`77`	`77`	`if !filepath.IsAbs(filePath) {`
`78`	`78`	`return nil, fmt.Errorf("file URL %q is not an absolute path", locator)`
Original file line number	Diff line number	Diff line change
`@@ -206,8 +206,8 @@ func Validate(y *LimaYAML, warn bool) error {`
`206`	`206`	`// y.Firmware.LegacyBIOS is ignored for aarch64, but not a fatal error.`
`207`	`207`
`208`	`208`	`for i, p := range y.Provision {`
`209`		`- if p.File != nil && *p.File != "" {`
`210`		- return fmt.Errorf("field `provision[%d].file` must be empty during validation (script should already be embedded)", i)
	`209`	`+ if p.File != nil && p.File.URL != "" {`
	`210`	+ return fmt.Errorf("field `provision[%d].file.url` must be empty during validation (script should already be embedded)", i)
`211`	`211`	`}`
`212`	`212`	`switch p.Mode {`
`213`	`213`	`case ProvisionModeSystem, ProvisionModeUser, ProvisionModeBoot:`
`@@ -249,8 +249,8 @@ func Validate(y *LimaYAML, warn bool) error {`
`249`	`249`	`}`
`250`	`250`	`}`
`251`	`251`	`for i, p := range y.Probes {`
`252`		`- if p.File != nil && *p.File != "" {`
`253`		- return fmt.Errorf("field `probes[%d].file` must be empty during validation (script should already be embedded)", i)
	`252`	`+ if p.File != nil && p.File.URL != "" {`
	`253`	+ return fmt.Errorf("field `probes[%d].file.url` must be empty during validation (script should already be embedded)", i)
`254`	`254`	`}`
`255`	`255`	`if !strings.HasPrefix(p.Script, "#!") {`
`256`	`256`	return fmt.Errorf("field `probe[%d].script` must start with a '#!' line", i)