Crossplane构建Configuration包报错：not exactly one package meta type

This error occurs because the crossplane xpkg build command can't locate exactly one valid package metadata file (like crossplane.yaml or package.yaml) in the specified --package-root directory, or it found multiple conflicting metadata files. Here's how to resolve it:

1. Fix file structure and command alignment #

You placed crossplane.yaml in your project root, but ran the command with --package-root=apis/. The tool expects the package metadata file to exist inside the specified root directory—so it only found your Composition and XRD files (which aren't package metadata types) in apis/, triggering the error.

Choose one of these fixes:

• Option 1: Keep crossplane.yaml in the root directory, run the command without the --package-root flag:

  crossplane xpkg build
  

  The tool will automatically scan the current directory and subdirectories (including apis/) for valid resources.
• Option 2: Move crossplane.yaml into the apis/ directory, then run:

  crossplane xpkg build --package-root=apis/
  

2. Validate your package metadata file #

Ensure your crossplane.yaml is correctly formatted for a Configuration package. Example valid content:

apiVersion: meta.pkg.crossplane.io/v1
kind: Configuration
metadata:
  name: my-custom-configuration
spec:
  crossplane:
    version: ">=1.10.0"
  dependsOn:
    - provider: xpkg.upbound.io/crossplane/provider-aws
      version: ">=v0.34.0"
  resources:
    - kinds:
        - CompositeResourceDefinition
      versions:
        - v1alpha1
    - kinds:
        - Composition
      versions:
        - v1alpha1

Confirm there are no typos in the API version, kind, or spec fields—especially that kind is set to Configuration for your use case.

3. Remove duplicate metadata files #

Double-check the target directory (root or apis/) for accidental duplicate crossplane.yaml or package.yaml files. Multiple metadata files will directly cause the "not exactly one" error.

4. Verify resource file validity #

Make sure your Composition and XRD files in apis/ are valid YAML with no syntax errors. Corrupted files might cause the tool to misinterpret their types, leading to unexpected metadata count issues.

内容的提问来源于stack exchange，提问作者jonashackt