kubernetes/kops · error

error rendering Instance UserData: %v

Error message

error rendering Instance UserData: %v

What it means

Instance.RenderAWS reads the task's UserData resource fully into memory via fi.ResourceAsBytes before base64-encoding it into the RunInstances request. If reading the resource fails (unreadable file, broken resource implementation, I/O error), kOps wraps the failure as 'error rendering Instance UserData'. The instance is not created in this case.

Source

Thrown at upup/pkg/fi/cloudup/awstasks/instance.go:272

		// Build up the actual block device mappings
		// TODO: Support RootVolumeType & RootVolumeSize (see launchconfiguration)
		blockDeviceMappings, err := buildEphemeralDevices(t.Cloud, e.InstanceType)
		if err != nil {
			return err
		}

		if len(blockDeviceMappings) != 0 {
			request.BlockDeviceMappings = []ec2types.BlockDeviceMapping{}
			for deviceName, bdm := range blockDeviceMappings {
				request.BlockDeviceMappings = append(request.BlockDeviceMappings, bdm.ToEC2(deviceName))
			}
		}

		if e.UserData != nil {
			d, err := fi.ResourceAsBytes(e.UserData)
			if err != nil {
				return fmt.Errorf("error rendering Instance UserData: %v", err)
			}
			if len(d) > MaxUserDataSize {
				// TODO: Re-enable gzip?
				// But it exposes some bugs in the AWS console, so if we can avoid it, we should
				//d, err = fi.GzipBytes(d)
				//if err != nil {
				//	return fmt.Errorf("error while gzipping UserData: %v", err)
				//}
				return fmt.Errorf("Instance UserData was too large (%d bytes)", len(d))
			}
			request.UserData = aws.String(base64.StdEncoding.EncodeToString(d))
		}

		if e.IAMInstanceProfile != nil {
			request.IamInstanceProfile = &ec2types.IamInstanceProfileSpecification{
				Name: e.IAMInstanceProfile.Name,
			}
		}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Check that the UserData source (file path or template) exists and is readable by the user running kops.
2. Run `kops update cluster --v=8` to see the underlying wrapped I/O error and fix the specific resource.
3. If using templates/assets, regenerate them (`kops create instancegroup` / update manifests) so the resource is valid.
4. Verify file permissions (chmod/chown) or copy the script into the repo and use a relative path.
5. Test rendering with a minimal inline UserData to isolate the failing resource.

Example fix

# before
kops edit cluster  # igconfig userData: file:///etc/kubernetes/bootstrap-old.sh  (file deleted)
# after
kops edit cluster  # igconfig userData: file:///etc/kubernetes/bootstrap.sh (exists, chmod 644)
kops update cluster

// Verify the UserData source is readable before running kops update
path := "/etc/kubernetes/bootstrap.sh"
f, err := os.Open(path)
if err != nil {
	return fmt.Errorf("userData source unreadable: %w", err)
}
f.Close()
// For custom fi.Resource implementations, dry-run Bytes() first
if r, ok := userDataResource.(interface{ Bytes() ([]byte, error) }); ok {
	if _, err := r.Bytes(); err != nil {
		return fmt.Errorf("userData resource fails to render: %w", err)
	}
}

err := runKopsUpdate(ctx)
if err != nil && strings.Contains(err.Error(), "error rendering Instance UserData") {
	return fmt.Errorf("check userData file paths/permissions in the cluster spec: %w", err)
}
return err

When it happens

Trigger: RunInstances-time rendering of an Instance task whose e.UserData resource cannot be read: missing file path in a file resource, permission denied, or a custom fi.Resource whose Bytes() returns an error.

Common situations: A bootstrap script path referenced in the cluster spec no longer exists or is unreadable; manifests using generated/template resources whose backing data failed to load; permission issues after running kops from a different user or container; packaging a nodeup/igconfig resource that errors on read.

Related errors

• error decoding EC2 UserData: %v
• Instance UserData was too large (%d bytes)
• error decoding userdata: %s
• DIGITALOCEAN_ACCESS_TOKEN is required
• timed out waiting for volume to detach

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/6921369cb4873c3f. Report an issue: GitHub.