feat(docs): update readme

Author: itcaat

.github/images/image01.png

@@ -1,41 +1,41 @@
 [![Terraform Apply](https://github.com/itcaat/terraform-kubernetes-desktop-startkit/actions/workflows/k8s.yml/badge.svg)](https://github.com/itcaat/terraform-kubernetes-desktop-startkit/actions/workflows/k8s.yml)
 
-# 🚀 Terraform Kubernetes — Starter Kit for Docker Desktop
+# Terraform Kubernetes — Starter Kit for Docker Desktop
 
 This starter kit is designed for local Kubernetes experimentation using Terraform. It provides a preconfigured setup with certificate management, ingress routing, and load balancing, making it easy to test, learn, and prototype cloud-native deployments.
 
-![alt text](image-1.png)
+![alt text](.github/images/image01.png)
 
-## 👨‍💻 Who is it for?
+## Who is it for?
 - DevOps Engineers & SREs who want a sandbox for testing infrastructure automation.
 - Developers exploring Kubernetes deployments without cloud costs.
 - Teams learning Terraform and Kubernetes best practices in a safe, local environment.
 
-## 📂 Project Structure
+## Project Structure
 
 ### **Environments**
 - `envs/local` - Local Environment. You can use Docker Desktop for local usage.
 
 ### **Modules**
 Each service is managed as a separate module for better reusability and organization.
 
-#### **📁 modules/metallb**
+#### **modules/metallb**
 - Deploys **MetalLB** via Helm.
 - Configures **IP address pools** dynamically using `kubectl_manifest`.
 
-#### **📁 modules/cert-manager**
+#### **modules/cert-manager**
 - Installs **Cert-Manager** using Helm.
 
-#### **📁 modules/ingress-nginx**
+#### **modules/ingress-nginx**
 - Deploys **Ingress-Nginx** as a controller for managing ingress traffic.
 
-#### **📁 modules/cluster-issuer-selfsigned**
+#### **modules/cluster-issuer-selfsigned**
 - Creates a **ClusterIssuer** and a self-signed CA certificate.
 
-#### **📁 modules/cluster-issuer-production**
+#### **modules/cluster-issuer-production**
 - Creates a **ClusterIssuer** that uses letsencrypt .
 
-#### **📁 modules/echo-server**
+#### **modules/echo-server**
 - Deploys **Echo Server** using Kubernetes manifests.
 - Configures an **Ingress resource** with self-signed TLS issued by Cert-Manager.
 
@@ -47,7 +47,7 @@ brew install mkcert
 mkcert -install
 ```
 
-## 🛠️ Setup and Deployment
+## Setup and Deployment
 
 The best way is fork the repo. But it's up to you.
 
@@ -91,17 +91,40 @@ The best way is fork the repo. But it's up to you.
    make tf-apply-approve
    ```
 
-6. **Verify resources in Kubernetes:**
+6. **Verify the deployment:**
+
+   Check that all pods are running:
    ```sh
    kubectl get pods -A
+   ```
+   All pods in `metallb-system`, `ingress-nginx`, `cert-manager`, and `demo` namespaces should be in `Running` status.
+
+   Check that services have received IP addresses:
+   ```sh
    kubectl get svc -A
+   ```
+   The `ingress-nginx-controller` service should have an `EXTERNAL-IP` assigned by MetalLB.
+
+   Check that ingress is created:
+   ```sh
    kubectl get ingress -A
    ```
 
-7. **Verify resources in Kubernetes:**
+   Check that the TLS certificate has been issued:
+   ```sh
+   kubectl get certificates -A
+   ```
+   The `READY` column should show `True`.
+
+   Send a request to the echo server:
    ```sh
    curl https://echo.127.0.0.1.nip.io
    ```
+   If the certificate is not trusted by the system, use the `-k` flag:
+   ```sh
+   curl -k https://echo.127.0.0.1.nip.io
+   ```
+   A JSON response from the echo server confirms the entire stack is working correctly.
 
 ### **Destroying the Infrastructure**
 To remove all deployed resources:
@@ -142,14 +165,190 @@ You can run basic validation for your Terraform configuration:
 make tf-test
 ```
 
-## 📌 Key Features
-✅ Modular architecture with separate Terraform modules.  
-✅ Uses Helm for package management.  
-✅ Configures self-signed certificates with Cert-Manager.  
-✅ Supports MetalLB for LoadBalancer services in local Kubernetes environments.  
-✅ Ingress-Nginx handles application routing.  
-✅ Secure and automated TLS handling via ClusterIssuer.  
+## Troubleshooting
+
+### Terraform asks for `cluster_issuer_selfsigned_ca_cert` interactively
+
+Terraform requires two environment variables for the self-signed CA. If they are not set, it will prompt for input.
+
+**Solution:** export the variables before running any Terraform command:
+```sh
+export TF_VAR_cluster_issuer_selfsigned_ca_cert="$(base64 < "$(mkcert -CAROOT)/rootCA.pem")"
+export TF_VAR_cluster_issuer_selfsigned_ca_key="$(base64 < "$(mkcert -CAROOT)/rootCA-key.pem")"
+```
+
+### Certificate is not trusted / `curl` returns SSL error
+
+When using `curl https://echo.127.0.0.1.nip.io` you may see:
+```
+curl: (60) SSL certificate problem: unable to get local issuer certificate
+```
+
+**Cause:** the mkcert root CA is not installed in the system trust store.
+
+**Solution:**
+```sh
+mkcert -install
+```
+This adds the mkcert CA to the system trust store. After that, `curl` and browsers will trust the certificate. As a quick workaround, use `curl -k` to skip verification.
+
+### Kubernetes is not running / `kubectl` cannot connect
+
+```
+The connection to the server localhost:6443 was refused
+```
+
+**Solution:** make sure Docker Desktop is running and Kubernetes is enabled in Docker Desktop settings (Settings > Kubernetes > Enable Kubernetes).
+
+### Ingress controller has no EXTERNAL-IP (shows `<pending>`)
+
+```sh
+kubectl get svc -n ingress-nginx
+# EXTERNAL-IP shows <pending>
+```
+
+**Cause:** MetalLB is not ready or the IP address pool is not configured.
+
+**Solution:**
+1. Check that MetalLB pods are running: `kubectl get pods -n metallb-system`
+2. Check the IPAddressPool resource: `kubectl get ipaddresspool -n metallb-system`
+3. Try redeploying: `make tf-recreate`
+
+### Certificate is not issued (READY is False)
+
+```sh
+kubectl get certificates -A
+# READY shows False
+```
+
+**Solution:** check the certificate request status and cert-manager logs:
+```sh
+kubectl describe certificaterequest -A
+kubectl logs -n cert-manager -l app.kubernetes.io/name=cert-manager
+```
+Common cause: cert-manager pods are not ready yet. Wait a minute and check again.
+
+### ClusterIssuer is not ready
+
+```sh
+kubectl get clusterissuer
+# READY shows False
+```
+
+**Cause:** the CA secret is missing or contains invalid data. This usually happens when `TF_VAR_cluster_issuer_selfsigned_ca_cert` or `TF_VAR_cluster_issuer_selfsigned_ca_key` were set with incorrect values (e.g. double base64 encoding, empty string, or wrong file path).
+
+**Diagnosis:**
+```sh
+kubectl describe clusterissuer selfsigned
+kubectl get secret selfsigned-ca -n cert-manager -o yaml
+```
+
+**Solution:** make sure the variables contain a single base64-encoded value:
+```sh
+# Check that mkcert CA files exist
+ls "$(mkcert -CAROOT)"
+
+# Re-export with correct values
+export TF_VAR_cluster_issuer_selfsigned_ca_cert="$(base64 < "$(mkcert -CAROOT)/rootCA.pem")"
+export TF_VAR_cluster_issuer_selfsigned_ca_key="$(base64 < "$(mkcert -CAROOT)/rootCA-key.pem")"
+
+# Reapply
+make tf-apply-approve
+```
+
+### Certificate issued but browser still shows "Not Secure"
+
+The certificate is valid inside the cluster (`kubectl get certificates` shows `True`), but the browser shows a security warning.
+
+**Cause:** the CA that signed the certificate is not trusted by your OS/browser. The cluster uses mkcert's root CA, which must be installed locally.
+
+**Solution:**
+```sh
+# Install mkcert CA into system trust store
+mkcert -install
+
+# Verify it's installed
+mkcert -CAROOT
+```
+After this, restart the browser. On macOS, you can also verify in Keychain Access — look for "mkcert" in the System keychain.
+
+### Certificate error only in specific namespace
+
+If the certificate works in one namespace but not another, the issue is likely a missing or misconfigured Ingress annotation.
+
+**Check** that your Ingress has the correct annotation:
+```yaml
+annotations:
+  cert-manager.io/cluster-issuer: selfsigned
+```
+
+**Verify** the certificate and secret exist in the correct namespace:
+```sh
+kubectl get certificates -n <namespace>
+kubectl get secrets -n <namespace> | grep tls
+```
+
+### Wrong certificate served / `SSL: no alternative certificate subject name matches`
+
+```
+curl: (60) SSL: no alternative certificate subject name matches target host name 'echo.127.0.0.1.nip.io'
+```
+
+The certificate inside Kubernetes is correct, but `curl` receives a different one.
+
+**Cause:** another Docker container or service is occupying ports 80/443 on the host, intercepting traffic before it reaches the Kubernetes ingress controller.
+
+**Diagnosis:**
+```sh
+docker ps | grep -E "0.0.0.0:(80|443)"
+```
+
+**Solution:** stop the conflicting container and restart the ingress controller:
+```sh
+docker stop <container-name>
+kubectl rollout restart deployment ingress-nginx-controller -n ingress-nginx
+```
+
+### `terraform init` fails with provider errors
+
+**Solution:** make sure you have Terraform >= 1.5.0 installed:
+```sh
+terraform version
+```
+Then retry with:
+```sh
+make tf-init
+```
+
+### Pods stuck in `ContainerCreating` or `CrashLoopBackOff`
+
+**Solution:** inspect the pod events:
+```sh
+kubectl describe pod <pod-name> -n <namespace>
+kubectl logs <pod-name> -n <namespace>
+```
+Common causes: image pull issues (check internet connection), resource limits exceeded in Docker Desktop (increase memory/CPU in Docker Desktop settings).
+
+### Need a completely fresh start
+
+If nothing helps, do a full reset — this destroys all resources, deletes state, and recreates everything from scratch:
+```sh
+make tf-reset
+```
+
+> For a detailed step-by-step guide, see [docs/getting-started.md](docs/getting-started.md).
+
+## Key Features
+- Modular architecture with separate Terraform modules.  
+- Uses Helm for package management.  
+- Configures self-signed certificates with Cert-Manager.  
+- Supports MetalLB for LoadBalancer services in local Kubernetes environments.  
+- Ingress-Nginx handles application routing.  
+- Secure and automated TLS handling via ClusterIssuer.  
+
+---
+**Contributions & Issues**
+If you encounter any issues or have suggestions for improvements, feel free to contribute or raise an issue!
 
 ---
-📢 **Contributions & Issues**
-If you encounter any issues or have suggestions for improvements, feel free to contribute or raise an issue! 🚀
+[Русская версия README](README.ru.md)