kubernetes/kops · error

unhandled aws metadata path %q

Error message

unhandled aws metadata path %q

What it means

readAWSMetadata only supports paths under /meta-data/; user-data and other IMDS trees are intentionally not exposed. Any metadata://aws URL whose path does not start with /meta-data/ returns this error.

Source

Thrown at util/pkg/vfs/context.go:245

	config, err := awsconfig.LoadDefaultConfig(ctx)
	if err != nil {
		return nil, fmt.Errorf("failed to load AWS config: %w", err)
	}

	client := imds.NewFromConfig(config)

	if strings.HasPrefix(path, "/meta-data/") {
		s, err := client.GetMetadata(ctx, &imds.GetMetadataInput{
			Path: strings.TrimPrefix(path, "/meta-data/"),
		})
		if err != nil {
			return nil, fmt.Errorf("error reading from AWS metadata service: %v", err)
		}
		defer s.Content.Close()
		return io.ReadAll(s.Content)
	}
	// There are others (e.g. user-data), but as we don't use them yet let's not expose them
	return nil, fmt.Errorf("unhandled aws metadata path %q", path)
}

// readHTTPLocation reads an http (or https) url.
// It returns the contents, or an error on any non-200 response.  On a 404, it will return os.ErrNotExist
// It will retry a few times on a 500 class error
func (c *VFSContext) readHTTPLocation(httpURL string, httpHeaders map[string]string, opts vfsOptions) ([]byte, error) {
	var body []byte

	done, err := RetryWithBackoff(opts.backoff, func() (bool, error) {
		klog.V(4).Infof("Performing HTTP request: GET %s", httpURL)
		req, err := http.NewRequest("GET", httpURL, nil)
		if err != nil {
			return false, err
		}
		for k, v := range httpHeaders {
			req.Header.Add(k, v)
		}
		response, err := http.DefaultClient.Do(req)

View on GitHub (pinned to 4c8573c808)

Solutions

1. Use a /meta-data/... path, e.g. metadata://aws/meta-data/instance-id
2. For user-data, fetch http://169.254.169.254/latest/user-data directly with an HTTP client
3. For instance identity documents, use the AWS SDK (ec2rolecreds / imds client) rather than this path

Example fix

// before
vfs.Context.ReadFile("metadata://aws/user-data")
// after
vfs.Context.ReadFile("metadata://aws/meta-data/instance-id")

func validateAWSMetadataPath(loc string) error {
	u, err := url.Parse(loc)
	if err != nil || u.Scheme != "metadata" || u.Host != "aws" {
		return nil
	}
	if !strings.HasPrefix(u.Path, "/meta-data/") {
		return fmt.Errorf("only /meta-data/* paths are supported: %q", loc)
	}
	return nil
}

func isSupportedAWSMetadataPath(loc string) bool {
	u, err := url.Parse(loc)
	return err == nil && u.Scheme == "metadata" && u.Host == "aws" && strings.HasPrefix(u.Path, "/meta-data/")
}

data, err := vfs.Context.ReadFile(loc)
if err != nil && strings.Contains(err.Error(), "unhandled aws metadata path") {
	return fmt.Errorf("use /meta-data/... or fetch user-data via IMDS HTTP directly: %w", err)
}

When it happens

Trigger: ReadFile('metadata://aws/user-data') or ReadFile('metadata://aws/dynamic/instance-identity/document') - any aws metadata path not prefixed with /meta-data/.

Common situations: Trying to fetch EC2 user-data through the vfs metadata scheme; copying GCE-style metadata paths (computeMetadata/v1 style) into the aws scheme.

Related errors

• error querying ec2 metadata service (for region): %v
• failed to load AWS config: %w
• failed to get local-ipv4 address from ec2 metadata: %w
• finding primary network interface: %w
• loading AWS config: %w

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