Getting started with Cryostat

Procedure

1. In the Red Hat OpenShift Container Platform, navigate to Home > Projects.
2. Select the name of the project in which you want to install the Red Hat build of Cryostat Operator.

3. Install the Red Hat build of Cryostat Operator:

   1. In the navigation menu of your web console, navigate to Operators > OperatorHub.
   2. Select Red Hat build of Cryostat from the list. You can use the search box in the upper part of the screen to find the Red Hat build of Cryostat Operator.

   3. To install the Red Hat build of Cryostat Operator in your project, click Install.

      Note

      In the Installation mode area, the All namespaces on the cluster (default) radio button is the only available option.

Procedure

1. If you want to create the CR manually, complete the following steps:

   1. Navigate to Operators > Installed Operators by using the web console and select Red Hat build of Cryostat Operator from the list of installed operators:

      Figure 2.2. Viewing the Red Hat build of Cryostat operator in the list of installed operators

      

      View larger image

      
   2. Click the Details tab.

   3. To create a Cryostat instance, go to the Provided APIs section. Then, under Cryostat, click Create instance.

      Note

      The Cryostat API enables you to create both single-namespace and multi-namespace Cryostat instances.

      Figure 2.3. Selecting the Cryostat API that is provided by the Red Hat build of Cryostat Operator

      

      View larger image

      
   4. Click either the Form view radio button or the YAML view radio button. If you want to enter your information in the YAML configuration file, click YAML view .
   5. Specify a unique name for the instance of Cryostat that you want to create.
   6. Optional: In the Labels field, specify a label or annotation for the Operand workload you want to deploy.

   7. In the Target Namespaces field, select namespaces whose workloads you want to permit this instance of Cryostat to access and work with. Optionally, you can select the same namespace where you installed Cryostat or you can choose a different namespace. To add additional namespaces, click +Add Target Namespace.

      Note

      If you leave this field blank, the Operator uses the installation namespace of your Cryostat instance as the target namespace.

      Important

      Users who can access the Cryostat instance have access to all target applications in any namespace that is visible to that Cryostat instance. Therefore, when you deploy a multi-namespace Cryostat instance, you must consider which namespaces to select for monitoring, which namespace to install Cryostat into, and which users you want to grant access to.

      You can also specify additional configuration options for your deployment:

      Figure 2.4. Creating an instance of Cryostat by using a form in the web console

      

      View larger image

      

      Alternatively, you can use a YAML template to create your instance and specify additional configuration options instead of using the form:

      Figure 2.5. Creating an instance of Cryostat by using a YAML template in the web console

      

      View larger image

      

2. If you want to create the CR by using the automatic prompt option, follow the prompt’s instructions and then complete the following steps:

   1. Click either the Form view radio button or the YAML view radio button. If you want to enter your information in the YAML configuration file, click YAML view.
   2. Specify a unique name for the instance of Cryostat that you want to create.
   3. Optional: In the Labels field, specify a label or annotation for the Operand workload you want to deploy.

   4. In the Target Namespaces field, select namespaces whose workloads you want to permit this instance of Cryostat to access and work with. Optionally, you can select the same namespace where you installed Cryostat or you can choose a different namespace. To add additional namespaces, click +Add Target Namespace.

      Note

      If you leave this field blank, the Operator uses the installation namespace of your Cryostat instance as the target namespace.

      Important

      Users who can access the Cryostat instance have access to all target applications in any namespace that is visible to that Cryostat instance. Therefore, when you deploy a multi-namespace Cryostat instance, you must consider which namespaces to select for monitoring, which namespace to install Cryostat into, and which users you want to grant access to.

      You can also specify additional configuration options for your deployment:

      Figure 2.6. Creating an instance of Cryostat by using a form in the web console

      

      View larger image

      

      Alternatively, you can use a YAML template to create your instance and specify additional configuration options instead of using the form:

      Figure 2.7. Creating an instance of Cryostat by using a YAML template in the web console

      

      View larger image

      

3. To start the creation process for your Cryostat instance, click Create.

   You must wait for all resources of your Cryostat instance to be ready before you can access it.

Verification

1. In the navigation menu of the web console, click Operators, then click Installed Operators.
2. From the table of installed operators, select Red Hat build of Cryostat.

3. Select the Cryostat tab.

   Your Cryostat instance opens in the table of instances and lists the following conditions:

   • TLSSetupComplete is set to true.
   • MainDeploymentAvailable is set to true.

   • Optional: If you enabled the reports generator service then ReportsDeploymentAvailable is shown and set to true.

     Figure 2.8. Example of conditions set to True under the Status column for a Cryostat instance on OpenShift

     

     View larger image

     

4. Optional: Select your Cryostat instance from the Cryostat table. Go to the Cryostat Conditions table, where you can see more information for each condition.

   Figure 2.9. Example of a Cryostat Conditions table that lists each condition and its criteria

   

   View larger image

   

Procedure

1. To enable remote JMX connections, complete the following steps:

   1. On your application, define the following Java system property:

      -Dcom.sun.management.jmxremote.port=<port_num>

      Copy to Clipboard Toggle word wrap
      Note

      To add the -Dcom.sun.management.jmxremote.port=<port_num> property without having to rebuild the target application, you can set the JAVA_OPTS_APPEND environment variable on the application. JAVA_OPTS_APPEND is an environment variable that is used by Red Hat Universal Base Images (UBI) only.

      If you use Red Hat UBI to build application images, set the JAVA_OPTS_APPEND variable at build time in the application Docker file, or at runtime by running the following command:

      oc set env deployment <name> JAVA_OPTS_APPEND="..."

      Copy to Clipboard Toggle word wrap

      If you do not use Red Hat UBI to build application images, refer to the documentation for your base image for information about how to add the Java system properties at build time or runtime.

   2. Specify that the application listens for remote JMX connections by allowing traffic to the application. Use an Red Hat OpenShift Service and specify the following values for its remote JMX port:

      Example service.yaml

      apiVersion: v1
      kind: Service
      ...
      spec:
        ports:
          - name: "jfr-jmx"
            port: 9091
            targetPort: 9091
      ...

      Copy to Clipboard Toggle word wrap

2. Secure the remote JMX connections:

   1. Enable and configure authentication and SSL/TLS for the remote JMX connections in your application:

      -Dcom.sun.management.jmxremote.port=<port_num>
      
       # enable JMX authentication
      -Dcom.sun.management.jmxremote.authenticate=true
      
      # define users for JMX auth
      -Dcom.sun.management.jmxremote.password.file=</path/to/jmxremote.password>
      
      # set permissions for JMX users
      -Dcom.sun.management.jmxremote.access.file=</path/to/jmxremote.access>
      
       # enable JMX SSL
       -Dcom.sun.management.jmxremote.ssl=true
      
      # enable JMX registry SSL
      -Dcom.sun.management.jmxremote.registry.ssl=true
      
      # set your SSL keystore
      -Djavax.net.ssl.keyStore=</path/to/keystore>
      
      # set your SSL keystore password
      -Djavax.net.ssl.keyStorePassword=<password>

      Copy to Clipboard Toggle word wrap

   2. Configure Cryostat to trust the application TLS certificate. Create a secret for the application in the same namespace as your Cryostat application and configure Cryostat to refer to the secret. To create a secret for the certificate, run the following command:

      oc create secret generic myapp-cert --from-file=tls.crt=/path/to/cert.pem

      Copy to Clipboard Toggle word wrap
      Note

      The certificate must be in a .pem file format.

   3. When you create your Cryostat instance, add the secret to the list of trusted TLS certificates. For more information, see Configuring TLS certificates.

   4. To allow your applications to verify that Cryostat is connecting to them by a means other than password authentication, enable TLS client authentication:

      -Dcom.sun.management.jmxremote.ssl.need.client.auth=true
      -Djavax.net.ssl.trustStore=</path/to/truststore>
      -Djavax.net.ssl.trustStorePassword=<password>

      Copy to Clipboard Toggle word wrap
      Note

      TLS client authentication requires the cert-manager operator for Red Hat OpenShift.

   5. If you use TLS client authentication for remote JMX connections, the application truststore must contain a Cryostat certificate. The Cryostat operator cert-manager integration creates a self-signed certificate for the Cryostat deployment. This certificate is located in the <cryostat>-tls secret, where <cryostat> is the name of the Cryostat instance you created.

      Note

      The cert-manager Operator also places a Java keystore truststore in the secret.

      To mount this truststore in your application deployment, run the following command, replacing "<myapp>" with the name of your application deployment and "<cryostat>" with the name of your Cryostat instance:

      oc set volumes deploy <myapp> --add --name=truststore \
        --secret-name=<cryostat>-tls --sub-path=truststore.p12 \
        --mount-path=/var/run/secrets/<myapp>/truststore.p12

      Copy to Clipboard Toggle word wrap

   6. The Cryostat operator generates the truststore password, which you can find in the <cryostat>-keystore secret. To mount this as an environment variable in your application deployment, run the following command:

      oc set env deploy <myapp> --from='secret/<cryostat>-keystore'

      Copy to Clipboard Toggle word wrap

   7. Configure the Java arguments for the container. Run the following commands:

      -Dcom.sun.management.jmxremote.ssl.need.client.auth=true
      -Djavax.net.ssl.trustStore=/var/run/secrets/<myapp>/truststore.p12
      -Djavax.net.ssl.trustStorePassword="$(KEYSTORE_PASS)"

      Copy to Clipboard Toggle word wrap
      Warning

      If you deployed Cryostat and your applications in a testing environment, you might want to configure the target applications without any JMX or TLS authentication. You can do so by using the following set of Java system properties, however, this configuration is not secure and not recommended.

      -Dcom.sun.management.jmxremote.port=<port_num>
      -Dcom.sun.management.jmxremote.ssl=false
      -Dcom.sun.management.jmxremote.authenticate=false

      Copy to Clipboard Toggle word wrap

Procedure

1. To allow the Cryostat Operator to configure and inject the agent automatically, ensure that you add the cryostat.io/name and cryostat.io/namespace labels to your application deployment, as described in Enabling automatic configuration of the agent by the Cryostat Operator.
2. Also ensure that you manually add the CRYOSTAT_AGENT_REGISTRATION_PREFER_JMX and ‑Dcom.sun.management.jmxremote.port settings to your application deployment by using environment variables or the argLine parameter.

3. To enable Cryostat to detect the target application and connect to the Cryostat agent, configure an application Service:

   Example

   apiVersion: v1
   kind: Service
   ...
   spec:
     ports:
       - name: "jfr-jmx"
         port: 9091
         targetPort: 9091
       - name: "cryostat-agent"
         port: 9977
         targetPort: 9977
   ...

   Copy to Clipboard Toggle word wrap

Procedure

1. On the Dashboard panel for your Cryostat web console, select a target JVM from the Target list.

   Note

   Depending on how you configured your target applications, your target JVMs might be using a JMX connection or an agent HTTP connection. For more information about configuring your target applications, see Configuring Java applications.

   Important

   If your target JVM is using an agent HTTP connection that you have configured manually, ensure that you set the cryostat.agent.api.writes-enabled property to true when you configured your target application to load the Cryostat agent. Otherwise, the Cryostat agent cannot accept requests to start and stop JFR recordings. Alternatively, if you want the Cryostat Operator to configure the agent automatically, ensure that you add the cryostat.io/name and cryostat.io/namespace labels to your application deployment. For more information about Cryostat agent configuration, see Working with the Cryostat agent.

   Figure 4.1. Example of selecting a Target JVM for your Cryostat instance

   

   View larger image

   

2. Optional: On the Dashboard panel, you can create a target JVM. From the Target list, click Create Target. The Create Custom Target window opens.

   1. In the Connection URL field, enter the URL for your JVM’s Java Management Extension (JMX) endpoint.
   2. Optional: To test if the Connection URL that you specified is valid, click the Click to test sample node image. If there is an issue with the Connection URL, an error message is displayed that provides a description of the issue and guidance to troubleshoot.
   3. Optional: In the Alias field, enter an alias for your JMX Service URL.

   4. Click Create.

      Figure 4.2. Create Custom Target window

      

      View larger image

      
3. From the navigation menu on the Cryostat web console, click Recordings.

4. Optional: Depending on how you configured your target JVM, an Authentication Required dialog might open on your web console. In the Authentication Required dialog box, enter your Username and Password. To provide your credentials to the target JVM, click Save.

   Figure 4.3. Example of a Cryostat Authentication Required window

   

   View larger image

   
   Note

   If the selected target JMX has Secure Socket Layer (SSL) certification enabled for JMX connections, you must add its certificate when prompted.

   Cryostat encrypts and stores credentials for a target JVM application in a database that is stored on a persistent volume claim (PVC) on Red Hat OpenShift. See Storing and managing credentials (Using Cryostat to manage a JFR recording).

5. On the Active Recordings tab, click Create.

   Figure 4.4. Example of creating an active recording

   

   View larger image

   

6. On the Custom Flight Recording tab:

   1. In the Name field, enter the name of the recording you want to create. If you enter a name in an invalid format, the web console displays an error message.

   2. If you want Cryostat to automatically restart an existing recording, select the Restart if recording already exists check box.

      Note

      If you enter a name that already exists but you do not select Restart if recording already exists, Cryostat refuses to create a custom recording when you click the Create button.

   3. In the Duration field, select whether you want this recording to stop after a specified duration or to run continuously without stopping. If you want Cryostat to automatically archive your new JFR recording after the recording stops, click Archive on Stop.
   4. In the Template field, select the template that you want to use for the recording.

   The following example shows continuous JVM monitoring, which you can enable by selecting Continuous from above the Duration field. This setting means that the recording will continue until you manually stop the recording. The example also shows selection of the Profiling template from the Template field. This provides additional JVM information to a JFR recording for troubleshooting purposes.

   Figure 4.5. Example of creating a custom flight recording

   

   View larger image

   

7. To access more options, click the following expandable hyperlinks:

   • Show advanced options, where you can select additional options for customizing your JFR recording.
   • Show metadata options, where you can add custom labels and metadata to your JFR recording.

8. To create your JFR recording, click Create. The Active Recordings tab opens and lists your JFR recording.

   Your active JFR recording starts collecting data on the target JVM location inside your containerized application. If you specified a fixed duration for your JFR recordings, the target JVM stops the recording when it reaches the fixed duration setting. Otherwise, you must manually stop the recording.

9. Optional: On the Active Recording tab, you can also stop the recording.

   1. Select the checkbox next to the JFR recording’s name. On the toolbar in the Active Recordings tab, the Cryostat web console activates the Stop button.

   2. Click Stop. The JFR adopts the STOPPED status, so it stops monitoring the target JVM. The JFR still shows under the Active Recording tab.

      Figure 4.6. Example of stopping an active recording

      

      View larger image

      
      Important

      JFR recording data might be lost in the following situations:

      • Target JVM fails
      • Target JVM restarts
      • Target JVM Red Hat OpenShift Deployment is scaled down

      Archive your JFR recordings to ensure you do not lose your JFR recording’s data.

Procedure

1. On the Active Recordings tab, click the Create button. A new window opens on the web console.

   Figure 4.7. Example of creating an active recording

   

   View larger image

   

2. Click the Snapshot Recording tab.

   Figure 4.8. Example of creating a snapshot recording

   

   View larger image

   

3. Click Create. The Active Recordings table opens and it lists your JFR snapshot recording. The following example shows a JFR snapshot recording named snapshot-3.

   Figure 4.9. Example of a completed snapshot recording

   

   View larger image

   
   Note

   You can identify snapshots by the snapshot prefix from the list of active recordings.