feature: "yq" provision mode

norio-nomura · norio-nomura · commit 2f2f47f64de5 · 2025-08-28T17:26:39.000+09:00
```yaml # Create or edit a file in the guest filesystem by using `yq`. # The file specified by `path` will be updated by `expression`. # An empty file of the required `format` will be created if it does not yet exist. # `format` defaults to "auto" and will be detected by file extension of `path`. # If the extension is not recognized by `yq` then `format` must be set to a # value from this list: # "auto", "csv", "ini", "json", "props", "tsv", "toml", "xml", "yaml" # See https://github.com/mikefarah/yq for more info. # Any missing directories will be created as needed. # The file permissions will be set to the specified value. # The file and directory creation will be performed as the specified owner. # If the existing file is not writable by the specified owner, the operation will fail. # `path` and `expression` are required. # `owner` and `permissions` are optional. Defaults to "root:root" and 644. - mode: yq path: "{{.Home}}/.config/docker/daemon.json" expression: ".features.containerd-snapshotter = {{.Param.containerdSnapshotter}}" format: auto owner: "{{.User}}" permissions: 644 ``` Signed-off-by: Norio Nomura <norio.nomura@gmail.com>
diff --git a/hack/test-templates.sh b/hack/test-templates.sh
@@ -56,6 +56,7 @@ declare -A CHECKS=(
 	["user-v2"]=""
 	["mount-path-with-spaces"]=""
 	["provision-data"]=""
+	["provision-yq"]=""
 	["param-env-variables"]=""
 	["set-user"]=""
 	["preserve-env"]="1"
@@ -90,6 +91,7 @@ case "$NAME" in
 	CHECKS["clone"]="1"
 	CHECKS["mount-path-with-spaces"]="1"
 	CHECKS["provision-data"]="1"
+	CHECKS["provision-yq"]="1"
 	CHECKS["param-env-variables"]="1"
 	CHECKS["set-user"]="1"
 	;;
@@ -199,6 +201,11 @@ if [[ -n ${CHECKS["provision-data"]} ]]; then
 	limactl shell "$NAME" grep -q fs.inotify.max_user_watches /etc/sysctl.d/99-inotify.conf
 fi
 
+if [[ -n ${CHECKS["provision-yq"]} ]]; then
+	INFO 'Testing that /tmp/param-yq.json was created successfully on provision'
+	limactl shell "$NAME" grep -q '"YQ": "yq"' /tmp/param-yq.json
+fi
+
 if [[ -n ${CHECKS["param-env-variables"]} ]]; then
 	INFO 'Testing that PARAM env variables are exported to all types of provisioning scripts and probes'
 	limactl shell "$NAME" test -e /tmp/param-ansible
diff --git a/hack/test-templates/test-misc.yaml b/hack/test-templates/test-misc.yaml
@@ -20,6 +20,7 @@ param:
   PROBE: probe
   SYSTEM: system
   USER: user
+  YQ: yq
 
 provision:
 - mode: ansible
@@ -37,6 +38,10 @@ provision:
   content: |
     fs.inotify.max_user_watches = 524288
     fs.inotify.max_user_instances = 512
+- mode: yq
+  path: "/tmp/param-{{.Param.YQ}}.json"
+  expression: .YQ = "{{.Param.YQ}}"
+  user: "{{.User}}"
 
 probes:
 - mode: readiness
diff --git a/pkg/cidata/cidata.TEMPLATE.d/boot.sh b/pkg/cidata/cidata.TEMPLATE.d/boot.sh
@@ -64,19 +64,93 @@ if [ -d "${LIMA_CIDATA_MNT}"/provision.data ]; then
 		owner=$(deref "LIMA_CIDATA_DATAFILE_${filename}_OWNER")
 		path=$(deref "LIMA_CIDATA_DATAFILE_${filename}_PATH")
 		permissions=$(deref "LIMA_CIDATA_DATAFILE_${filename}_PERMISSIONS")
+		user="${owner%%:*}"
 		if [ -e "$path" ] && [ "$overwrite" = "false" ]; then
 			INFO "Not overwriting $path"
 		else
 			INFO "Copying $f to $path"
-			# intermediate directories will be owned by root, regardless of OWNER setting
-			mkdir -p "$(dirname "$path")"
+			if ! sudo -iu "${user}" mkdir -p "$(dirname "$path")"; then
+				WARNING "Failed to create directory for ${path} (as user ${user})"
+				WARNING "Falling back to creating directory as root to maintain compatibility"
+				mkdir -p "$(dirname "$path")"
+			fi
 			cp "$f" "$path"
 			chown "$owner" "$path"
 			chmod "$permissions" "$path"
 		fi
 	done
 fi
 
+if [ -d "${LIMA_CIDATA_MNT}"/provision.yq ]; then
+	yq="${LIMA_CIDATA_MNT}/lima-guestagent yq"
+	for f in "${LIMA_CIDATA_MNT}"/provision.yq/*; do
+		filename=$(basename "${f}")
+		format=$(deref "LIMA_CIDATA_YQ_PROVISION_${filename}_FORMAT")
+		owner=$(deref "LIMA_CIDATA_YQ_PROVISION_${filename}_OWNER")
+		path=$(deref "LIMA_CIDATA_YQ_PROVISION_${filename}_PATH")
+		permissions=$(deref "LIMA_CIDATA_YQ_PROVISION_${filename}_PERMISSIONS")
+		user="${owner%%:*}"
+		# Creating intermediate directories may fail if the user does not have permission.
+		# TODO: Create intermediate directories with the specified group ownership.
+		if ! sudo -iu "${user}" mkdir -p "$(dirname "${path}")"; then
+			WARNING "Failed to create directory for ${path} (as user ${user})"
+			CODE=1
+			continue
+		fi
+		# Since CIDATA is mounted with dmode=700,fmode=700,
+		# `lima-guestagent yq` cannot be executed by non-root users,
+		# and provision.yq/* files cannot be read by non-root users.
+		if [ -f "${path}" ]; then
+			INFO "Updating ${path}"
+			# If the user does not have write permission, it should fail.
+			# This avoids changes being made by the wrong user.
+			if ! sudo -iu "${user}" test -w "${path}"; then
+				WARNING "File ${path} is not writable by user ${user}"
+				CODE=1
+				continue
+			fi
+			# Relies on the fact that yq does not change the owner of the existing file.
+			if ! ${yq} --inplace --from-file "${f}" --input-format "${format}" --output-format "${format}" "${path}"; then
+				WARNING "Failed to update ${path} (as user ${user})"
+				CODE=1
+				continue
+			fi
+		else
+			if [ "${format}" = "auto" ]; then
+				# yq can't determine the output format from non-existing files
+				case "${path}" in
+				*.csv) format=csv ;;
+				*.ini) format=ini ;;
+				*.json) format=json ;;
+				*.properties) format=properties ;;
+				*.toml) format=toml ;;
+				*.tsv) format=tsv ;;
+				*.xml) format=xml ;;
+				*.yaml | *.yml) format=yaml ;;
+				*)
+					format=yaml
+					WARNING "Cannot determine file type for ${path}, using yaml format"
+					;;
+				esac
+			fi
+			INFO "Creating ${path}"
+			if ! ${yq} --null-input --from-file "${f}" --output-format "${format}" | sudo -iu "${user}" tee "${path}"; then
+				WARNING "Failed to create ${path} (as user ${user})"
+				CODE=1
+				continue
+			fi
+		fi
+		if ! sudo -iu "${user}" chown "${owner}" "${path}"; then
+			WARNING "Failed to set owner for ${path} (as user ${user})"
+			CODE=1
+		fi
+		if ! sudo -iu "${user}" chmod "${permissions}" "${path}"; then
+			WARNING "Failed to set permissions for ${path} (as user ${user})"
+			CODE=1
+		fi
+	done
+fi
+
 if [ -d "${LIMA_CIDATA_MNT}"/provision.system ]; then
 	for f in "${LIMA_CIDATA_MNT}"/provision.system/*; do
 		INFO "Executing $f"
diff --git a/pkg/cidata/cidata.TEMPLATE.d/lima.env b/pkg/cidata/cidata.TEMPLATE.d/lima.env
@@ -25,6 +25,12 @@ LIMA_CIDATA_DATAFILE_{{$dataFile.FileName}}_OWNER={{$dataFile.Owner}}
 LIMA_CIDATA_DATAFILE_{{$dataFile.FileName}}_PATH={{$dataFile.Path}}
 LIMA_CIDATA_DATAFILE_{{$dataFile.FileName}}_PERMISSIONS={{$dataFile.Permissions}}
 {{- end}}
+{{- range $yqProvision := .YQProvisions}}
+LIMA_CIDATA_YQ_PROVISION_{{$yqProvision.FileName}}_FORMAT={{$yqProvision.Format}}
+LIMA_CIDATA_YQ_PROVISION_{{$yqProvision.FileName}}_OWNER={{$yqProvision.Owner}}
+LIMA_CIDATA_YQ_PROVISION_{{$yqProvision.FileName}}_PATH={{$yqProvision.Path}}
+LIMA_CIDATA_YQ_PROVISION_{{$yqProvision.FileName}}_PERMISSIONS={{$yqProvision.Permissions}}
+{{- end}}
 LIMA_CIDATA_GUEST_INSTALL_PREFIX={{ .GuestInstallPrefix }}
 {{- if .Containerd.User}}
 LIMA_CIDATA_CONTAINERD_USER=1
diff --git a/pkg/cidata/cidata.go b/pkg/cidata/cidata.go
@@ -335,6 +335,15 @@ func templateArgs(ctx context.Context, bootScripts bool, instDir, name string, i
 				Permissions: *f.Permissions,
 			})
 		}
+		if f.Mode == limatype.ProvisionModeYQ {
+			args.YQProvisions = append(args.YQProvisions, YQProvision{
+				FileName:    fmt.Sprintf("%08d", i),
+				Format:      *f.Format,
+				Owner:       *f.Owner,
+				Path:        *f.Path,
+				Permissions: *f.Permissions,
+			})
+		}
 	}
 
 	return &args, nil
@@ -402,6 +411,11 @@ func GenerateISO9660(ctx context.Context, drv driver.Driver, instDir, name strin
 				Path:   fmt.Sprintf("provision.%s/%08d", f.Mode, i),
 				Reader: strings.NewReader(*f.Content),
 			})
+		case limatype.ProvisionModeYQ:
+			layout = append(layout, iso9660util.Entry{
+				Path:   fmt.Sprintf("provision.%s/%08d", f.Mode, i),
+				Reader: strings.NewReader(*f.Expression),
+			})
 		case limatype.ProvisionModeBoot:
 			continue
 		case limatype.ProvisionModeAnsible:
diff --git a/pkg/cidata/template.go b/pkg/cidata/template.go
@@ -58,6 +58,14 @@ type DataFile struct {
 	Permissions string
 }
 
+type YQProvision struct {
+	FileName    string
+	Format      string
+	Owner       string
+	Path        string
+	Permissions string
+}
+
 type Disk struct {
 	Name   string
 	Device string
@@ -93,6 +101,7 @@ type TemplateArgs struct {
 	Param                           map[string]string
 	BootScripts                     bool
 	DataFiles                       []DataFile
+	YQProvisions                    []YQProvision
 	DNSAddresses                    []string
 	CACerts                         CACerts
 	HostHomeMountPoint              string
diff --git a/pkg/limatmpl/embed.go b/pkg/limatmpl/embed.go
@@ -648,6 +648,11 @@ func (tmpl *Template) embedAllScripts(ctx context.Context, embedAll bool) error
 			if p.Content != nil {
 				continue
 			}
+		case limatype.ProvisionModeYQ:
+			newName = "expression"
+			if p.Expression != nil {
+				continue
+			}
 		default:
 			if p.Script != "" {
 				continue
diff --git a/pkg/limatmpl/embed_test.go b/pkg/limatmpl/embed_test.go
@@ -343,6 +343,9 @@ provision:
 - mode: data
   file: base1.sh # This comment will move to the "content" key
   path: /tmp/data
+- mode: yq
+  file: base1.sh # This comment will move to the "expression" key
+  path: /tmp/yq
 `,
 		`
 # base0.yaml is ignored
@@ -364,6 +367,11 @@ provision:
     #!/usr/bin/env bash
     echo "This is base1.sh"
   path: /tmp/data
+- mode: yq
+  expression: |-  # This comment will move to the "expression" key
+    #!/usr/bin/env bash
+    echo "This is base1.sh"
+  path: /tmp/yq
 
 # base0.yaml is ignored
 `,
diff --git a/pkg/limatype/lima_yaml.go b/pkg/limatype/lima_yaml.go
@@ -235,6 +235,7 @@ const (
 	ProvisionModeDependency ProvisionMode = "dependency"
 	ProvisionModeAnsible    ProvisionMode = "ansible" // DEPRECATED
 	ProvisionModeData       ProvisionMode = "data"
+	ProvisionModeYQ         ProvisionMode = "yq"
 )
 
 type Provision struct {
@@ -245,6 +246,9 @@ type Provision struct {
 	Playbook                        string             `yaml:"playbook,omitempty" json:"playbook,omitempty"` // DEPRECATED
 	// All ProvisionData fields must be nil unless Mode is ProvisionModeData
 	ProvisionData `yaml:",inline"` // Flatten fields for "strict" YAML mode
+	// ProvisionModeYQ borrows Owner, Path, and Permissions from ProvisionData
+	Expression *string `yaml:"expression,omitempty" json:"expression,omitempty" jsonschema:"nullable"`
+	Format     *string `yaml:"format,omitempty" json:"format,omitempty" jsonschema:"nullable"`
 }
 
 type ProvisionData struct {
diff --git a/pkg/limayaml/defaults.go b/pkg/limayaml/defaults.go
@@ -405,13 +405,27 @@ func FillDefault(ctx context.Context, y, d, o *limatype.LimaYAML, filePath strin
 			if provision.Overwrite == nil {
 				provision.Overwrite = ptr.Of(true)
 			}
+		}
+		if provision.Mode == limatype.ProvisionModeYQ {
+			if provision.Expression != nil {
+				if out, err := executeGuestTemplate(*provision.Expression, instDir, y.User, y.Param); err == nil {
+					provision.Expression = ptr.Of(out.String())
+				} else {
+					logrus.WithError(err).Warnf("Couldn't process expression %q as a template", *provision.Expression)
+				}
+			}
+			if provision.Format == nil {
+				provision.Format = ptr.Of("auto")
+			}
+		}
+		if provision.Mode == limatype.ProvisionModeData || provision.Mode == limatype.ProvisionModeYQ {
 			if provision.Owner == nil {
 				provision.Owner = ptr.Of("root:root")
 			} else {
 				if out, err := executeGuestTemplate(*provision.Owner, instDir, y.User, y.Param); err == nil {
 					provision.Owner = ptr.Of(out.String())
 				} else {
-					logrus.WithError(err).Warnf("Couldn't owner %q as a template", *provision.Owner)
+					logrus.WithError(err).Warnf("Couldn't process owner %q as a template", *provision.Owner)
 				}
 			}
 			// Path is required; validation will throw an error when it is nil
diff --git a/pkg/limayaml/validate.go b/pkg/limayaml/validate.go
@@ -181,33 +181,37 @@ func Validate(y *limatype.LimaYAML, warn bool) error {
 			}
 		}
 		switch p.Mode {
-		case limatype.ProvisionModeSystem, limatype.ProvisionModeUser, limatype.ProvisionModeBoot, limatype.ProvisionModeData, limatype.ProvisionModeDependency, limatype.ProvisionModeAnsible:
+		case limatype.ProvisionModeSystem, limatype.ProvisionModeUser, limatype.ProvisionModeBoot, limatype.ProvisionModeData, limatype.ProvisionModeDependency, limatype.ProvisionModeAnsible, limatype.ProvisionModeYQ:
 		default:
-			errs = errors.Join(errs, fmt.Errorf("field `provision[%d].mode` must one of %q, %q, %q, %q, %q, or %q",
-				i, limatype.ProvisionModeSystem, limatype.ProvisionModeUser, limatype.ProvisionModeBoot, limatype.ProvisionModeData, limatype.ProvisionModeDependency, limatype.ProvisionModeAnsible))
+			errs = errors.Join(errs, fmt.Errorf("field `provision[%d].mode` must one of %q, %q, %q, %q, %q, %q, or %q",
+				i, limatype.ProvisionModeSystem, limatype.ProvisionModeUser, limatype.ProvisionModeBoot, limatype.ProvisionModeData, limatype.ProvisionModeDependency, limatype.ProvisionModeAnsible, limatype.ProvisionModeYQ))
 		}
 		if p.Mode != limatype.ProvisionModeDependency && p.SkipDefaultDependencyResolution != nil {
 			errs = errors.Join(errs, fmt.Errorf("field `provision[%d].mode` cannot set skipDefaultDependencyResolution, only valid on scripts of type %q",
 				i, limatype.ProvisionModeDependency))
 		}
 
 		// This can lead to fatal Panic if p.Path is nil, better to return an error here
-		if p.Mode == limatype.ProvisionModeData {
+		switch p.Mode {
+		case limatype.ProvisionModeData, limatype.ProvisionModeYQ:
 			if p.Path == nil {
-				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].path` must not be empty when mode is %q", i, limatype.ProvisionModeData))
+				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].path` must not be empty when mode is %q", i, p.Mode))
 				return errs
 			}
 			if !path.IsAbs(*p.Path) {
 				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].path` must be an absolute path", i))
 			}
-			if p.Content == nil {
-				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].content` must not be empty when mode is %q", i, limatype.ProvisionModeData))
+			if p.Mode == limatype.ProvisionModeData && p.Content == nil {
+				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].content` must not be empty when mode is %q", i, p.Mode))
+			}
+			if p.Mode == limatype.ProvisionModeYQ && p.Expression == nil {
+				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].expression` must not be empty when mode is %q", i, p.Mode))
 			}
 			// FillDefaults makes sure that p.Permissions is not nil
 			if _, err := strconv.ParseInt(*p.Permissions, 8, 64); err != nil {
 				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].permissions` must be an octal number: %w", i, err))
 			}
-		} else {
+		default:
 			if p.Script == "" && p.Mode != limatype.ProvisionModeAnsible {
 				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].script` must not be empty", i))
 			}
@@ -221,10 +225,13 @@ func Validate(y *limatype.LimaYAML, warn bool) error {
 				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].owner` can only be set when mode is %q", i, limatype.ProvisionModeData))
 			}
 			if p.Path != nil {
-				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].path` can only be set when mode is %q", i, limatype.ProvisionModeData))
+				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].path` can only be set when mode is %q, or %q", i, limatype.ProvisionModeData, limatype.ProvisionModeYQ))
 			}
 			if p.Permissions != nil {
-				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].permissions` can only be set when mode is %q", i, limatype.ProvisionModeData))
+				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].permissions` can only be set when mode is %q, or %q", i, limatype.ProvisionModeData, limatype.ProvisionModeYQ))
+			}
+			if p.Format != nil {
+				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].format` can only be set when mode is %q", i, limatype.ProvisionModeYQ))
 			}
 		}
 		if p.Playbook != "" {
@@ -489,13 +496,11 @@ func validateParamIsUsed(y *limatype.LimaYAML) error {
 		}
 		keyIsUsed := false
 		for _, p := range y.Provision {
-			if re.MatchString(p.Script) {
-				keyIsUsed = true
-				break
-			}
-			if p.Content != nil && re.MatchString(*p.Content) {
-				keyIsUsed = true
-				break
+			for _, ptr := range []*string{&p.Script, p.Content, p.Expression, p.Owner, p.Path, p.Permissions} {
+				if ptr != nil && re.MatchString(*ptr) {
+					keyIsUsed = true
+					break
+				}
 			}
 			if p.Playbook != "" {
 				playbook, err := os.ReadFile(p.Playbook)
diff --git a/pkg/limayaml/validate_test.go b/pkg/limayaml/validate_test.go
diff --git a/templates/default.yaml b/templates/default.yaml
diff --git a/templates/docker-rootful.yaml b/templates/docker-rootful.yaml
diff --git a/templates/docker.yaml b/templates/docker.yaml
diff --git a/website/content/en/docs/dev/internals.md b/website/content/en/docs/dev/internals.md
