Skip to content

Migrate to community packages

Change the url in the packages

Change the url from 

xpkg.upbound.io/upbound/XXXXXX

to

xpkg.crossplane.io/crossplane-contrib/XXXXXX

!!! danger "Only change the url, do not rename the provider because it can remove all your managed resources"

Notes:

  • Use a pinned package version, like v2.3.0
  • Use the same pinned versions in all the packages from the same family
  • Do not declare the family provider. It will be installed as dependency

Fix the provider deployment

This will fail because the lock can have old dependencies and the old family provider can be there

  • Recreate the dependencies

Remove the lock

kubectl delete locks.pkg.crossplane.io lock
  • Remove the old family provider

Remove the family provider with the xpkg.upbound.io/upbound/

kubectl get providers.pkg.crossplane.io
kubectl delete providers.pkg.crossplane.io XXX

Remove the owner of the providerconfig CRD

This will permit the new provider family own the crd

For example, for aws providers

kubectl patch crd providerconfigs.aws.m.upbound.io --type=json -p='[{"op":"remove","path":"/metadata/ownerReferences"}]'

Fix the providerconfig

If the ProviderConfigs are stuck in a terminating state, it means the in-use.crossplane.io finalizer is being held by existing ProviderConfigUsage objects.

ProviderConfigUsage objects are auto-generated by the managed resource controller to track which managed resources reference a given ProviderConfig. They are not GitOps-managed resources. Deleting them:

  • Does not delete managed resources (IAM Roles, Policies, etc.)
  • Does not delete any cloud resources
  • Only removes the lock that holds the ProviderConfig finalizer

For example, for AWS providers:

kubectl delete providerconfigusages.aws.m.upbound.io -A --all

!!! warning "The command above may not clear all namespaces at once" If some ProviderConfigs remain stuck, delete per namespace:

kubectl delete providerconfigusages.aws.m.upbound.io -n <namespace> --all

Once the usages are removed, the ProviderConfigs complete their deletion and ArgoCD recreates them automatically from the git manifests.

Remove stuck finalizers

If a ProviderConfig still has the in-use.crossplane.io finalizer after all its ProviderConfigUsages have been deleted (the controller did not reconcile it), remove the finalizer directly:

kubectl patch providerconfig.<group> <name> -n <namespace> \
  --type=json -p='[{"op":"remove","path":"/metadata/finalizers/0"}]'

After the finalizer is removed, Kubernetes completes the deletion and ArgoCD recreates the ProviderConfig from git.

!!! note "The new community provider supports both API groups" The crossplane-contrib/provider-family-aws package manages both providerconfigs.aws.m.upbound.io (namespaced) and providerconfigs.aws.upbound.io (cluster-scoped) CRDs. There is no need to migrate existing managed resources or ProviderConfig manifests to a different API group.