MTV-1590 Improved hooks description

documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc

@@ -318,13 +318,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,65 @@
+// 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 in the `openshift-mtv` namespace using the `ServiceAccount` you choose.
+
+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,115 @@
+// 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` 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
+* File containing the Secret for the source provider
+* {ocp} service account called by the hook and 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
+
+.Additional resources
+For instructions for creating a service account, see link:https://docs.openshift.com/container-platform/{ocp-version}/authentication/understanding-and-creating-service-accounts.html[Understanding and creating service accounts].
+
+.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: openshift-mtv
+type: Opaque
+----
+. Encode your playbook by concatenating a file and piping it for Base64 encoding, for example:
++
+[source,shell]
+----
+$ cat playbook.yml | base64 -w0
+----
+
+. 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
+  serviceAccount:<service account> <1>
+  playbook: |
+    LS0tCi0gbm... <2>
+EOF
+----
+<1> (Optional) {ocp} service account. The `serviceAccount` must be provided if you want to manipulate any resources of the cluster.
+<2> Base64-encoded Ansible Playbook. If you specify a playbook, the `image` must include an `ansible-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,55 @@
+// 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.
+
+For example, you can create a hook 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.
+====
+
+.Prerequisites
+
+* Migration plan
+* Migration hook file, whose contents you copy and paste into the web console
+* File containing the `Secret` for the source provider
+* {ocp} service account called by the hook and 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
+
+.Additional resources
+For instructions for creating a service account, see link:https://docs.openshift.com/container-platform/{ocp-version}/authentication/understanding-and-creating-service-accounts.html[Understanding and creating service accounts].
+
+.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*. If you are specifying the `spec.playbook`, you need to use an image that has an `ansible-runner`.
+.. 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*. If you are specifying the `spec.playbook`, you need to use an image that has an `ansible-runner`.
+.. 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/common-attributes.adoc

@@ -8,7 +8,7 @@
 :ocp: Red Hat OpenShift
 :ocp-name: OpenShift
 :ocp-short: OpenShift
-// when udating the ocp-version, update the ocp-y-version
+// when updating the ocp-version, update the ocp-y-version
 :ocp-version: 4.17
 :ocp-y-version: 4.17, 4.16, 4.15
 :operator: mtv-operator

documentation/modules/new-migrating-virtual-machines-cli.adoc

@@ -735,18 +735,13 @@ metadata:
   namespace: <namespace>
 spec:
   image: quay.io/konveyor/hook-runner
+  serviceAccount:<ervice account> <1>
   playbook: |
-    LS0tCi0gbmFtZTogTWFpbgogIGhvc3RzOiBsb2NhbGhvc3QKICB0YXNrczoKICAtIG5hbWU6IExv
-    YWQgUGxhbgogICAgaW5jbHVkZV92YXJzOgogICAgICBmaWxlOiAiL3RtcC9ob29rL3BsYW4ueW1s
-    IgogICAgICBuYW1lOiBwbGFuCiAgLSBuYW1lOiBMb2FkIFdvcmtsb2FkCiAgICBpbmNsdWRlX3Zh
-    cnM6CiAgICAgIGZpbGU6ICIvdG1wL2hvb2svd29ya2xvYWQueW1sIgogICAgICBuYW1lOiB3b3Jr
-    bG9hZAoK
+    LS0tCi0gbm... <2>
 EOF
 ----
-+
-where:
-+
-`playbook` refers to an optional Base64-encoded Ansible Playbook. If you specify a playbook, the `image` must be `hook-runner`.
+<1> (Optional) {ocp} service account. The `serviceAccount` must be provided if you want to manipulate any resources of the cluster.
+<2> Base64-encoded Ansible Playbook. If you specify a playbook, the `image` must include an `ansible-runner`.
 +
 [NOTE]
 ====

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: "{{ vm.ipaddress }}"  # ALT "{{ 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
+----