Switch to RFC compliant opaque template:name URLs

jandubois · jandubois · commit e46309ee5f7f · 2025-09-28T23:24:13.000-07:00
The old style template://name URLs are malformed because they do not
contain a valid AUTHORITY (host name), but treat the host name as part
of the path. They are still fully supported, but will emit a warning.

Signed-off-by: Jan Dubois &lt;jan.dubois@suse.com&gt;
diff --git a/README.md b/README.md
@@ -39,14 +39,14 @@ lima nerdctl run --rm hello-world
 
 To run containers with Docker:
 ```bash
-limactl start template://docker
+limactl start template:docker
 export DOCKER_HOST=$(limactl list docker --format 'unix://{{.Dir}}/sock/docker.sock')
 docker run --rm hello-world
 ```
 
 To run containers with Kubernetes:
 ```bash
-limactl start template://k8s
+limactl start template:k8s
 export KUBECONFIG=$(limactl list k8s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
 kubectl apply -f ...
 ```
diff --git a/cmd/apptainer.lima b/cmd/apptainer.lima
@@ -4,7 +4,7 @@ set -eu
 : "${APPTAINER_BINDPATH:=}"
 
 if [ "$(limactl ls -q "$LIMA_INSTANCE" 2>/dev/null)" != "$LIMA_INSTANCE" ]; then
-  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE template://apptainer\` to create a new instance" >&2
+  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE template:apptainer\` to create a new instance" >&2
   exit 1
 elif [ "$(limactl ls -f '{{ .Status }}' "$LIMA_INSTANCE" 2>/dev/null)" != "Running" ]; then
   echo "instance \"$LIMA_INSTANCE\" is not running, run \`limactl start $LIMA_INSTANCE\` to start the existing instance" >&2
diff --git a/cmd/docker.lima b/cmd/docker.lima
@@ -8,7 +8,7 @@ set -eu
 : "${DOCKER:=docker}"
 
 if [ "$(limactl ls -q "$LIMA_INSTANCE" 2>/dev/null)" != "$LIMA_INSTANCE" ]; then
-  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE template://docker\` to create a new instance" >&2
+  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE template:docker\` to create a new instance" >&2
   exit 1
 elif [ "$(limactl ls -f '{{ .Status }}' "$LIMA_INSTANCE" 2>/dev/null)" != "Running" ]; then
   echo "instance \"$LIMA_INSTANCE\" is not running, run \`limactl start $LIMA_INSTANCE\` to start the existing instance" >&2
diff --git a/cmd/kubectl.lima b/cmd/kubectl.lima
@@ -14,8 +14,8 @@ if [ -z "$LIMA_INSTANCE" ]; then
     LIMA_INSTANCE=k8s
   else
     echo "No k3s or k8s existing instances found. Either create one with" >&2
-    echo "limactl create --name=k3s template://k3s" >&2
-    echo "limactl create --name=k8s template://k8s" >&2
+    echo "limactl create --name=k3s template:k3s" >&2
+    echo "limactl create --name=k8s template:k8s" >&2
     echo "or set LIMA_INSTANCE to the name of your Kubernetes instance" >&2
     exit 1
   fi
diff --git a/cmd/limactl/completion.go b/cmd/limactl/completion.go
@@ -28,7 +28,7 @@ func bashCompleteTemplateNames(_ *cobra.Command, toComplete string) ([]string, c
 	var comp []string
 	if templates, err := templatestore.Templates(); err == nil {
 		for _, f := range templates {
-			name := "template://" + f.Name
+			name := "template:" + f.Name
 			if !strings.HasPrefix(name, toComplete) {
 				continue
 			}
diff --git a/cmd/limactl/start.go b/cmd/limactl/start.go
@@ -49,7 +49,7 @@ func newCreateCommand() *cobra.Command {
   $ limactl create
 
   To create an instance "default" from a template "docker":
-  $ limactl create --name=default template://docker
+  $ limactl create --name=default template:docker
 
   To create an instance "default" with modified parameters:
   $ limactl create --cpus=2 --memory=2
@@ -87,7 +87,7 @@ func newStartCommand() *cobra.Command {
   $ limactl start
 
   To create an instance "default" from a template "docker", and start it:
-  $ limactl start --name=default template://docker
+  $ limactl start --name=default template:docker
 `,
 		Short:             "Start an instance of Lima",
 		Args:              WrapArgsError(cobra.MaximumNArgs(1)),
@@ -234,19 +234,19 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*
 	if isTemplateURL, templateName := limatmpl.SeemsTemplateURL(arg); isTemplateURL {
 		switch templateName {
 		case "experimental/vz":
-			logrus.Warn("template://experimental/vz was merged into the default template in Lima v1.0. See also <https://lima-vm.io/docs/config/vmtype/>.")
+			logrus.Warn("template:experimental/vz was merged into the default template in Lima v1.0. See also <https://lima-vm.io/docs/config/vmtype/>.")
 		case "experimental/riscv64":
-			logrus.Warn("template://experimental/riscv64 was merged into the default template in Lima v1.0. Use `limactl create --arch=riscv64 template://default` instead.")
+			logrus.Warn("template:experimental/riscv64 was merged into the default template in Lima v1.0. Use `limactl create --arch=riscv64 template:default` instead.")
 		case "experimental/armv7l":
-			logrus.Warn("template://experimental/armv7l was merged into the default template in Lima v1.0. Use `limactl create --arch=armv7l template://default` instead.")
+			logrus.Warn("template:experimental/armv7l was merged into the default template in Lima v1.0. Use `limactl create --arch=armv7l template:default` instead.")
 		case "vmnet":
-			logrus.Warn("template://vmnet was removed in Lima v1.0. Use `limactl create --network=lima:shared template://default` instead. See also <https://lima-vm.io/docs/config/network/>.")
+			logrus.Warn("template:vmnet was removed in Lima v1.0. Use `limactl create --network=lima:shared template:default` instead. See also <https://lima-vm.io/docs/config/network/>.")
 		case "experimental/net-user-v2":
-			logrus.Warn("template://experimental/net-user-v2 was removed in Lima v1.0. Use `limactl create --network=lima:user-v2 template://default` instead. See also <https://lima-vm.io/docs/config/network/>.")
+			logrus.Warn("template:experimental/net-user-v2 was removed in Lima v1.0. Use `limactl create --network=lima:user-v2 template:default` instead. See also <https://lima-vm.io/docs/config/network/>.")
 		case "experimental/9p":
-			logrus.Warn("template://experimental/9p was removed in Lima v1.0. Use `limactl create --vm-type=qemu --mount-type=9p template://default` instead. See also <https://lima-vm.io/docs/config/mount/>.")
+			logrus.Warn("template:experimental/9p was removed in Lima v1.0. Use `limactl create --vm-type=qemu --mount-type=9p template:default` instead. See also <https://lima-vm.io/docs/config/mount/>.")
 		case "experimental/virtiofs-linux":
-			logrus.Warn("template://experimental/virtiofs-linux was removed in Lima v1.0. Use `limactl create --mount-type=virtiofs template://default` instead. See also <https://lima-vm.io/docs/config/mount/>.")
+			logrus.Warn("template:experimental/virtiofs-linux was removed in Lima v1.0. Use `limactl create --mount-type=virtiofs template:default` instead. See also <https://lima-vm.io/docs/config/mount/>.")
 		}
 	}
 	if arg == "-" {
@@ -298,8 +298,8 @@ func loadOrCreateInstance(cmd *cobra.Command, args []string, createOnly bool) (*
 			return nil, err
 		}
 		if arg != "" && arg != DefaultInstanceName {
-			logrus.Infof("Creating an instance %q from template://default (Not from template://%s)", tmpl.Name, tmpl.Name)
-			logrus.Warnf("This form is deprecated. Use `limactl create --name=%s template://default` instead", tmpl.Name)
+			logrus.Infof("Creating an instance %q from template:default (Not from template:%s)", tmpl.Name, tmpl.Name)
+			logrus.Warnf("This form is deprecated. Use `limactl create --name=%s template:default` instead", tmpl.Name)
 		}
 		// Read the default template for creating a new instance
 		tmpl.Bytes, err = templatestore.Read(templatestore.Default)
diff --git a/cmd/limactl/template.go b/cmd/limactl/template.go
@@ -52,13 +52,13 @@ func newValidateCommand() *cobra.Command {
 	return validateCommand
 }
 
-var templateCopyExample = `  Template locators are local files, file://, https://, or template:// URLs
+var templateCopyExample = `  Template locators are local files, file://, https://, or template: URLs
 
   # Copy default template to STDOUT
-  limactl template copy template://default -
+  limactl template copy template:default -
 
   # Copy template from web location to local file and embed all external references
-  # (this does not embed template:// references)
+  # (this does not embed template: references)
   limactl template copy --embed https://example.com/lima.yaml mighty-machine.yaml
 `
 
@@ -177,10 +177,10 @@ External references are embedded and default values are filled in
 before the YQ expression is evaluated.
 
 Example:
-  limactl template yq template://default '.images[].location'
+  limactl template yq template:default '.images[].location'
 
 The example command is equivalent to using an external yq command like this:
-  limactl template copy --fill template://default - | yq '.images[].location'
+  limactl template copy --fill template:default - | yq '.images[].location'
 `
 
 func newTemplateYQCommand() *cobra.Command {
diff --git a/cmd/podman.lima b/cmd/podman.lima
@@ -4,7 +4,7 @@ set -eu
 : "${PODMAN:=podman}"
 
 if [ "$(limactl ls -q "$LIMA_INSTANCE" 2>/dev/null)" != "$LIMA_INSTANCE" ]; then
-  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE template://podman\` to create a new instance" >&2
+  echo "instance \"$LIMA_INSTANCE\" does not exist, run \`limactl create --name=$LIMA_INSTANCE template:podman\` to create a new instance" >&2
   exit 1
 elif [ "$(limactl ls -f '{{ .Status }}' "$LIMA_INSTANCE" 2>/dev/null)" != "Running" ]; then
   echo "instance \"$LIMA_INSTANCE\" is not running, run \`limactl start $LIMA_INSTANCE\` to start the existing instance" >&2
diff --git a/hack/bats/tests/preserve-env.bats b/hack/bats/tests/preserve-env.bats
@@ -17,7 +17,7 @@ local_setup_file() {
     limactl delete --force "$NAME" || :
     # Make sure that the host agent doesn't inherit file handles 3 or 4.
     # Otherwise bats will not finish until the host agent exits.
-    limactl start --yes --name "$NAME" template://default 3>&- 4>&-
+    limactl start --yes --name "$NAME" template:default 3>&- 4>&-
 }
 
 local_teardown_file() {
diff --git a/hack/common.inc.sh b/hack/common.inc.sh
@@ -31,7 +31,7 @@ _IPERF3=iperf3
 : "${IPERF3:=$_IPERF3}"
 
 # Setup LIMA_TEMPLATES_PATH because the templates are not installed, but reference base templates
-# via template://_images/* and template://_default/*.
+# via template:_images/* and template:_default/*.
 templates_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../templates" && pwd)"
 : "${LIMA_TEMPLATES_PATH:-$templates_dir}"
 export LIMA_TEMPLATES_PATH
diff --git a/hack/test-templates/test-misc.yaml b/hack/test-templates/test-misc.yaml
@@ -3,7 +3,7 @@
 # - snapshots
 # - (More to come)
 #
-base: template://ubuntu-22.04
+base: template:ubuntu-22.04
 
 # 9p is not compatible with `limactl snapshot`
 mountTypesUnsupported: ["9p"]
diff --git a/hack/test-upgrade.sh b/hack/test-upgrade.sh
@@ -68,7 +68,7 @@ export LIMA_INSTANCE="test-upgrade"
 
 INFO "Creating an instance \"${LIMA_INSTANCE}\" with the old Lima"
 defer "show_lima_log;limactl delete -f \"${LIMA_INSTANCE}\""
-limactl start --tty=false --name="${LIMA_INSTANCE}" template://ubuntu-lts || (
+limactl start --tty=false --name="${LIMA_INSTANCE}" template:ubuntu-lts || (
 	show_lima_log
 	exit 1
 )
diff --git a/pkg/limainfo/limainfo.go b/pkg/limainfo/limainfo.go
@@ -48,7 +48,7 @@ type GuestAgent struct {
 }
 
 // New returns a LimaInfo object with the Lima version, a list of all Templates and their location,
-// the DefaultTemplate corresponding to template://default with all defaults filled in, the
+// the DefaultTemplate corresponding to template:default with all defaults filled in, the
 // LimaHome location, a list of all supported VMTypes, and a map of GuestAgents for each architecture.
 func New(ctx context.Context) (*LimaInfo, error) {
 	b, err := templatestore.Read(templatestore.Default)
diff --git a/pkg/limatmpl/abs.go b/pkg/limatmpl/abs.go
@@ -89,6 +89,9 @@ func basePath(locator string) (string, error) {
 	// Single-letter schemes will be drive names on Windows, e.g. "c:/foo"
 	if err == nil && len(u.Scheme) > 1 {
 		// path.Dir("") returns ".", which must be removed for url.JoinPath() to do the right thing later
+		if u.Opaque != "" {
+			return u.Scheme + ":" + strings.TrimSuffix(path.Dir(u.Opaque), "."), nil
+		}
 		return u.Scheme + "://" + strings.TrimSuffix(path.Dir(path.Join(u.Host, u.Path)), "."), nil
 	}
 	base, err := filepath.Abs(filepath.Dir(locator))
@@ -132,6 +135,10 @@ func absPath(locator, basePath string) (string, error) {
 			return "", err
 		}
 		if len(u.Scheme) > 1 {
+			// Treat empty "template:" URL as opaque
+			if u.Opaque != "" || (u.Scheme == "template" && u.Host == "") {
+				return u.Scheme + ":" + path.Join(u.Opaque, locator), nil
+			}
 			return u.JoinPath(locator).String(), nil
 		}
 		locator = filepath.Join(basePath, locator)
diff --git a/pkg/limatmpl/abs_test.go b/pkg/limatmpl/abs_test.go
@@ -23,67 +23,73 @@ type useAbsLocatorsTestCase struct {
 var useAbsLocatorsTestCases = []useAbsLocatorsTestCase{
 	{
 		"Template without base or script file",
-		"template://foo",
+		"template:foo",
 		`arch: aarch64`,
 		`arch: aarch64`,
 	},
 	{
 		"Single string base template",
+		"template:foo",
+		`base: bar.yaml`,
+		`base: template:bar.yaml`,
+	},
+	{
+		"Legacy template:// base template",
 		"template://foo",
 		`base: bar.yaml`,
-		`base: template://bar.yaml`,
+		`base: template:bar.yaml`,
 	},
 	{
 		"Flow style array of one base template",
-		"template://foo",
+		"template:foo",
 		`base: [{url: bar.yaml, digest: deadbeef}]`,
 		// not sure why the quotes around the URL were added; maybe because we don't copy the style from the source
-		`base: [{url: 'template://bar.yaml', digest: deadbeef}]`,
+		`base: [{url: 'template:bar.yaml', digest: deadbeef}]`,
 	},
 	{
 		"Flow style array of sequence of two base URLs",
-		"template://foo",
+		"template:foo",
 		`base: [bar.yaml, baz.yaml]`,
-		`base: ['template://bar.yaml', 'template://baz.yaml']`,
+		`base: ['template:bar.yaml', 'template:baz.yaml']`,
 	},
 	{
 		"Flow style array of sequence of two base locator objects",
-		"template://foo",
+		"template:foo",
 		`base: [{url: bar.yaml, digest: deadbeef}, {url: baz.yaml, digest: decafbad}]`,
-		`base: [{url: 'template://bar.yaml', digest: deadbeef}, {url: 'template://baz.yaml', digest: decafbad}]`,
+		`base: [{url: 'template:bar.yaml', digest: deadbeef}, {url: 'template:baz.yaml', digest: decafbad}]`,
 	},
 	{
 		"Block style array of one base template",
-		"template://foo",
+		"template:foo",
 		`
 base:
 - bar.yaml
 `,
 		`
 base:
-- template://bar.yaml`,
+- template:bar.yaml`,
 	},
 	{
 		"Block style of four base templates",
-		"template://foo",
+		"template:foo",
 		`
 base:
 - bar.yaml
-- template://my
+- template:my
 - https://example.com/my.yaml
 - baz.yaml
 `,
 		`
 base:
-- template://bar.yaml
-- template://my
+- template:bar.yaml
+- template:my
 - https://example.com/my.yaml
-- template://baz.yaml
+- template:baz.yaml
 `,
 	},
 	{
 		"Provisioning and probe scripts",
-		"template://experimental/foo",
+		"template:experimental/foo",
 		`
 provision:
 - mode: user
@@ -101,15 +107,15 @@ probes:
 		`
 provision:
 - mode: user
-  file: template://experimental/userscript.sh
+  file: template:experimental/userscript.sh
 - mode: system
   file:
-    url: template://experimental/systemscript.sh
+    url: template:experimental/systemscript.sh
     digest: abc123
 probes:
-- file: template://experimental/probe.sh
+- file: template:experimental/probe.sh
 - file:
-    url: template://experimental/probe.sh
+    url: template:experimental/probe.sh
     digest: digest
 `,
 	},
@@ -153,15 +159,15 @@ func TestBasePath(t *testing.T) {
 	})
 
 	t.Run("", func(t *testing.T) {
-		actual, err := basePath("template://foo")
+		actual, err := basePath("template:foo")
 		assert.NilError(t, err)
-		assert.Equal(t, actual, "template://")
+		assert.Equal(t, actual, "template:")
 	})
 
 	t.Run("", func(t *testing.T) {
-		actual, err := basePath("template://foo/bar")
+		actual, err := basePath("template:foo/bar")
 		assert.NilError(t, err)
-		assert.Equal(t, actual, "template://foo")
+		assert.Equal(t, actual, "template:foo")
 	})
 
 	t.Run("", func(t *testing.T) {
@@ -216,9 +222,9 @@ func TestAbsPath(t *testing.T) {
 	})
 
 	t.Run("", func(t *testing.T) {
-		actual, err := absPath("template://foo", volume+"/root")
+		actual, err := absPath("template:foo", volume+"/root")
 		assert.NilError(t, err)
-		assert.Equal(t, actual, "template://foo")
+		assert.Equal(t, actual, "template:foo")
 	})
 
 	t.Run("", func(t *testing.T) {
@@ -272,15 +278,15 @@ func TestAbsPath(t *testing.T) {
 	}
 
 	t.Run("", func(t *testing.T) {
-		actual, err := absPath("foo", "template://")
+		actual, err := absPath("foo", "template:")
 		assert.NilError(t, err)
-		assert.Equal(t, actual, "template://foo")
+		assert.Equal(t, actual, "template:foo")
 	})
 
 	t.Run("", func(t *testing.T) {
-		actual, err := absPath("bar", "template://foo")
+		actual, err := absPath("bar", "template:foo")
 		assert.NilError(t, err)
-		assert.Equal(t, actual, "template://foo/bar")
+		assert.Equal(t, actual, "template:foo/bar")
 	})
 
 	t.Run("", func(t *testing.T) {
diff --git a/pkg/limatmpl/embed.go b/pkg/limatmpl/embed.go
@@ -76,15 +76,15 @@ func (tmpl *Template) embedAllBases(ctx context.Context, embedAll, defaultBase b
 		}
 		isTemplate, _ := SeemsTemplateURL(baseLocator.URL)
 		if isTemplate && !embedAll {
-			// Once we skip a template:// URL we can no longer embed any other base template
+			// 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].URL)
 				if !isTemplate {
 					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?
+			// TODO should we track embedding of template: URLs so we can warn if we embed a non-template: URL afterwards?
 		}
 
 		if seen[baseLocator.URL] {
diff --git a/pkg/limatmpl/embed_test.go b/pkg/limatmpl/embed_test.go
diff --git a/pkg/limatmpl/locator.go b/pkg/limatmpl/locator.go
diff --git a/pkg/limatmpl/locator_test.go b/pkg/limatmpl/locator_test.go

Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ func bashCompleteTemplateNames(_ *cobra.Command, toComplete string) ([]string, c`
`28`	`28`	`var comp []string`
`29`	`29`	`if templates, err := templatestore.Templates(); err == nil {`
`30`	`30`	`for _, f := range templates {`
`31`		`- name := "template://" + f.Name`
	`31`	`+ name := "template:" + f.Name`
`32`	`32`	`if !strings.HasPrefix(name, toComplete) {`
`33`	`33`	`continue`
`34`	`34`	`}`
Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@ local_setup_file() {`
`17`	`17`	`limactl delete --force "$NAME" \|\| :`
`18`	`18`	`# Make sure that the host agent doesn't inherit file handles 3 or 4.`
`19`	`19`	`# Otherwise bats will not finish until the host agent exits.`
`20`		`- limactl start --yes --name "$NAME" template://default 3>&- 4>&-`
	`20`	`+ limactl start --yes --name "$NAME" template:default 3>&- 4>&-`
`21`	`21`	`}`
`22`	`22`
`23`	`23`	`local_teardown_file() {`