Skip to content

Commit 84cb85f

Browse files
RichardHochRichardHoch
committed
Improved description of hooks
Signed-off-by: RichardHoch <[email protected]>
1 parent e0925da commit 84cb85f

7 files changed

+311
-54
lines changed

‎documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc

+6-5
Original file line numberDiff line numberDiff line change
@@ -312,13 +312,14 @@ include::modules/creating-validation-rule.adoc[leveloffset=+3]
312312
include::modules/updating-validation-rules-version.adoc[leveloffset=+3]
313313
include::modules/retrieving-validation-service-json.adoc[leveloffset=+2]
314314

315-
[id="adding-hooks-migration-plan-using-api"]
316-
=== Adding hooks to a migration plan
317-
You can add hooks a migration plan from the command line by using the {project-full} API.
315+
[id="adding-hooks-mtv-migration-plan"]
316+
=== Adding hooks to an MTV migration plan
318317

319-
include::modules/about-hook-crs-for-migration-plans-api.adoc[leveloffset=+3]
318+
You can add hooks to an {project-first} migration plan to perform automated operations on a VM either before or after you migrate it.
320319

321-
include::modules/adding-hook-crs-to-migration-plans-api.adoc[leveloffset=+3]
320+
include::modules/about-hooks-for-migration-plans.adoc[leveloffset=+3]
321+
include::modules/adding-hook-using-ui.adoc[leveloffset=+3]
322+
include::modules/adding-hook-using-cli.adoc[leveloffset=+3]
322323

323324
include::modules/upgrading-mtv-ui.adoc[leveloffset=+1]
324325

‎documentation/modules/about-hook-crs-for-migration-plans-api.adoc

-49
This file was deleted.

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

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="about-hooks-for-migration-plans_{context}"]
7+
= About hooks for {project-short} migration plans
8+
9+
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.
10+
11+
* _Pre-migration_ hooks are hooks that perform operations on a VM that is located on a provider. This prepares the VM for migration.
12+
13+
* _Post-migration_ hooks are hooks that perform operations on a VM that has migrated to {virt}.
14+
15+
[id="default-hook-image_{context}"]
16+
== Default hook image
17+
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.
18+
19+
[id="hook-execution_{context}"]
20+
== Hook execution
21+
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.
22+
23+
24+
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.
25+
26+
[IMPORTANT]
27+
====
28+
In order for a hook to run on a VM, the VM must be started and available using SSH.
29+
====
30+
31+
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].
32+
33+
.Adding a hook to a migration plan
34+
image::migration_hook_process.png[Adding a hook to a migration plan]
35+
36+
*Process:*
37+
38+
. Input your Ansible hook and credentials.
39+
40+
.. Input an Ansible hook image to the {project-short} controller using either the UI or the CLI.
41+
+
42+
* In the UI, specify the `ansible-runner` and enter the `playbook.yml` that contains the hook.
43+
* In the CLI, input the hook image, which specifies the playbook that runs the hook.
44+
45+
.. 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.
46+
+
47+
[NOTE]
48+
====
49+
This Secret is not the same as the `Secret` CR that contains the credentials of your source provider.
50+
====
51+
52+
. The {project-short} controller creates the `ConfigMap`, which contains:
53+
54+
** `workload.yml`, which contains information about the VMs.
55+
** `playbook.yml`, the raw string playbook you want to execute.
56+
** `plan.yml`, which is the `Plan` CR.
57+
+
58+
The `ConfigMap` contains the name of the VM and instructs the playbook what to do.
59+
60+
. The {project-short} controller creates a job that starts the user specified image.
61+
.. Mounts the `ConfigMap` to the container.
62+
+
63+
The Ansible hook imports the Secret that the user previously entered.
64+
. The job runs a pre-migration hook or a post-migration hook as follows:
65+
66+
.. For a pre-migration hook, the job logs into the VMs on the source provider using SSH and runs the hook.
67+
.. 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

+132
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="adding-migration-hook-via-cli_{context}"]
7+
= Adding a migration hook to a migration plan using the CLI
8+
9+
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.
10+
11+
For example, you can create a `Hook` CR to install the `cloud-init` service on a VM and write a file before migration.
12+
13+
[NOTE]
14+
====
15+
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.
16+
====
17+
18+
[NOTE]
19+
====
20+
You can retrieve additional information stored in a secret or in a `ConfigMap` by using a `k8s` module.
21+
====
22+
23+
.Prerequisites
24+
25+
* Migration plan
26+
* Migration hook image or the playbook containing the hook image
27+
28+
[NOTE]
29+
====
30+
You can run one pre-migration hook, one post-migration hook, or one of each per migration plan.
31+
====
32+
33+
* File containing the Secret for the source provider
34+
* {ocp} service account that has at least write access for the namespace you are working in
35+
* SSH access for VMs you want to migrate with the public key installed on the VMs
36+
* VMs running on Microsoft Server only: Remote Execution enabled
37+
38+
.Procedure
39+
. If needed, create a Secret with an SSH private key for the VM.
40+
.. Choose an existing key or generate a key pair.
41+
.. Install the public key on the VM.
42+
.. Encode the private key in the Secret to base64.
43+
+
44+
[source,yaml]
45+
----
46+
apiVersion: v1
47+
data:
48+
key: VGhpcyB3YXMgZ2Vu...
49+
kind: Secret
50+
metadata:
51+
name: ssh-credentials
52+
namespace: konveyor-forklift
53+
type: Opaque
54+
----
55+
. Encode your playbook by concatenating a file and piping it for base64, for example:
56+
+
57+
[source,shell]
58+
----
59+
$ cat playbook.yml | base64 -w0
60+
----
61+
+
62+
[NOTE]
63+
====
64+
You can also use a `here` document to add instructions to encode a playbook inside a larger command:
65+
66+
[source,shell]
67+
----
68+
$ cat << EOF | base64 -w0
69+
- hosts: localhost
70+
tasks:
71+
- debug:
72+
msg: test
73+
EOF
74+
----
75+
====
76+
77+
. Create a Hook CR:
78+
+
79+
[source,yaml,subs="attributes+"]
80+
----
81+
$ cat << EOF | {oc} apply -f -
82+
apiVersion: forklift.konveyor.io/v1beta1
83+
kind: Hook
84+
metadata:
85+
name: <hook>
86+
namespace: <namespace>
87+
spec:
88+
image: quay.io/konveyor/hook-runner
89+
playbook: |
90+
LS0tCi0gbm...
91+
EOF
92+
----
93+
+
94+
where:
95+
+
96+
`playbook` refers to an optional Base64-encoded Ansible Playbook. If you specify a playbook, the `image` must be `hook-runner`.
97+
+
98+
[NOTE]
99+
====
100+
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.
101+
====
102+
+
103+
[NOTE]
104+
====
105+
To decode an attached playbook, retrieve the resource with custom output and pipe it to base64. For example:
106+
[source,shell]
107+
----
108+
oc get -n konveyor-forklift hook playbook -o \
109+
go-template='{{ .spec.playbook }}' | base64 -d
110+
----
111+
====
112+
+
113+
. In the `Plan` CR of the migration, for each VM, add the following section to the end of the CR:
114+
+
115+
[source,yaml]
116+
----
117+
vms:
118+
- id: <vm_id>
119+
hooks:
120+
- hook:
121+
namespace: <namespace>
122+
name: <name_of_hook>
123+
step: <type_of_hook> <1>
124+
----
125+
<1> Options are `PreHook`, to run the hook before the migration, and `PostHook`, to run the hook after the migration.
126+
127+
[IMPORTANT]
128+
====
129+
In order for a PreHook to run on a VM, the VM must be started and available via SSH.
130+
====
131+
132+
include::snip_example-hook-for-migration-plans.adoc[]

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

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * documentation/doc-Migration_Toolkit_for_Virtualization/master.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="adding-migration-hook-via-ui_{context}"]
7+
= Adding a migration hook to a migration plan using the {ocp} web console
8+
9+
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.
10+
11+
.Prerequisites
12+
13+
* Migration plan
14+
* Migration hook file, whose contents you copy and paste into the web console
15+
16+
[NOTE]
17+
====
18+
You can run one pre-migration hook, one post-migration hook, or one of each per migration plan.
19+
====
20+
21+
* File containing the `Secret` for the source provider
22+
* {ocp} service account that has at least write access for the namespace you are working in
23+
* SSH access for VMs you want to migrate with the public key installed on the VMs
24+
* VMs running on Microsoft Server only: Remote Execution enabled
25+
26+
27+
.Procedure
28+
29+
. In the {ocp} web console, click *Migration* > *Plans for virtualization* and then click the migration plan you want to add the hook to.
30+
. Click *Hooks*.
31+
. For a pre-migration hook, perform the following steps:
32+
33+
.. In the *Pre migration hook* section, toggle the *Enable hook* switch to *Enable pre migration hook*.
34+
.. 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.
35+
.. Paste your hook as a YAML file in the *Ansible playbook* text box.
36+
37+
. For a post-migration hook, perform the following steps:
38+
39+
.. In the *Post migration hook*, toggle the *Enable hook* switch *Enable post migration hook*..
40+
.. 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.
41+
.. Paste your hook as a YAML file in the *Ansible playbook* text box.
42+
43+
. At the top of the tab, click *Update hooks*.
44+
. In a terminal, enter the following command to associate each hook with your {ocp} service account:
45+
+
46+
[source,terminal,subs="attributes+"]
47+
----
48+
$ oc -n openshift-mtv patch hook <name_of_hook> \
49+
-p '{"spec":{"serviceAccount":"<service_account>"}}' --type merge
50+
----
51+
52+
include::snip_example-hook-for-migration-plans.adoc[]

‎documentation/modules/images/migration_hook_process.png

34.7 KB
Loading

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

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
:_content-type: SNIPPET
2+
3+
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.
4+
5+
.Example migration hook
6+
[source,yaml,subs="attributes+"]
7+
----
8+
- name: Main
9+
hosts: localhost
10+
vars_files:
11+
- plan.yml
12+
- workload.yml
13+
tasks:
14+
- k8s_info:
15+
api_version: v1
16+
kind: Secret
17+
name: privkey
18+
namespace: openshift-mtv
19+
register: ssh_credentials
20+
21+
- name: Ensure SSH directory exists
22+
file:
23+
path: ~/.ssh
24+
state: directory
25+
mode: 0750
26+
27+
- name: Create SSH key
28+
copy:
29+
dest: ~/.ssh/id_rsa
30+
content: "{{ ssh_credentials.resources[0].data.key | b64decode }}"
31+
mode: 0600
32+
33+
- add_host:
34+
name: "{{ workload.vm.ipaddress }}" # ALT "{{ workload.vm.guestnetworks[2].ip }}"
35+
ansible_user: root
36+
groups: vms
37+
38+
- hosts: vms
39+
vars_files:
40+
- plan.yml
41+
- workload.yml
42+
tasks:
43+
- name: Stop MariaDB
44+
service:
45+
name: mariadb
46+
state: stopped
47+
48+
- name: Create Test File
49+
copy:
50+
dest: /premigration.txt
51+
content: "Migration from {{ provider.source.name }}
52+
of {{ vm.vm1.vm0.id }} has finished\n"
53+
mode: 0644
54+
----

0 commit comments

Comments
 (0)