Create a documenation how to debug the agent

Signed-off-by: Aviel Segev <[email protected]>

doc/debugging.md

@@ -0,0 +1,139 @@
+# Discovery VM Troubleshooter
+
+## Objective
+This troubleshooter is designed to guide you through the steps necessary to resolve issues related to the Discovery VM deployment.
+If you see the source status as "not-connected" in the migration assessment service or if the Discovery VM is not functioning 
+as expected, follow these steps to diagnose and fix the problem.
+## Troubleshooting steps
+
+**1. Ensure that the virtual machine is powered on**  
+Verify that the deployed VM is in a powered-on state.
+
+**2. Verify Network Configuration**  
+* If using DHCP networking: Ensure that your DHCP server is enabled.
+* If using static IP, bridges, or bonded networking - Ensure that your configurations are correct.
+
+**3. SSH into the Discovery VM Machine**  
+Retrieve the IP address of the deployed Discovery VM. If the VM is running in a vCenter environment, check the Virtual 
+Machine Details under IP Addresses.
+
+Once you have the IP address, verify that you can access the machine using SSH. Run the following command in the CLI:  
+`ssh -i <identity_file> core@<machine-ip>`
+
+* The -i parameter specifies the private key that corresponds to the public key provided during the OVA generation.  
+* Replace <identity_file> with the actual path to your private key.
+
+**4. Unable to SSH into the Discovery VM through the network?**
+* The machine's IP address should be displayed in the CLI if the network interface is available.
+* Verify that the previously used IP address is correct and that Steps 1 and 2 were completed successfully.
+* Follow common troubleshooting steps such as:
+  1. Ping the Discovery VM from your machine.
+  2. Check firewall rules to ensure traffic to the Discovery VM is allowed.
+After resolving any connectivity issues, proceed with Step 3 again.
+
+## Now, depending on your case, proceed with the additional steps
+
+### Case: Unable to Access the Login Page
+
+**1. Verify That the Discovery VM Components Are Running**  
+
+Run the following command to check all containers:
+
+`podman ps -a`  
+
+Expected output should be similar to:
+
+```
+| CONTAINER ID | IMAGE                                               | COMMAND               | CREATED       | STATUS        | PORTS | NAMES          |
+| cc0a71a37c1b | quay.io/kubev2v/forklift-validation:release-v2.6.4  | run --server /usr...  | 2 minutes ago | Up 31 minutes |       | opa            |
+| 70ad0a7cbdc5 | quay.io/kubev2v/migration-planner-agent:latest      | -config /agent/co...  | 2 minutes ago | Up 31 minutes |       | planner-agent  |
+```
+
+If the planner-agent is not running, try restarting the Discovery VM.
+**Note:** If only the OPA is not running, you should still be able to use the agent and view the final report. However, 
+this report will be partial and may not include warnings regarding the migration to OpenShift.
+
+**2. Use the Discovery VM UI**  
+Navigate to: **`https://<machine-ip>:3333/login`**. You should see a login form asking for VMware credentials. 
+If the site isn't reachable:  
+1. Ensure that traffic to port 3333 is allowed for the destination <machine-ip> in the firewall. 
+2. If the issue persists, restart the Discovery VM and try again.
+
+### Case: 'not-connected' state of source keeps appearing
+
+**1. Verify the Connection to the Service** 
+
+The planner-agent exposes a `/status` endpoint, providing information to the Discovery VM UI and components regarding:
+
+* The status of the process and status information
+* The connection status to the migration service
+
+If you can reach the login page but the source status is still "not-connected", check the Discovery VM connection status:
+
+Navigate to: **`https://<machine-ip>:3333/api/v1/status`**.  
+You will likely see output similar to:
+
+```json
+{
+"status": "waiting-for-credentials",
+"connected": "false",
+"statusInfo": "No credentials provided"
+}
+```
+
+If the output indicates that the service is unreachable ("connected": "false"), follow these steps:
+1. Inspect the network traffic from the Discovery VM to the migration assessment service. 
+(The service, which is hosted by Red Hat, is available at console.redhat.com)
+2. Recheck the network assigned to the VM's interface to ensure it is connected to a proper network with access to the 
+public internet or the service network destination.
+3. Ensure that the necessary outbound connections are allowed through the firewall.
+
+**Note:** The migration service provided by Red Hat is hosted at **console.redhat.com**. If you deployed the service locally, 
+you must update the agent's configuration file to point to the correct IP address for the migration service.
+
+**Viewing or Changing the Planner Agent Configuration**  
+To access and view the configuration file, run:  
+```shell
+podman exec -it planner-agent /bin/bash # opens a shell inside the planner-agent container
+cat /agent/config/config.yaml # Displays the current configuration file for the planner-agent
+```
+
+Expected output should be similar to:
+
+```txt
+config-dir: /agent/config
+data-dir: /agent/data
+persistent-data-dir: /agent/persistent-data
+www-dir: /app/www
+log-level: debug
+update-interval: 5s
+source-id: <uuid>
+planner-service:
+  service:
+    server: https://<default-server>:7443
+    ui: https://<default-server>:3000/migrate/wizard
+```
+
+Since the environment is minimal, follow these steps to update the configuration:  
+1. Backup the Original File (Optional):
+`cp /agent/config/config.yaml /agent/config/config.yaml.bak`
+2. Replace the Server and UI URLs with the New Address:  
+Replace `<new-desired-server>` with the appropriate service domain or IP address and run:  
+```shell
+{
+   echo "config-dir: /agent/config"
+   echo "data-dir: /agent/data"
+   echo "persistent-data-dir: /agent/persistent-data"
+   echo "www-dir: /app/www"
+   echo "log-level: debug"
+   echo "update-interval: 5s"
+   echo "source-id: f2c0e350-6701-4abc-b742-9cf8899913de"
+   echo "planner-service:"
+   echo "  service:"
+   echo "    server: https://<new-desired-server>:7443
+   echo "    ui: https://<new-desired-server>:3000/migrate/wizard
+} > /agent/config/config.yaml
+```
+3. Verify the Changes:  
+`cat /agent/config/config.yaml`
+4. Restart the Discovery VM in order to apply the changes