Merge pull request #2 from emteelb/mat/add-step-2-collect-migration-info

add collecting info instructs for v1 -> v2 upgrading
LINBIT · Dec 14, 2023 · 5c8bb4d · 5c8bb4d
2 parents a684b4a + 5c2fafb
commit 5c8bb4d
Show file tree

Hide file tree

Showing 4 changed files with 718 additions and 2 deletions.
diff --git a/content/mvp.css b/content/mvp.css
@@ -251,15 +251,14 @@ p {
 pre {
     margin: 1rem 0;
     max-width: var(--width-card-wide);
-    padding: 1rem 0;
 }
 
 pre code,
 pre samp {
     display: block;
     max-width: var(--width-card-wide);
     padding: 0.5rem 2rem;
-    white-space: pre-wrap;
+    overflow-x: scroll;
 }
 
 small {

diff --git a/migration/1-migrate-db.html b/migration/1-migrate-db.html
@@ -16,6 +16,7 @@
             <li><a href="/migration/">Migration ▾</a>
                 <ul>
                     <li>1. Migrate Database</li>
+                    <li><a href="2-collect-information.html">2. Collect Information</a></li>
                 </ul>
             </li>
             <li><a href="/helm.html">Operator v1</a></li>

diff --git a/migration/2-collect-information.html b/migration/2-collect-information.html
@@ -0,0 +1,118 @@
+<!DOCTYPE html>
+<html lang="en" xmlns="http://www.w3.org/1999/html">
+<head>
+    <title>Collecting Information About the Current Deployment</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" href="/content/mvp.css"/>
+    <link rel="icon" href="/content/symbol.svg"/>
+</head>
+<body>
+<header>
+    <nav>
+        <img alt="Logo" src="/content/linbit_sds.svg" height="70"/>
+        <ul>
+            <li><a href="/">Operator v2</a></li>
+            <li><a href="/migration/">Migration ▾</a>
+                <ul>
+                    <li><a href="1-migrate-db.html">1. Migrate Database</a></li>
+                    <li>2. Collect Information</li>
+                </ul>
+            </li>
+            <li><a href="/helm.html">Operator v1</a></li>
+        </ul>
+    </nav>
+
+    <h1>Collecting Information About the Current Deployment</h1>
+</header>
+<main>
+    <article>
+        <p>
+            Before you upgrade a LINSTOR Operator v1 deployment to Operator v2, and remove the old v1 deployment,
+            collect information on the state of your cluster. You will use this collected information from your
+            Operator v1 deployment when you deploy Operator v2. Doing this ensures that the new upgraded deployment will
+            have a compatible configuration with your old deployment.
+        </p>
+
+        <p>
+            This is the second step when migrating the LINSTOR Operator from version 1 (v1) to version 2 (v2).
+        </p>
+
+        <h2>Prerequisites</h2>
+        <p>
+            To collect information about your current deployment, you will need to install the following tools:
+        </p>
+
+        <ul>
+            <li><a href="https://kubernetes.io/docs/tasks/tools/">kubectl</a> - to read the cluster state</li>
+            <li><a href="https://jqlang.github.io/jq/download/">jq</a> - a command-line JSON processor</li>
+        </ul>
+
+        <h2>Running the Data Collection Script</h2>
+        <p>
+            To collect the necessary information to migrate resources in your Operator v1 deployment to an upgraded
+            Operator v2 deployment, you can run a script provided by LINBIT.
+        </p>
+
+        <!-- For local development, try running "cat migration/collect.sh | bash -s" -->
+        <pre><code class="console">curl --proto '=https' --tlsv1.2 -sSf https://charts.linstor.io/migration/collect.sh | bash -s</code></pre>
+
+        <p>
+            When you run the script, the script will ask you if you want to keep modifications made with the LINSTOR
+            Operator. For each modification, the script will show you the proposed change to the deployed resources and
+            ask you for confirmation before making a change.
+        </p>
+
+        <p>
+            The script will also tell you about values in your deployment that cannot automatically be migrated, along
+            with recommended actions, in case you need to keep the modification.
+        </p>
+
+        <p>Example output from the script is as follows:</p>
+        <pre><code>Using kubectl context: kubernetes-admin@kubernetes
+Found LinstorControllers: [&quot;linstor-op-cs&quot;]
+Found LinstorSatelliteSets: [&quot;linstor-op-ns&quot;]
+Found LinstorCSIDrivers: [&quot;linstor-op&quot;]
+Found LINSTOR Controller passphrase secret
+--- Default resource
++++ Updated resource
+@@ -3,4 +3,5 @@ kind: LinstorCluster
+ metadata:
+   name: linstorcluster
+ spec:
++  linstorPassphraseSecret: linstor-op-passphrase
+   patches: []
+Apply the patch (Y/n)? y
+[...]
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------
+| The following non-default values have not been converted:                                                                                                       |
+|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Resource            | Key                            | Recommended Action                                  | Value                                              |
+|---------------------|--------------------------------|-----------------------------------------------------|----------------------------------------------------|
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+---------------------------------------------------------------------------------------------
+| After upgrading, apply the following resources. They have been saved to v2-resources.yaml |
+---------------------------------------------------------------------------------------------
+[...]</code></pre>
+
+        <p>
+            A copy of the identified resources in your current deployment is saved in a file named <code>v2-resources.yaml</code>.
+        </p>
+
+        <h2>Collecting Helm-Generated Secrets</h2>
+        <p>
+            Helm automatically generates a passphrase for LINSTOR. Once LINSTOR is initialized with the passphrase, the
+            LINSTOR Controller will not be able fully start without supplying the passphrase.
+        </p>
+
+        <p>
+            To migrate the generated passphrase to LINSTOR Operator v2, create a backup of the secret by entering the
+            following command:
+        </p>
+        <pre><code># kubectl get secrets linstor-op-passphrase -ogo-template=&#39;{{.data.MASTER_PASSPHRASE}}{{&quot;\n&quot;}}&#39;</code></pre>
+<p>Output from the command will show a generated passphrase. Save the passphrase for later use.</p>
+    </article>
+</main>
+</body>
+</html>