MCP-OCP-Lightspeed (#894)

* mcp-ocp-lightspeed

* ui updates and comments

* edits and fixes

* planning-lightspeed-assembly

* feedback updates

* lightspeed updates

* coderabbitai fixes

* lightspeed variable

* namespace variable

* feature_mcp_server

* external-ai-risk-note

* edit

* note edit

* review updates

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: Jenny-Anne

documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_troubleshooting-migration.adoc

@@ -16,6 +16,8 @@ Troubleshoot migration issues by following diagnostic workflows, resolving commo
 
 include::../modules/proc_troubleshooting-workflow.adoc[leveloffset=+1]
 
+include::../modules/proc_using-lightspeed-troubleshooting.adoc[leveloffset=+1]
+
 include::../modules/ref_common-migration-issues.adoc[leveloffset=+1]
 
 include::../modules/ref_error-messages.adoc[leveloffset=+1]

documentation/doc-Planning_your_migration/assemblies/assembly_lightspeed-integration.adoc

@@ -0,0 +1,33 @@
+// Module included in the following assemblies:
+//
+// * documentation/doc-Planning_your_migration/master.adoc
+ifdef::context[:parent-context: {context}]
+
+:_mod-docs-content-type: ASSEMBLY
+
+[id="assembly_lightspeed-integration_{context}"]
+
+= {lightspeed-full} integration with {project-short}
+
+:context: lightspeed-integration
+
+[role="_abstract"]
+Get AI-powered troubleshooting assistance for your virtual machine migrations with {lightspeed-full}, which provides plain-language explanations of errors and recommended solutions.
+
+== Prerequisites
+
+* {ocp} 4.15 or later
+* {project-short} {project-version} or later
+* {lightspeed-full} Operator installed and configured on your cluster
+
+include::../modules/con_using-lightspeed-with-mtv.adoc[leveloffset=+1]
+
+include::../modules/proc_enabling-lightspeed-integration.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+== Additional resources
+
+* link:https://docs.redhat.com/en/documentation/red_hat_openshift_lightspeed[{lightspeed-full} documentation]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

documentation/doc-Planning_your_migration/master.adoc

@@ -20,6 +20,8 @@ include::assemblies/assembly_provider-specific-requirements-for-migration.adoc[l
 
 include::assemblies/assembly_installing-mtv-operator.adoc[leveloffset=+1]
 
+include::assemblies/assembly_lightspeed-integration.adoc[leveloffset=+1]
+
 include::assemblies/assembly_migrating-vms-web-console.adoc[leveloffset=+1]
 
 include::assemblies/assembly_migrating-vms-cli.adoc[leveloffset=+1]

documentation/modules/common-attributes.adoc

@@ -34,6 +34,11 @@
 :manager: Manager
 :vmw: VMware
 
+// Red Hat OpenShift Lightspeed
+:lightspeed-full: Red Hat OpenShift Lightspeed
+:lightspeed-short: Lightspeed
+:lightspeed-operator: Red Hat OpenShift Lightspeed Operator
+
 // doc metadata
 :icons: font
 :build: downstream

documentation/modules/con_using-lightspeed-with-mtv.adoc

@@ -0,0 +1,80 @@
+// Module included in the following assemblies:
+//
+// * documentation/doc-Planning_your_migration/assemblies/assembly_lightspeed-integration.adoc
+
+:_mod-docs-content-type: CONCEPT
+
+[id="con_using-lightspeed-with-mtv_{context}"]
+= About {lightspeed-short} and {project-short}
+
+[role="_abstract"]
+Use {lightspeed-full} to quickly diagnose migration issues and get step-by-step guidance without manually parsing logs or searching documentation.
+
+{lightspeed-full} is integrated into the {ocp} web console. It provides intelligent assistance through a natural-language interface where you can ask questions, receive troubleshooting guidance, and get step-by-step instructions.
+
+[NOTE]
+====
+{lightspeed-full} integration with {project-short} is available as a Technology Preview feature. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
+====
+
+== {lightspeed-short} use cases
+
+You can ask {lightspeed-short} questions in natural language throughout the migration lifecycle:
+
+Planning and assessment:: Ask questions about migration prerequisites, recommended settings, best practices, and configuration requirements for your specific environment and source platform.
++
+For example:
++
+* "What are the prerequisites for warm migration from VMware?"
+* "What network requirements do I need for migrating VMs?"
+* "How do I check network mapping for a failed migration?"
+
+Real-time troubleshooting:: Get plain-language explanations of migration failures, error messages, and stalled migrations without manually parsing logs.
++
+For example:
++
+* "Why did the migration for VM 'ProdDB-01' fail?"
+* "Why is my warm migration stalled?"
+* "What does the error 'import retry limit exceeded' mean?"
+* "How do I resolve Changed Block Tracking (CBT) snapshot issues?"
+
+Post-migration guidance:: Receive recommendations for validating migrated virtual machines, optimizing resource configurations, and troubleshooting post-migration issues.
++
+For example:
++
+* "Why are my VMs not working after migration?"
+* "How do I verify my migrated VMs are running correctly?"
+* "What should I check after migration is complete?"
+
+== Data access and analysis
+
+When you ask {lightspeed-short} a question about {project-short}, {lightspeed-short}:
+
+. Accesses real-time data from your cluster, including migration plan status, custom resources, and logs
+. Analyzes the data based on your user credentials and role-based access control (RBAC) permissions
+. Provides a conversational response with specific, actionable information
+
+== Privacy and data handling
+
+{lightspeed-short} uses your own user credentials and can only access resources that you have permission to view. {lightspeed-short} accesses cluster metadata, migration resource status, and log data to provide contextual assistance. All data access respects your existing RBAC permissions, and {lightspeed-short} cannot access resources beyond your authorization level.
+
+[IMPORTANT]
+====
+When you use {lightspeed-short} with an external AI service provider, cluster information, logs, and resource details may be transmitted to that provider. Evaluate whether external AI services align with the security and compliance requirements of your organization.
+====
+
+== How the integration works
+
+After you enable the `feature_mcp_server` feature flag in the `ForkliftController` custom resource, the {project-short} Operator configures the integration with {lightspeed-full} by:
+
+* Deploying the {project-short} MCP (Model Context Protocol) server
+* Registering the MCP server with {lightspeed-full}
+* Configuring the necessary endpoints
+
+This integration enables {lightspeed-short} to access {project-short} resources and provide context-aware assistance for your migrations.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:proc_enabling-lightspeed-integration_{context}[Enabling the {lightspeed-full} integration]
+* link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]

documentation/modules/proc_enabling-lightspeed-integration.adoc

@@ -0,0 +1,76 @@
+// Module included in the following assemblies:
+//
+// * documentation/doc-Planning_your_migration/assemblies/assembly_lightspeed-integration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc_enabling-lightspeed-integration_{context}"]
+= Enabling the {lightspeed-full} integration
+
+[role="_abstract"]
+Enable {lightspeed-full} integration to access AI-powered migration assistance and troubleshooting directly from the {ocp} web console.
+
+.Prerequisites
+
+* You are logged in to the {ocp} web console as a user with cluster administrator privileges.
+* {lightspeed-full} is installed and configured on the cluster.
++
+For information about installing and configuring {lightspeed-full}, see the link:https://docs.redhat.com/en/documentation/red_hat_openshift_lightspeed[{lightspeed-full} documentation].
+* The {project-short} Operator is installed.
+
+.Procedure
+
+. In the {ocp} web console, click *Operators* -> *Installed Operators* in the left navigation menu.
+
+. Ensure you are in the correct project. For example, +{namespace}+.
+
+. Click the *{operator-name}* from the list of installed operators.
+
+. Click the *ForkliftController* tab.
+
+. Click your controller instance to view its details.
+
+. Click the *YAML* tab to edit the resource configuration.
+
+. In the `spec:` section, locate or add the `feature_mcp_server` parameter and set its value to `'true'`:
++
+[source,yaml]
+----
+spec:
+  feature_mcp_server: 'true'
+----
++
+[NOTE]
+====
+To disable the feature later, you can change this value to `'false'`.
+====
+
+. Click *Save*.
++
+The {lightspeed-full} pods restart to load the new Model Context Protocol (MCP) configuration for {project-short}.
+
+. Optional: Monitor the pod restart progress by running the following command:
++
+[source,terminal]
+----
+$ oc get pods -n openshift-lightspeed -w
+----
+
+.Verification
+
+. In the {ocp} web console, open the {lightspeed-full} chat assistant:
++
+* Click the *{lightspeed-full}* icon in the top global header of the web console, or
+* Click the floating *{lightspeed-full}* icon at the bottom right of the screen.
+
+. Type a query related to your {project-short} environment into the chat prompt.
++
+For example:
++
+----
+Can you list my MTV providers from all namespaces?
+----
+
+. Press *Enter* or click the send icon.
++
+{lightspeed-short} uses its `mtv_read` capabilities to fetch and display your providers directly in the chat window.

documentation/modules/proc_troubleshooting-workflow.adoc

@@ -2,6 +2,7 @@
 //
 // * documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_troubleshooting-migration.adoc
 
+
 :_mod-docs-content-type: PROCEDURE
 [id="proc_troubleshooting-workflow_{context}"]
 = Troubleshooting workflow
@@ -21,6 +22,14 @@ You can typically find where the error is occurring at this stage. VMs can be mi
 * *Warm migration*: VMs are migrated with minimal downtime while remaining powered on during the precopy stage.
 * *Cold migration*: VMs are shut down during the entire migration process.
 
+. *Ask {lightspeed-full}* for AI-assisted troubleshooting guidance.
++
+If {lightspeed-full} is configured with {project-short}, you can ask questions in natural language to get plain-language explanations of migration failures, recommended solutions, and guidance for resolving common issues.
++
+For example: "Why did the migration for VM 'ProdDB-01' fail?"
++
+See xref:proc_using-lightspeed-troubleshooting_{context}[Using {lightspeed-full} to troubleshoot migration issues] for detailed instructions.
+
 . *View pod logs* for specific information about pod status within Kubernetes.
 +
 [NOTE]
@@ -32,7 +41,7 @@ Pod logs are only available after the image conversion stage has started.
 .. Under the *Pod* subheading, click *View logs*.
 .. Review the logs for error messages or warnings that indicate the cause of the failure.
 
-. *Review forklift controller logs* if the migration progress and pod logs are not helpful.
+. *Review forklift controller logs* if the migration progress, AI guidance, and pod logs are not helpful.
 +
 Forklift controller logs capture {project-first} related events and provide detailed information about the migration process.
 +
@@ -41,7 +50,7 @@ Forklift controller logs capture {project-first} related events and provide deta
 
 . *Collect must-gather logs* if previous troubleshooting steps do not resolve the issue.
 +
-The `must-gather` tool collects comprehensive diagnostic information about your cluster.
+The `must-gather` tool collects comprehensive diagnostic information about your cluster and packages it for Red Hat Support analysis.
 +
 .. Navigate to the directory where you want to store the `must-gather` data:
 +

documentation/modules/proc_using-lightspeed-troubleshooting.adoc

@@ -0,0 +1,62 @@
+// Module included in the following assemblies:
+//
+// * documentation/doc-Migrating_your_virtual_machines/assemblies/assembly_troubleshooting-migration.adoc
+
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc_using-lightspeed-troubleshooting_{context}"]
+= Using {lightspeed-full} to troubleshoot migration issues
+
+[role="_abstract"]
+Quickly resolve migration issues by asking {lightspeed-full} questions in natural language instead of manually parsing logs and error messages.
+
+.Prerequisites
+
+* {ocp} 4.15 or later
+* {lightspeed-operator} installed and configured on your cluster
++
+For information about installing and configuring {lightspeed-full}, see the link:https://docs.redhat.com/en/documentation/red_hat_openshift_lightspeed[{lightspeed-full} documentation].
+* {project-short} {project-version} or later
+* The {lightspeed-full} integration is enabled in the `ForkliftController` custom resource
++
+For more information, see link:{mtv-plan}index#proc_enabling-lightspeed-integration[Enabling the {lightspeed-full} integration] in _Planning your migration_.
+* You have access to the {ocp} web console
+* You have permission to view {project-short} resources in the cluster
+
+.Procedure
+
+. While viewing your migration plans or resources in the {project-short} user interface, open the {lightspeed-full} chat assistant:
++
+* Click the *{lightspeed-full}* icon in the top global header of the web console, or
+* Click the floating *{lightspeed-full}* icon at the bottom right of the screen.
++
+The chat assistant opens as a slide-out panel.
+
+. Type your question about the migration issue in natural language.
++
+For example:
++
+* "Why is my network mapping failing for plan 'vmware-prod-vms'?"
+* "What is the current status of the warm migration for my database cluster?"
+* "How do I fix naming convention violations in my migration plan?"
+
+. Review the response from {lightspeed-short}, which provides:
++
+* A plain-language diagnosis of the issue
+* Specific error details from the migration logs
+* Recommended actions to resolve the problem
+
+. Follow the recommended steps to resolve the issue.
+
+. Optional: Ask follow-up questions for clarification or additional guidance.
+
+.Verification
+
+* Compare the plain-language diagnosis from {lightspeed-short} with the raw error message in the migration logs to understand the root cause.
+* Check that the recommended solution addresses your specific migration failure.
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://docs.redhat.com/en/documentation/red_hat_openshift_lightspeed[{lightspeed-full} documentation]
+* link:{mtv-plan}index#con_using-lightspeed-with-mtv[{lightspeed-full} integration with {project-short}]

documentation/upstream-attributes.adoc

@@ -27,6 +27,11 @@
 :operator-name: Forklift Operator
 :must-gather: quay.io/kubev2v/forklift-must-gather:latest
 
+// Red Hat OpenShift Lightspeed
+:lightspeed-full: Red Hat OpenShift Lightspeed
+:lightspeed-short: Lightspeed
+:lightspeed-operator: Red Hat OpenShift Lightspeed Operator
+
 // Guide titles
 :planning-guide-title: Planning your migration
 :migrating-guide-title: Migrating your virtual machines