feat: support kubeconfig from string

Dockerfile

@@ -42,7 +42,7 @@ RUN mkdir -p /build/helm_sdkpy/_lib/linux-amd64 && \
     cd shim && \
     go build -buildmode=c-shared \
         -o /build/helm_sdkpy/_lib/linux-amd64/libhelm_sdkpy.so \
-        main.go
+        .
 
 # Verify the shared library was built
 RUN ls -lh /build/helm_sdkpy/_lib/linux-amd64/libhelm_sdkpy.so && \

README.md

@@ -138,6 +138,50 @@ chart_path="https://charts.bitnami.com/bitnami/nginx-15.0.0.tgz"
 chart_path="https://example.com/charts/myapp-1.2.3.tgz"
 ```
 
+## 🔧 Kubeconfig Configuration
+
+helm-sdkpy provides flexible options for configuring Kubernetes cluster access:
+
+### Default Kubeconfig
+```python
+# Uses $KUBECONFIG env var or ~/.kube/config
+config = helm_sdkpy.Configuration(namespace="default")
+```
+
+### File Path
+```python
+# Explicit path to kubeconfig file
+config = helm_sdkpy.Configuration(
+    namespace="default",
+    kubeconfig="/path/to/kubeconfig.yaml"
+)
+```
+
+### YAML String
+Pass kubeconfig content directly as a string - useful for dynamic configurations, secrets, or CI/CD environments:
+```python
+# Kubeconfig from environment variable
+kubeconfig_content = os.environ.get("KUBECONFIG_CONTENT")
+
+# Or read from a secret, API response, etc.
+config = helm_sdkpy.Configuration(
+    namespace="default",
+    kubeconfig=kubeconfig_content  # YAML string auto-detected
+)
+```
+
+### Specific Context
+```python
+# Use a specific context from multi-cluster kubeconfig
+config = helm_sdkpy.Configuration(
+    namespace="production",
+    kubeconfig="/path/to/kubeconfig.yaml",
+    kubecontext="production-cluster"
+)
+```
+
+See [examples/kubeconfig_usage.py](examples/kubeconfig_usage.py) for more detailed examples.
+
 ## 📖 API Overview
 
 ### Core Actions (All Async)

examples/kubeconfig_usage.py

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+# Copyright 2025 Vantage Compute
+#
+# 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.
+
+"""
+Kubeconfig Usage Example
+
+This example demonstrates different ways to configure kubeconfig in helm-sdkpy:
+1. Using the default kubeconfig (~/.kube/config or $KUBECONFIG)
+2. Using an explicit file path
+3. Using a kubeconfig YAML string directly
+
+The kubeconfig string approach is particularly useful when:
+- Working with dynamic or programmatically generated configurations
+- Retrieving kubeconfig from Kubernetes secrets, environment variables, or APIs
+- Working in containerized environments where file access may be limited
+"""
+
+import asyncio
+import os
+from pathlib import Path
+
+import helm_sdkpy
+
+
+async def example_default_kubeconfig():
+    """Example 1: Use default kubeconfig location.
+
+    This uses $KUBECONFIG environment variable if set,
+    otherwise falls back to ~/.kube/config.
+    """
+    print("=" * 60)
+    print("Example 1: Default Kubeconfig")
+    print("=" * 60)
+
+    # When kubeconfig is None, uses default locations
+    config = helm_sdkpy.Configuration(
+        namespace="default",
+        # kubeconfig=None uses default: $KUBECONFIG or ~/.kube/config
+    )
+
+    # List releases to verify connection
+    list_action = helm_sdkpy.List(config)
+    releases = await list_action.run()
+    print(f"Found {len(releases)} releases in default namespace")
+
+    return config
+
+
+async def example_kubeconfig_filepath():
+    """Example 2: Use explicit kubeconfig file path.
+
+    Useful when you have multiple kubeconfig files for different clusters.
+    """
+    print("\n" + "=" * 60)
+    print("Example 2: Kubeconfig from File Path")
+    print("=" * 60)
+
+    # Specify an explicit path to a kubeconfig file
+    kubeconfig_path = os.path.expanduser("~/.kube/config")
+
+    # Or use a different file for a specific cluster
+    # kubeconfig_path = "/path/to/production-cluster.yaml"
+    # kubeconfig_path = "/etc/rancher/k3s/k3s.yaml"
+
+    config = helm_sdkpy.Configuration(
+        namespace="kube-system",
+        kubeconfig=kubeconfig_path,
+    )
+
+    # List releases in kube-system namespace
+    list_action = helm_sdkpy.List(config)
+    releases = await list_action.run()
+    print(f"Found {len(releases)} releases in kube-system namespace")
+
+    return config
+
+
+async def example_kubeconfig_string():
+    """Example 3: Use kubeconfig YAML content as a string.
+
+    This is useful when:
+    - Retrieving kubeconfig from environment variables
+    - Loading from Kubernetes secrets
+    - Programmatically generating configurations
+    - Working in serverless or containerized environments
+    """
+    print("\n" + "=" * 60)
+    print("Example 3: Kubeconfig from String")
+    print("=" * 60)
+
+    # Example: Read kubeconfig content from a file into a string
+    # In practice, this could come from an environment variable,
+    # API response, Kubernetes secret, etc.
+
+    kubeconfig_path = os.path.expanduser("~/.kube/config")
+    if Path(kubeconfig_path).exists():
+        with open(kubeconfig_path, "r") as f:
+            kubeconfig_content = f.read()
+    else:
+        # Example kubeconfig YAML structure (won't work without real cluster)
+        kubeconfig_content = """
+apiVersion: v1
+kind: Config
+clusters:
+- cluster:
+    server: https://kubernetes.example.com:6443
+    certificate-authority-data: <base64-encoded-ca-cert>
+  name: my-cluster
+contexts:
+- context:
+    cluster: my-cluster
+    user: my-user
+    namespace: default
+  name: my-context
+current-context: my-context
+users:
+- name: my-user
+  user:
+    token: <your-token-here>
+"""
+
+    # Pass the YAML content directly as the kubeconfig parameter
+    # helm-sdkpy automatically detects if it's a file path or YAML content
+    config = helm_sdkpy.Configuration(
+        namespace="default",
+        kubeconfig=kubeconfig_content,  # YAML string, not a file path!
+    )
+
+    # List releases to verify connection
+    list_action = helm_sdkpy.List(config)
+    releases = await list_action.run()
+    print(f"Found {len(releases)} releases using kubeconfig string")
+
+    return config
+
+
+async def example_kubeconfig_from_env():
+    """Example 4: Load kubeconfig from environment variable.
+
+    Many CI/CD systems and container orchestrators provide kubeconfig
+    as an environment variable.
+    """
+    print("\n" + "=" * 60)
+    print("Example 4: Kubeconfig from Environment Variable")
+    print("=" * 60)
+
+    # Common patterns for kubeconfig in environment variables:
+    # - KUBECONFIG_CONTENT: Full YAML content
+    # - KUBECONFIG_BASE64: Base64-encoded YAML content
+
+    import base64
+
+    kubeconfig_content = None
+
+    # Try getting YAML content directly
+    if "KUBECONFIG_CONTENT" in os.environ:
+        kubeconfig_content = os.environ["KUBECONFIG_CONTENT"]
+        print("Loaded kubeconfig from KUBECONFIG_CONTENT env var")
+
+    # Try getting base64-encoded content (common in CI/CD)
+    elif "KUBECONFIG_BASE64" in os.environ:
+        kubeconfig_content = base64.b64decode(
+            os.environ["KUBECONFIG_BASE64"]
+        ).decode("utf-8")
+        print("Loaded kubeconfig from KUBECONFIG_BASE64 env var")
+
+    # Fall back to file path from KUBECONFIG env var
+    elif "KUBECONFIG" in os.environ:
+        kubeconfig_path = os.environ["KUBECONFIG"]
+        print(f"Using kubeconfig file from KUBECONFIG env var: {kubeconfig_path}")
+        config = helm_sdkpy.Configuration(
+            namespace="default",
+            kubeconfig=kubeconfig_path,
+        )
+        list_action = helm_sdkpy.List(config)
+        releases = await list_action.run()
+        print(f"Found {len(releases)} releases")
+        return config
+
+    else:
+        print("No kubeconfig environment variable found")
+        print("Set KUBECONFIG_CONTENT, KUBECONFIG_BASE64, or KUBECONFIG")
+        return None
+
+    # Use the content string directly
+    config = helm_sdkpy.Configuration(
+        namespace="default",
+        kubeconfig=kubeconfig_content,
+    )
+
+    list_action = helm_sdkpy.List(config)
+    releases = await list_action.run()
+    print(f"Found {len(releases)} releases")
+
+    return config
+
+
+async def example_kubeconfig_with_context():
+    """Example 5: Use kubeconfig with specific context.
+
+    When your kubeconfig has multiple contexts (clusters), you can
+    specify which one to use.
+    """
+    print("\n" + "=" * 60)
+    print("Example 5: Kubeconfig with Specific Context")
+    print("=" * 60)
+
+    kubeconfig_path = os.path.expanduser("~/.kube/config")
+
+    # Specify both the kubeconfig file and the context to use
+    config = helm_sdkpy.Configuration(
+        namespace="default",
+        kubeconfig=kubeconfig_path,
+        kubecontext="my-cluster-context",  # Use a specific context
+    )
+
+    print(f"Using kubeconfig: {kubeconfig_path}")
+    print(f"Using context: my-cluster-context")
+
+    # This would fail if the context doesn't exist
+    # list_action = helm_sdkpy.List(config)
+    # releases = await list_action.run()
+
+    return config
+
+
+async def main():
+    """Run all kubeconfig usage examples."""
+    print("helm-sdkpy Kubeconfig Usage Examples")
+    print("=" * 60)
+    print(f"helm-sdkpy version: {helm_sdkpy.__version__}")
+
+    try:
+        print(f"Library version: {helm_sdkpy.get_version()}")
+    except helm_sdkpy.HelmLibraryNotFound:
+        print("\nLibrary not found - please build the library first with 'just build-lib'")
+        return
+
+    # Run examples that work with available kubeconfig
+    try:
+        await example_default_kubeconfig()
+    except Exception as e:
+        print(f"Example 1 failed (expected if no cluster): {e}")
+
+    try:
+        await example_kubeconfig_filepath()
+    except Exception as e:
+        print(f"Example 2 failed (expected if no cluster): {e}")
+
+    try:
+        await example_kubeconfig_string()
+    except Exception as e:
+        print(f"Example 3 failed (expected if no cluster): {e}")
+
+    try:
+        await example_kubeconfig_from_env()
+    except Exception as e:
+        print(f"Example 4 failed (expected if no env vars set): {e}")
+
+    print("\n" + "=" * 60)
+    print("Summary: Kubeconfig Configuration Options")
+    print("=" * 60)
+    print("""
+Configuration(namespace, kubeconfig, kubecontext) parameters:
+
+1. kubeconfig=None (default)
+   - Uses $KUBECONFIG environment variable if set
+   - Falls back to ~/.kube/config
+
+2. kubeconfig="/path/to/config.yaml"
+   - Uses explicit file path to kubeconfig
+
+3. kubeconfig="apiVersion: v1\\nkind: Config\\n..."
+   - YAML content passed directly as a string
+   - Auto-detected by looking for apiVersion:, kind:, or clusters: markers
+   - Useful for dynamic configurations, secrets, or environment variables
+
+4. kubecontext="my-context"
+   - Select a specific context from the kubeconfig
+   - Works with both file paths and string content
+""")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())