Chapter 2. New features

This section describes new features that the Cryostat 3.0 release provides.

Cryostat DB container

From Cryostat 3.0 onward, the Red Hat Ecosystem Catalog also includes a Cryostat DB container image (cryostat-db). When you install Cryostat by using either the Cryostat Operator or a Helm chart, the cryostat-db container is also automatically deployed.

The cryostat-db container provides a lightly customized Postgres database. Cryostat now uses this database for storing information such as the encrypted target JMX credentials keyring, Automated Rules definitions, discovered targets, and discovery plug-ins.

In previous releases, Cryostat stored information such as the JMX credentials keyring in a simple H2 file-based database, and other information such as Automated Rules definitions were stored directly as files on disk. With the introduction of the cryostat-db container, Cryostat can now store different types of information in the same Postgres database.

Cryostat Storage container

From Cryostat 3.0 onward, the Red Hat Ecosystem Catalog also includes a Cryostat Storage container image (cryostat-storage). When you install Cryostat by using either the Cryostat Operator or a Helm chart, the cryostat-storage container is also automatically deployed.

The cryostat-storage container provides a lightly customized SeaweedFS storage solution that acts as an S3-compatible storage provider.

In previous releases, Cryostat used direct storage of files on disk for archived Flight Recordings and custom Event Templates. With the introduction of the cryostat-storage container, Cryostat no longer needs to use direct file-system access for this type of information.

Reverse proxy architecture

When you install Cryostat 3.0 by using either the Cryostat Operator or a Helm chart, Cryostat now includes a reverse proxy (openshift-oauth-proxy or oauth2_proxy) in the pod. Only this proxy is exposed to cluster traffic through a service. This means that all API requests to Cryostat and all users of the Cryostat web console or Grafana dashboard are directed through the proxy.

The proxy handles user sessions to control access to the application, providing unified access control and user sessions for both the Cryostat web console and Grafana dashboard. Both of these user interfaces are accessible through the same route and present the same TLS certificate.

When deployed on Red Hat OpenShift, the proxy uses the Cryostat installation namespace to perform role-based access control (RBAC) checks for user authentication and authorization by integrating with the Red Hat OpenShift cluster SSO provider. You can optionally configure the auth proxy with an htpasswd file to enable Basic authentication. On Red Hat OpenShift, this allows for defining additional user accounts that can access Cryostat beyond those with Red Hat OpenShift SSO RBAC access.

Support for customizing the route host name

By default, Red Hat OpenShift Container Platform automatically assigns a host name, based on the cluster’s default ingress domain name, for any routes that do not specify a host. Depending on your requirements, you might want to use a particular host name for the route that the Cryostat Operator creates for your Cryostat deployment. In Cryostat 3.0, you can use a new .spec.networkOptions.coreConfig.externalHost property in the Cryostat custom resource (CR) to specify a custom host name for the Cryostat route.

In the Red Hat OpenShift console, you can access this property when creating your Cryostat CR:

Alternatively, you can create your Cryostat CR in YAML format. For example:

apiVersion: operator.cryostat.io/v1beta2
kind: Cryostat
metadata:
  name: cryostat-sample
spec:
  networkOptions:
    coreConfig:
      externalHost: cryostat.example.com

Once a route is created in Red Hat OpenShift Container Platform, you cannot change the route’s host name. If you need to change the route’s host name after you have already created your Cryostat CR, you must delete the Cryostat CR and create a new CR with the modified host name.

Dynamic attachment to the JVM

From Cryostat 3.0 onward, the Cryostat agent can attach dynamically to an application JVM that is already running without requiring an application restart. This dynamic attachment feature has the following requirements:

Dynamic attachment supports ad hoc one-time profiling or troubleshooting workflows where you might not need the agent to be attached every time the JVM starts. Dynamic attachment also suits situations where you cannot or do not want to reconfigure your application for the sole purpose of attaching the agent. Because the agent can attach to a running JVM without requiring an application restart, this also means there is no application downtime.

Support for launching the Cryostat agent as a standalone process

From Cryostat 3.0 onward, if you want the Cryostat agent to attach dynamically to an application JVM that is already running, you can launch the agent as a standalone Java process. This feature requires that you have already copied the agent’s JAR file to the JVM’s file system (for example, by using the oc cp command).

To launch the agent, you can run the following command, where <agent_jar_file> represents the agent’s JAR file name and <pid> represents the process ID (PID) of the JVM:

$ java -jar target/<agent_jar_file> <pid>

For example:

$ java -jar target/cryostat-agent-0.4.0.jar 1234

The agent process uses its Attach providers to look up the specified PID. If the specified PID is found, the agent process attaches to this PID and attempts to load the agent’s JAR file into this JVM, which then bootstraps into the normal agent launch process.

You can also specify additional late-binding configuration options to the agent launcher by using command-line options. For example:

$ java -jar target/cryostat-agent-0.4.0.jar \
-Dcryostat.agent.baseuri=http://cryostat.local \
--smartTrigger=[ProcessCpuLoad>0.2]~profile \
@/deployment/app/moreAgentArgs \
1234

For more information about the available options and their behavior, run the java -jar target/cryostat-agent-0.4.0.jar -h help command. System properties that you specify with -D are set onto the host JVM before the injected agent attempts to read the configuration values. This has the same effect as setting these system properties or equivalent environment variables on the host JVM process itself.