revert provider docs to previous version

Signed-off-by: Sebastian Hoß <[email protected]>

docs/index.md

@@ -10,16 +10,111 @@ description: |-
 
 Provider for [Kubernetes](https://kubernetes.io/) resources using [server-side apply](https://kubernetes.io/docs/reference/using-api/server-side-apply/). Requires Terraform 1.0 or later.
 
+This provider only deals with creating Kubernetes manifests. In order to apply those manifests to a running cluster use
+other providers like the [kubectl provider](https://registry.terraform.io/providers/gavinbunney/kubectl/).
+
 All resources of this provider are automatically generated based on the OpenAPI schemas provided by the [Kubernetes](https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec)
 project itself or embedded into custom resource definitions of the various upstream projects. We are happy to accept
 additional schemas in either OpenAPIv2/OpenAPIv3 or CRDv1 format!
 
-**NOTE: THIS IS ALPHA QUALITY - USE AT YOUR OWN RISK - BEWARE OF SHARKS**
-
 ## Example Usage
 
 ```terraform
 provider "k8s" {
   # requires no configuration at the moment
 }
 ```
+
+### terraform-provider-kubectl
+
+The [kubectl provider](https://registry.terraform.io/providers/gavinbunney/kubectl/) offers the [kubectl_manifest](https://registry.terraform.io/providers/gavinbunney/kubectl/latest/docs/resources/kubectl_manifest)
+resource which can be used to deploy the YAML manifests generated by this provider like this:
+
+```terraform
+# declare any resource from the k8s provider
+data "k8s_monitoring_coreos_com_pod_monitor_v1_manifest" "example" {
+  metadata = {
+    name = "example"
+  }
+  spec = {
+    pod_metrics_endpoints = [
+      {
+        path = "/metrics"
+        port = "metrics"
+      }
+    ]
+    selector = {
+      match_labels = {
+        "app.kubernetes.io/name" = "some-name"
+      }
+    }
+  }
+}
+
+# use the 'yaml' attribute as input for the kubectl provider
+resource "kubectl_manifest" "example" {
+  yaml_body = data.k8s_monitoring_coreos_com_pod_monitor_v1_manifest.example.yaml
+}
+```
+
+### terraform-provider-k8s (banzaicloud)
+
+The [k8s provider](https://registry.terraform.io/providers/banzaicloud/k8s/) by banzaicloud offers the [k8s_manifest](https://registry.terraform.io/providers/banzaicloud/k8s/latest/docs/resources/manifest)
+resource which can be used to deploy the YAML manifests generated by this provider as shown in the example below. Note
+that the provider by banzaicloud and this provider use the same name, thus you have to do extra work in order to resolve
+the [local name conflict](https://www.terraform.io/language/providers/requirements#handling-local-name-conflicts).
+
+```terraform
+terraform {
+  required_providers {
+    # define local alias banzaicloud provider
+    banzaicloud-k8s = {
+      source  = "banzaicloud/k8s"
+      version = "0.9.1"
+    }
+    # define another alias for metio provider
+    metio-k8s = {
+      source  = "metio/k8s"
+      version = "> 2024.3.30"
+    }
+  }
+}
+
+provider "banzaicloud-k8s" {
+  # Configuration options for banzaicloud's provider
+}
+provider "metio-k8s" {
+  # we need no configuration
+}
+
+# declare any resource from the k8s provider
+data "k8s_monitoring_coreos_com_pod_monitor_v1_manifest" "example" {
+  # be explicit about the provider to use
+  provider = metio-k8s
+
+  metadata = {
+    name = "example"
+  }
+  spec = {
+    pod_metrics_endpoints = [
+      {
+        path = "/metrics"
+        port = "metrics"
+      }
+    ]
+    selector = {
+      match_labels = {
+        "app.kubernetes.io/name" = "some-name"
+      }
+    }
+  }
+}
+
+# use the 'yaml' attribute as input for the k8s provider by banzaicloud
+resource "k8s_manifest" "example" {
+  # be explicit about the provider to use
+  provider = banzaicloud-k8s
+
+  content = data.k8s_monitoring_coreos_com_pod_monitor_v1_manifest.example.yaml
+}
+```

examples/provider/terraform-provider-k8s-banzaicloud.tf

@@ -0,0 +1,52 @@
+terraform {
+  required_providers {
+    # define local alias banzaicloud provider
+    banzaicloud-k8s = {
+      source  = "banzaicloud/k8s"
+      version = "0.9.1"
+    }
+    # define another alias for metio provider
+    metio-k8s = {
+      source  = "metio/k8s"
+      version = "> 2024.3.30"
+    }
+  }
+}
+
+provider "banzaicloud-k8s" {
+  # Configuration options for banzaicloud's provider
+}
+provider "metio-k8s" {
+  # we need no configuration
+}
+
+# declare any resource from the k8s provider
+data "k8s_monitoring_coreos_com_pod_monitor_v1_manifest" "example" {
+  # be explicit about the provider to use
+  provider = metio-k8s
+
+  metadata = {
+    name = "example"
+  }
+  spec = {
+    pod_metrics_endpoints = [
+      {
+        path = "/metrics"
+        port = "metrics"
+      }
+    ]
+    selector = {
+      match_labels = {
+        "app.kubernetes.io/name" = "some-name"
+      }
+    }
+  }
+}
+
+# use the 'yaml' attribute as input for the k8s provider by banzaicloud
+resource "k8s_manifest" "example" {
+  # be explicit about the provider to use
+  provider = banzaicloud-k8s
+
+  content = data.k8s_monitoring_coreos_com_pod_monitor_v1_manifest.example.yaml
+}

examples/provider/terraform-provider-kubectl.tf

@@ -0,0 +1,24 @@
+# declare any resource from the k8s provider
+data "k8s_monitoring_coreos_com_pod_monitor_v1_manifest" "example" {
+  metadata = {
+    name = "example"
+  }
+  spec = {
+    pod_metrics_endpoints = [
+      {
+        path = "/metrics"
+        port = "metrics"
+      }
+    ]
+    selector = {
+      match_labels = {
+        "app.kubernetes.io/name" = "some-name"
+      }
+    }
+  }
+}
+
+# use the 'yaml' attribute as input for the kubectl provider
+resource "kubectl_manifest" "example" {
+  yaml_body = data.k8s_monitoring_coreos_com_pod_monitor_v1_manifest.example.yaml
+}

templates/index.md.tmpl

@@ -10,15 +10,32 @@ description: |-
 
 {{ .Description | trimspace }}
 
+This provider only deals with creating Kubernetes manifests. In order to apply those manifests to a running cluster use
+other providers like the [kubectl provider](https://registry.terraform.io/providers/gavinbunney/kubectl/).
+
 All resources of this provider are automatically generated based on the OpenAPI schemas provided by the [Kubernetes](https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec)
 project itself or embedded into custom resource definitions of the various upstream projects. We are happy to accept
 additional schemas in either OpenAPIv2/OpenAPIv3 or CRDv1 format!
 
-**NOTE: THIS IS ALPHA QUALITY - USE AT YOUR OWN RISK - BEWARE OF SHARKS**
-
 {{ if .HasExample -}}
 ## Example Usage
 
 {{ tffile "examples/provider/provider.tf" }}
 
 {{- end }}
+
+### terraform-provider-kubectl
+
+The [kubectl provider](https://registry.terraform.io/providers/gavinbunney/kubectl/) offers the [kubectl_manifest](https://registry.terraform.io/providers/gavinbunney/kubectl/latest/docs/resources/kubectl_manifest)
+resource which can be used to deploy the YAML manifests generated by this provider like this:
+
+{{ tffile "examples/provider/terraform-provider-kubectl.tf" }}
+
+### terraform-provider-k8s (banzaicloud)
+
+The [k8s provider](https://registry.terraform.io/providers/banzaicloud/k8s/) by banzaicloud offers the [k8s_manifest](https://registry.terraform.io/providers/banzaicloud/k8s/latest/docs/resources/manifest)
+resource which can be used to deploy the YAML manifests generated by this provider as shown in the example below. Note
+that the provider by banzaicloud and this provider use the same name, thus you have to do extra work in order to resolve
+the [local name conflict](https://www.terraform.io/language/providers/requirements#handling-local-name-conflicts).
+
+{{ tffile "examples/provider/terraform-provider-k8s-banzaicloud.tf" }}