Merge branch '143-story-update-written-content-for-240' into consiste…

…ntFormating

Signed-off-by: Atif Ali <56743004+aali309@users.noreply.github.com>

_data/versions.yaml

@@ -1,16 +1,21 @@
 cryostat:
-  version: 2.3.0
-  release-branch: cryostat-v2.3
+  version: '2.4.0'
+  release-branch: 'cryostat-v2.4'
+agent:
+  version: '0.3.0'
 openshift:
   version: '4.10'
 kubernetes:
   version: '1.19'
 operator-sdk:
-  version: '1.28.0'
+  version: '1.31.0'
 operator-lifecycle-manager:
-  version: '0.24.0'
+  version: '0.25.0'
+cert-manager:
+  version: '1.11.5'
 documentation:
   - 'latest'
+  - 2.3.0
   - 2.2.0
   - 2.1.0
   - 2.0.0

demo/index.md

@@ -16,7 +16,7 @@ Core JFR functionality is not available in this stubbed out demo, but you can us
   <iframe
     id="demo-frame"
     class="demo-iframe"
-    src="https://cryostatio-cryostat-web-cryostat-v23.surge.sh"
+    src="https://cryostatio-cryostat-web-{{ site.data.versions.cryostat.release-branch | remove: '.' }}.surge.sh"
   ></iframe>
 </div>
 <script>

get-started/index.md

@@ -15,8 +15,9 @@ Cryostat {{ site.data.versions.cryostat.version }}
 Follow the steps below to install the **Cryostat Operator** via [**OperatorHub**](https://operatorhub.io/operator/cryostat-operator).
 
 ### [Install cert-manager](#install-cert-manager)
-The **Cryostat Operator** requires [cert-manager](https://cert-manager.io/) to run.
-If not already installed in your cluster, please
+
+The **Cryostat Operator** requires [cert-manager](https://cert-manager.io/) v{{ site.data.versions.cert-manager.version }}+ to run.
+If not already installed in your cluster, please 
 [install](https://cert-manager.io/docs/installation/) it using your preferred method.
 Once installed, proceed with the **Operator** installation steps below.
 
@@ -307,7 +308,7 @@ or you may use the following snippet in your `pom.xml` to streamline this.
                 <artifactItem>
                   <groupId>io.cryostat</groupId>
                   <artifactId>cryostat-agent</artifactId>
-                  <version>0.2.1</version>
+                  <version>{{ site.data.versions.agent.version }}</version>
                 </artifactItem>
               </artifactItems>
               <stripVersion>true</stripVersion>
@@ -509,7 +510,7 @@ Add dependency configurations to `pom.xml`:
                 <artifactItem>
                   <groupId>io.cryostat</groupId>
                   <artifactId>cryostat-agent</artifactId>
-                  <version>0.2.1</version>
+                  <version>{{ site.data.versions.agent.version }}</version>
                 </artifactItem>
               </artifactItems>
               <stripVersion>true</stripVersion>

version/2.3.0/guides/_subsections/add-a-trusted-certificate.md

@@ -0,0 +1,40 @@
+## [Add a Trusted Certificate](#add-a-trusted-certificate)
+If you have Java Management Extensions (JMX) over SSL enabled on your containerized JVMs, you must configure Cryostat to trust the SSL certificate presented by the containerized JVM when Cryostat attempts to open a JMX connection. If you do not complete this configuration, Cryostat cannot open a JMX connection for the purposes of performing JFR management tasks.
+
+Here's how to add a trusted SSL certificate with the Cryostat web UI.
+
+<ol>
+    <li>
+        {% include howto_step.html
+          summary="Navigate to the Security tab"
+          image-name="2.3.0/navigate-to-security.png"
+          text="Click the <i>Security</i> tab."
+        %}
+    </li>
+    <li>
+        {% include howto_step.html
+          summary="Upload the Certificate"
+          image-name="2.3.0/add-a-trusted-certificate-upload.png"
+          text="
+              Click the <i>Upload</i> button on the <i>Import SSL Certificates</i> card. This action opens a file-upload dialog, where you can choose the certificate that you want to upload to Cryostat. You can repeat this process multiple times to add multiple trusted certificates.
+          "
+        %}
+    </li>
+    <li>
+        Restart Cryostat to apply the changes. If you do not restart your Cryostat instance, the added certificates are not reloaded. This causes connections to fail because the Cryostat JMX client cannot trust the certificates. Depending on your deployment platform and configuration, restarting Cryostat might require any of the following:
+        <ul>
+            <li>
+                On OpenShift/Kubernetes with Cryostat Operator:
+                <pre>oc delete cryostat/&lt;my-cryostat-cr-name&gt;<br>oc create -f &lt;my-cryostat-cr-name&gt;.yaml</pre>
+            </li>
+            <li>
+                On OpenShift/Kubernetes without Cryostat Operator:
+                <pre>oc rollout retry dc/&lt;my-cryostat-dc-name&gt;</pre>
+            </li>
+            <li>
+                On Podman:
+                <pre>podman restart &lt;my-cryostat-container-id&gt;</pre>
+            </li>
+        </ul>
+    </li>
+</ol>

version/2.3.0/guides/_subsections/add-and-edit-recording-metadata-labels.md

@@ -0,0 +1,83 @@
+## [Add and Edit Recording Metadata Labels](#add-and-edit-recording-metadata-labels)
+Users can attach metadata or custom labels to JDK flight recordings managed by Cryostat. Recording labels can be used to identify recordings during queries or perform actions on multiple recordings containing the same labels. Here’s how to add and edit metadata labels on your JDK flight recordings.
+
+<ol>
+  <li>
+    {% include_relative _subsections/common/navigate-to-recordings.md %}
+  </li>
+  <li>
+    {% include_relative _subsections/common/click-create.md %}
+  </li>
+  <li>
+    {% include howto_step.html
+      summary="Add metadata labels to the Create Recording form"
+      image-name="2.3.0/add-and-edit-recording-metadata-labels-1.png"
+      text="
+        When creating a custom flight recording with Cryostat, expand the form section <i>Show metadata options</i>. Click <i>Add Label</i> and add key-value label pairs to the form. Finally, click <i>Create</i> to attach the labels and create the recording.
+      "
+    %}
+  </li>
+  <li>
+    {% include howto_step.html
+      summary="View your labels on the Active Recordings Table"
+      image-name="2.3.0/add-and-edit-recording-metadata-labels-2.png"
+      text="
+        The new recording will appear in the Recordings tab with your custom label as well as default labels containing information about the selected recording template.
+      "
+    %}
+  </li>
+  <li>
+    {% capture edit-an-existing-label-text %}
+    <p>
+      Recording labels can also be edited after recordings have been created or re-uploaded to archives. It looks like the custom label in our example contains a typo - we can fix the typo by editing the label. First select a recording from the table with the 🗹 checkbox. Then, click the <i>Edit Labels</i> button to bring up the label drawer. Finally, click the <i>Edit</i> button that appears from the drawer.
+      <br><br>
+      <a href="{{ site.url }}/images/2.3.0/add-and-edit-recording-metadata-labels-4.png" target="_blank">
+        <img src="{{ site.url }}/images/2.3.0/add-and-edit-recording-metadata-labels-4.png">
+      </a>
+      <br><br>
+      The labels section will appear as a form where you can add, edit, or delete existing labels, just like before when we created the recording. Fix the typo, and click <i>Save</i> to save your edited labels.
+    </p>
+    {% endcapture %}
+    {% include howto_step.html
+      summary="Edit an existing label"
+      image-name="2.3.0/add-and-edit-recording-metadata-labels-3.png"
+      text=edit-an-existing-label-text
+    %}
+  </li>
+  <li>
+    {% include howto_step.html
+      summary="View your edited labels"
+      image-name="2.3.0/add-and-edit-recording-metadata-labels-5.png"
+      text="
+        The recording labels should be updated in the Active Recordings table. 
+      "
+    %}
+  </li>
+  <li>
+    {% include howto_step.html
+      summary="<i>(Optional)</i> Archive your recording to view labels copied onto the archived recording"
+      image-name="2.3.0/add-and-edit-recording-metadata-labels-6.png"
+      text="
+        On the Active Recordings table, click the checkbox next to the recording, then click <i>Archive</i> to archive your recording. Notice that the archived recording also copies the labels from the active recording. You can also add labels to any recording uploaded to Cryostat’s archives.
+      "
+    %}
+  </li>
+  <li>
+    {% capture bulk-edit-recording-labels-text %}
+    <p>
+      Create another recording on the same target. Then select both recordings on the Recordings Table and click <i>Edit Labels</i> and <i>Edit</i>.This time, only labels that are present on both recordings will be shown in the form. Let's delete the two common template-related labels, and add a new label to both recordings. Then finally, click <i>Save</i>.
+      <br><br>
+      <a href="{{ site.url }}/images/2.3.0/add-and-edit-recording-metadata-labels-8.png" target="_blank">
+        <img src="{{ site.url }}/images/2.3.0/add-and-edit-recording-metadata-labels-8.png">
+      </a>
+      <br><br>
+      Congratulations, you have successfully bulk-edited labels across multiple recordings!
+    </p>
+    {% endcapture %}
+    {% include howto_step.html
+      summary="<i>(Optional)</i> Bulk-edit recording labels across multiple recordings"
+      image-name="2.3.0/add-and-edit-recording-metadata-labels-7.png"
+      text=bulk-edit-recording-labels-text
+    %}
+  </li>
+</ol>

version/2.3.0/guides/_subsections/archive-a-recording.md

@@ -0,0 +1,55 @@
+## [Archive a Recording](#archive-a-recording)
+In contrast to <i>Active Recordings</i>, which reside within the container
+of the target application, <i>Archived Recordings</i> reside within persistent
+storage attached to a Cryostat instance. In OpenShift, for example, the
+archives are stored in a `PersistentVolumeClaim`.
+
+Archived recordings are created by performing archival upon active recordings.
+When this is requested, Cryostat connects to the target application and copies
+the Flight Recorder data from the selected active recording into an archived
+recording file in storage. The active source recording may be continuous or
+fixed-duration, may be using any event template, may be in
+any state (`RUNNING`, `STOPPED`, etc.), and may even be a snapshot.
+
+<ol>
+  <li>
+    {% include_relative _subsections/common/select-target-application.md %}
+  </li>
+  <li>
+    {% include_relative _subsections/common/navigate-to-recordings.md %}
+  </li>
+  <li>
+    {% capture select-recording-additional-content %}
+      <p>
+        If you do not have any recordings present in the Active Recordings
+        view, follow
+        <a href="{{ page.url }}#startstop-a-recording">Start/Stop a Recording</a>
+        to create one, or select a different target application.
+      </p>
+    {% endcapture %}
+    {% include howto_step.html
+      summary="Select an Active Recording"
+      image-name="2.3.0/archive-a-recording-1.png"
+      caption=select-recording-additional-content
+    %}
+  </li>
+  <li>
+    <summary>Click the <i>Archive</i> button</summary>
+  </li>
+  <li>
+    {% include howto_step.html
+      summary="Navigate to the <i>Archived Recordings</i> tab"
+      image-name="2.3.0/archive-a-recording-2.png"
+      caption="
+        Once the recording has been archived, a new entry will appear in the
+        target JVM's <i>Archived Recordings</i> table. All recordings that were
+        saved from the current target will be listed here in their own table.
+        Switching to a different target from the dropdown will list only the 
+        recordings archived from that source target. The name of the archived 
+        recording reflects the address of the target application, the original 
+        name of the active recording that it was retrieved from, and includes a 
+        timestamp indicating when the archived recording was created.
+      "
+    %}
+  </li>
+</ol>

version/2.3.0/guides/_subsections/automated-analysis.md

@@ -0,0 +1,90 @@
+## [View and Download Automated Analysis for a Recording](#view-and-download-automated-analysis-for-a-recording)
+Cryostat integrates the same automated analysis reports that you would
+find in [JDK Mission Control](https://github.com/openjdk/jmc). The
+JMC rules engine analyzes your recording and looks for common problems
+and assigns a severity score from 0 (no problem) to 100 (potentially
+severe problem). Results with score 0 are hidden from the report unless
+you select the _Show OK Results_ checkbox. More details on each
+result can be found by clicking on the _+_ symbol to the right of
+the rule name. These details often include suggestions on how to fix
+the problem. Cryostat also allows you to download the report HTML file
+for offline use.
+
+Cryostat also provides an *Automated Analysis Card* that is able to display the same information in a more user-friendly format, with more tools and control over the data you see. The card is available for use in the *Dashboard*. Read the section on the [Automated Analysis Card](#automated-analysis-card) for more information.
+
+<ol>
+  <li>
+    {% include_relative _subsections/common/select-target-application.md %}
+  </li>
+  <li>
+    {% include_relative _subsections/common/navigate-to-recordings.md %}
+  </li>
+  <li>
+    {% include_relative _subsections/common/select-a-recording.md
+      select-a-recording-caption="
+        If you do not have any recordings present in the Active Recordings
+        view, follow
+        <a href='#startstop-a-recording'>Start/Stop a Recording</a>
+        to create one, or select a different target application.
+        You may also select an archived recording for automated analysis.
+      "
+    %}
+  </li>
+  <li>
+    {% include howto_step.html
+      summary="Expand the recording"
+      image-name="2.3.0/automated-analysis-1.png"
+      caption="
+        Expand the recording with the chevron to the left of the recording
+        name. The automated analysis report will appear below the recording.
+      "
+    %}
+  </li>
+  <li>
+    {% include howto_step.html
+      summary="View details and suggestions for results"
+      image-name="2.3.0/automated-analysis-2.png"
+      caption="
+        Click the <i>+</i> button on the right side of each result to view
+        specifics on what the result means and possible suggestions to fix
+        the potential problem.
+      "
+    %}
+  </li>
+  <li>
+    {% capture download-report-text %}
+    <p>
+      <figure>
+        <a href="{{ site.url }}/images/2.3.0/automated-analysis-4.png" target="_blank">
+          <img src="{{ site.url }}/images/2.3.0/automated-analysis-4.png">
+        </a>
+        <figcaption>
+          View the report on its own without connecting to Cryostat.
+          Check <i>Show OK Results</i> to include results where the rules
+          engine found no issues in the recording.
+        </figcaption>
+      </figure>
+      <figure>
+        <a href="{{ site.url }}/images/2.3.0/automated-analysis-5.png" target="_blank">
+          <img src="{{ site.url }}/images/2.3.0/automated-analysis-5.png">
+        </a>
+        <figcaption>
+          To download the HTML <i>Automated Analysis</i> report to local disk, right click 
+          the page and select <i>Save Page As...</i>. Alternatively, press <kbd>Ctrl</kbd>+<kbd>S</kbd> 
+          on Windows/Linux, or <kbd>⌘</kbd>+<kbd>S</kbd> on macOS.
+        </figcaption>
+      </figure>
+    </p>
+    {% endcapture %}
+    {% include howto_step.html
+      summary="Download the report"
+      image-name="2.3.0/automated-analysis-3.png"
+      caption="
+        To download the automated analysis report for offline viewing,
+        select <i>View Report ...</i> from the recording's overflow
+        menu.
+      "
+      text=download-report-text
+    %}
+  </li>
+</ol>

version/2.3.0/guides/_subsections/common/card-catalog.md

@@ -0,0 +1,9 @@
+{% capture card-catalog-include-text %}
+ The <i>Dashboard Card Catalog</i> contains a list of available cards that can be added to the dashboard. Clicking on a card will open a panel containing a preview.
+{% endcapture %}
+{% include howto_step.html
+  summary="Open the Card Catalog"
+  image-name="2.3.0/dashboard/card-catalog.png"
+  caption="Open the card catalog by clicking the Catalog icon on the Dashboard toolbar."
+  text=card-catalog-include-text
+%}

version/2.3.0/guides/_subsections/common/click-create.md

@@ -0,0 +1,4 @@
+{% include howto_step.html
+  summary="Click <i>Create</i>"
+  image-name="2.3.0/click-create.png"
+%}

version/2.3.0/guides/_subsections/common/layout-selector.md

@@ -0,0 +1,9 @@
+{% capture layout-selector-text %}
+The layout selector contains a list of all available layouts. The currently selected layout is indicated with a check mark "✓".
+{% endcapture %}
+{% include howto_step.html
+summary="Open the layout selector dropdown"
+image-name="2.3.0/dashboard/dashboard-layoutselector.png"
+caption="Click the layout selector dropdown to view the available layouts."
+text=layout-selector-text
+%}

version/2.3.0/guides/_subsections/common/navigate-to-dashboard.md

@@ -0,0 +1,9 @@
+{% capture navigate-to-dashboard-include-text %}
+ The <i>Cryostat Dashboard</i> provides a high-level overview of the state of your Cryostat instance and the target JVM applications it is monitoring.
+{% endcapture %}
+{% include howto_step.html
+  summary="Navigate to <i>Dashboard</i>"
+  image-name="2.3.0/navigate-to-dashboard.png"
+  caption="Add dashboard cards, switch between dashboard layouts, and modify the layout configuration to suit your needs."
+  text=navigate-to-dashboard-include-text
+%}

version/2.3.0/guides/_subsections/common/navigate-to-recordings.md

@@ -0,0 +1,20 @@
+{% capture navigate-to-recordings-include-text %}
+  If the target JVM has SSL/TLS enabled on JMX connections then it may be
+  necessary to add the target's certificate to Cryostat's trust store. Go
+  to <a href="{{ site.url }}/guides/#add-a-trusted-certificate">Add a Trusted Certificate</a>
+  and return to this section after completing that guide.
+  <a href="{{ site.url }}/images/2.3.0/navigate-to-recordings-2.png" target="_blank">
+    <img src="{{ site.url }}/images/2.3.0/navigate-to-recordings-2.png">
+  </a>
+  {{ include.additional-content }}
+{% endcapture %}
+{% include howto_step.html
+  summary="Navigate to Recordings"
+  image-name="2.3.0/navigate-to-recordings-1.png"
+  caption="
+    Supply JMX credentials to authenticate to the target, if necessary. If
+    the target is not configured with JMX authentication then the
+    connection attempt will continue without prompting for credentials.
+  "
+  text=navigate-to-recordings-include-text
+%}