What causes "Could not create Kubernetes cluster "${clusterId}"." in zhisheng17/flink-learning?

Inspect the cause attached to the ClusterDeploymentException and cluster events: kubectl describe deploy/svc, kubectl get events in the namespace.

zhisheng17/flink-learning · error · ClusterDeploymentException

Could not create Kubernetes cluster "${clusterId}".

Error message

Could not create Kubernetes cluster "${clusterId}".

What it means

Thrown by deployClusterInternal when creating the Kubernetes cluster (deploying JobManager/TaskManager resources) fails. The handler first attempts client.stopAndCleanupCluster(clusterId) to remove residual resources, then wraps the original exception in a ClusterDeploymentException.

Source

Thrown at flink-learning-k8s/flink-k8s/src/main/java/org/apache/flink/kubernetes/KubernetesClusterDescriptor.java:258

			final KubernetesJobManagerParameters kubernetesJobManagerParameters =
				new KubernetesJobManagerParameters(flinkConfig, clusterSpecification);

			//todo：构建 jm spec
			final KubernetesJobManagerSpecification kubernetesJobManagerSpec =
				KubernetesJobManagerFactory.buildKubernetesJobManagerSpecification(kubernetesJobManagerParameters);

			//todo：create jm deployment
			client.createJobManagerComponent(kubernetesJobManagerSpec);

			return createClusterClientProvider(clusterId);
		} catch (Exception e) {
			try {
				LOG.warn("Failed to create the Kubernetes cluster \"{}\", try to clean up the residual resources.", clusterId);
				client.stopAndCleanupCluster(clusterId);
			} catch (Exception e1) {
				LOG.info("Failed to stop and clean up the Kubernetes cluster \"{}\".", clusterId, e1);
			}
			throw new ClusterDeploymentException("Could not create Kubernetes cluster \"" + clusterId + "\".", e);
		}
	}

	@Override
	public void killCluster(String clusterId) throws FlinkException {
		try {
			client.stopAndCleanupCluster(clusterId);
		} catch (Exception e) {
			client.handleException(e);
			throw new FlinkException("Could not kill Kubernetes cluster " + clusterId);
		}
	}

	@Override
	public void close() {
		try {
			client.close();
		} catch (Exception e) {

View on GitHub (pinned to d731cee761)

Solutions

Inspect the cause attached to the ClusterDeploymentException and cluster events: kubectl describe deploy/svc, kubectl get events in the namespace.
Verify RBAC: the service account needs permissions to create deployments, services, configmaps.
Check the container image name/tag is correct and pullable from the cluster (kubernetes.container-image.pull-policy).
Check namespace ResourceQuotas and LimitRanges against requested CPU/memory.
If cleanup also failed (log line 'Failed to stop and clean up'), manually delete residual resources: kubectl delete deploy,svc,cm -l app=<clusterId>.

Example fix

// before
cfg.setString(KubernetesConfigOptions.CONTAINER_IMAGE, "flink:latest");
// after: pin a pullable image and namespace with proper RBAC
cfg.setString(KubernetesConfigOptions.CONTAINER_IMAGE, "apache/flink:1.17.1");
cfg.setString(KubernetesConfigOptions.NAMESPACE, "flink-prod");
descriptor.deployApplicationCluster(spec, appConfig);

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: RBAC + quota sanity
kubeClient.getService(KubernetesService.ServiceType.REST_SERVICE, clusterId); // proves service creation permissions

Try / catch

try {
    descriptor.deployApplicationCluster(spec, appConfig);
} catch (ClusterDeploymentException e) {
    LOG.error("Deploy failed for {}", clusterId, e.getCause());
    // cleanup residual resources, fix RBAC/quota/image, retry
}

Prevention

Grant deploy/service/configmap RBAC to the Flink service account
Pin valid, pullable container images
Check namespace ResourceQuotas before large deployments
kubectl get events to catch scheduling/image errors early

When it happens

Trigger: deployClusterInternal (reached from deploySessionCluster/deployApplicationCluster) when creating Kubernetes resources throws — e.g. fabric8/kube client API errors, quota exceeded, image pull failures, invalid pod templates.

Common situations: Insufficient namespace RBAC to create deployments/services; resource quota limits exceeded; invalid or non-pullable JobManager image (kubernetes.container-image); malformed pod template configuration; Kubernetes API server unreachable.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

AI-assisted analysis of zhisheng17/flink-learning@d731cee761 (2026-09-06). Data as JSON: /api/errors/468206d0dcd5bf09. Report an issue: GitHub.