Document workaround for Kubernetes IPv6 Clusters using KubernetesClient

README.md

@@ -36,6 +36,7 @@ This client provides access to the full [Kubernetes](http://kubernetes.io/) &
 - [Kubernetes and Red Hat OpenShift Compatibility Matrix](#compatibility-matrix)
 - [Kubernetes Client CHEAT SHEET](https://github.com/fabric8io/kubernetes-client/blob/master/doc/CHEATSHEET.md)
 - [Kubectl Java Equivalents](#kubectl-java-equivalents)
+- [FAQs](doc/FAQ.md)
 
 ## Usage
 

doc/FAQ.md

@@ -0,0 +1,6 @@
+# Frequently Asked Questions:
+
+### How do I use KubernetesClient with IPv6 Kubernetes Clusters?
+We're aware of this [issue](https://github.com/fabric8io/kubernetes-client/issues/2632) in Fabric8 Kubernetes Client. Unfortunately, this is caused by the OkHttp transitive dependency. You can check suggested workaround here:
+
+[Using KubernetesClient with IPv6 based Kubernetes Clusters](./KubernetesClientWithIPv6Clusters.md)

doc/KubernetesClientWithIPv6Clusters.md

@@ -0,0 +1,43 @@
+# Using KubernetesClient with IPv6 based Kubernetes Clusters
+
+Right now Fabric8 Kubernetes Client doesn't work with IPv6 based Kubernetes Clusters due to an issue in OkHttp [square/okhttp#5889](https://github.com/square/okhttp/pull/5889). The issue is solved for OkHttp 4, but Fabric8 Kubernetes Client depends on OkHttp 3.x.
+
+We have decided **not** to upgrade to OkHttp 4.x, because it's based on Kotlin ([square/okhttp#4723](https://github.com/square/okhttp/issues/4723)) and this might be an issue for downstream and dependent projects .
+
+We're still discussing a proper replacement for OkHttp ([#2764](https://github.com/fabric8io/kubernetes-client/issues/2764), [#2632](https://github.com/fabric8io/kubernetes-client/issues/2632)). In the meantime you can switch to use OkHttp 4.x in your project by configuring 3.x exclusions and adding your own direct 4.x OkHttp dependencies ([since it's binary compatible](https://github.com/fabric8io/kubernetes-client/issues/2632#issuecomment-748434878)):
+```xml
+<properties>
+    <fabric8.version>5.5.0</fabric8.version>
+    <okhttp.version>4.9.0</okhttp.version>
+</properties>
+
+<dependencies>
+    <dependency>
+        <groupId>io.fabric8</groupId>
+        <artifactId>kubernetes-client</artifactId>
+        <version>${fabric8.version}</version>
+        <exclusions>
+            <exclusion>
+                <groupId>com.squareup.okhttp3</groupId>
+                <artifactId>okhttp</artifactId>
+            </exclusion>
+            <exclusion>
+                <groupId>com.squareup.okhttp3</groupId>
+                <artifactId>logging-interceptor</artifactId>
+            </exclusion>
+        </exclusions>
+    </dependency>
+    <dependency>
+        <groupId>com.squareup.okhttp3</groupId>
+        <artifactId>okhttp</artifactId>
+        <version>${okhttp.version}</version>
+    </dependency>
+    <dependency>
+        <groupId>com.squareup.okhttp3</groupId>
+        <artifactId>logging-interceptor</artifactId>
+        <version>${okhttp.version}</version>
+    </dependency>
+</dependencies>
+```
+
+You can find an example demo project [here](https://github.com/rohankanojia-forks/fabric8-okhttp-ipv6-k8s-cluster-bug-reproducer).