Why does installing a v1 provider pull in v2 family provider dependencies?

Customers installing specific provider versions expect the dependency resolution to respect major version boundaries. When installing a v1 service provider, customers expect to get a v1 family provider, but instead may see v2 family providers being pulled in automatically.

This behavior is caused by Crossplane's package manager dependency resolution algorithm, which always pulls the latest available version of dependencies regardless of major version boundaries.

Root Cause: The Crossplane package manager respects constraints for dependencies, but the constraint on the family provider dependency is >= 0.0.0, so it installs the latest version, even if the specific service provider is from an older major version.

Example Scenario: Installing provider-azure-containerservice:v1.11.1 may pull provider-family-azure:v2.x.x instead of the expected provider-family-azure:v1.x.x.

Current Impact: While this doesn't cause functional issues today, it could potentially cause problems in the future if breaking changes are introduced in major version updates.

Affected Versions:

• All Provider Families: azure, aws, gcp

Resolution Options

Option 1: Pre-install Family Provider (Recommended)

Install the desired family provider version first:

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-family-azure  # Use appropriate family provider
spec:
  package: xpkg.upbound.io/upbound/provider-family-azure:v1.13.1 # Specify desired version

Wait for family provider to be ready:

kubectl wait --for=condition=healthy provider.pkg.crossplane.io/provider-family-azure --timeout=300s

Then install your specific service provider:

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-azure-containerservice  # Example service provider
spec:
  package: xpkg.upbound.io/upbound/provider-azure-containerservice:v1.11.1

Option 2: Skip Dependency Resolution

For more control, use skipDependencyResolution:

apiVersion: pkg.crossplane.io/v1
kind: Provider
metadata:
  name: provider-azure-containerservice  # Example service provider
spec:
  package: xpkg.upbound.io/upbound/provider-azure-containerservice:v1.11.1
  skipDependencyResolution: true

Workaround Limitations

• Option 1: Requires careful ordering of provider installations

• Option 2: Manual dependency management increases complexity

• Both: Future provider updates may still pull unexpected versions

Verification

# Check installed provider versions
kubectl get providers.pkg.crossplane.io kubectl get providers -o 'custom-columns=NAME:.metadata.name,PACKAGE:.spec.package,HEALTHY:.status.conditions[?(@.type=='"'"'Healthy'"'"')].status'

# Verify family provider version
kubectl get providers provider-family-azure -o jsonpath='{.spec.package}'