Problem adding custom provider with URL in fetchConfig

[AMacedoP]

What steps did you take and what happened:

When adding a IPAM provider for Metal3 to a CAPI manager cluster the documentation states that you can only have to set the URL up to the releases path. Example 4.

But when trying to use this manifest:

apiVersion: operator.cluster.x-k8s.io/v1alpha2
kind: IPAMProvider
metadata:
  name: ipam-metal3
  namespace: metal3-ipam-system
spec:
  version: v1.10.0
  fetchConfig:
    url: https://github.com/metal3-io/ip-address-manager/releases

The CAPI operator controller fails with:

E0506 19:59:52.976457       1 controller.go:347] "Reconciler error" err="failed to create repo from provider url for provider \"ipam-metal3\": error creating the GitHub repository client: invalid url: a GitHub repository url should be in the form https://github.com/{owner}/{Repository}/releases/{latest|version-tag}/{componentsClient.yaml}" controller="ipamprovider" controllerGroup="operator.cluster.x-k8s.io" controllerKind="IPAMProvider" IPAMProvider="metal3-ipam-system/ipam-metal3" namespace="metal3-ipam-system" name="ipam-metal3" reconcileID="b40410de-f220-4faa-956c-35fdcabaa4d4"

When specifying the URL up to the yaml file in the release the installation completes without problem:

apiVersion: operator.cluster.x-k8s.io/v1alpha2
kind: IPAMProvider
metadata:
  name: ipam-metal3
  namespace: metal3-ipam-system
spec:
  version: v1.10.0
  fetchConfig:
    url: "https://github.com/metal3-io/ip-address-manager/releases/v1.10.0/ipam-components.yaml"

Am I doing something wrong or is the documentation wrong?

What did you expect to happen:

The IPAM provider installs successfully without providing the full URL to the release.

Environment:

• Cluster-api-operator version: v0.19.0
• Cluster-api version:
• Minikube/KIND version: k3d v5.8.3
• Kubernetes version: (use kubectl version): v1.31.5+k3s1
• OS (e.g. from /etc/os-release): Ubuntu 25.04

/kind bug

[k8s-ci-robot]

This issue is currently awaiting triage.

If CAPI Operator contributors determines this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[m18unet]

Hey @AMacedoP,

I applied the second YAML, this provider successfully.

I am using cluster-api-operator:v0.19.0. Which version are you using?

• The manifest:

  $ kubectl get ipamproviders.operator.cluster.x-k8s.io ipam-metal3 -o yaml
  apiVersion: operator.cluster.x-k8s.io/v1alpha2
  kind: IPAMProvider
  metadata:
    name: ipam-metal3
    namespace: metal3-ipam-system
  spec:
    fetchConfig:
      url: https://github.com/metal3-io/ip-address-manager/releases/v1.10.0/ipam-components.yaml
    version: v1.10.0

• cluster-api-operator log:

  phases.go:545] "Provider successfully installed" controller="ipamprovider" controllerGroup="operator.cluster.x-k8s.io" controllerKind="IPAMProvider" IPAMProvider="metal3-ipam-system/ipam-metal3" namespace="metal3-ipam-system" name="ipam-metal3" reconcileID="621fdc54-c725-4684-9c67-a6abbbb8409e"
  

• $ kubectl get ipamproviders.operator.cluster.x-k8s.io
  NAME          INSTALLEDVERSION   READY
  ipam-metal3   v1.10.0            True

• $ kubectl get pods -l cluster.x-k8s.io/provider=ipam-metal3
  NAME                                       READY   STATUS    RESTARTS   AGE
  ipam-controller-manager-77d4b9d984-ltk4n   1/1     Running   0          8m48s

[AMacedoP]

Hi @m18unet

Yes, using the second manifest the provider should install sucessfully, but the problem I described is using the first manifest as that's the example provided in the docs.

So my bug report is to ask if the documentation is wrong and fix it if that's the case.

[m18unet]

Okay I see,

I misunderstood

[PatrickLaabs]

I am not sure, if this is really a problem.
Providing a correct path to the YAML is also what i can see in the testfiles:

cluster-api-operator/internal/controller/manifests_downloader_test.go

Lines 71 to 82 in 95adca5

	func TestProviderDownloadWithOverrides(t *testing.T) {
	g := NewWithT(t)
	ctx := context.Background()
	fakeclient := fake.NewClientBuilder().WithObjects().Build()
	reader := configclient.NewMemoryReader()
	_, err := reader.AddProvider("cluster-api", clusterctlv1.CoreProviderType, "https://github.com/kubernetes-sigs/cluster-api/releases/v1.4.3/core-components.yaml")
	g.Expect(err).ToNot(HaveOccurred())
	overridesClient, err := configclient.New(ctx, "", configclient.InjectReader(reader))

So applying your second manifest, matches the expectations of the operator and what the error message said:
controller.go:347] "Reconciler error" err="failed to create repo from provider url for provider \"ipam-metal3\": error creating the GitHub repository client: invalid url: a GitHub repository url should be in the form https://github.com/{owner}/{Repository}/releases/{latest|version-tag}/{componentsClient.yaml}"

But yes, I would also agree, that the provided example is missing some informations, and the API documentation as well:

cluster-api-operator/api/v1alpha2/provider_types.go

Lines 63 to 69 in 95adca5

	// FetchConfig determines how the operator will fetch the components and metadata for the provider.
	// If nil, the operator will try to fetch components according to default
	// embedded fetch configuration for the given kind and `ObjectMeta.Name`.
	// For example, the infrastructure name `aws` will fetch artifacts from
	// https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases.
	// +optional
	FetchConfig *FetchConfiguration `json:"fetchConfig,omitempty"`

[Danil-Grigorev]

@AMacedoP @PatrickLaabs What you are asking to do is not supported by clusterctl, which is what CAPIO is using for handling this logic. URL format should include the full path to the <provider>-components.yaml file as in your second example: https://cluster-api.sigs.k8s.io/clusterctl/configuration#provider-repositories

It should be possible to add a new field beyond url, something like baseURL which will try to compose the full path for the components from version field and provider type.

[AMacedoP]

Hi, I'm not really asking to add another field for this use case, but to check if the documentation needs to be fixed because the provided example doesn't work.

Maybe it would be better if I open an PR to fix it?

[furkatgofurov7]

@AMacedoP feel free to send a PR and tag maintainers, thank you!

[Danil-Grigorev]

@AMacedoP Yes please, should be a simple one for docs then.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten