Create a documenation how to debug the agent

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

doc/debugging.md

@@ -0,0 +1,93 @@
+# Agent troubleshooter
+
+## Objective
+This troubleshooter is designed to guide you through the steps necessary to resolve issues related to the agent deployment.
+If you see the source status as "not-connected" in the migration assessment service or if the agent 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: Confirm that your configurations are correct.
+
+**3. SSH into the Agent Machine**  
+Retrieve the IP address of the deployed agent 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 Agent Machine through the network?**  
+If SSH fails, try accessing the machine directly using:
+* Physical access
+* Out-of-band management
+* A virtual machine console
+
+Once logged in:
+
+* The machine's IP address should be displayed in the CLI if a 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 agent from your machine.
+  2. Check firewall rules to ensure traffic to the agent is allowed.
+After resolving any connectivity issues, retry Step 3.
+
+## Now, depending on your case, proceed with the additional steps
+
+### Case: Unable to Access the Login Page
+
+**1. Verify That the Agent Components Are Running**  
+
+Run the following command to check running containers:
+
+`podman ps`  
+
+Expected output should include running containers 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 agent components are not running, try restarting the agent VM.
+
+**2. Use the agent 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 agent VM and try again.
+
+### Case: 'not-connected' state of source keep appearing
+
+**1. Verify the Connection to the Service** 
+
+The agent exposes a `/status` endpoint, providing information to the agent UI and components regarding:
+
+* The status of the process and status information
+* The connection to the migration service hosted at **console.redhat.com**
+
+If you can reach the login page but the source status is still "not-connected", check the agent’s 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, follow these steps:  
+1. Review the network traffic from the agent to console.redhat.com.
+2. Re-check the network assigned to the network interface of the VM to ensure it is connected to a proper network 
+that has access to the public internet.
+3. Ensure that the necessary outbound connections are allowed in the firewall.