MTV-1590 Improved hooks description

documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc

@@ -312,13 +312,14 @@ include::modules/creating-validation-rule.adoc[leveloffset=+3]
 include::modules/updating-validation-rules-version.adoc[leveloffset=+3]
 include::modules/retrieving-validation-service-json.adoc[leveloffset=+2]
 
-[id="adding-hooks-migration-plan-using-api"]
-=== Adding hooks to a migration plan
-You can add hooks a migration plan from the command line by using the {project-full} API.
+[id="adding-hooks-mtv-migration-plan"]
+=== Adding hooks to an MTV migration plan
 
-include::modules/about-hook-crs-for-migration-plans-api.adoc[leveloffset=+3]
+You can add hooks to an {project-first} migration plan to perform automated operations on a VM either before or after you migrate it.
 
-include::modules/adding-hook-crs-to-migration-plans-api.adoc[leveloffset=+3]
+include::modules/about-hooks-for-migration-plans.adoc[leveloffset=+3]
+include::modules/adding-hook-using-ui.adoc[leveloffset=+3]
+include::modules/adding-hook-using-cli.adoc[leveloffset=+3]
 
 include::modules/upgrading-mtv-ui.adoc[leveloffset=+1]
 

documentation/modules/about-hooks-for-migration-plans.adoc

@@ -0,0 +1,67 @@
+// Module included in the following assemblies:
+//
+// * documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc
+
+:_content-type: CONCEPT
+[id="about-hooks-for-migration-plans_{context}"]
+= About hooks for {project-short} migration plans
+
+You can add hooks to {project-first} migration plans using either the {project-short} CLI or the {project-short} user interface, which is located in the {ocp} web console.
+
+* _Pre-migration_ hooks are hooks that perform operations on a VM that is located on a provider. This prepares the VM for migration.
+
+* _Post-migration_ hooks are hooks that perform operations on a VM that has migrated to {virt}.
+
+[id="default-hook-image_{context}"]
+== Default hook image
+The default hook image for an {project-short} hook is `quay.io/konveyor/hook-runner`. The image is based on the Ansible Runner image with the addition of `python-openshift` to provide Ansible Kubernetes resources and a recent `oc` binary.
+
+[id="hook-execution_{context}"]
+== Hook execution
+An Ansible playbook that is provided as part of a migration hook is mounted into the hook container as a `ConfigMap`. The hook container is run as a job on the desired cluster, using the default `ServiceAccount` in the `konveyor-forklift` namespace.
+
+
+When you add a hook, you must specify the namespace where the `Hook` CR is located, the name of the hook, and whether the hook is a pre-migration hook or a post-migration hook.
+
+[IMPORTANT]
+====
+In order for a hook to run on a VM, the VM must be started and available using SSH.
+====
+
+The illustration that follows shows the general process of using a migration hook. For specific procedures, see xref:adding-migration-hook-via-ui_{context}[Adding a migration hook to a migration plan using the {ocp} web console] and xref:adding-migration-hook-via-cli_{context}[Adding a migration hook to a migration plan using the CLI].
+
+.Adding a hook to a migration plan
+image::migration_hook_process.png[Adding a hook to a migration plan]
+
+*Process:*
+
+. Input your Ansible hook and credentials.
+
+.. Input an Ansible hook image to the {project-short} controller using either the UI or the CLI.
++
+* In the UI, specify the `ansible-runner` and enter the `playbook.yml` that contains the hook.
+* In the CLI, input the hook image, which specifies the playbook that runs the hook.
+
+.. If you need additional data to run the playbook inside the pod, such as SSH data, create a Secret that contains credentials for the VM. The Secret is not mounted to the pod, but is called by the playbook.
++
+[NOTE]
+====
+This Secret is not the same as the `Secret` CR that contains the credentials of your source provider.
+====
+
+. The {project-short} controller creates the `ConfigMap`, which contains:
+
+** `workload.yml`, which contains information about the VMs.
+** `playbook.yml`, the raw string playbook you want to execute.
+** `plan.yml`, which is the `Plan` CR.
++
+The `ConfigMap` contains the name of the VM and instructs the playbook what to do.
+
+. The {project-short} controller creates a job that starts the user specified image.
+.. Mounts the `ConfigMap` to the container.
++
+The Ansible hook imports the Secret that the user previously entered.
+. The job runs a pre-migration hook or a post-migration hook as follows:
+
+.. For a pre-migration hook, the job logs into the VMs on the source provider using SSH and runs the hook.
+.. For a post-migration hook, the job logs into the VMs on {virt} using SSH and runs the hook.

documentation/modules/adding-hook-using-cli.adoc

@@ -0,0 +1,132 @@
+// Module included in the following assemblies:
+//
+// * documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc
+
+:_content-type: PROCEDURE
+[id="adding-migration-hook-via-cli_{context}"]
+= Adding a migration hook to a migration plan using the CLI
+
+You can use a `Hook` CR to add a pre-migration hook or a post-migration hook to an existing migration plan using the {project-first} CLI.
+
+For example, you can create a `Hook` CR to install the `cloud-init` service on a VM and write a file before migration.
+
+[NOTE]
+====
+You can run one pre-migration hook, one post-migration hook, or one of each per migration plan. Each hook needs its own `Hook` needs its own CR, but a `Plan` CR contains data for all the hooks it uses.
+====
+
+[NOTE]
+====
+You can retrieve additional information stored in a secret or in a `ConfigMap` by using a `k8s` module.
+====
+
+.Prerequisites
+
+* Migration plan
+* Migration hook image or the playbook containing the hook image
+
+[NOTE]
+====
+You can run one pre-migration hook, one post-migration hook, or one of each per migration plan.
+====
+
+* File containing the Secret for the source provider
+* {ocp} service account that has at least write access for the namespace you are working in
+* SSH access for VMs you want to migrate with the public key installed on the VMs
+* VMs running on Microsoft Server only: Remote Execution enabled
+
+.Procedure
+. If needed, create a Secret with an SSH private key for the VM.
+.. Choose an existing key or generate a key pair.
+.. Install the public key on the VM.
+.. Encode the private key in the Secret to base64.
++
+[source,yaml]
+----
+apiVersion: v1
+data:
+  key: VGhpcyB3YXMgZ2Vu...
+kind: Secret
+metadata:
+  name: ssh-credentials
+  namespace: konveyor-forklift
+type: Opaque
+----
+. Encode your playbook by concatenating a file and piping it for base64, for example:
++
+[source,shell]
+----
+$ cat playbook.yml | base64 -w0
+----
++
+[NOTE]
+====
+You can also use a `here` document to add instructions to encode a playbook inside a larger command:
+
+[source,shell]
+----
+$ cat << EOF | base64 -w0
+- hosts: localhost
+  tasks:
+  - debug:
+      msg: test
+EOF
+----
+====
+
+. Create a Hook CR:
++
+[source,yaml,subs="attributes+"]
+----
+$  cat << EOF | {oc} apply -f -
+apiVersion: forklift.konveyor.io/v1beta1
+kind: Hook
+metadata:
+  name: <hook>
+  namespace: <namespace>
+spec:
+  image: quay.io/konveyor/hook-runner
+  playbook: |
+    LS0tCi0gbm...
+EOF
+----
++
+where:
++
+`playbook` refers to an optional Base64-encoded Ansible Playbook. If you specify a playbook, the `image` must be `hook-runner`.
++
+[NOTE]
+====
+You can use the default `hook-runner` image or specify a custom image. If you specify a custom image, you do not have to specify a playbook.
+====
++
+[NOTE]
+====
+To decode an attached playbook, retrieve the resource with custom output and pipe it to base64. For example:
+[source,shell]
+----
+ oc get -n konveyor-forklift hook playbook -o \
+   go-template='{{ .spec.playbook }}' | base64 -d
+----
+====
++
+. In the `Plan` CR of the migration, for each VM, add the following section to the end of the CR:
++
+[source,yaml]
+----
+  vms:
+    - id: <vm_id>
+      hooks:
+        - hook:
+            namespace: <namespace>
+            name: <name_of_hook>
+          step: <type_of_hook> <1>
+----
+<1> Options are `PreHook`, to run the hook before the migration, and `PostHook`, to run the hook after the migration.
+
+[IMPORTANT]
+====
+In order for a PreHook to run on a VM, the VM must be started and available via SSH.
+====
+
+include::snip_example-hook-for-migration-plans.adoc[]

documentation/modules/adding-hook-using-ui.adoc

@@ -0,0 +1,52 @@
+// Module included in the following assemblies:
+//
+// * documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc
+
+:_content-type: PROCEDURE
+[id="adding-migration-hook-via-ui_{context}"]
+= Adding a migration hook to a migration plan using the {ocp} web console
+
+You can add a migration hook to an existing migration plan using the {ocp} web console. Note that you need to run one command in the {project-first} CLI.
+
+.Prerequisites
+
+* Migration plan
+* Migration hook file, whose contents you copy and paste into the web console
+
+[NOTE]
+====
+You can run one pre-migration hook, one post-migration hook, or one of each per migration plan.
+====
+
+* File containing the `Secret` for the source provider
+* {ocp} service account that has at least write access for the namespace you are working in
+* SSH access for VMs you want to migrate with the public key installed on the VMs
+* VMs running on Microsoft Server only: Remote Execution enabled
+
+
+.Procedure
+
+. In the {ocp} web console, click *Migration* > *Plans for virtualization* and then click the migration plan you want to add the hook to.
+. Click *Hooks*.
+. For a pre-migration hook, perform the following steps:
+
+.. In the *Pre migration hook* section, toggle the *Enable hook* switch to *Enable pre migration hook*.
+.. Enter the *Hook runner image*. The default image is `quay.io/konveyor/hook-runner` and this value must be used if you are adding an Ansible playbook.
+.. Paste your hook as a YAML file in the *Ansible playbook* text box.
+
+. For a post-migration hook, perform the following steps:
+
+.. In the *Post migration hook*, toggle the *Enable hook* switch *Enable post migration hook*..
+.. Enter the *Hook runner image*. The default image is `quay.io/konveyor/hook-runner` and this value must be used if you are adding an Ansible playbook.
+.. Paste your hook as a YAML file in the *Ansible playbook* text box.
+
+. At the top of the tab, click *Update hooks*.
+. In a terminal, enter the following command to associate each hook with your {ocp} service account:
++
+[source,terminal,subs="attributes+"]
+----
+$ oc -n openshift-mtv patch hook <name_of_hook> \
+    -p '{"spec":{"serviceAccount":"<service_account>"}}' --type merge
+----
+
+include::snip_example-hook-for-migration-plans.adoc[]

documentation/modules/snip_example-hook-for-migration-plans.adoc

@@ -0,0 +1,54 @@
+:_content-type: SNIPPET
+
+The example migration hook that follows ensures that the VM can be accessed using SSH, creates an SSH key, and runs 2 tasks: stopping the Maria database and generating a text file.
+
+.Example migration hook
+[source,yaml,subs="attributes+"]
+----
+- name: Main
+  hosts: localhost
+  vars_files:
+    - plan.yml
+    - workload.yml
+  tasks:
+  - k8s_info:
+      api_version: v1
+      kind: Secret
+      name: privkey
+      namespace: openshift-mtv
+    register: ssh_credentials
+
+  - name: Ensure SSH directory exists
+    file:
+      path: ~/.ssh
+      state: directory
+      mode: 0750
+
+  - name: Create SSH key
+    copy:
+      dest: ~/.ssh/id_rsa
+      content: "{{ ssh_credentials.resources[0].data.key | b64decode }}"
+      mode: 0600
+
+  - add_host:
+      name: "{{ workload.vm.ipaddress }}"  # ALT "{{ workload.vm.guestnetworks[2].ip }}"
+      ansible_user: root
+      groups: vms
+
+- hosts: vms
+  vars_files:
+    - plan.yml
+    - workload.yml
+  tasks:
+  - name: Stop MariaDB
+    service:
+      name: mariadb
+      state: stopped
+
+  - name: Create Test File
+    copy:
+      dest: /premigration.txt
+      content: "Migration from {{ provider.source.name }}
+                of {{ vm.vm1.vm0.id }} has finished\n"
+      mode: 0644
+----