refactor(terraform): merge versions into main and enhance docs with concise troubleshooting

onelrian · onelrian · commit 2da3d407d6db · 2026-01-10T09:13:55.000+01:00
- Refactor  and  modules by merging [versions.tf] into [main.tf] for self-contained configuration.
- Generalize component documentation to reflect platform-wide utility beyond just observability.
- Add concise, code-centric troubleshooting sections to all READMEs and manual guides (, , argocd controls a Argo CD server

Usage:
  argocd [flags]
  argocd [command]

Available Commands:
  account     Manage account settings
  admin       Contains a set of commands useful for Argo CD administrators and requires direct Kubernetes access
  app         Manage applications
  appset      Manage ApplicationSets
  cert        Manage repository certificates and SSH known hosts entries
  cluster     Manage cluster credentials
  completion  output shell completion code for the specified shell (bash, zsh or fish)
  configure   Manage local configuration
  context     Switch between contexts
  gpg         Manage GPG keys used for signature verification
  help        Help about any command
  login       Log in to Argo CD
  logout      Log out from Argo CD
  proj        Manage projects
  relogin     Refresh an expired authenticate token
  repo        Manage repository connection parameters
  repocreds   Manage credential templates for repositories
  version     Print version information

Flags:
      --argocd-context string           The name of the Argo-CD server context to use
      --auth-token string               Authentication token; set this or the ARGOCD_AUTH_TOKEN environment variable
      --client-crt string               Client certificate file
      --client-crt-key string           Client certificate key file
      --config string                   Path to Argo CD config (default "/home/onel/.config/argocd/config")
      --controller-name string          Name of the Argo CD Application controller; set this or the ARGOCD_APPLICATION_CONTROLLER_NAME environment variable when the controller's name label differs from the default, for example when installing via the Helm chart (default "argocd-application-controller")
      --core                            If set to true then CLI talks directly to Kubernetes instead of talking to Argo CD API server
      --grpc-web                        Enables gRPC-web protocol. Useful if Argo CD server is behind proxy which does not support HTTP2.
      --grpc-web-root-path string       Enables gRPC-web protocol. Useful if Argo CD server is behind proxy which does not support HTTP2. Set web root.
  -H, --header strings                  Sets additional header to all requests made by Argo CD CLI. (Can be repeated multiple times to add multiple headers, also supports comma separated headers)
  -h, --help                            help for argocd
      --http-retry-max int              Maximum number of retries to establish http connection to Argo CD server
      --insecure                        Skip server certificate and domain verification
      --kube-context string             Directs the command to the given kube-context
      --logformat string                Set the logging format. One of: json|text (default "json")
      --loglevel string                 Set the logging level. One of: debug|info|warn|error (default "info")
      --plaintext                       Disable TLS
      --port-forward                    Connect to a random argocd-server port using port forwarding
      --port-forward-namespace string   Namespace name which should be used for port forwarding
      --prompts-enabled                 Force optional interactive prompts to be enabled or disabled, overriding local configuration. If not specified, the local configuration value will be used, which is false by default.
      --redis-compress string           Enable this if the application controller is configured with redis compression enabled. (possible values: gzip, none) (default "gzip")
      --redis-haproxy-name string       Name of the Redis HA Proxy; set this or the ARGOCD_REDIS_HAPROXY_NAME environment variable when the HA Proxy's name label differs from the default, for example when installing via the Helm chart (default "argocd-redis-ha-haproxy")
      --redis-name string               Name of the Redis deployment; set this or the ARGOCD_REDIS_NAME environment variable when the Redis's name label differs from the default, for example when installing via the Helm chart (default "argocd-redis")
      --repo-server-name string         Name of the Argo CD Repo server; set this or the ARGOCD_REPO_SERVER_NAME environment variable when the server's name label differs from the default, for example when installing via the Helm chart (default "argocd-repo-server")
      --server string                   Argo CD server address
      --server-crt string               Server certificate file
      --server-name string              Name of the Argo CD API server; set this or the ARGOCD_SERVER_NAME environment variable when the server's name label differs from the default, for example when installing via the Helm chart (default "argocd-server")

Use "argocd [command] --help" for more information about a command., ).
- Standardize troubleshooting format using bash code blocks for direct usability.
- Update argocd controls a Argo CD server

Usage:
  argocd [flags]
  argocd [command]

Available Commands:
  account     Manage account settings
  admin       Contains a set of commands useful for Argo CD administrators and requires direct Kubernetes access
  app         Manage applications
  appset      Manage ApplicationSets
  cert        Manage repository certificates and SSH known hosts entries
  cluster     Manage cluster credentials
  completion  output shell completion code for the specified shell (bash, zsh or fish)
  configure   Manage local configuration
  context     Switch between contexts
  gpg         Manage GPG keys used for signature verification
  help        Help about any command
  login       Log in to Argo CD
  logout      Log out from Argo CD
  proj        Manage projects
  relogin     Refresh an expired authenticate token
  repo        Manage repository connection parameters
  repocreds   Manage credential templates for repositories
  version     Print version information

Flags:
      --argocd-context string           The name of the Argo-CD server context to use
      --auth-token string               Authentication token; set this or the ARGOCD_AUTH_TOKEN environment variable
      --client-crt string               Client certificate file
      --client-crt-key string           Client certificate key file
      --config string                   Path to Argo CD config (default "/home/onel/.config/argocd/config")
      --controller-name string          Name of the Argo CD Application controller; set this or the ARGOCD_APPLICATION_CONTROLLER_NAME environment variable when the controller's name label differs from the default, for example when installing via the Helm chart (default "argocd-application-controller")
      --core                            If set to true then CLI talks directly to Kubernetes instead of talking to Argo CD API server
      --grpc-web                        Enables gRPC-web protocol. Useful if Argo CD server is behind proxy which does not support HTTP2.
      --grpc-web-root-path string       Enables gRPC-web protocol. Useful if Argo CD server is behind proxy which does not support HTTP2. Set web root.
  -H, --header strings                  Sets additional header to all requests made by Argo CD CLI. (Can be repeated multiple times to add multiple headers, also supports comma separated headers)
  -h, --help                            help for argocd
      --http-retry-max int              Maximum number of retries to establish http connection to Argo CD server
      --insecure                        Skip server certificate and domain verification
      --kube-context string             Directs the command to the given kube-context
      --logformat string                Set the logging format. One of: json|text (default "json")
      --loglevel string                 Set the logging level. One of: debug|info|warn|error (default "info")
      --plaintext                       Disable TLS
      --port-forward                    Connect to a random argocd-server port using port forwarding
      --port-forward-namespace string   Namespace name which should be used for port forwarding
      --prompts-enabled                 Force optional interactive prompts to be enabled or disabled, overriding local configuration. If not specified, the local configuration value will be used, which is false by default.
      --redis-compress string           Enable this if the application controller is configured with redis compression enabled. (possible values: gzip, none) (default "gzip")
      --redis-haproxy-name string       Name of the Redis HA Proxy; set this or the ARGOCD_REDIS_HAPROXY_NAME environment variable when the HA Proxy's name label differs from the default, for example when installing via the Helm chart (default "argocd-redis-ha-haproxy")
      --redis-name string               Name of the Redis deployment; set this or the ARGOCD_REDIS_NAME environment variable when the Redis's name label differs from the default, for example when installing via the Helm chart (default "argocd-redis")
      --repo-server-name string         Name of the Argo CD Repo server; set this or the ARGOCD_REPO_SERVER_NAME environment variable when the server's name label differs from the default, for example when installing via the Helm chart (default "argocd-repo-server")
      --server string                   Argo CD server address
      --server-crt string               Server certificate file
      --server-name string              Name of the Argo CD API server; set this or the ARGOCD_SERVER_NAME environment variable when the server's name label differs from the default, for example when installing via the Helm chart (default "argocd-server")

Use "argocd [command] --help" for more information about a command. documentation to match the project's standard structure.
diff --git a/cert-manager/README.md b/cert-manager/README.md
@@ -9,12 +9,40 @@ Cert-Manager provides:
 
 ## Deployment Options
 
-You can deploy Cert-Manager using one of the following methods:
-
 ### 1. Automated Deployment
 This method uses the Terraform configuration located in the `terraform/` directory. It is the recommended approach for automation.
 
 For detailed instructions, see the [Terraform deployment guide](../docs/cert-manager-terraform-deployment.md).
 
 ### 2. Manual (Helm & Kubectl)
 If you prefer to deploy manually using CLI tools, you can follow the [manual deployment guide](../docs/cert-manager-manual-deployment.md).
+
+## Troubleshooting
+
+### Deployment Flags
+Ensure variables are set correctly in `terraform.tfvars`:
+```hcl
+install_cert_manager = true
+```
+
+### Common Issues
+
+**Webhook Pod Not Ready**
+```bash
+# Check pod status (look for CrashLoopBackOff)
+kubectl get pods -n cert-manager
+
+# Fix: Ensure installCRDs=true is set in Helm release
+```
+
+**Certificate Stuck in "False" State**
+```bash
+# Check certificate events for challenge failures
+kubectl describe certificate <name> -n <namespace>
+```
+
+**Issuer Not Ready**
+```bash
+# Check issuer status and ACME server URL
+kubectl describe clusterissuer letsencrypt-prod
+```
diff --git a/cert-manager/terraform/main.tf b/cert-manager/terraform/main.tf
@@ -1,3 +1,17 @@
+terraform {
+  required_version = ">= 1.0"
+  required_providers {
+    kubernetes = {
+      source  = "hashicorp/kubernetes"
+      version = "~> 2.0"
+    }
+    helm = {
+      source  = "hashicorp/helm"
+      version = "~> 2.12"
+    }
+  }
+}
+
 resource "helm_release" "cert_manager" {
   count = var.install_cert_manager ? 1 : 0
 
diff --git a/cert-manager/terraform/versions.tf b/cert-manager/terraform/versions.tf
diff --git a/docs/cert-manager-manual-deployment.md b/docs/cert-manager-manual-deployment.md
@@ -72,3 +72,28 @@ Check the status of the ClusterIssuer:
 kubectl get clusterissuer letsencrypt-prod -o wide
 ```
 It should say `True` in the `READY` column.
+
+## 5. Troubleshooting
+
+### Pods Not Starting
+```bash
+# Check for ImagePullBackOff or CrashLoopBackOff
+kubectl describe pod <pod-name> -n cert-manager
+
+# Fix: Verify internet access to pull images
+```
+
+### CRD Errors
+```bash
+# Fix: Ensure installCRDs=true was passed to Helm
+helm upgrade cert-manager jetstack/cert-manager -n cert-manager --set installCRDs=true
+```
+
+### Certificate Issuance Failed
+```bash
+# Check certificate lifecycle events
+kubectl describe certificate <name>
+kubectl describe challengerequest <name>
+
+# Fix: Ensure Ingress is publicly reachable for Let's Encrypt validation
+```
diff --git a/docs/ingress-controller-manual-deployment.md b/docs/ingress-controller-manual-deployment.md
@@ -48,3 +48,27 @@ kubectl config current-context
    kubectl get svc -n ingress-nginx # Adjust namespace if changed above
    ```
    Wait for the `EXTERNAL-IP` to be assigned.
+
+## 4. Troubleshooting
+
+### External IP Pending
+```bash
+# Check service status
+kubectl get svc -n ingress-nginx
+
+# Fix: Check Cloud Provider LoadBalancer quotas or usage
+```
+
+### 404 on Access
+```bash
+# Verify Ingress resource exists and has valid backend
+kubectl get ingress -A
+
+# Fix: Define an Ingress resource routing to your service
+```
+
+### Ingress Class Conflict
+```bash
+# Fix: Ensure controller.ingressClass is unique (default: nginx)
+helm upgrade ... --set controller.ingressClass=unique-name
+```
diff --git a/docs/kubernetes-observability.md b/docs/kubernetes-observability.md
@@ -244,3 +244,26 @@ terraform destroy
 ```
 
 > **Warning**: Google Cloud Storage buckets containing observability data have `force_destroy` set to `false` to prevent accidental data loss. If you intend to delete the data, you must empty the buckets manually before running destroy.
+
+## Troubleshooting
+
+### Terraform State Locks
+```bash
+# Fix: Unlock state if sure no other process is running
+terraform force-unlock <LOCK_ID>
+```
+
+### Provider Authentication Errors
+```bash
+# Fix: Re-authenticate with GCP
+gcloud auth application-default login
+```
+
+### Pods Pending (Resources)
+```bash
+# Check for InsufficientCpu/Memory events
+kubectl describe pod <pod-name>
+
+# Fix: Enable GKE Autoscaling or resize node pool
+```
+
diff --git a/docs/manual-lgtm-deployment.md b/docs/manual-lgtm-deployment.md
@@ -82,3 +82,27 @@ To stop and remove the stack:
 ```bash
 docker compose down
 ```
+
+## 7. Troubleshooting
+
+### Network Not Found Error
+```bash
+# Fix: Create missing network
+docker network create netbird_netbird
+```
+
+### Port Conflicts
+```bash
+# Check what is using port 3000
+lsof -i :3000
+
+# Fix: Stop conflicting service or change port mapping in docker-compose.yml
+```
+
+### Container Exits Immediately
+```bash
+# Check crash logs
+docker compose logs <service_name>
+
+# Fix: Common issue is permission on mounted volumes (chown -R 10001:10001)
+```
diff --git a/ingress-controller/README.md b/ingress-controller/README.md
@@ -9,12 +9,42 @@ The Ingress Controller provides:
 
 ## Deployment Options
 
-You can deploy the Ingress Controller using one of the following methods:
-
 ### 1. Automated Deployment
 This method uses the Terraform configuration located in the `terraform/` directory.
 
 For detailed instructions, see the [Terraform deployment guide](../docs/ingress-controller-terraform-deployment.md).
 
 ### 2. Manual (Helm)
 If you prefer to deploy manually using Helm, you can follow the [manual deployment guide](../docs/ingress-controller-manual-deployment.md).
+
+## Troubleshooting
+
+### Deployment Flags
+Ensure variables are set correctly in `terraform.tfvars`:
+```hcl
+install_nginx_ingress = true
+```
+
+### Common Issues
+
+**LoadBalancer External IP Pending**
+```bash
+# Check service status for EXTERNAL-IP
+kubectl get svc -n ingress-nginx
+
+# Fix: Verify GCP LoadBalancer quota or cloud-controller logs
+```
+
+**404 Not Found**
+```bash
+# Verify Ingress resource points to valid Service/Port
+kubectl describe ingress <name> -n <namespace>
+
+# Fix: Ensure Ingress Class is set to 'nginx'
+```
+
+**SSL Certificate Issues**
+```bash
+# Check secret name in TLS section matches Cert-Manager secret
+kubectl describe ingress <name> -n <namespace>
+```
diff --git a/ingress-controller/terraform/main.tf b/ingress-controller/terraform/main.tf
@@ -1,3 +1,17 @@
+terraform {
+  required_version = ">= 1.0"
+  required_providers {
+    kubernetes = {
+      source  = "hashicorp/kubernetes"
+      version = "~> 2.0"
+    }
+    helm = {
+      source  = "hashicorp/helm"
+      version = "~> 2.12"
+    }
+  }
+}
+
 resource "helm_release" "nginx_ingress" {
   count = var.install_nginx_ingress ? 1 : 0
 
diff --git a/ingress-controller/terraform/versions.tf b/ingress-controller/terraform/versions.tf
