apache/pulsar · error · IllegalArgumentException

Function authentication provider %s must implement Kubernete

Error message

Function authentication provider %s must implement KubernetesFunctionAuthProvider

What it means

KubernetesRuntimeFactory.initialize validates that the configured function authentication provider implements KubernetesFunctionAuthProvider. The check runs before the provider is initialized with the Kubernetes core client and server CA, failing fast with IllegalArgumentException if the class is not a Kubernetes auth provider.

Source

Thrown at pulsar-functions/runtime/src/main/java/org/apache/pulsar/functions/runtime/kubernetes/KubernetesRuntimeFactory.java:247

        // make sure the provided class is a kubernetes auth provider, this needs to run before the authProvider!
        if (runtimeCustomizer.isPresent()) {
            if (!(runtimeCustomizer.get() instanceof KubernetesManifestCustomizer)) {
                throw new IllegalArgumentException("Function runtime customizer "
                        + runtimeCustomizer.get().getClass().getName()
                        + " must implement KubernetesManifestCustomizer");
            } else {
                KubernetesManifestCustomizer manifestCustomizer =
                        (KubernetesManifestCustomizer) runtimeCustomizer.get();
                this.manifestCustomizer = Optional.of(manifestCustomizer);
            }
        } else {
            this.manifestCustomizer = Optional.empty();
        }

        // make sure the provided class is a kubernetes auth provider
        if (functionAuthProvider.isPresent()) {
            if (!(functionAuthProvider.get() instanceof KubernetesFunctionAuthProvider)) {
                throw new IllegalArgumentException("Function authentication provider "
                        + functionAuthProvider.get().getClass().getName()
                        + " must implement KubernetesFunctionAuthProvider");
            } else {
                KubernetesFunctionAuthProvider kubernetesFunctionAuthProvider =
                        (KubernetesFunctionAuthProvider) functionAuthProvider.get();
                kubernetesFunctionAuthProvider.initialize(coreClient, serverCaBytes,
                        (funcDetails) -> getRuntimeCustomizer()
                                .map((customizer) -> customizer.customizeNamespace(funcDetails, jobNamespace))
                                .orElse(jobNamespace), factoryConfig.getKubernetesFunctionAuthProviderConfig());
                this.authProvider = Optional.of(kubernetesFunctionAuthProvider);
            }
        } else {
            this.authProvider = Optional.empty();
        }

        this.grpcPort = factoryConfig.getGrpcPort();
        this.metricsPort = factoryConfig.getMetricsPort();
        this.narExtractionDirectory = factoryConfig.getNarExtractionDirectory();

View on GitHub (pinned to 820761864e)

Solutions

Make the configured provider class implement KubernetesFunctionAuthProvider (with initialize/configureAuthenticationConfig methods).
Point the auth provider config at org.apache.pulsar.functions.auth.KubernetesFunctionAuthProvider implementations (e.g. KubernetesSecretsTokenAuthProvider).
Rebuild the custom auth plugin against the deployed Pulsar version's API.
Disable the k8s function auth provider config if Kubernetes-level function auth is not needed.

Example fix

// before
public class MyAuthProvider implements AuthenticationDataProvider { ... }
// after
public class MyAuthProvider implements KubernetesFunctionAuthProvider { ... }

Defensive patterns

Strategy: validation

Validate before calling

Class<?> c = Class.forName(configuredAuthProviderClassName);
if (!KubernetesFunctionAuthProvider.class.isAssignableFrom(c)) {
    throw new IllegalArgumentException(configuredAuthProviderClassName + " must implement KubernetesFunctionAuthProvider");
}

Type guard

boolean isValidAuthProvider(Object o) { return o instanceof KubernetesFunctionAuthProvider; }

Try / catch

try { factory.initialize(...); } catch (IllegalArgumentException e) { if (e.getMessage().contains("KubernetesFunctionAuthProvider")) { log.fatal("Bad auth provider config"); } throw e; }

Prevention

Do not reuse broker/client AuthPlugin classes as the k8s function auth provider
Rebuild custom auth plugins on Pulsar upgrades
Validate auth provider config with a startup test before production rollout

When it happens

Trigger: Setting k8s function auth provider class (functionAuthProvider config) to a class that does not implement KubernetesFunctionAuthProvider; the instanceof check at line 247 fails during worker initialization when authentication is enabled on the Kubernetes runtime.

Common situations: Configuring a generic Pulsar client AuthPlugin class instead of the Kubernetes-specific provider; custom auth plugin built against an older Pulsar interface; copy-paste of class name from broker auth config; missing recompilation after a Pulsar upgrade.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/2438be9f770650ec. Report an issue: GitHub.