feat(release): update for Cryostat 4.2.0 release

_data/versions.yaml

@@ -1,23 +1,24 @@
 cryostat:
-  version: '4.1.0'
-  release-branch: 'cryostat-v4.1'
+  version: '4.2.0'
+  release-branch: 'cryostat-v4.2'
 agent:
-  version: '0.6.0'
+  version: '0.7.0'
 openshift:
-  version: '4.16'
+  version: '4.19'
 kubernetes:
-  version: '1.29'
+  version: '1.32'
 operator-sdk:
-  version: '1.31.0'
+  version: '1.42.0'
 operator-lifecycle-manager:
   version: '0.25.0'
 cert-manager:
-  version: '1.13.6'
+  version: '1.18.6'
 maven-plugins:
   dependency:
     version: '3.9.0'
 documentation:
   - 'latest'
+  - 4.1.0
   - 4.0.0
   - 3.0.0
   - 2.4.0

docs/_subsections/configure-agent-harvester.md

@@ -12,6 +12,7 @@ The **Harvester** supports a number of configuration options that can be used to
 - `cryostat.agent.harvester.exit.max-size-b` [`long`]: the JFR `maxsize` setting, specified in bytes, to apply to exit uploads as described above.
 - `cryostat.agent.harvester.max-age-ms` [`long`]: the JFR `maxage` setting, specified in milliseconds, to apply to periodic uploads during the application lifecycle. Defaults to `0`, which is interpreted as 1.5x the harvester period (`cryostat.agent.harvester.period-ms`).
 - `cryostat.agent.harvester.max-size-b` [`long`]: the JFR `maxsize` setting, specified in bytes, to apply to periodic uploads during the application lifecycle. Defaults to `0`, which means `unlimited`.
+- `cryostat.agent.harvester.autoanalyze` [`boolean`]: whether the pushed recordings should be marked for automatic analysis by the Cryostat server. Defaults to true.
 
 Note that the **Harvester Period** and **Template** options must be set for the **Harvester** to regularly push **JFR** data. If only the **Template** is set the **Harvester** will only attempt to push on shutdown. If neither are set the **Harvester** will not do anything unless configured alongside **Smart Triggers** as described below.
 
@@ -30,6 +31,9 @@ or by setting them as environment variables, for example:
 - name: CRYOSTAT_AGENT_HARVESTER_TEMPLATE  
   value: Profiling
 ```
+
+The **Cryostat Operator** supports several labels for configuring the **Harvester** through **Agent Autoconfiguration**. For more information, see [Agent Autoconfiguration](/docs/#agent-autoconfiguration)
+
 #### [MBean Trigger Integration](#mbean-trigger-integration)
 
 When the **Cryostat Agent** is configured to start dynamic recordings based on custom MBean triggers, you can also integrate them with the **Harvester** to automatically push the collected **JFR** data to the **Cryostat Server**.

docs/_subsections/configuring-the-operator.md

@@ -50,7 +50,7 @@ spec:
 Multiple templates can be specified in the `eventTemplates` array. Each `configMapName` must refer to the name of a **Config Map** in the same namespace as **Cryostat**. The corresponding `filename` must be a key within that **Config Map** containing the template file.
 
 ### Trusted TLS Certificates
-By default, **Cryostat** uses TLS when connecting to the user's applications over JMX. In order to verify the identity of the applications **Cryostat** connects to, it should be configured to trust the TLS certificates presented by those applications. One way to do that is to specify certificates that **Cryostat** should trust in the `spec.trustedCertSecrets` property.
+By default, **Cryostat** uses TLS when connecting to the user's applications over JMX. In order to verify the identity of the applications **Cryostat** connects to, it should be configured to trust the TLS certificates presented by those applications. Certificates can be provided through the `spec.trustedCertSecrets` property, and each entry may reference either a **Secret** or a **ConfigMap** in the same namespace as the `Cryostat` object.
 ```yaml
 apiVersion: operator.cryostat.io/v1beta2
 kind: Cryostat
@@ -60,8 +60,12 @@ spec:
   trustedCertSecrets:
   - secretName: my-tls-secret
     certificateKey: ca.crt
+  - configMapName: my-service-ca
+    certificateKey: service-ca.crt
 ```
-Multiple TLS secrets may be specified in the `trustedCertSecrets` array. The `secretName` property is mandatory, and must refer to the name of a Secret within the same namespace as the `Cryostat` object. The `certificateKey` must point to the X.509 certificate file to be trusted. If `certificateKey` is omitted, the default key name of `tls.crt` will be used.
+Multiple certificate entries may be specified in the `trustedCertSecrets` array. Each entry must specify exactly one of `secretName` or `configMapName`. The `certificateKey` must point to the X.509 certificate or CA bundle file to be trusted. If `certificateKey` is omitted, the default key name is `tls.crt` for **Secrets** and `service-ca.crt` for **ConfigMaps**.
+
+The `configMapName` option is useful on **OpenShift**, where service serving certificate CA bundles are commonly injected into **ConfigMap** resources. In that case, the injected certificate bundle normally uses the `service-ca.crt` key, so you can omit `certificateKey` when using that default key name.
 
 ### Storage Options
 **Cryostat** uses <code>storage volumes</code> to persist data in its database and object storage. In the interest of persisting these files across redeployments, **Cryostat** uses a **Persistent Volume Claim** by default. Unless overidden, the operator will create a **Persistent Volume Claim** with the default **Storage Class** and **500MiB** of storage capacity.
@@ -302,6 +306,23 @@ spec:
     targetCacheTTL: 10
 ```
 
+### Audit Logging
+
+**Cryostat** can persist audit history in its database. This history enables features that refer back to information about target applications and their Kubernetes lineages after those targets are no longer discoverable.
+
+The `spec.enableAudit` property configures audit logging for the **Cryostat** application. For newly created `Cryostat` objects, the **Cryostat Operator** defaults `spec.enableAudit` to `true`. Existing `Cryostat` objects created before this field was introduced keep their previous behavior until you explicitly set the property.
+
+When audit logging is enabled, the **Cryostat** database grows over time and might require additional storage.
+
+```yaml
+apiVersion: operator.cryostat.io/v1beta2
+kind: Cryostat
+metadata:
+  name: cryostat-sample
+spec:
+  enableAudit: false
+```
+
 ### Application Database
 
 **Cryostat** stores various pieces of information in a database. This can also include target application connection credentials, such as target applications' JMX credentials, which are stored in an encrypted database table. By default, the **Cryostat Operator** will generate both a random database connection key and a random table encryption key and configure **Cryostat** and the database to use these. You may also specify these keys yourself by creating a Secret containing the keys `CONNECTION_KEY` and `ENCRYPTION_KEY`.

docs/_subsections/operator-architecture.md

@@ -51,16 +51,43 @@ With this setup, the target applications are not able to assume the privileges a
 
 ### [Agent Autoconfiguration](#agent-autoconfiguration)
 
-Using labels on a <code>Deployment's</code> <code>.spec.template.metadata.labels</code> field, a user can request the **Cryostat Operator** to patch their application <code>Deployment</code> to add and configure the **Cryostat Agent**. The two required labels are <code>cryostat.io/namespace</code> and <code>cryostat.io/name</code>. These should be populated with values corresponding to the installation <code>namespace</code> of a **Cryostat Custom Resource** that the user wishes their application to be registered with. The **Cryostat Operator** will validate that the application <code>Deployment</code> belongs to one of the Target <code>Namespaces</code> of the **Cryostat CR**, and ignore the request if it does not. The patching done by the **Cryostat Operator** involves mounting <code>volumes</code> to the </code>Deployment's</code> <code>Pods</code> containing the **Cryostat Agent** JAR and various TLS certificates required for secure communications; patching the <code>JAVA_TOOL_OPTIONS</code> environment variable to append the <code>-javaagent:/path/to/cryostat-agent.jar</code> flag so that the application statically attaches the **Cryostat Agent** at startup; and adding additional environment variables to the <code>Deployment</code> to configure the **Cryostat Agent** to load the TLS certificates, determine its own callback URL, and to communicate with the **Cryostat Agent** <code>Service</code> in its own <code>Namespace</code>. The **Cryostat Operator** places an Agent <code>Service</code> in each Target <code>namespace</code>, which points at the **Agent Proxy (Gateway)** component of the associated **Cryostat** instance.
+Using labels on a <code>Deployment's</code> <code>metadata.labels</code> or <code>.spec.template.metadata.labels</code> field, a user can request the **Cryostat Operator** to patch their application <code>Deployment</code> to add and configure the **Cryostat Agent**. The two required labels are <code>cryostat.io/namespace</code> and <code>cryostat.io/name</code>. These should be populated with values corresponding to the installation <code>namespace</code> of a **Cryostat Custom Resource** that the user wishes their application to be registered with. The **Cryostat Operator** will validate that the application <code>Deployment</code> belongs to one of the Target <code>Namespaces</code> of the **Cryostat CR**, and ignore the request if it does not. The patching done by the **Cryostat Operator** involves mounting <code>volumes</code> to the </code>Deployment's</code> <code>Pods</code> containing the **Cryostat Agent** JAR and various TLS certificates required for secure communications; patching the <code>JAVA_TOOL_OPTIONS</code> environment variable to append the <code>-javaagent:/path/to/cryostat-agent.jar</code> flag so that the application statically attaches the **Cryostat Agent** at startup; and adding additional environment variables to the <code>Deployment</code> to configure the **Cryostat Agent** to load the TLS certificates, determine its own callback URL, and to communicate with the **Cryostat Agent** <code>Service</code> in its own <code>Namespace</code>. The **Cryostat Operator** places an Agent <code>Service</code> in each Target <code>namespace</code>, which points at the **Agent Proxy (Gateway)** component of the associated **Cryostat** instance.
 
 The environment variable selection can be modified using the <code>cryostat.io/java-options-var</code> label. This defaults to <code>JAVA_TOOL_OPTIONS</code> as described above.
 
+Starting with **Cryostat** 4.2, the Agent Autoconfiguration labels can be applied to the application's <code>Deployment</code> directly, rather than just the <code>Pod Template</code>.
+
 If the <code>Deployment</code> template describes a <code>Pod</code> containing more than one container, the <code>cryostat.io/container</code> can be used to select a container by name. This container will be the one configured to use the **Cryostat Agent**. If this is not specified, the **Operator** will default to picking the first container within the <code>Pod</code>.
 
 The label <code>cryostat.io/read-only</code> can be used to configure the injected **Cryostat Agent** instance to only accept "read" requests on its internal webserver. The **Cryostat Agent** will permit the **Cryostat** instance to perform actions such as querying for the list of active **Flight Recordings**, or the list of registered **JFR** Event Types, or reading MBean metrics. The agent will reject actions such as starting new **Flight Recordings**.
 
 The label <code>cryostat.io/callback-port</code> can be used to control the HTTPS port exposed by the **Cryostat Agent** instance, which is how the **Agent** receives requests from the **Cryostat** instance. This defaults to 9977. If this port number is already used by the application or has some other meaning within the larger deployment, then this label can be used to change the **Cryostat Agent** HTTPS port number.
 
+The label <code>cryostat.io/smart-triggers</code> can be used to attach <code>Smart Triggers</code> to a target application. This label specifies a list of config maps containing <code>Smart Trigger</code> definitions. These config maps will be mounted to the target Pod and a startup flag will be set with the agent to read and enable them. See [using smart triggers](/guides/#using-smart-triggers) for more information on <code>Smart Triggers</code>
+
+There are also several labels for configuring the agent harvester through Agent Autoconfiguration. The label <code>cryostat.io/harvester-template</code> can be used to specify a recording template for use when starting an agent harvester recording. The labels <code>cryostat.io/harvester-period</code> and <code>cryostat.io/harvester-max-files</code> can be used to specify the length of time between JFR collections and pushes by the harvester, and the maximum number of pushed files that Cryostat will keep from the agent respectively. See [configuring the agent harvester](/docs/#configure-the-agent-harvester) for more information on configuring the agent harvester.
+
+### [Agent Autoconfiguration with the Console Plugin](#agent-autoconfiguration-with-the-console-plugin)
+
+The **Cryostat Console Plugin** contains a graphical wizard for registering targets with **Cryostat** through the **Agent Autoconfiguration** feature.
+
+<ol>
+  <li>
+    {% include howto_step.html
+      summary="Select a target in the topology view to register."
+      image-name="4.2.0/agent-autoconfiguration-wizard-1.png"
+      caption="Select the 'Register with Cryostat' option. This will open the graphical wizard for Agent Autoconfiguration."
+    %}
+  </li>
+  <li>
+    {% include howto_step.html
+      summary="Fill out the required fields in the wizard"
+      image-name="4.2.0/agent-autoconfiguration-wizard-2.png"
+      caption="After filling out the wizard with the available Agent Autoconfiguration options, review the configuration and select Register. Agent Autoconfiguration will then be performed with the selected options and the target will be registered with Cryostat"
+    %}
+  </li>
+</ol>
+
 ### [Flow of JFR Data](#flow-of-jfr-data)
 
 **Cryostat** traditonally connects to other **JVM** applications within its cluster using remote JMX, using cluster-internal URLs so that no traffic will leave the cluster. **Cryostat** supports connecting to target **JVMs** with JMX auth credentials enabled ("Basic" style authentication). When a connection attempt to a target fails due to a <code>SecurityException</code>, Cryostat responds to the requesting client with an HTTP 427 status code and the header <code>X-JMX-Authenticate: Basic</code>. The client is expected to create a [Stored Credential](/guides/#store-credentials) object via the **Cryostat API** before retrying the request, which results in the required target credentials being stored in an encrypted database table. When deployed in **OpenShift** the requests are already encrypted using **OpenShift** TLS re-encryption as mentioned above, so the credentials are never transmitted in cleartext. The table is encrypted with a passphrase either provided by the user at deployment time, or generated by the **Operator** if none is specified. It is also possible to configure **Cryostat** to trust SSL certificates used by target JVMs by adding the certificate to a <code>Secret</code> and linking that to the **Cryostat CR**, which will add the certificate to the SSL trust store used by **Cryostat**. The Operator also uses **cert-manager** to generate a self-signed CA and provides **Cryostat's** auth proxy with certificates as a mounted volume. For more information on setting this up, see [Configuring the Operator](/docs/#configure-the-cryostat-operator)

docs/_subsections/using-the-cryostat-agent.md

@@ -8,6 +8,8 @@ The **Agent** may also be configured, using the property `cryostat.agent.api.wri
 
 The programming interfaces for **Cryostat** and its **Agent** are designed to implement **Cryostat's** specific feature set, rather than being generalized and flexible like **JMX**. The benefit of this is that the security considerations are easier to understand and model, but choosing to use the **Cryostat Agent** over **JMX** may also forego the ability to interoperate with other **JMX** tooling such as `JDK Mission Control`, `visualvm`, `jconsole`, `hawtio`, etc.
 
+Note that <code>cryostat.agent.baseuri</code> and <code>cryostat.agent.callback</code> are required properties. These ensure that the agent can communicate with Cryostat and Cryostat can communicate back to the agent.
+
 <ol>
     <li>The <b>Cryostat Agent</b> retrieves a wide range of information from those <b>Cryostat</b> applications such as <code>memory usage</code>, <code>CPU utilization</code>, etc. </li>
     <li>The <b>Cryostat</b> analyzes these collected data to identify problems that might be affecting the application’s performance.</li>

docs/index.md

@@ -16,6 +16,8 @@ title: Cryostat Documentation
 
 {% include_relative _subsections/external-storage.md %}
 
+{% include_relative _subsections/configuring-the-helm-chart.md %}
+
 # Additional Information
 
 {% include_relative _subsections/operator-architecture.md %}

get-started/index.md

@@ -78,6 +78,37 @@ Click "*Install*" and wait for the installation to complete.
 
 Continue to [Setup](#setup).
 
+### [Install via Helm Chart](#install-via-helm-chart)
+
+**Cryostat** can also be installed through the helm chart. Note that installing **Cryostat** through the helm chart comes with several limitations to be aware of. The helm chart will install **Cryostat** directly without the **Cryostat Operator** to manage it. The helm chart also does not integrate with cert-manager. When installed through the helm chart, the Agent Auto Configuration feature will not work since it requires the **Cryostat Operator**. Finally, the **Openshift Console Plugin** will not be installed by the helm chart. For more information on configuring the helm chart including configuring TLS, see [Configuring the Helm Chart](/docs/#configure-the-cryostat-helm-chart)
+
+#### From Helm repository
+
+The chart is available at the following repositories:
+
+- https://cryostat.io/helm-charts
+- https://charts.openshift.io
+
+To install the chart, add the repository and install, for example:
+
+```bash
+helm repo add cryostat-charts https://cryostat.io/helm-charts
+helm repo update
+helm install cryostat cryostat-charts/cryostat
+```
+
+#### From OCI container registry
+
+The chart is also available as an OCI image on GitHub Container Registry (`ghcr.io`).
+
+To install the chart, run:
+
+```bash
+helm install cryostat oci://ghcr.io/cryostatio/cryostat-helm --version $VERSION
+```
+
+Continue to [Setup](#setup).
+
 ## [Setup](#setup)
 
 ### [Deploying Cryostat](#deploying-cryostat)