feat: add diagnostic hint log when driver cannot reach kube-apiserver on startup

/kind feature

**What this PR does / why we need it**:

Motivation:
When the driver fails to start because it cannot reach the kube-apiserver
(e.g. RESTMapper/discovery client construction in ctrl.NewManager, or cache
sync in mgr.Start failing due to DNS, connection refused, or timeouts), the
existing logs ("failed to start manager", "failed to run manager") give no
hint about the likely root cause. Issue #1753 reports exactly this: a driver
pod failed to initialize with only a generic wrapped error, with no guidance
that network connectivity to the kube-apiserver should be checked.

Approach:
Add an `isNetworkError` helper in cmd/secrets-store-csi-driver/main.go that
classifies an error as network-related if it unwraps to a `net.Error` (covers
`*net.DNSError`, `*net.OpError`, etc.) or its message contains one of a small
set of well-known connectivity failure substrings ("connection refused", "no
such host", "i/o timeout", "context deadline exceeded"). When this helper
returns true at the two manager-startup failure points, an additional
klog.ErrorS call logs: "the driver is unable to communicate with the
kube-apiserver, check network connectivity between the node and the
kube-apiserver". This mirrors the existing isMaxRecvMsgSizeError pattern in
pkg/secrets-store/provider_client.go.

This change is purely additive: it does not alter control flow, return
values, exit codes, or any existing log message. The original error is still
logged and returned/panicked exactly as before; only an extra diagnostic log
line is emitted when the error looks network-related. User-visible behavior
(pod restarts on manager start failure) is unchanged before/after this fix —
the benefit is a clearer, more actionable log line for operators debugging a
non-starting driver pod, not a change in recovery behavior.

Validation:
- `go build ./...` passes.
- `go test ./cmd/... -v` passes, including the new table-driven
  TestIsNetworkError covering nil errors, unrelated errors, wrapped
  net.DNSError, and each of the matched substring cases.
- `gofmt -l` and `go vet ./cmd/...` report no issues.

Signed-off-by: Pujitha Paladugu <10557236+pujitha24@users.noreply.github.com>

Author: pujitha24

cmd/secrets-store-csi-driver/main.go

@@ -18,8 +18,10 @@ package main
 
 import (
 	"context"
+	"errors"
 	"flag"
 	"fmt"
+	"net"
 	"net/http"
 	_ "net/http/pprof" // #nosec
 	"strings"
@@ -160,6 +162,9 @@ func mainErr() error {
 	})
 	if err != nil {
 		klog.ErrorS(err, "failed to start manager")
+		if isNetworkError(err) {
+			klog.ErrorS(err, "the driver is unable to communicate with the kube-apiserver, check network connectivity between the node and the kube-apiserver")
+		}
 		return err
 	}
 
@@ -190,6 +195,9 @@ func mainErr() error {
 		klog.Info("starting manager")
 		if err := mgr.Start(ctx); err != nil {
 			klog.ErrorS(err, "failed to run manager")
+			if isNetworkError(err) {
+				klog.ErrorS(err, "the driver is unable to communicate with the kube-apiserver, check network connectivity between the node and the kube-apiserver")
+			}
 			panic(err)
 		}
 	}()
@@ -229,3 +237,21 @@ func getKlogLevel() klog.Level {
 
 	return -1
 }
+
+// isNetworkError returns true if err looks like it originates from a failure
+// to reach the kube-apiserver (DNS resolution, connection refused, timeout,
+// etc.), as opposed to some other manager startup failure.
+func isNetworkError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var netErr net.Error
+	if errors.As(err, &netErr) {
+		return true
+	}
+	msg := err.Error()
+	return strings.Contains(msg, "connection refused") ||
+		strings.Contains(msg, "no such host") ||
+		strings.Contains(msg, "i/o timeout") ||
+		strings.Contains(msg, "context deadline exceeded")
+}

cmd/secrets-store-csi-driver/main_test.go

@@ -0,0 +1,77 @@
+/*
+Copyright 2026 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"net"
+	"testing"
+)
+
+func TestIsNetworkError(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		want bool
+	}{
+		{
+			name: "nil error",
+			err:  nil,
+			want: false,
+		},
+		{
+			name: "unrelated error",
+			err:  errors.New("failed to create controller"),
+			want: false,
+		},
+		{
+			name: "wrapped net.Error",
+			err:  fmt.Errorf("could not create RESTMapper from config: %w", &net.DNSError{Err: "no such host", Name: "kubernetes.default.svc", IsNotFound: true}),
+			want: true,
+		},
+		{
+			name: "connection refused string",
+			err:  errors.New("Get \"https://10.0.0.1:443/api\": dial tcp 10.0.0.1:443: connect: connection refused"),
+			want: true,
+		},
+		{
+			name: "no such host string",
+			err:  errors.New("dial tcp: lookup kubernetes.default.svc: no such host"),
+			want: true,
+		},
+		{
+			name: "i/o timeout string",
+			err:  errors.New("dial tcp 10.0.0.1:443: i/o timeout"),
+			want: true,
+		},
+		{
+			name: "context deadline exceeded string",
+			err:  errors.New("Get \"https://10.0.0.1:443/api\": context deadline exceeded"),
+			want: true,
+		},
+	}
+
+	for _, test := range cases {
+		t.Run(test.name, func(t *testing.T) {
+			got := isNetworkError(test.err)
+			if got != test.want {
+				t.Errorf("isNetworkError() = %v, want %v", got, test.want)
+			}
+		})
+	}
+}