use kube-authkit for better k8s authentication

README.md

@@ -17,6 +17,86 @@ Full documentation can be found [here](https://project-codeflare.github.io/codef
 
 Can be installed via `pip`: `pip install codeflare-sdk`
 
+## Authentication
+
+CodeFlare SDK uses [kube-authkit](https://github.com/opendatahub-io/kube-authkit) for Kubernetes authentication, supporting multiple authentication methods:
+
+- **Auto-Detection** - Automatically detects kubeconfig or in-cluster authentication
+- **Token-Based** - Authenticate with API server token
+- **OIDC** - OpenID Connect authentication with device flow or client credentials
+- **OpenShift OAuth** - Native OpenShift OAuth support
+- **Kubeconfig** - Traditional kubeconfig file authentication
+- **In-Cluster** - Service account authentication when running in a pod
+
+### Quick Start
+
+```python
+from kube_authkit import get_k8s_client, AuthConfig
+from codeflare_sdk import set_api_client, Cluster, ClusterConfiguration
+
+# Option 1: Auto-detect authentication (recommended - no explicit auth needed!)
+cluster = Cluster(ClusterConfiguration(
+    name='my-cluster',
+    num_workers=2,
+))
+cluster.apply()
+
+# Option 2: OIDC authentication
+auth_config = AuthConfig(
+    method="oidc",
+    oidc_issuer="https://your-oidc-provider.com",
+    client_id="your-client-id",
+    use_device_flow=True
+)
+api_client = get_k8s_client(config=auth_config)
+set_api_client(api_client)  # Register with CodeFlare SDK
+
+# Option 3: OpenShift OAuth with token
+auth_config = AuthConfig(
+    k8s_api_host="https://api.example.com:6443",
+    token="your-token"
+)
+api_client = get_k8s_client(config=auth_config)
+set_api_client(api_client)  # Register with CodeFlare SDK
+
+# Now create your cluster
+cluster = Cluster(ClusterConfiguration(
+    name='my-cluster',
+    num_workers=2,
+))
+cluster.apply()
+```
+
+### Migration from Legacy Authentication
+
+If you're using the deprecated `TokenAuthentication` or `KubeConfigFileAuthentication` classes, please see our [Migration Guide](./docs/auth_migration_guide.md) for detailed instructions on updating to kube-authkit.
+
+**Legacy classes (deprecated):**
+```python
+# ⚠️ Deprecated - will be removed in v1.0.0
+from codeflare_sdk import TokenAuthentication
+auth = TokenAuthentication(token="...", server="...")
+auth.login()
+```
+
+**New recommended approach:**
+```python
+# ✅ Recommended - Auto-detection (no explicit auth needed!)
+from codeflare_sdk import Cluster, ClusterConfiguration
+cluster = Cluster(ClusterConfiguration(name="my-cluster"))
+
+# ✅ For OIDC or OpenShift OAuth with token
+from kube_authkit import AuthConfig, get_k8s_client
+from codeflare_sdk import set_api_client
+
+auth_config = AuthConfig(
+    k8s_api_host="https://api.example.com:6443",
+    token="your-token"
+)
+api_client = get_k8s_client(config=auth_config)
+set_api_client(api_client)  # Register with CodeFlare SDK
+```
+
 ## Development
 
 Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed instructions.