Add a more concrete eg of in-cluster config (#2324)

Co-authored-by: Aleksandr Rybolovlev <[email protected]>

Author: sheneska

_examples/in-cluster/README.md

@@ -1,25 +1,129 @@
 # Example: In-cluster
 
-Running terraform in a kubernetes cluster and using in-cluster config.
+Running Terraform in a Kubernetes cluster using in-cluster config.
 
-## Prerequisites
+## Steps
 
-*This example uses syntax elements specific to Terraform version 0.12+.
-It will not work out-of-the-box with Terraform 0.11.x and lower.*
+Executing Terraform in a Kubernetes cluster using an in-cluster config would require a service account with appropriate privileges attached to the Pod where Terraform is running.
 
+Below are the necessary steps to create a new service account `terraform` and grant permissions to create a Pod in a `default` namespace using the `kubernetes_pod_v1` Terraform resource as a namespaced resource example.
 
-Standard run:
+1. Create a new service account:
 
-```
-# terraform apply \
-  -var "minikube_host_ip=$(minikube --profile kubernetes-1.16 ip)"
-```
+    ```yaml
+    apiVersion: v1
+    kind: ServiceAccount
+    metadata:
+      name: terraform
+    ```
 
-With a custom build:
+1. Create a Role to grant permissions that are enought to manage Pods via Terraform:
 
-```
-# terraform apply \
-  -var "minikube_host_ip=$(minikube --profile kubernetes-1.16 ip)" \
-  -var "in_cluster_provider_version=v1.10.1-dev" \
-  -var "in_cluster_provider_url=https://storage.googleapis.com/my-custom-bucket/terraform-provider-kubernetes"
-```
+    ```yaml
+    apiVersion: rbac.authorization.k8s.io/v1
+    kind: Role
+    metadata:
+      name: terraform
+    rules:
+    - apiGroups:
+      - ""
+      resources:
+      - pods
+      verbs:
+      - create
+      - get
+      - delete
+      - patch
+    ```
+
+1. Create a RoleBinding to attach service account `terraform` to the target Role:
+
+    ```yaml
+    apiVersion: rbac.authorization.k8s.io/v1
+    kind: RoleBinding
+    metadata:
+      name: terraform
+    roleRef:
+      apiGroup: rbac.authorization.k8s.io
+      kind: Role
+      name: terraform
+    subjects:
+    - kind: ServiceAccount
+      name: terraform
+    ```
+
+1. Create a Pod that will initialize and apply Terraform code:
+
+    ```yaml
+    apiVersion: v1
+    kind: Pod
+    metadata:
+      name: terraform
+    spec:
+      serviceAccount: terraform
+      initContainers:
+        - name: init
+          image: "hashicorp/terraform"
+          command: [ "terraform", "-chdir=/terraform", "init" ]
+          volumeMounts:
+          - name: terraform
+            mountPath: /terraform
+      containers:
+        - name: apply
+          image: "hashicorp/terraform"
+          command: [ "terraform", "-chdir=/terraform", "apply", "-auto-approve" ]
+          volumeMounts:
+          - name: terraform
+            mountPath: /terraform
+      volumes:
+        - name: terraform
+          persistentVolumeClaim:
+            claimName: terraform
+      restartPolicy: Never
+    ```
+
+Terraform code example that will work with the above configuration resides in files [`provider.tf`](provider.tf) and [`pod.tf`](pod.tf). As you can see, the provider configuration block is empty. In this case, all the necessary privileges are granted via the service account.
+
+Let's extend the previous example with privileges that are enough to create a Namespace using the `kubernetes_namespace_v1` Terraform resource as a cluster-level resource example.
+
+1. Create a ClusterRole to grant permissions that are enought to manage Pods via Terraform:
+
+    ```yaml
+    apiVersion: rbac.authorization.k8s.io/v1
+    kind: ClusterRole
+    metadata:
+      name: terraform
+    rules:
+    - apiGroups:
+      - ""
+      resources:
+      - namespaces
+      verbs:
+      - create
+      - get
+      - delete
+      - list
+      - patch
+      - update
+    ```
+
+1. Create a ClusterRoleBinding to attach service account `terraform` to the target ClusterRole:
+
+    ```yaml
+    apiVersion: rbac.authorization.k8s.io/v1
+    kind: ClusterRoleBinding
+    metadata:
+      name: terraform
+    roleRef:
+      apiGroup: rbac.authorization.k8s.io
+      kind: ClusterRole
+      name: terraform
+    subjects:
+    - kind: ServiceAccount
+      name: terraform
+      namespace: default
+    ```
+
+Terraform code example can be extanded with [`namespace.tf`](namespace.tf) file. To apply changes restart the Pod where Terraform is running.
+
+Please, always consult with the security team and follow the guidance accepted in your organization when granting RBAC privileges in a Kubernetes cluster.

_examples/in-cluster/main.tf

@@ -0,0 +1,8 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+resource "kubernetes_namespace_v1" "this" {
+  metadata {
+    name = "this"
+  }
+}

_examples/in-cluster/namespace.tf

@@ -0,0 +1,16 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+resource "kubernetes_pod_v1" "this" {
+  metadata {
+    name      = "this"
+    namespace = "default"
+  }
+  spec {
+    container {
+      name    = "this"
+      image   = "busybox"
+      command = ["sleep", "infinity"]
+    }
+  }
+}

_examples/in-cluster/pod.tf

@@ -0,0 +1,4 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+provider "kubernetes" {}

_examples/in-cluster/provider.tf

@@ -112,6 +112,8 @@ The provider uses the `KUBERNETES_SERVICE_HOST` and `KUBERNETES_SERVICE_PORT` en
 
 If you want to connect to a different cluster than the one terraform is running inside, configure the provider as [above](#credentials-config).
 
+Find more comprehensive `in-cluster` config example [here](https://github.com/hashicorp/terraform-provider-kubernetes/tree/main/_examples/in-cluster).
+
 ## Exec plugins
 
 Some cloud providers have short-lived authentication tokens that can expire relatively quickly. To ensure the Kubernetes provider is receiving valid credentials, an exec-based plugin can be used to fetch a new token before initializing the provider. For example, on EKS, the command `eks get-token` can be used: