diff --git a/documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc b/documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc index 956fca66bf0..b52e5c28ea8 100644 --- a/documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc +++ b/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] diff --git a/documentation/modules/about-hook-crs-for-migration-plans-api.adoc b/documentation/modules/about-hook-crs-for-migration-plans-api.adoc deleted file mode 100644 index 4715cf6ce52..00000000000 --- a/documentation/modules/about-hook-crs-for-migration-plans-api.adoc +++ /dev/null @@ -1,49 +0,0 @@ -// Module included in the following assemblies: -// -// * documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc - -:_content-type: CONCEPT -[id="about-api-hooks-in-migration-plans_{context}"] -= API-based hooks for {project-short} migration plans - -You can add hooks to a migration plan from the command line by using the {project-full} API. - -[discrete] -== Default hook image -The default hook image for an {project-short} hook is `registry.redhat.io/rhmtc/openshift-migration-hook-runner-rhel8:v1.8.2-2`. 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. - -[discrete] -== 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. - -[discrete] -== PreHooks and PostHooks -You specify hooks per VM and you can run each as a _PreHook_ or a _PostHook_. In this context, a PreHook is a hook that is run before a migration and a PostHook is a hook that is run after a migration. - -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 PreHook or PostHook. - -[IMPORTANT] -==== -In order for a PreHook to run on a VM, the VM must be started and available via SSH. -==== - -.Example PreHook: - -[source,yaml] ----- -kind: Plan -apiVersion: forklift.konveyor.io/v1beta1 -metadata: - name: test - namespace: konveyor-forklift -spec: - vms: - - id: vm-2861 - hooks: - - hook: - namespace: konveyor-forklift - name: playbook - step: PreHook ----- - - diff --git a/documentation/modules/about-hooks-for-migration-plans.adoc b/documentation/modules/about-hooks-for-migration-plans.adoc new file mode 100644 index 00000000000..8256f9f1b42 --- /dev/null +++ b/documentation/modules/about-hooks-for-migration-plans.adoc @@ -0,0 +1,66 @@ +// 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. diff --git a/documentation/modules/adding-hook-using-cli.adoc b/documentation/modules/adding-hook-using-cli.adoc new file mode 100644 index 00000000000..4fbce54c1a1 --- /dev/null +++ b/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: openshift-mtv +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: + 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: + hooks: + - hook: + namespace: + name: + step: <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[] \ No newline at end of file diff --git a/documentation/modules/adding-hook-using-ui.adoc b/documentation/modules/adding-hook-using-ui.adoc new file mode 100644 index 00000000000..c2dc77172f3 --- /dev/null +++ b/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*. but if they specify the spec.playbook they need to provide us with 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*. 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 \ + -p '{"spec":{"serviceAccount":""}}' --type merge +---- + +include::snip_example-hook-for-migration-plans.adoc[] diff --git a/documentation/modules/common-attributes.adoc b/documentation/modules/common-attributes.adoc index 1dbebeb68e9..e7371b22d86 100644 --- a/documentation/modules/common-attributes.adoc +++ b/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 diff --git a/documentation/modules/images/migration_hook_process.png b/documentation/modules/images/migration_hook_process.png new file mode 100644 index 00000000000..745515213f5 Binary files /dev/null and b/documentation/modules/images/migration_hook_process.png differ diff --git a/documentation/modules/snip_example-hook-for-migration-plans.adoc b/documentation/modules/snip_example-hook-for-migration-plans.adoc new file mode 100644 index 00000000000..5c1972a0137 --- /dev/null +++ b/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 +---- \ No newline at end of file diff --git a/documentation/modules/virt-v2v-mtv.adoc b/documentation/modules/virt-v2v-mtv.adoc index 660622ef9e5..f61434f94bb 100644 --- a/documentation/modules/virt-v2v-mtv.adoc +++ b/documentation/modules/virt-v2v-mtv.adoc @@ -33,7 +33,7 @@ If you are migrating from VMware or from OVA files, `virt-v2v` also sets their I [NOTE] ==== -You can also run pre-defined Ansible hooks before or after a migration using {project-short}. For more information, see xref:../master.adoc#adding-hooks-migration-plan-using-api[Adding hooks to a migration plan]. +You can also run pre-defined Ansible hooks before or after a migration using {project-short}. For more information, see xref:../master.adoc#adding-hooks-mtv-migration-plan[Adding hooks to an MTV migration plan]. These hooks do not necessarily use `virt-v2v`. ====