Defining servers and shell.

docs/migration_invoking.md

@@ -1,57 +1,86 @@
 # Staging and running a migration
 
+In the following documentation the following servers are referenced:
+
+#### dc server
+Refers to the server that has `kubectl` and access to the cluster. It can be
+connected to as needed by [SSHing][kubernetes-access] to it.
+
+#### Drupal container
+Refers to the container that is running the Drupal instance and represents the
+site being migrated. It can be connected to as needed by
+[configuring][drupal-container-config] `kubectl` to point to it while on the
+[dc server][dc-server] and getting a shell.
+
 ## Preflight checks
+
 ### Splitting the objects into namespaces
 
-1. SSH to the `dc` server or any other server that has the Fedora data mounted.
-2. Navigate to the Fedora data directory.
+1. From the [dc server][dc-server] navigate to the Fedora data directory.<br />
    `cd /usr/local/fedora/data`
-3. Open a `screen` as it is a long running process.
-4. Invoke the namespaces splitting script.
+2. Open a `screen` as it is a long running process.
+3. Invoke the namespaces splitting script.<br />
    `sudo NAMESPACES=foo,bar ./namespace_split.sh`
-5. Detach from the screen.
+4. Detach from the screen.
 
 ### Ensure akubra_adapter is configured
 
-1. `echo $FEDORA_OBJECT_PATH`
-2. Ensure that this matches to the split out directory as noted above.
-3. If it does not, edit the [Drupal helm chart][helm-chart]'s `values.yml` for
-`FEDORA_OBJECT_PATH` and redeploy.
+1. From the [dc server][dc-server] point the
+[`kubectl` context][drupal-container-config] at the site being migrated.
+2. Verify the directory is correct for Fedora objects.<br />
+   `kubectl exec deployments/drupal -- /bin/bash -c 'echo $FEDORA_OBJECT_PATH'`
+3. Ensure that this matches to the split out directory as noted [above][split].
+4. If it does not, edit the [Drupal helm chart][helm-chart]'s `values.yml` on
+   the [dc server][dc-server] for the correct `FEDORA_OBJECT_PATH` and redeploy.
 
 ### Ensure Fedora data is readable
-1. `drush php:eval "var_dump(is_readable('foxml://object/a:pid'))"`
-This will return `TRUE` if the data exists and is readable. Choose an object
-that exists in the data set to compare.
+
+1. From the [dc server][dc-server] point the
+   [`kubectl` context][drupal-container-config] at the site being migrated.
+2. Ensure the data is readable.<br />
+   `kubectl exec deployments/drupal -- /bin/bash -c "drush php:eval \"var_dump(is_readable('foxml://object/a:pid'))\""`
+   <br />This will return `TRUE` if the data exists and is readable; `FALSE` otherwise.
+   Choose an object that exists in the data set to compare.
 
 ### Ensure the migration config split is enabled and imported
 
-1. `drush config-split:status-override migration active`
-2. `drush config-split:import migration`
+1. From the [Drupal container][drupal-server] get a shell.
+2. Ensure the migration config split is active.<br />
+   `drush config-split:status-override migration active`
+3. Import the config split to ensure it takes effect.<br />
+   `drush config-split:import migration`
 
 ### Disable entity_hierarchy rewriting
-1. `drush -r app sset entity_hierarchy_disable_writes 1`
+1. From the [Drupal container][drupal-server] get a shell.
+2. Disable `entity_hierarchy` from writing during the migration.<br />
+   `drush -r app sset entity_hierarchy_disable_writes 1`
 
 ## Invoking a migration
 
-1. Navigate to the migration logging directory for ease of use.
+1. From the [Drupal container][drupal-server] get a shell.
+2. Navigate to the migration logging directory for ease of use.<br />
    `cd $LOG_DIR`
-> [!NOTE] 
+> [!NOTE]
 > The `$LOG_DIR` variable is in an environment variable that is built into the
 > [Drupal container][log-dir] image.
-2. Open a `screen`.
-3. Invoke the migration script.
+3. Open a `screen`.
+4. Invoke the migration script.<br />
    `bash /opt/www/drupal/web/modules/contrib/dgi_migrate/scripts/migration.sh $LOG_DIR`
-4. Detach from the screen.
-5. Verify migration status.
-`drush ms --group=foxml_to_dgis`
-> [!NOTE] 
+5. Detach from the screen.
+6. Verify migration status.<br />
+   `drush ms --group=foxml_to_dgis`
+> [!NOTE]
 > A breakdown of the columns and their meanings can be found within the
-[status and error checking][status-and-error] portion of the 
+[status and error checking][status-and-error] portion of the
 > [migration overview][migration-overview] document.
-6. If required go through the [log messages][logging] to dig into any issues
-further.
-
+7. If required go through the [log messages][logging] to dig into any issues
+   further.
 
+[kubernetes-access]: migration_overview.md#kubernetes-access
+[drupal-container-config]: migration_overview.md#drupal-container-configuration
+[dc-server]: #dc-server
+[drupal-server]: #drupal-container
+[split]: #splitting-the-objects-into-namespaces
 [log-dir]: https://github.com/discoverygarden/bceln-drupal/blob/20226a504bd97853d737d08d39ee3236304a6709/Dockerfile#L57
 [status-and-error]: migration_overview.md#status-and-error-checking
 [migration-overview]: migration_overview.md

docs/migration_overview.md

@@ -111,13 +111,18 @@ Drupal.
 > in the [troubleshooting](#troubleshooting) section.
 
 ## Kubernetes Access
+
 1. Connect to the VPN.
 2. SSH to the node.
-3. List all available namespaces via: `kubectl get namespaces`.
-4. Switch to the desired site via: `kubectl config set-context --current 
+
+### Drupal Container Configuration
+1. List all available namespaces via: `kubectl get namespaces`.
+2. Switch to the desired site via: `kubectl config set-context --current
 --namespace={site}`.
-5. Get a shell via:
+3. Get a shell (if required) via:
    `kubectl exec --stdin --tty deployments/drupal  -- /bin/bash`
+4. Verify the site is correct via:
+   `echo $DRUSH_OPTIONS_URI`
 
 ## Staging data for ingestion
 The `akubra` filesystem is the source for the migration which the `foxml` source