MTV-1590 Improved hooks description

documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc

@@ -309,13 +309,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,77 @@
+// 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.
+
+* Hooks that perform operations on VMs before migration are called _pre-migration_ hooks.  A pre-migration hook is performed on a VM that is located on the provider and prepares the VM for migration.
+
+* Hooks that perform operations on VMs after migration are called _post-migration_ hooks. A post-migration hook is performed on a VM after it has been 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 specify 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 via SSH.
+====
+
+The illustration that follows shows the general process of using a migration hook. Specific procedures are described in 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].
+
+// THE FIGURE WILL BE REPLACED
+
+.Adding a hook to a migration plan
+image::updated_hooks_figure_from_martin_cropped.png[Adding a hook to 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 prehook or a posthook 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,130 @@
+// 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 add a migration hook to an existing migration plan using the {project-first} CLI.
+
+You can add a `PreHook` or a `PostHook` Hook CR when you migrate a virtual machine from the command line by using the {project-full} API. A `PreHook` runs before a migration, a `PostHook`, after.
+
+[NOTE]
+====
+You can retrieve additional information stored in a secret or in a `configMap` by using a `k8s` module.
+====
+
+For example, you can create a hook CR to install `cloud-init` on a VM and write a file before migration.
+
+.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 permission 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. You can either use an existing key or generate a key pair, install the public key on the VM, and base64 encode the private key in the Secret.
++
+[source,yaml]
+----
+apiVersion: v1
+data:
+  key: VGhpcyB3YXMgZ2VuZXJhdGVkIHdpdGggc3NoLWtleWdlbiBwdXJlbHkgZm9yIHRoaXMgZXhhbXBsZS4KSXQgaXMgbm90IHVzZWQgYW55d2hlcmUuCi0tLS0tQkVHSU4gT1BFTlNTSCBQUklWQVRFIEtFWS0tLS0tCmIzQmxibk56YUMxclpYa3RkakVBQUFBQUJHNXZibVVBQUFBRWJtOXVaUUFBQUFBQUFBQUJBQUFCbHdBQUFBZHpjMmd0Y24KTmhBQUFBQXdFQUFRQUFBWUVBMzVTTFRReDBFVjdPTWJQR0FqcEsxK2JhQURTTVFuK1NBU2pyTGZLNWM5NGpHdzhDbnA4LwovRHErZHFBR1pxQkg2ZnAxYmVJM1BZZzVWVDk0RVdWQ2RrTjgwY3dEcEo0Z1R0NHFUQ1gzZUYvY2x5VXQyUC9zaTNjcnQ0CjBQdi9wVnZXU1U2TlhHaDJIZC93V0MwcGh5Z0RQOVc5SHRQSUF0OFpnZmV2ZnUwZHpraVl6OHNVaElWU2ZsRGpaNUFqcUcKUjV2TVVUaGlrczEvZVlCeTdiMkFFSEdzYU8xN3NFbWNiYUlHUHZuUFVwWmQrdjkyYU1JdWZoYjhLZkFSbzZ3Ty9ISW1VbQovdDdHWFBJUmxBMUhSV0p1U05odTQzZS9DY3ZYd3Z6RnZrdE9kYXlEQzBMTklHMkpVaURlNWd0UUQ1WHZXc1p3MHQvbEs1CklacjFrZXZRNUJsYWNISmViV1ZNYUQvdllpdFdhSFo4OEF1Y0czaGh2bjkrOGNSTGhNVExiVlFSMWh2UVpBL1JtQXN3eE0KT3VJSmRaUmtxTThLZlF4Z28zQThRNGJhQW1VbnpvM3Zwa0FWdC9uaGtIOTRaRE5rV2U2RlRhdThONStyYTJCZkdjZVA4VApvbjFEeTBLRlpaUlpCREVVRVc0eHdTYUVOYXQ3c2RDNnhpL1d5OURaQUFBRm1NRFBXeDdBejFzZUFBQUFCM056YUMxeWMyCkVBQUFHQkFOK1VpMDBNZEJGZXpqR3p4Z0k2U3RmbTJnQTBqRUova2dFbzZ5M3l1WFBlSXhzUEFwNmZQL3c2dm5hZ0JtYWcKUituNmRXM2lOejJJT1ZVL2VCRmxRblpEZk5ITUE2U2VJRTdlS2t3bDkzaGYzSmNsTGRqLzdJdDNLN2VORDcvNlZiMWtsTwpqVnhvZGgzZjhGZ3RLWWNvQXovVnZSN1R5QUxmR1lIM3IzN3RIYzVJbU0vTEZJU0ZVbjVRNDJlUUk2aGtlYnpGRTRZcExOCmYzbUFjdTI5Z0JCeHJHanRlN0JKbkcyaUJqNzV6MUtXWGZyL2RtakNMbjRXL0Nud0VhT3NEdnh5SmxKdjdleGx6eUVaUU4KUjBWaWJrallidU4zdnduTDE4TDh4YjVMVG5Xc2d3dEN6U0J0aVZJZzN1WUxVQStWNzFyR2NOTGY1U3VTR2E5WkhyME9RWgpXbkJ5WG0xbFRHZy83MklyVm1oMmZQQUxuQnQ0WWI1L2Z2SEVTNFRFeTIxVUVkWWIwR1FQMFpnTE1NVERyaUNYV1VaS2pQCkNuME1ZS053UEVPRzJnSmxKODZONzZaQUZiZjU0WkIvZUdRelpGbnVoVTJydkRlZnEydGdYeG5Iai9FNko5UTh0Q2hXV1UKV1FReEZCRnVNY0VtaERXcmU3SFF1c1l2MXN2UTJRQUFBQU1CQUFFQUFBR0JBSlZtZklNNjdDQmpXcU9KdnFua2EvakRrUwo4TDdpSE5mekg1TnRZWVdPWmRMTlk2L0lRa1pDeFcwTWtSKzlUK0M3QUZKZzBNV2Q5ck5PeUxJZDkxNjZoOVJsNG0xdFJjCnViZ1o2dWZCZ3hGVDlXS21mSEdCNm4zelh5b2pQOEFJTnR6ODVpaUVHVXFFRWtVRVdMd0RGSmdvcFllQ3l1VmZ2ZE92MUgKRm1WWmEwNVo0b3NQNkNENXVmc2djQ1RYQTR6VnZ5ZHVCYkxqdHN5RjdYZjNUdjZUQ1QxU0swZHErQk1OOXRvb0RZaXpwagpzbDh6NzlybXp3eUFyWFlVcnFUUkpsNmpwRkNrWHJLcy9LeG96MHhhbXlMY2RORk9hWE51LzlnTkpjRERsV2hPcFRqNHk4CkpkNXBuV1Jueis1RHJLRFdhY0loUW1CMUxVd2ZLWmQwbVFxaUpzMUMxcXZVUmlKOGExaThKUTI4bHFuWTFRRk9wbk13emcKWEpla2FndThpT1ExRFJlQkhaM0NkcVJUYnY3bVJZSGxramx0dXJmZGc4M3hvM0ErZ1JSR001eUVOcW5xSkplQjhJQVB5UwptMFp0dGdqbHNqNTJ2K1B1NmExMHoxZndKK1VML2N6dTRKeEpOYlp6WTFIMnpLODJBaVI1T3JYNmx2aUEvSWFSRVcwUUFBCkFNQndVeUJpcUc5bEZCUnltL2UvU1VORVMzdHpicUZNdTdIcy84WTV5SnAxKzR6OXUxNGtJR2ttV0Y5eE5HT3hrY3V0cWwKeHVUcndMbjFUaFNQTHQrTjUwTGhVdzR4ZjBhNUxqemdPbklPU0FRbm5HY1Nxa0dTRDlMR21obGE2WmpydFBHY29lQ3JHdAo5M1Vvcmx5YkxNRzFFRFAxWmpKS1RaZzl6OUMwdDlTTGd3ei9DbFhydW9UNXNQVUdKWnUrbHlIZXpSTDRtcHl6OEZMcnlOCkdNci9leVM5bWdISjNVVkZEYjNIZ3BaK1E1SUdBRU5rZVZEcHIwMGhCZXZndGd6YWtBQUFEQkFQVXQ1RitoMnBVby94V1YKenRkcVQvMzA4dFB5MXVMMU1lWFoydEJPQmRwSDJyd0JzdWt0aTIySGtWZUZXQjJFdUlFUXppMzY3MGc1UGdxR1p4Vng4dQpobEE0Rkg4ZXN1NTNQckZqVW9EeFJhb3d3WXBFcFh5Y2pnNUE1MStwR1VQcWljWjB0YjliaWlhc3BWWXZhWW5sdGlnVG5iClN0UExMY29nemNiL0dGcVYyaXlzc3lwTlMwKzBNRTUxcEtxWGNaS2swbi8vVHpZWWs4TW8vZzRsQ3pmUEZQUlZrVVM5blIKWU1pQzRlcEk0TERmbVdnM0xLQ2N1Zk85all3aWgwYlFBQUFNRUE2WEtldDhEMHNvc0puZVh5WFZGd0dyVyszNlhBVGRQTwpMWDdjaStjYzFoOGV1eHdYQWx3aTJJNFhxSmJBVjBsVEhuVGEycXN3Uy9RQlpJUUJWSkZlVjVyS1daZTc4R2F3d1pWTFZNCldETmNwdFFyRTFaM2pGNS9TdUVzdlVxSDE0Tkc5RUFXWG1iUkNzelE0Vlk3NzQrSi9sTFkvMnlDT1diNzlLYTJ5OGxvYUoKVXczWWVtSld3blp2R3hKNldsL3BmQ2xYN3lEVXlXUktLdGl0cWNjbmpCWVkyRE1tZURwdURDYy9ZdDZDc3dLRmRkMkJ1UwpGZGt5cDlZY3VMaDlLZEFBQUFIR3BoYzI5dVFFRlVMVGd3TWxVdWJXOXVkR3hsYjI0dWFXNTBjbUVCQWdNRUJRWT0KLS0tLS1FTkQgT1BFTlNTSCBQUklWQVRFIEtFWS0tLS0tCgo=
+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 encode a playbook:
+
+[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: |
+    LS0tCi0gbmFtZTogTWFpbgogIGhvc3RzOiBsb2NhbGhvc3QKICB0YXNrczoKICAtIG5hbWU6IExv
+    YWQgUGxhbgogICAgaW5jbHVkZV92YXJzOgogICAgICBmaWxlOiAiL3RtcC9ob29rL3BsYW4ueW1s
+    IgogICAgICBuYW1lOiBwbGFuCiAgLSBuYW1lOiBMb2FkIFdvcmtsb2FkCiAgICBpbmNsdWRlX3Zh
+    cnM6CiAgICAgIGZpbGU6ICIvdG1wL2hvb2svd29ya2xvYWQueW1sIgogICAgICBuYW1lOiB3b3Jr
+    bG9hZAoK
+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 will need to execute one command in the {project-first} CLI.
+
+.Prerequisites
+
+* Migration plan
+* Migration hook file, whose contents you will copy-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 permission 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,53 @@
+:_content-type: SNIPPET
+
+
+.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
+----