Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/_subsections/operator-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ 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.

Expand All @@ -61,6 +61,8 @@ The label <code>cryostat.io/read-only</code> can be used to configure the inject

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>

### [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)
Expand Down