From 981198eca8969cb860234686c72434c792a33b31 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 12:52:10 -0400 Subject: [PATCH 01/31] docs(get-started): add information about the Agent and JMX config --- get-started/index.md | 287 ++++++++++++++++++ .../_subsections/using-the-cryostat-agent.md | 4 +- 2 files changed, 289 insertions(+), 2 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 094ac813..321234ec 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -8,6 +8,9 @@ layout: get-started {:.cryostat-heading-1} Cryostat {{ site.data.versions.cryostat.version }} +* auto-gen TOC: +{:toc} + ## [Installing Cryostat Operator](#installing-cryostat-operator) Follow the steps below to install the Cryostat Operator via [OperatorHub](https://operatorhub.io/operator/cryostat-operator). @@ -62,6 +65,290 @@ the specifics of how to deploy your Cryostat instance. Continue to [Setup](#setu Note: Alternative methods for installing the operator are described in [Alternate Installation Options](/alternate-installation-options) (not recommended). ## [Setup](#setup) +### [Configuring Applications](#configuring-applications) +The following sections will briefly describe how to configure your Java applications so that Cryostat is able to discover and monitor them. +These examples will assume the application is built with Maven, packaged into an image with a `Dockerfile`, and running in OpenShift, +but the instructions will be similar for other toolchains and platforms as well. + +#### [Using the Cryostat Agent](#using-the-cryostat-agent) + +[The Cryostat Agent](/guides/#using-the-cryostat-agent) +is compatible with Cryostat versions 2.3.0 and newer, and application JDKs 11 and newer. If you are using an older version of Cryostat, please upgrade. +If your application uses a recent version of JDK8 with JFR support, please either upgrade to JDK11+ or continue to the next section to learn how to configure your +application without the Cryostat Agent. + +The Cryostat Agent JAR must be available to your application JVM. The JAR asset can be downloaded [directly from upstream](https://github.com/cryostatio/cryostat-agent/releases), +or you may use the following snippet in your `pom.xml` to streamline this. + +```xml + + ... + + + github + https://maven.pkg.github.com/cryostatio/cryostat-agent + + + ... + + + + maven-dependency-plugin + 3.3.0 + + + prepare-package + + copy + + + + + io.cryostat + cryostat-agent + 0.2.0 + + + true + + + + + + ... + + ... + +``` + +The next time we build our application, the Cryostat Agent JAR will be located at `target/dependency/cryostat-agent.jar`. Then we can update our Dockerfile: + +```Dockerfile +... +COPY target/dependency/cryostat-agent.jar /deployments/app/ +... +# We are using a framework where the JAVA_OPTS environment variable can be used to pass JVM flags +ENV JAVA_OPTS="-javaagent:/deployments/app/cryostat-agent.jar" +``` + +Next we must rebuild our container image. This is specific to your application but will likely look something like `docker build -t docker.io/myorg/myapp:latest -f src/main/docker/Dockerfile .`. +Push that updated image or otherwise get it updated in your OpenShift registry, then modify your application `Deployment` to supply JVM system properties or environment variables configuring +the Cryostat Agent: + +```yaml +apiVersion: apps/v1 +kind: Deployment +... +spec: + ... + template: + ... + spec: + containers: + - name: sample-app + image: docker.io/myorg/myapp:latest + env: + - name: CRYOSTAT_AGENT_APP_NAME + value: "myapp" + - name: CRYOSTAT_AGENT_BASEURI + value: "http://cryostat.mynamespace.mycluster.svc:8181" + - name: POD_IP + valueFrom: + fieldRef: + fieldPath: status.PodIP + - name: CRYOSTAT_AGENT_CALLBACK + value: "http://$(POD_IP):9977" + - name: CRYOSTAT_AGENT_AUTHORIZATION + value: "Bearer abcd1234" + ports: + - containerPort: 9977 + protocol: TCP + resources: {} + restartPolicy: Always +status: {} +``` + +Port number `9977` is the default HTTP port that the Agent exposes for its internal webserver that services Cryostat requests. The `CRYOSTAT_AGENT_AUTHORIZATION` value is particularly +noteworthy: these are the credentials that the Agent will include in API requests it makes to Cryostat to advertise its own presence. You should create an OpenShift Service Account for +this purpose and replace `abcd1234` with the base64-encoded authentication token associated with the service account. For testing purposes you may use your own user account's +authentication token, for example with `oc whoami --show-token`. + +Finally, create a Service to enable Cryostat to make requests to this Agent: + +```yaml +apiVersion: v1 +kind: Service +... +spec: + ports: + - name: "cryostat-agent" + port: 9977 + targetPort: 9977 +... +``` + +More details about the configuration options for the Cryostat Agent [are available here](https://github.com/cryostatio/cryostat-agent/blob/main/README.md#configuration). + +#### [Using JMX](#using-jmx) +Cryostat is also able to use Java Management Extensions (JMX) to communicate with target applications. This is a standard JDK feature that can be enabled by passing JVM +flags to your application at startup. A basic and insecure setup suitable for testing requires only the following three flags: + +``` +-Dcom.sun.management.jmxremote.port=9091 +-Dcom.sun.management.jmxremote.ssl=false +-Dcom.sun.management.jmxremote.authenticate=false +``` + +[comment]: # TODO explain how to configure SSL and auth for JMX, or link to external docs + +In a real scenario you should enable both SSL and authentication on your application. You can then [trust the certificate](/guides/#add-a-trusted-certificate) +and [store the credentials](/guides/#store-jmx-credentials). + +Depending on your application or its framework, you may set these flags directly in a `Dockerfile` entrypoint, an environment variable, or similar. This may or +may not require a container image rebuild, and it will require the container to be restarted. Once this is done the application container will be listening for +incoming JMX connections on port 9091. Let's assume it can be done by setting an environment variable, so we only need to mofify our Deployment: + +```yaml +apiVersion: apps/v1 +kind: Deployment +... +spec: + ... + template: + ... + spec: + containers: + - name: sample-app + image: docker.io/myorg/myapp:latest + env: + - name: JAVA_OPTS + value: "-Dcom.sun.management.jmxremote.port=9091 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false" + ... +``` + +Next, we need to configure an OpenShift Service to expose this port for cluster-internal traffic, so that Cryostat can see +and connect to this application JMX port. + +```yaml +apiVersion: v1 +kind: Service +... +spec: + ports: + - name: "jfr-jmx" + port: 9091 + targetPort: 9091 +... +``` + +Cryostat queries the OpenShift API server and looks for Services with a port either named `jfr-jmx` or with the number `9091`. One or both of these conditions +must be met or else Cryostat will not automatically detect your application. In this case you may wish to use the [Cryostat Agent](#using-the-cryostat-agent-with-jmx) +to enable discovery, while keeping communications over JMX rather than HTTP. + +#### [Using the Cryostat Agent with JMX](#using-the-cryostat-agent-with-jmx) +The two prior sections have discussed how to use the Cryostat Agent to do application discovery and expose data over HTTP, and how to use OpenShift configurations +for discovery and JMX to expose data. There is a third, hybrid approach: using the Cryostat Agent to do application discovery, and JMX to expose data. This may be +useful since the Agent HTTP data model is readonly, whereas JMX is read-write. This means that using JMX to communicate between Cryostat and your applications +allows for more dynamic flexibility, for example the ability to start and stop Flight Recordings on demand. Using the Cryostat Agent for application discovery +is also more flexible than depending on OpenShift Services with specially-named or specially-numbered ports. For more context about these concepts, please review +the previous two sections on [using the Cryostat Agent](#using-the-cryostat-agent) and [using JMX](#using-jmx). + +`pom.xml` +```xml + + ... + + + github + https://maven.pkg.github.com/cryostatio/cryostat-agent + + + ... + + + + maven-dependency-plugin + 3.3.0 + + + prepare-package + + copy + + + + + io.cryostat + cryostat-agent + 0.2.0 + + + true + + + + + + ... + + ... + +``` + +`application Deployment` +```yaml +apiVersion: apps/v1 +kind: Deployment +... +spec: + ... + template: + ... + spec: + containers: + - name: sample-app + image: docker.io/myorg/myapp:latest + env: + - name: CRYOSTAT_AGENT_APP_NAME + value: "myapp" + - name: CRYOSTAT_AGENT_BASEURI + value: "http://cryostat.mynamespace.mycluster.svc:8181" + - name: POD_IP + valueFrom: + fieldRef: + fieldPath: status.PodIP + - name: CRYOSTAT_AGENT_CALLBACK + value: "http://$(POD_IP):9977" + - name: CRYOSTAT_AGENT_AUTHORIZATION + value: "Bearer abcd1234" + - name: CRYOSTAT_AGENT_REGISTRATION_PREFER_JMX + value: "true" + - name: JAVA_OPTS + value: "-javaagent:/deployments/app/cryostat-agent.jar -Dcom.sun.management.jmxremote.port=9091 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false" + ports: + - containerPort: 9977 + protocol: TCP + resources: {} + restartPolicy: Always +status: {} +``` + +`application Service` +```yaml +apiVersion: v1 +kind: Service +... +spec: + ports: + - name: "jfr-jmx" + port: 9091 + targetPort: 9091 + - name: "cryostat-agent" + port: 9977 + targetPort: 9977 +... +``` + ### [Deploying Cryostat](#deploying-cryostat) Create a `Cryostat` object to deploy and set up Cryostat in the `cryostat-operator-system` namespace. For full details on how to configure the Cryostat deployment, see diff --git a/guides/_subsections/using-the-cryostat-agent.md b/guides/_subsections/using-the-cryostat-agent.md index 892be31f..e3db58bc 100644 --- a/guides/_subsections/using-the-cryostat-agent.md +++ b/guides/_subsections/using-the-cryostat-agent.md @@ -2,7 +2,7 @@ The Cryostat Agent is a new component of Cryostat, implemented as a Java Insutrumentation Agent, which acts as a plugin for applications running on the JVM. Prior to the Agent, Cryostat extracted data from the JVM by initiating a connection over JMX. It then fetches the data from JFR and pulls it over the network back toward the Cryostat to be accessible to end users. -The Agent works differently. It is responsible for fetching data from the JVM and sending it back to Cryostat. The Agent works by looking for data within itself and the application it is plugged into. The Cryostat Agent locates Cryostat applications running on the network and it is able to initiate a connection with those applications. It is also able to communicate back to Cryostat about the Cryostat Agent and how to reach it. The Cryostat Agent also pushes its own Java Flight Recorder (JFR) data back to Cryostat by first initiating a network connection with Cryostat, which then analyzes and saves the data to makes it accessible to end users. +The Agent works differently. It is responsible for fetching data from the JVM and sending it back to Cryostat over HTTP. The Agent works by looking for data within itself and the application it is plugged into. The Cryostat Agent locates Cryostat applications running on the network and it is able to initiate a connection with those applications. It is also able to communicate back to Cryostat about the Cryostat Agent and how to reach it. The Cryostat Agent also pushes its own Java Flight Recorder (JFR) data back to Cryostat by first initiating a network connection with Cryostat, which then analyzes and saves the data to makes it accessible to end users. 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. @@ -16,4 +16,4 @@ The programming interfaces for Cryostat and its Agent are designed to implement
  • Once the Agent has been installed or attached to the running JVM instance, it can begin collecting data and sending it to Cryostat for analysis.
    • -[comment]: # TODO continue explaining how to include the Agent in application builds, how to configure it +For instructions on how to install the Cryostat Agent into your applications, [check the Getting Started section](/get-started/#using-the-cryostat-agent). From d5f5c4584b70d68f58e3c7496c362fab46461ff3 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 16:17:23 -0400 Subject: [PATCH 02/31] typo --- guides/_subsections/using-the-cryostat-agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/_subsections/using-the-cryostat-agent.md b/guides/_subsections/using-the-cryostat-agent.md index e3db58bc..f9c8a9f9 100644 --- a/guides/_subsections/using-the-cryostat-agent.md +++ b/guides/_subsections/using-the-cryostat-agent.md @@ -1,6 +1,6 @@ ## [Using the Cryostat Agent](#using-the-cryostat-agent) -The Cryostat Agent is a new component of Cryostat, implemented as a Java Insutrumentation Agent, which acts as a plugin for applications running on the JVM. Prior to the Agent, Cryostat extracted data from the JVM by initiating a connection over JMX. It then fetches the data from JFR and pulls it over the network back toward the Cryostat to be accessible to end users. +The Cryostat Agent is a new component of Cryostat, implemented as a Java Instrumentation Agent, which acts as a plugin for applications running on the JVM. Prior to the Agent, Cryostat extracted data from the JVM by initiating a connection over JMX. It then fetches the data from JFR and pulls it over the network back toward the Cryostat to be accessible to end users. The Agent works differently. It is responsible for fetching data from the JVM and sending it back to Cryostat over HTTP. The Agent works by looking for data within itself and the application it is plugged into. The Cryostat Agent locates Cryostat applications running on the network and it is able to initiate a connection with those applications. It is also able to communicate back to Cryostat about the Cryostat Agent and how to reach it. The Cryostat Agent also pushes its own Java Flight Recorder (JFR) data back to Cryostat by first initiating a network connection with Cryostat, which then analyzes and saves the data to makes it accessible to end users. From e768b802950e4b309fec72c8ffb758f619325301 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 16:22:50 -0400 Subject: [PATCH 03/31] rephrase --- guides/_subsections/using-the-cryostat-agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/_subsections/using-the-cryostat-agent.md b/guides/_subsections/using-the-cryostat-agent.md index f9c8a9f9..ea29f931 100644 --- a/guides/_subsections/using-the-cryostat-agent.md +++ b/guides/_subsections/using-the-cryostat-agent.md @@ -16,4 +16,4 @@ The programming interfaces for Cryostat and its Agent are designed to implement
  • Once the Agent has been installed or attached to the running JVM instance, it can begin collecting data and sending it to Cryostat for analysis.
    • -For instructions on how to install the Cryostat Agent into your applications, [check the Getting Started section](/get-started/#using-the-cryostat-agent). +For instructions on how to install the Cryostat Agent into your applications, [check the Setup section in Getting Started](/get-started/#using-the-cryostat-agent). From d1af0d0b1f01f6d7adb03081b4a858cfe60f3d7b Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 16:47:59 -0400 Subject: [PATCH 04/31] quotes and typo --- get-started/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 321234ec..77274f5f 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -169,11 +169,11 @@ status: {} ``` Port number `9977` is the default HTTP port that the Agent exposes for its internal webserver that services Cryostat requests. The `CRYOSTAT_AGENT_AUTHORIZATION` value is particularly -noteworthy: these are the credentials that the Agent will include in API requests it makes to Cryostat to advertise its own presence. You should create an OpenShift Service Account for +noteworthy: these are the credentials that the Agent will include in API requests it makes to Cryostat to advertise its own presence. You should create an OpenShift `Service Account` for this purpose and replace `abcd1234` with the base64-encoded authentication token associated with the service account. For testing purposes you may use your own user account's authentication token, for example with `oc whoami --show-token`. -Finally, create a Service to enable Cryostat to make requests to this Agent: +Finally, create a `Service` to enable Cryostat to make requests to this Agent: ```yaml apiVersion: v1 @@ -206,7 +206,7 @@ and [store the credentials](/guides/#store-jmx-credentials). Depending on your application or its framework, you may set these flags directly in a `Dockerfile` entrypoint, an environment variable, or similar. This may or may not require a container image rebuild, and it will require the container to be restarted. Once this is done the application container will be listening for -incoming JMX connections on port 9091. Let's assume it can be done by setting an environment variable, so we only need to mofify our Deployment: +incoming JMX connections on port 9091. Let's assume it can be done by setting an environment variable, so we only need to modify our `Deployment:` ```yaml apiVersion: apps/v1 @@ -226,7 +226,7 @@ spec: ... ``` -Next, we need to configure an OpenShift Service to expose this port for cluster-internal traffic, so that Cryostat can see +Next, we need to configure an OpenShift `Service` to expose this port for cluster-internal traffic, so that Cryostat can see and connect to this application JMX port. ```yaml @@ -241,7 +241,7 @@ spec: ... ``` -Cryostat queries the OpenShift API server and looks for Services with a port either named `jfr-jmx` or with the number `9091`. One or both of these conditions +Cryostat queries the OpenShift API server and looks for `Service`s with a port either named `jfr-jmx` or with the number `9091`. One or both of these conditions must be met or else Cryostat will not automatically detect your application. In this case you may wish to use the [Cryostat Agent](#using-the-cryostat-agent-with-jmx) to enable discovery, while keeping communications over JMX rather than HTTP. @@ -250,7 +250,7 @@ The two prior sections have discussed how to use the Cryostat Agent to do applic for discovery and JMX to expose data. There is a third, hybrid approach: using the Cryostat Agent to do application discovery, and JMX to expose data. This may be useful since the Agent HTTP data model is readonly, whereas JMX is read-write. This means that using JMX to communicate between Cryostat and your applications allows for more dynamic flexibility, for example the ability to start and stop Flight Recordings on demand. Using the Cryostat Agent for application discovery -is also more flexible than depending on OpenShift Services with specially-named or specially-numbered ports. For more context about these concepts, please review +is also more flexible than depending on OpenShift `Service`s with specially-named or specially-numbered ports. For more context about these concepts, please review the previous two sections on [using the Cryostat Agent](#using-the-cryostat-agent) and [using JMX](#using-jmx). `pom.xml` From 9056d90b5d025dc83f2fa7bf2a343f5541c09c5a Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 16:50:11 -0400 Subject: [PATCH 05/31] add anchors --- get-started/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 77274f5f..52b4cf50 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -74,8 +74,8 @@ but the instructions will be similar for other toolchains and platforms as well. [The Cryostat Agent](/guides/#using-the-cryostat-agent) is compatible with Cryostat versions 2.3.0 and newer, and application JDKs 11 and newer. If you are using an older version of Cryostat, please upgrade. -If your application uses a recent version of JDK8 with JFR support, please either upgrade to JDK11+ or continue to the next section to learn how to configure your -application without the Cryostat Agent. +If your application uses a recent version of JDK8 with JFR support, please either upgrade to JDK11+ or [continue to the next section](#using-jmx) +to learn how to configure your application without the Cryostat Agent. The Cryostat Agent JAR must be available to your application JVM. The JAR asset can be downloaded [directly from upstream](https://github.com/cryostatio/cryostat-agent/releases), or you may use the following snippet in your `pom.xml` to streamline this. @@ -407,7 +407,7 @@ $ kubectl apply -f cryostat.yaml For demo purposes, let's go ahead and deploy a sample application to our OpenShift cluster in the same namespace as our Cryostat instance. If you have deployed Cryostat into a namespace where you are already running other -applications, feel free to continue to the next step. +applications, feel free to [continue to the next step](#open-the-cryostat-web-ui). ```bash $ oc new-app --docker-image=quay.io/andrewazores/quarkus-test:0.0.10 @@ -419,7 +419,7 @@ listen on port 9097. After deploying the container we patch its service to name the 9097 service port `jfr-jmx`. Cryostat will detect and use this port to determine that this is a compatible Java application that it should monitor. -### Open the Cryostat Web UI +### [Open the Cryostat Web UI](#open-the-cryostat-web-ui) Let's visit the Cryostat web dashboard UI. We can get there from the Cryostat resource's Status field: From b7051b599ad6990620ad71f628dd91840e2d76ea Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 16:57:29 -0400 Subject: [PATCH 06/31] openshift -> kubernetes --- get-started/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 52b4cf50..db2fff48 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -67,7 +67,7 @@ Note: Alternative methods for installing the operator are described in [Alternat ### [Configuring Applications](#configuring-applications) The following sections will briefly describe how to configure your Java applications so that Cryostat is able to discover and monitor them. -These examples will assume the application is built with Maven, packaged into an image with a `Dockerfile`, and running in OpenShift, +These examples will assume the application is built with Maven, packaged into an image with a `Dockerfile`, and running in Kubernetes, but the instructions will be similar for other toolchains and platforms as well. #### [Using the Cryostat Agent](#using-the-cryostat-agent) @@ -132,7 +132,7 @@ ENV JAVA_OPTS="-javaagent:/deployments/app/cryostat-agent.jar" ``` Next we must rebuild our container image. This is specific to your application but will likely look something like `docker build -t docker.io/myorg/myapp:latest -f src/main/docker/Dockerfile .`. -Push that updated image or otherwise get it updated in your OpenShift registry, then modify your application `Deployment` to supply JVM system properties or environment variables configuring +Push that updated image or otherwise get it updated in your Kubernetes registry, then modify your application `Deployment` to supply JVM system properties or environment variables configuring the Cryostat Agent: ```yaml @@ -169,7 +169,7 @@ status: {} ``` Port number `9977` is the default HTTP port that the Agent exposes for its internal webserver that services Cryostat requests. The `CRYOSTAT_AGENT_AUTHORIZATION` value is particularly -noteworthy: these are the credentials that the Agent will include in API requests it makes to Cryostat to advertise its own presence. You should create an OpenShift `Service Account` for +noteworthy: these are the credentials that the Agent will include in API requests it makes to Cryostat to advertise its own presence. You should create a Kubernetes `Service Account` for this purpose and replace `abcd1234` with the base64-encoded authentication token associated with the service account. For testing purposes you may use your own user account's authentication token, for example with `oc whoami --show-token`. @@ -226,7 +226,7 @@ spec: ... ``` -Next, we need to configure an OpenShift `Service` to expose this port for cluster-internal traffic, so that Cryostat can see +Next, we need to configure a Kubernetes `Service` to expose this port for cluster-internal traffic, so that Cryostat can see and connect to this application JMX port. ```yaml @@ -241,16 +241,16 @@ spec: ... ``` -Cryostat queries the OpenShift API server and looks for `Service`s with a port either named `jfr-jmx` or with the number `9091`. One or both of these conditions +Cryostat queries the Kubernetes API server and looks for `Service`s with a port either named `jfr-jmx` or with the number `9091`. One or both of these conditions must be met or else Cryostat will not automatically detect your application. In this case you may wish to use the [Cryostat Agent](#using-the-cryostat-agent-with-jmx) to enable discovery, while keeping communications over JMX rather than HTTP. #### [Using the Cryostat Agent with JMX](#using-the-cryostat-agent-with-jmx) -The two prior sections have discussed how to use the Cryostat Agent to do application discovery and expose data over HTTP, and how to use OpenShift configurations +The two prior sections have discussed how to use the Cryostat Agent to do application discovery and expose data over HTTP, and how to use Kubernetes configurations for discovery and JMX to expose data. There is a third, hybrid approach: using the Cryostat Agent to do application discovery, and JMX to expose data. This may be useful since the Agent HTTP data model is readonly, whereas JMX is read-write. This means that using JMX to communicate between Cryostat and your applications allows for more dynamic flexibility, for example the ability to start and stop Flight Recordings on demand. Using the Cryostat Agent for application discovery -is also more flexible than depending on OpenShift `Service`s with specially-named or specially-numbered ports. For more context about these concepts, please review +is also more flexible than depending on Kubernetes `Service`s with specially-named or specially-numbered ports. For more context about these concepts, please review the previous two sections on [using the Cryostat Agent](#using-the-cryostat-agent) and [using JMX](#using-jmx). `pom.xml` From 4ce35651682e81511d672e8a031dd38866584ec4 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:03:39 -0400 Subject: [PATCH 07/31] add note about maven registry auth --- get-started/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/get-started/index.md b/get-started/index.md index db2fff48..303ad86a 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -121,6 +121,8 @@ or you may use the following snippet in your `pom.xml` to streamline this. ``` +**Note**: You may be required to [authenticate to the GitHub Maven Packages registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#installing-a-package) in order to pull this JAR. + The next time we build our application, the Cryostat Agent JAR will be located at `target/dependency/cryostat-agent.jar`. Then we can update our Dockerfile: ```Dockerfile From 311f1e362b91bf7bea8a1fcb5a6968f4f5f1fd0c Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:08:44 -0400 Subject: [PATCH 08/31] add comments --- get-started/index.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 303ad86a..9cd2d15c 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -160,6 +160,7 @@ spec: fieldPath: status.PodIP - name: CRYOSTAT_AGENT_CALLBACK value: "http://$(POD_IP):9977" + # Replace "abcd1234" with a base64-encoded authentication token - name: CRYOSTAT_AGENT_AUTHORIZATION value: "Bearer abcd1234" ports: @@ -255,7 +256,7 @@ allows for more dynamic flexibility, for example the ability to start and stop F is also more flexible than depending on Kubernetes `Service`s with specially-named or specially-numbered ports. For more context about these concepts, please review the previous two sections on [using the Cryostat Agent](#using-the-cryostat-agent) and [using JMX](#using-jmx). -`pom.xml` +Add dependency configuration to `pom.xml`: ```xml ... @@ -297,7 +298,7 @@ the previous two sections on [using the Cryostat Agent](#using-the-cryostat-agen ``` -`application Deployment` +Modify the `application Deployment`: ```yaml apiVersion: apps/v1 kind: Deployment @@ -322,9 +323,12 @@ spec: - name: CRYOSTAT_AGENT_CALLBACK value: "http://$(POD_IP):9977" - name: CRYOSTAT_AGENT_AUTHORIZATION + # Replace "abcd1234" with a base64-encoded authentication token value: "Bearer abcd1234" + # This environment variable is key to the "hybrid" setup. This instructs the Agent to register itself with Cryostat as reachable via JMX, rather than reachable via HTTP. - name: CRYOSTAT_AGENT_REGISTRATION_PREFER_JMX value: "true" + # Here we configure the application to load the Agent JAR as well as to enable JMX, since we want the Agent to register itself as reachable via JMX. - name: JAVA_OPTS value: "-javaagent:/deployments/app/cryostat-agent.jar -Dcom.sun.management.jmxremote.port=9091 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false" ports: @@ -335,7 +339,7 @@ spec: status: {} ``` -`application Service` +Create an `application Service`: ```yaml apiVersion: v1 kind: Service From 688d5ecd14f16951124d879e1f7e42b7e25feded Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:10:40 -0400 Subject: [PATCH 09/31] accept suggestion --- get-started/index.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 9cd2d15c..4dd2ab8b 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -249,11 +249,16 @@ must be met or else Cryostat will not automatically detect your application. In to enable discovery, while keeping communications over JMX rather than HTTP. #### [Using the Cryostat Agent with JMX](#using-the-cryostat-agent-with-jmx) -The two prior sections have discussed how to use the Cryostat Agent to do application discovery and expose data over HTTP, and how to use Kubernetes configurations -for discovery and JMX to expose data. There is a third, hybrid approach: using the Cryostat Agent to do application discovery, and JMX to expose data. This may be +The two prior sections have discussed: + - How to use the Cryostat Agent to do application discovery and expose data over HTTP. + - How to use Kubernetes `Service` configurations for discovery and JMX to expose data. + +There is a third, hybrid approach: **using the Cryostat Agent to do application discovery, and JMX to expose data**. This may be useful since the Agent HTTP data model is readonly, whereas JMX is read-write. This means that using JMX to communicate between Cryostat and your applications -allows for more dynamic flexibility, for example the ability to start and stop Flight Recordings on demand. Using the Cryostat Agent for application discovery -is also more flexible than depending on Kubernetes `Service`s with specially-named or specially-numbered ports. For more context about these concepts, please review +allows for more dynamic flexibility, for example, the ability to start and stop Flight Recordings on demand. Using the Cryostat Agent for application discovery +is also more flexible than depending on `Services` with specially-named or specially-numbered ports. + +For more context about these concepts, please review the previous two sections on [using the Cryostat Agent](#using-the-cryostat-agent) and [using JMX](#using-jmx). Add dependency configuration to `pom.xml`: From 6ea2f0d1bb5a478edeb836bf9f596c817aae2d40 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:30:22 -0400 Subject: [PATCH 10/31] typo --- get-started/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 4dd2ab8b..09c40d52 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -62,7 +62,7 @@ Click "Install" and wait for the installation to complete. Once the installation is complete, click "Create Cryostat" to create a Cryostat Custom Resource instance. This provides configuration information for the Operator to know the specifics of how to deploy your Cryostat instance. Continue to [Setup](#setup). -Note: Alternative methods for installing the operator are described in [Alternate Installation Options](/alternate-installation-options) (not recommended). +**Note**: Alternative methods for installing the operator are described in [Alternate Installation Options](/alternate-installation-options) (not recommended). ## [Setup](#setup) ### [Configuring Applications](#configuring-applications) @@ -209,7 +209,7 @@ and [store the credentials](/guides/#store-jmx-credentials). Depending on your application or its framework, you may set these flags directly in a `Dockerfile` entrypoint, an environment variable, or similar. This may or may not require a container image rebuild, and it will require the container to be restarted. Once this is done the application container will be listening for -incoming JMX connections on port 9091. Let's assume it can be done by setting an environment variable, so we only need to modify our `Deployment:` +incoming JMX connections on port 9091. Let's assume it can be done by setting an environment variable, so we only need to modify our `Deployment`: ```yaml apiVersion: apps/v1 From e8c3f3d5c9c497ae6a2feb3d37a60e8b1cb9f645 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:30:43 -0400 Subject: [PATCH 11/31] formatting --- get-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/index.md b/get-started/index.md index 09c40d52..6f5774bf 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -209,7 +209,7 @@ and [store the credentials](/guides/#store-jmx-credentials). Depending on your application or its framework, you may set these flags directly in a `Dockerfile` entrypoint, an environment variable, or similar. This may or may not require a container image rebuild, and it will require the container to be restarted. Once this is done the application container will be listening for -incoming JMX connections on port 9091. Let's assume it can be done by setting an environment variable, so we only need to modify our `Deployment`: +incoming JMX connections on port `9091`. Let's assume it can be done by setting an environment variable, so we only need to modify our `Deployment`: ```yaml apiVersion: apps/v1 From 91bc8cd7f74b6f270f01d89dccb21a4f306f7819 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:30:57 -0400 Subject: [PATCH 12/31] typo --- get-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/index.md b/get-started/index.md index 6f5774bf..5b92af9e 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -256,7 +256,7 @@ The two prior sections have discussed: There is a third, hybrid approach: **using the Cryostat Agent to do application discovery, and JMX to expose data**. This may be useful since the Agent HTTP data model is readonly, whereas JMX is read-write. This means that using JMX to communicate between Cryostat and your applications allows for more dynamic flexibility, for example, the ability to start and stop Flight Recordings on demand. Using the Cryostat Agent for application discovery -is also more flexible than depending on `Services` with specially-named or specially-numbered ports. +is also more flexible than depending on `Service`s with specially-named or specially-numbered ports. For more context about these concepts, please review the previous two sections on [using the Cryostat Agent](#using-the-cryostat-agent) and [using JMX](#using-jmx). From 28b2abb368d292f3f943c5a4ea48cd4c551f5819 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:31:27 -0400 Subject: [PATCH 13/31] formatting --- get-started/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 5b92af9e..e4a75a99 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -303,7 +303,7 @@ Add dependency configuration to `pom.xml`: ``` -Modify the `application Deployment`: +Modify the application `Deployment`: ```yaml apiVersion: apps/v1 kind: Deployment @@ -344,7 +344,7 @@ spec: status: {} ``` -Create an `application Service`: +Create an application `Service`: ```yaml apiVersion: v1 kind: Service From b0b5b6375fc9de6082d0505731b989402636533e Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:32:28 -0400 Subject: [PATCH 14/31] break comment lines --- get-started/index.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index e4a75a99..80b64204 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -330,10 +330,14 @@ spec: - name: CRYOSTAT_AGENT_AUTHORIZATION # Replace "abcd1234" with a base64-encoded authentication token value: "Bearer abcd1234" - # This environment variable is key to the "hybrid" setup. This instructs the Agent to register itself with Cryostat as reachable via JMX, rather than reachable via HTTP. + # This environment variable is key to the "hybrid" setup. + # This instructs the Agent to register itself with Cryostat + # as reachable via JMX, rather than reachable via HTTP. - name: CRYOSTAT_AGENT_REGISTRATION_PREFER_JMX value: "true" - # Here we configure the application to load the Agent JAR as well as to enable JMX, since we want the Agent to register itself as reachable via JMX. + # Here we configure the application to load the Agent JAR as + # well as to enable JMX, since we want the Agent to register + # itself as reachable via JMX. - name: JAVA_OPTS value: "-javaagent:/deployments/app/cryostat-agent.jar -Dcom.sun.management.jmxremote.port=9091 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false" ports: From 45dc1447aee2ef3deea39d0312729f76c2d25827 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:34:40 -0400 Subject: [PATCH 15/31] use yaml multiline --- get-started/index.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 80b64204..b96a47b9 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -225,7 +225,10 @@ spec: image: docker.io/myorg/myapp:latest env: - name: JAVA_OPTS - value: "-Dcom.sun.management.jmxremote.port=9091 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false" + value: >- + -Dcom.sun.management.jmxremote.port=9091 + -Dcom.sun.management.jmxremote.ssl=false + -Dcom.sun.management.jmxremote.authenticate=false ... ``` @@ -339,7 +342,11 @@ spec: # well as to enable JMX, since we want the Agent to register # itself as reachable via JMX. - name: JAVA_OPTS - value: "-javaagent:/deployments/app/cryostat-agent.jar -Dcom.sun.management.jmxremote.port=9091 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false" + value: >- + -javaagent:/deployments/app/cryostat-agent.jar + -Dcom.sun.management.jmxremote.port=9091 + -Dcom.sun.management.jmxremote.ssl=false + -Dcom.sun.management.jmxremote.authenticate=false ports: - containerPort: 9977 protocol: TCP From a2d43333be7f097fc42900bf93006b62754f425f Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:35:19 -0400 Subject: [PATCH 16/31] plural --- get-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/index.md b/get-started/index.md index b96a47b9..db898a43 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -264,7 +264,7 @@ is also more flexible than depending on `Service`s with specially-named or speci For more context about these concepts, please review the previous two sections on [using the Cryostat Agent](#using-the-cryostat-agent) and [using JMX](#using-jmx). -Add dependency configuration to `pom.xml`: +Add dependency configurations to `pom.xml`: ```xml ... From 80b3aef0454b4d9c9c6db5e927db4c977d9c1a85 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:35:46 -0400 Subject: [PATCH 17/31] rephrase --- get-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/index.md b/get-started/index.md index db898a43..48cf09b1 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -73,7 +73,7 @@ but the instructions will be similar for other toolchains and platforms as well. #### [Using the Cryostat Agent](#using-the-cryostat-agent) [The Cryostat Agent](/guides/#using-the-cryostat-agent) -is compatible with Cryostat versions 2.3.0 and newer, and application JDKs 11 and newer. If you are using an older version of Cryostat, please upgrade. +is compatible with Cryostat versions 2.3.0 and newer, and application JDKs 11 and newer. If you are using an older version of Cryostat, we recommend upgrading to ensure compatibility. If your application uses a recent version of JDK8 with JFR support, please either upgrade to JDK11+ or [continue to the next section](#using-jmx) to learn how to configure your application without the Cryostat Agent. From ee7fc3df10c0a870ec868ce7240a07ad6fac23cc Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:36:41 -0400 Subject: [PATCH 18/31] add explanation comment --- get-started/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/get-started/index.md b/get-started/index.md index 48cf09b1..b0838126 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -152,6 +152,7 @@ spec: env: - name: CRYOSTAT_AGENT_APP_NAME value: "myapp" + # Replace this with the Kubernetes DNS record for the Cryostat Service - name: CRYOSTAT_AGENT_BASEURI value: "http://cryostat.mynamespace.mycluster.svc:8181" - name: POD_IP @@ -322,6 +323,7 @@ spec: env: - name: CRYOSTAT_AGENT_APP_NAME value: "myapp" + # Replace this with the Kubernetes DNS record for the Cryostat Service - name: CRYOSTAT_AGENT_BASEURI value: "http://cryostat.mynamespace.mycluster.svc:8181" - name: POD_IP From 96060e5f6e25763965780c172d45fe8231169422 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 26 Apr 2023 17:37:05 -0400 Subject: [PATCH 19/31] fixup! add explanation comment --- get-started/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index b0838126..b6b5ae6d 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -152,7 +152,8 @@ spec: env: - name: CRYOSTAT_AGENT_APP_NAME value: "myapp" - # Replace this with the Kubernetes DNS record for the Cryostat Service + # Replace this with the Kubernetes DNS record + # for the Cryostat Service - name: CRYOSTAT_AGENT_BASEURI value: "http://cryostat.mynamespace.mycluster.svc:8181" - name: POD_IP @@ -323,7 +324,8 @@ spec: env: - name: CRYOSTAT_AGENT_APP_NAME value: "myapp" - # Replace this with the Kubernetes DNS record for the Cryostat Service + # Replace this with the Kubernetes DNS record + # for the Cryostat Service - name: CRYOSTAT_AGENT_BASEURI value: "http://cryostat.mynamespace.mycluster.svc:8181" - name: POD_IP From 5bb3f59ef3fd05bd608af376473b49be425e993b Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Thu, 27 Apr 2023 16:19:37 -0400 Subject: [PATCH 20/31] rebase fix --- get-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/index.md b/get-started/index.md index b6b5ae6d..b4e1beac 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -207,7 +207,7 @@ flags to your application at startup. A basic and insecure setup suitable for te [comment]: # TODO explain how to configure SSL and auth for JMX, or link to external docs In a real scenario you should enable both SSL and authentication on your application. You can then [trust the certificate](/guides/#add-a-trusted-certificate) -and [store the credentials](/guides/#store-jmx-credentials). +and [store the credentials](/guides/#store-credentials). Depending on your application or its framework, you may set these flags directly in a `Dockerfile` entrypoint, an environment variable, or similar. This may or may not require a container image rebuild, and it will require the container to be restarted. Once this is done the application container will be listening for From 6441c18b70870026b849dabf648df9e66170587d Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Tue, 2 May 2023 18:01:53 -0400 Subject: [PATCH 21/31] list configuration combinations before explaining them --- get-started/index.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index b4e1beac..b791d75e 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -66,9 +66,14 @@ the specifics of how to deploy your Cryostat instance. Continue to [Setup](#setu ## [Setup](#setup) ### [Configuring Applications](#configuring-applications) -The following sections will briefly describe how to configure your Java applications so that Cryostat is able to discover and monitor them. -These examples will assume the application is built with Maven, packaged into an image with a `Dockerfile`, and running in Kubernetes, -but the instructions will be similar for other toolchains and platforms as well. +There are three methods of configuring your Java applications so that Cryostat is able to discover and monitor them: + +1. using the Cryostat Agent for discovery and connectivity +2. using platform mechanisms for discovery and Java Management Extensions (JMX) for connectivity +3. using the Cryostat Agent for discovery and JMX for connectivity + +The following sections will briefly explain how to accomplish each of these approaches by example. For simplicity the examples will assume your application +is built with Maven, packaged into an image with a `Dockerfile`, and running in Kubernetes, but the instructions will be similar for other toolchains and platforms as well. #### [Using the Cryostat Agent](#using-the-cryostat-agent) From a05724118b56225577452532e04c8568670cac04 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Tue, 2 May 2023 18:03:34 -0400 Subject: [PATCH 22/31] add links --- get-started/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index b791d75e..a6018ad9 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -68,9 +68,9 @@ the specifics of how to deploy your Cryostat instance. Continue to [Setup](#setu ### [Configuring Applications](#configuring-applications) There are three methods of configuring your Java applications so that Cryostat is able to discover and monitor them: -1. using the Cryostat Agent for discovery and connectivity -2. using platform mechanisms for discovery and Java Management Extensions (JMX) for connectivity -3. using the Cryostat Agent for discovery and JMX for connectivity +1. [using the Cryostat Agent for discovery and connectivity](#using-the-cryostat-agent) +2. [using platform mechanisms for discovery and Java Management Extensions (JMX) for connectivity](#using-jmx) +3. [using the Cryostat Agent for discovery and JMX for connectivity](#using-the-cryostat-agent-with-jmx) The following sections will briefly explain how to accomplish each of these approaches by example. For simplicity the examples will assume your application is built with Maven, packaged into an image with a `Dockerfile`, and running in Kubernetes, but the instructions will be similar for other toolchains and platforms as well. From 67080919dad4521ccf3eccc44e71d8190f62ffa2 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Tue, 2 May 2023 18:03:40 -0400 Subject: [PATCH 23/31] rephrase --- get-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/index.md b/get-started/index.md index a6018ad9..e072115f 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -211,7 +211,7 @@ flags to your application at startup. A basic and insecure setup suitable for te [comment]: # TODO explain how to configure SSL and auth for JMX, or link to external docs -In a real scenario you should enable both SSL and authentication on your application. You can then [trust the certificate](/guides/#add-a-trusted-certificate) +It is recommended that you enable both SSL and authentication on your application. You can then [trust the certificate](/guides/#add-a-trusted-certificate) and [store the credentials](/guides/#store-credentials). Depending on your application or its framework, you may set these flags directly in a `Dockerfile` entrypoint, an environment variable, or similar. This may or From 1f911fe9dc8d68cb91907df38a75f2163defb9db Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Tue, 2 May 2023 18:14:49 -0400 Subject: [PATCH 24/31] fix typo --- get-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/index.md b/get-started/index.md index e072115f..fa30032f 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -164,7 +164,7 @@ spec: - name: POD_IP valueFrom: fieldRef: - fieldPath: status.PodIP + fieldPath: status.podIP - name: CRYOSTAT_AGENT_CALLBACK value: "http://$(POD_IP):9977" # Replace "abcd1234" with a base64-encoded authentication token From 1b84966f0b7e8b6de52bb28cca6ec9d84cc47e1f Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Tue, 2 May 2023 18:17:49 -0400 Subject: [PATCH 25/31] fixup! fix typo --- get-started/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/index.md b/get-started/index.md index fa30032f..c32113d9 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -336,7 +336,7 @@ spec: - name: POD_IP valueFrom: fieldRef: - fieldPath: status.PodIP + fieldPath: status.podIP - name: CRYOSTAT_AGENT_CALLBACK value: "http://$(POD_IP):9977" - name: CRYOSTAT_AGENT_AUTHORIZATION From b16856807c1d1ca029a29cdd16fe009d21923262 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 3 May 2023 11:30:45 -0400 Subject: [PATCH 26/31] explain agent deployment environment variables more --- get-started/index.md | 42 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 34 insertions(+), 8 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index c32113d9..c67ccdee 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -156,18 +156,31 @@ spec: image: docker.io/myorg/myapp:latest env: - name: CRYOSTAT_AGENT_APP_NAME + # Replace this with any value you like to use to identify your application. value: "myapp" - # Replace this with the Kubernetes DNS record - # for the Cryostat Service + - name: NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace - name: CRYOSTAT_AGENT_BASEURI - value: "http://cryostat.mynamespace.mycluster.svc:8181" + # Replace this with the Kubernetes DNS record for the Cryostat Service + # by changing the first 'cryostat' subdomain to the name of your Cryostat + # deployment, if needed. + # (https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) + value: "http://cryostat.$(NAMESPACE).svc:8181" - name: POD_IP valueFrom: fieldRef: fieldPath: status.podIP - name: CRYOSTAT_AGENT_CALLBACK + # This infers the Agent Callback directly from the Pod's IP address using the + # Kubernetes Downward API. Use this value directly as provided. The port number + # 9977 can be changed but must match the containerPort below. value: "http://$(POD_IP):9977" - # Replace "abcd1234" with a base64-encoded authentication token + # Replace "abcd1234" with a base64-encoded authentication token. For example, + # in your terminal, do 'oc whoami -t | base64' to use your user account's + # token as the token that the Agent will pass to authorize itself with + # the Cryostat server. - name: CRYOSTAT_AGENT_AUTHORIZATION value: "Bearer abcd1234" ports: @@ -328,19 +341,32 @@ spec: image: docker.io/myorg/myapp:latest env: - name: CRYOSTAT_AGENT_APP_NAME + # Replace this with any value you like to use to identify your application. value: "myapp" - # Replace this with the Kubernetes DNS record - # for the Cryostat Service + - name: NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace - name: CRYOSTAT_AGENT_BASEURI - value: "http://cryostat.mynamespace.mycluster.svc:8181" + # Replace this with the Kubernetes DNS record for the Cryostat Service + # by changing the first 'cryostat' subdomain to the name of your Cryostat + # deployment, if needed. + # (https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) + value: "http://cryostat.$(NAMESPACE).svc:8181" - name: POD_IP valueFrom: fieldRef: fieldPath: status.podIP - name: CRYOSTAT_AGENT_CALLBACK + # This infers the Agent Callback directly from the Pod's IP address using the + # Kubernetes Downward API. Use this value directly as provided. The port number + # 9977 can be changed but must match the containerPort below. value: "http://$(POD_IP):9977" + # Replace "abcd1234" with a base64-encoded authentication token. For example, + # in your terminal, do 'oc whoami -t | base64' to use your user account's + # token as the token that the Agent will pass to authorize itself with + # the Cryostat server. - name: CRYOSTAT_AGENT_AUTHORIZATION - # Replace "abcd1234" with a base64-encoded authentication token value: "Bearer abcd1234" # This environment variable is key to the "hybrid" setup. # This instructs the Agent to register itself with Cryostat From db8e6e0abfc0877dc74524fc49f5066656d22b17 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Fri, 5 May 2023 12:20:09 -0400 Subject: [PATCH 27/31] explain cross-namespace Agent and Cryostat --- get-started/index.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index c67ccdee..01f028cf 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -163,11 +163,13 @@ spec: fieldRef: fieldPath: metadata.namespace - name: CRYOSTAT_AGENT_BASEURI - # Replace this with the Kubernetes DNS record for the Cryostat Service - # by changing the first 'cryostat' subdomain to the name of your Cryostat - # deployment, if needed. + # Update this to correspond to the name of your Cryostat instance + # if it is not 'cryostat'. This assumes that the target application + # and the Cryostat instance are in the same Namespace, but you may + # choose to configure the Agent to communicate with a Cryostat in + # a different Namespace, too. # (https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) - value: "http://cryostat.$(NAMESPACE).svc:8181" + value: https://cryostat.$(NAMESPACE).svc:8181 - name: POD_IP valueFrom: fieldRef: @@ -348,11 +350,13 @@ spec: fieldRef: fieldPath: metadata.namespace - name: CRYOSTAT_AGENT_BASEURI - # Replace this with the Kubernetes DNS record for the Cryostat Service - # by changing the first 'cryostat' subdomain to the name of your Cryostat - # deployment, if needed. + # Update this to correspond to the name of your Cryostat instance + # if it is not 'cryostat'. This assumes that the target application + # and the Cryostat instance are in the same Namespace, but you may + # choose to configure the Agent to communicate with a Cryostat in + # a different Namespace, too. # (https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) - value: "http://cryostat.$(NAMESPACE).svc:8181" + value: https://cryostat.$(NAMESPACE).svc:8181 - name: POD_IP valueFrom: fieldRef: From a6fa3ec6d6dbb76f14304d7325c94c2e5cec3b30 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Fri, 5 May 2023 15:47:24 -0400 Subject: [PATCH 28/31] reference agent version 0.2.1 --- get-started/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 01f028cf..e4485be3 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -111,7 +111,7 @@ or you may use the following snippet in your `pom.xml` to streamline this. io.cryostat cryostat-agent - 0.2.0 + 0.2.1 true @@ -313,7 +313,7 @@ Add dependency configurations to `pom.xml`: io.cryostat cryostat-agent - 0.2.0 + 0.2.1 true From d6f8e6ecaf74dad13a3779f0b873f845494dd97a Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Fri, 5 May 2023 16:05:20 -0400 Subject: [PATCH 29/31] in hybrid agent setup, skip the jfr-jmx named port --- get-started/index.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index e4485be3..16952ca3 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -401,9 +401,6 @@ kind: Service ... spec: ports: - - name: "jfr-jmx" - port: 9091 - targetPort: 9091 - name: "cryostat-agent" port: 9977 targetPort: 9977 From f4fd3a7f320cdc58024676c7519878bd4837ae1a Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Fri, 5 May 2023 16:06:34 -0400 Subject: [PATCH 30/31] set explicit hostname for JMX --- get-started/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/get-started/index.md b/get-started/index.md index 16952ca3..48b2a274 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -361,6 +361,8 @@ spec: valueFrom: fieldRef: fieldPath: status.podIP + - name: CRYOSTAT_AGENT_HOSTNAME + value: $(POD_IP) - name: CRYOSTAT_AGENT_CALLBACK # This infers the Agent Callback directly from the Pod's IP address using the # Kubernetes Downward API. Use this value directly as provided. The port number From a89d234ed4eeb3787c588068ed8b816a9c9b7090 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Wed, 10 May 2023 18:39:10 -0400 Subject: [PATCH 31/31] reorganize --- get-started/index.md | 340 +++++++++++++++++++++---------------------- 1 file changed, 170 insertions(+), 170 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 48b2a274..64fb2c84 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -65,7 +65,173 @@ the specifics of how to deploy your Cryostat instance. Continue to [Setup](#setu **Note**: Alternative methods for installing the operator are described in [Alternate Installation Options](/alternate-installation-options) (not recommended). ## [Setup](#setup) -### [Configuring Applications](#configuring-applications) +### [Deploying Cryostat](#deploying-cryostat) +Create a `Cryostat` object to deploy and set up Cryostat in the `cryostat-operator-system` namespace. For +full details on how to configure the Cryostat deployment, see +[Configuring Cryostat](https://github.com/cryostatio/cryostat-operator/blob/v{{ site.data.versions.cryostat.version }}/docs/config.md). + +If running Cryostat on Kubernetes, you will also need to add Ingress configurations to your Cryostat resource. +See the [Network Options](https://github.com/cryostatio/cryostat-operator/blob/v{{ site.data.versions.cryostat.version }}/docs/config.md#network-options) section of Configuring Cryostat for examples. + +You can create the resource graphically in the OperatorHub UI after following [Install via OperatorHub](#install-via-operatorhub): + +{% include howto_step.html + details-attributes="open" + summary="Installed Operators View" + image-name="installed-operators.png" +%} +{% include howto_step.html + summary="Cryostat Resources Before" + image-name="cryostat-resources-before.png" +%} +{% include howto_step.html + summary="Cryostat Resource Creation" + image-name="cryostat-resource-creation.png" +%} +{% include howto_step.html + summary="Cryostat Resources After" + image-name="cryostat-resources-after.png" +%} + +You can also create the resource manually using a YAML definition like the following: + +```yaml +apiVersion: operator.cryostat.io/v1beta1 +kind: Cryostat +metadata: + name: cryostat-sample +spec: + minimal: false + enableCertManager: true + trustedCertSecrets: [] + eventTemplates: [] + storageOptions: + pvc: + labels: {} + annotations: {} + spec: {} + reportOptions: + replicas: 0 +``` + +Then apply the resource: +``` +$ kubectl apply -f cryostat.yaml +``` + +### [Open the Cryostat Web UI](#open-the-cryostat-web-ui) +Let's visit the Cryostat web dashboard UI. + +We can get there from the Cryostat resource's Status field: + +{% include howto_step.html + details-attributes="open" + summary="Cryostat Resource Status" + image-name="cryostat-resource-status.png" +%} + +Or, we can open the application link from the Topology view: + +{% include howto_step.html + details-attributes="open" + summary="Topology View" + image-name="topology-view.png" +%} + +We can also find the URL using `oc`: +```bash +$ oc get cryostat -o jsonpath='{$.items[0].status.applicationUrl}' +``` + +#### [Authenticate through Cryostat](#authenticate-through-cryostat) + +##### [OpenShift Authentication](#openshift-authentication) +When deployed in OpenShift, Cryostat will use the existing internal cluster +authentication system to ensure all requests come from users with correct +access to the Cryostat instance and the namespace that it is deployed within. + +{% include howto_step.html + details-attributes="open" + summary="OpenShift SSO Login" + image-name="sso-auth-page.png" +%} +{% include howto_step.html + details-attributes="open" + summary="OpenShift Service Account Permissions" + image-name="permissions-auth-page.png" +%} +Once you have authenticated through the cluster's SSO login you will be +redirected back to the Cryostat web application. The redirect URL contains +an access token for Cryostat's service account with the permissions you have +granted to it. The Cryostat web application passes this OpenShift token back +to the Cryostat server on each request using `Bearer` authorization headers. +The Cryostat server forwards this token back to the OpenShift auth server on +each client request to check the token authorization for the current request. +This access token will eventually expire and you will be required to log back +in on the cluster SSO login page. + +For direct access to the Cryostat HTTP API you may follow the same pattern. +Using a client such as `curl`, an OpenShift auth token can be passed with +requests using the `Authorization: Bearer` header. The token must be base64 +encoded. For example, +``` +curl -v -H "Authorization: Bearer $(oc whoami -t | base64)" https://cryostat.example.com:8181/api/v1/targets +``` + +##### [Other Platforms Authentication](#other-platforms-authentication) + +In non-OpenShift environments, Cryostat will default to no authentication. +Access to the web application and the HTTP API will be unsecured. You should +either configure Cryostat's built-in `Basic` authentication system, or better, +place an authenticating reverse proxy server in front of Cryostat so that +accesses to the Cryostat application must first pass through the reverse +proxy. The configuration of a reverse proxy is out of scope of this guide. + +###### [Basic Auth](#basic-auth) + +Cryostat includes a very rudimentary HTTP `Basic` authentication implementation. +This can be configured by creating a `cryostat-users.properties` file in the +Cryostat server `conf` directory, defined by the environment variable +`CRYOSTAT_CONFIG_PATH` and defaulting to `/opt/cryostat.d/conf.d`. +The credentials stored in the Java properties file are the user name and a +SHA-256 sum hex of the user's password. The property file contents should look +like: + +``` +user1=abc123 +user2=def987 +``` +Where `abc123` and `def987` are substituted for the SHA-256 sum hexes of the +desired user passwords. These can be obtained by ex. +`echo -n PASS | sha256sum | cut -d' ' -f1`. The `Basic` user credentials `user:pass` +would therefore be entered as +`user:d74ff0ee8da3b9806b18c877dbf29bbde50b5bd8e4dad7a3a725000feb82e8f1`. + +This mechanism only supports fully-privileged user definitions, authorized to +perform any action within the Cryostat API. + +Once the `cryostat-users.properties` file defining the user credentials is +created, the environment variable `CRYOSTAT_AUTH_MANAGER` should be set +to the value `io.cryostat.net.BasicAuthManager` to enable the corresponding +auth implementation. + +### [Deploy an Application](#deploy-an-application) +For demo purposes, let's go ahead and deploy a sample application to our +OpenShift cluster in the same namespace as our Cryostat instance. If you have +deployed Cryostat into a namespace where you are already running other +applications, feel free to [continue to the next step](#open-the-cryostat-web-ui). + +```bash +$ oc new-app --docker-image=quay.io/andrewazores/quarkus-test:0.0.10 +$ oc patch svc/quarkus-test -p '{"spec":{"$setElementOrder/ports":[{"port":9097},{"port":8080}],"ports":[{"name":"jfr-jmx","port":9097}]}}' +``` + +This is a Quarkus container in JVM mode with JMX enabled and pre-configured to +listen on port 9097. After deploying the container we patch its service to +name the 9097 service port `jfr-jmx`. Cryostat will detect and use this port +to determine that this is a compatible Java application that it should monitor. + +#### [Configuring Applications](#configuring-applications) There are three methods of configuring your Java applications so that Cryostat is able to discover and monitor them: 1. [using the Cryostat Agent for discovery and connectivity](#using-the-cryostat-agent) @@ -75,7 +241,7 @@ There are three methods of configuring your Java applications so that Cryostat i The following sections will briefly explain how to accomplish each of these approaches by example. For simplicity the examples will assume your application is built with Maven, packaged into an image with a `Dockerfile`, and running in Kubernetes, but the instructions will be similar for other toolchains and platforms as well. -#### [Using the Cryostat Agent](#using-the-cryostat-agent) +##### [Using the Cryostat Agent](#using-the-cryostat-agent) [The Cryostat Agent](/guides/#using-the-cryostat-agent) is compatible with Cryostat versions 2.3.0 and newer, and application JDKs 11 and newer. If you are using an older version of Cryostat, we recommend upgrading to ensure compatibility. @@ -214,7 +380,7 @@ spec: More details about the configuration options for the Cryostat Agent [are available here](https://github.com/cryostatio/cryostat-agent/blob/main/README.md#configuration). -#### [Using JMX](#using-jmx) +##### [Using JMX](#using-jmx) Cryostat is also able to use Java Management Extensions (JMX) to communicate with target applications. This is a standard JDK feature that can be enabled by passing JVM flags to your application at startup. A basic and insecure setup suitable for testing requires only the following three flags: @@ -273,7 +439,7 @@ Cryostat queries the Kubernetes API server and looks for `Service`s with a port must be met or else Cryostat will not automatically detect your application. In this case you may wish to use the [Cryostat Agent](#using-the-cryostat-agent-with-jmx) to enable discovery, while keeping communications over JMX rather than HTTP. -#### [Using the Cryostat Agent with JMX](#using-the-cryostat-agent-with-jmx) +##### [Using the Cryostat Agent with JMX](#using-the-cryostat-agent-with-jmx) The two prior sections have discussed: - How to use the Cryostat Agent to do application discovery and expose data over HTTP. - How to use Kubernetes `Service` configurations for discovery and JMX to expose data. @@ -409,172 +575,6 @@ spec: ... ``` -### [Deploying Cryostat](#deploying-cryostat) -Create a `Cryostat` object to deploy and set up Cryostat in the `cryostat-operator-system` namespace. For -full details on how to configure the Cryostat deployment, see -[Configuring Cryostat](https://github.com/cryostatio/cryostat-operator/blob/v{{ site.data.versions.cryostat.version }}/docs/config.md). - -If running Cryostat on Kubernetes, you will also need to add Ingress configurations to your Cryostat resource. -See the [Network Options](https://github.com/cryostatio/cryostat-operator/blob/v{{ site.data.versions.cryostat.version }}/docs/config.md#network-options) section of Configuring Cryostat for examples. - -You can create the resource graphically in the OperatorHub UI after following [Install via OperatorHub](#install-via-operatorhub): - -{% include howto_step.html - details-attributes="open" - summary="Installed Operators View" - image-name="installed-operators.png" -%} -{% include howto_step.html - summary="Cryostat Resources Before" - image-name="cryostat-resources-before.png" -%} -{% include howto_step.html - summary="Cryostat Resource Creation" - image-name="cryostat-resource-creation.png" -%} -{% include howto_step.html - summary="Cryostat Resources After" - image-name="cryostat-resources-after.png" -%} - -You can also create the resource manually using a YAML definition like the following: - -```yaml -apiVersion: operator.cryostat.io/v1beta1 -kind: Cryostat -metadata: - name: cryostat-sample -spec: - minimal: false - enableCertManager: true - trustedCertSecrets: [] - eventTemplates: [] - storageOptions: - pvc: - labels: {} - annotations: {} - spec: {} - reportOptions: - replicas: 0 -``` - -Then apply the resource: -``` -$ kubectl apply -f cryostat.yaml -``` - -### [Deploy an Application](#deploy-an-application) -For demo purposes, let's go ahead and deploy a sample application to our -OpenShift cluster in the same namespace as our Cryostat instance. If you have -deployed Cryostat into a namespace where you are already running other -applications, feel free to [continue to the next step](#open-the-cryostat-web-ui). - -```bash -$ oc new-app --docker-image=quay.io/andrewazores/quarkus-test:0.0.10 -$ oc patch svc/quarkus-test -p '{"spec":{"$setElementOrder/ports":[{"port":9097},{"port":8080}],"ports":[{"name":"jfr-jmx","port":9097}]}}' -``` - -This is a Quarkus container in JVM mode with JMX enabled and pre-configured to -listen on port 9097. After deploying the container we patch its service to -name the 9097 service port `jfr-jmx`. Cryostat will detect and use this port -to determine that this is a compatible Java application that it should monitor. - -### [Open the Cryostat Web UI](#open-the-cryostat-web-ui) -Let's visit the Cryostat web dashboard UI. - -We can get there from the Cryostat resource's Status field: - -{% include howto_step.html - details-attributes="open" - summary="Cryostat Resource Status" - image-name="cryostat-resource-status.png" -%} - -Or, we can open the application link from the Topology view: - -{% include howto_step.html - details-attributes="open" - summary="Topology View" - image-name="topology-view.png" -%} - -We can also find the URL using `oc`: -```bash -$ oc get cryostat -o jsonpath='{$.items[0].status.applicationUrl}' -``` - -### [Authenticate through Cryostat](#authenticate-through-cryostat) - -#### [OpenShift Authentication](#openshift-authentication) -When deployed in OpenShift, Cryostat will use the existing internal cluster -authentication system to ensure all requests come from users with correct -access to the Cryostat instance and the namespace that it is deployed within. - -{% include howto_step.html - details-attributes="open" - summary="OpenShift SSO Login" - image-name="sso-auth-page.png" -%} -{% include howto_step.html - details-attributes="open" - summary="OpenShift Service Account Permissions" - image-name="permissions-auth-page.png" -%} -Once you have authenticated through the cluster's SSO login you will be -redirected back to the Cryostat web application. The redirect URL contains -an access token for Cryostat's service account with the permissions you have -granted to it. The Cryostat web application passes this OpenShift token back -to the Cryostat server on each request using `Bearer` authorization headers. -The Cryostat server forwards this token back to the OpenShift auth server on -each client request to check the token authorization for the current request. -This access token will eventually expire and you will be required to log back -in on the cluster SSO login page. - -For direct access to the Cryostat HTTP API you may follow the same pattern. -Using a client such as `curl`, an OpenShift auth token can be passed with -requests using the `Authorization: Bearer` header. The token must be base64 -encoded. For example, -``` -curl -v -H "Authorization: Bearer $(oc whoami -t | base64)" https://cryostat.example.com:8181/api/v1/targets -``` - -#### [Other Platforms Authentication](#other-platforms-authentication) - -In non-OpenShift environments, Cryostat will default to no authentication. -Access to the web application and the HTTP API will be unsecured. You should -either configure Cryostat's built-in `Basic` authentication system, or better, -place an authenticating reverse proxy server in front of Cryostat so that -accesses to the Cryostat application must first pass through the reverse -proxy. The configuration of a reverse proxy is out of scope of this guide. - -##### [Basic Auth](#basic-auth) - -Cryostat includes a very rudimentary HTTP `Basic` authentication implementation. -This can be configured by creating a `cryostat-users.properties` file in the -Cryostat server `conf` directory, defined by the environment variable -`CRYOSTAT_CONFIG_PATH` and defaulting to `/opt/cryostat.d/conf.d`. -The credentials stored in the Java properties file are the user name and a -SHA-256 sum hex of the user's password. The property file contents should look -like: - -``` -user1=abc123 -user2=def987 -``` -Where `abc123` and `def987` are substituted for the SHA-256 sum hexes of the -desired user passwords. These can be obtained by ex. -`echo -n PASS | sha256sum | cut -d' ' -f1`. The `Basic` user credentials `user:pass` -would therefore be entered as -`user:d74ff0ee8da3b9806b18c877dbf29bbde50b5bd8e4dad7a3a725000feb82e8f1`. - -This mechanism only supports fully-privileged user definitions, authorized to -perform any action within the Cryostat API. - -Once the `cryostat-users.properties` file defining the user credentials is -created, the environment variable `CRYOSTAT_AUTH_MANAGER` should be set -to the value `io.cryostat.net.BasicAuthManager` to enable the corresponding -auth implementation. - ## [Next Steps](#next-steps) Now that you have installed and deployed Cryostat and know how to access its web client, continue on to [Guides]({% link guides/index.md %}) for