From f5a2e50537786567ef611baa12db0567947f743f Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Thu, 2 Nov 2023 15:43:59 -0400 Subject: [PATCH 1/7] edited --- get-started/index.md | 188 +++++++++++++++++++++---------------------- 1 file changed, 93 insertions(+), 95 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index d6659c27..1529ff42 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -12,24 +12,24 @@ Cryostat {{ site.data.versions.cryostat.version }} {:toc} ## [Installing Cryostat Operator](#installing-cryostat-operator) -Follow the steps below to install the Cryostat Operator via [OperatorHub](https://operatorhub.io/operator/cryostat-operator). +Follow the steps below to install the **Cryostat Operator** via [OperatorHub](https://operatorhub.io/operator/cryostat-operator). ### [Install cert-manager](#install-cert-manager) -The Cryostat Operator requires [cert-manager](https://cert-manager.io/) to run. -If not already installed in your cluster, please +The **Cryostat Operator** requires [cert-manager](https://cert-manager.io/) to run. +If not already installed in your cluster, please [install](https://cert-manager.io/docs/installation/) it using your preferred method. Once installed, proceed with the Operator installation steps below. -**Warning**: Although it is possible to [disable cert-manager integration](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#disabling-cert-manager-integration), it is NOT recommended to +**Warning**: Although it is possible to [disable cert-manager integration](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#disabling-cert-manager-integration), it is NOT recommended to do so unless cert-manager is unavailable AND one of the following applies to you: - You have another solution for encrypting traffic -- You trust everything running in the same cluster where the Cryostat Operator is deployed +- You trust everything running in the same cluster where the **Cryostat Operator** is deployed ### [Install via OperatorHub](#install-via-operatorhub) -See below for a summary of the installation steps from the Cryostat Operator page on [OperatorHub](https://operatorhub.io/cryostat-operator). For more details, visit [Installing the Cryostat Operator from OperatorHub](https://developers.redhat.com/articles/2022/01/20/install-cryostat-operator-kubernetes-operatorhubio#). +See below for a summary of the installation steps from the **Cryostat Operator** page on [OperatorHub](https://operatorhub.io/cryostat-operator). For more details, visit [Installing the Cryostat Operator from OperatorHub](https://developers.redhat.com/articles/2022/01/20/install-cryostat-operator-kubernetes-operatorhubio#). -1. Install the Operator Lifecycle Manager: - Check if OLM is already installed: +1. Install the Operator Lifecycle Manager **(OLM)**: + Check if **OLM** is already installed: ```bash $ operator-sdk olm status $ # or without the operator-sdk binary, @@ -58,7 +58,7 @@ packageserver-8cccc99dd-dv8rp 1/1 Running 0 3m3s packageserver-8cccc99dd-g7lkh 1/1 Running 0 3m3s ``` -3. Install Cryostat from OperatorHub: +3. Install **Cryostat** from **OperatorHub**: {% include howto_step.html details-attributes="open" summary="Cryostat on OperatorHub" @@ -67,25 +67,24 @@ packageserver-8cccc99dd-g7lkh 1/1 Running 0 3m3s Use the search bar to find the **Red Hat build of Cryostat** catalog item. {% include howto_step.html summary="Select the Cryostat Operator and click the Install button" - image-name="cryostat-operatorhub-install.png" + image-name="`cryostat-operatorhub-install.png`" %} Choose your Operator installation mode: -1. In **All Namespaces** installation mode, the Cryostat Operator instance will watch for `Cryostat` or -`ClusterCryostat` Custom Resources (`CR`s) created in any Namespace and create corresponding Cryostat instances. -2. In the **A specific namespace** installation mode, you must also select an installation Namespace, and the Cryostat -Operator instance will only watch for `Cryostat` or `ClusterCryostat` instances created in that same Namespace. +1. In **All Namespaces** installation mode, the **Cryostat Operator** instance will watch for **Cryostat** or +**ClusterCryostat** Custom Resources (`CR`s) created in any Namespace and create corresponding Cryostat instances. +2. In the **A specific namespace** installation mode, you must also select an installation Namespace, and the **Cryostat Operator** instance will only watch for **Cryostat** or **ClusterCryostat** instances created in that same Namespace. {% include howto_step.html summary="Install the Operator" image-name="cryostat-operatorhub-install-in-progress.png" %} -Click "Install" and wait for the installation to complete. In this example we will proceed with **All Namespaces**. +Click "*Install*" and wait for the installation to complete. In this example we will proceed with **All Namespaces**. Continue to [Setup](#setup). ## [Setup](#setup) -**Note:** An alternative setup using the multi-namespace `ClusterCryostat` `CR` is described in -[Alternate Setup](#alternate-setup). For simplicity we will continue with the single-namespace `Cryostat` `CR`. +**Note:** An alternative setup using the multi-namespace **ClusterCryostat** `CR` is described in +[Alternate Setup](#alternate-setup). For simplicity we will continue with the single-namespace **Cryostat** `CR`. ### [Deploying Cryostat](#deploying-cryostat) @@ -93,16 +92,16 @@ Continue to [Setup](#setup). summary="Create a Cryostat instance" image-name="cryostat-operatorhub-install-complete.png" %} -Once the installation is complete, click **Create Cryostat** to create a `Cryostat` `CR` instance in an OpenShift -Project (Kubernetes `Namespace`) of your choice. This provides configuration information for the Operator to know the -specifics of how to deploy your Cryostat instance. For full details on how to configure the Cryostat deployment, see +Once the installation is complete, click ***Create Cryostat*** to create a **Cryostat** `CR` instance in an **OpenShift +Project** (Kubernetes `Namespace`) of your choice. This provides configuration information for the **Operator** to know the +specifics of how to deploy your **Cryostat** instance. For full details on how to configure the **Cryostat** deployment, see [Configuring Cryostat](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md). -If running Cryostat on Kubernetes and not OpenShift, you will also need to add Ingress configurations to your Cryostat +If running **Cryostat** on **Kubernetes** and not **OpenShift**, you will also need to add **Ingress** configurations to your **Cryostat** custom resource (`CR`). -See the [Network Options](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#network-options) section of Configuring Cryostat for examples. +See the [Network Options](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#network-options) section of Configuring **Cryostat** for examples. -You can create the `CR` graphically in the OperatorHub UI after following [Install via OperatorHub](#install-via-operatorhub): +You can create the `CR` graphically in the **OperatorHub** UI after following [Install via OperatorHub](#install-via-operatorhub): {% include howto_step.html details-attributes="open" @@ -122,7 +121,7 @@ You can create the `CR` graphically in the OperatorHub UI after following [Insta image-name="cryostat-resources-after.png" %} -You can also create the `CR` manually using a YAML definition like the following: +You can also create the `CR` manually using a **YAML** definition like the following: ```yaml apiVersion: operator.cryostat.io/v1beta1 @@ -151,9 +150,9 @@ $ kubectl apply -f cryostat.yaml ``` ### [Open the Cryostat Web UI](#open-the-cryostat-web-ui) -Let's visit the Cryostat web dashboard UI. +Let's visit the **Cryostat** web dashboard UI. -We can get there from the `Cryostat` `CR`'s status fields: +We can get there from the **Cryostat** `CR`'s status fields: {% include howto_step.html details-attributes="open" @@ -161,7 +160,7 @@ We can get there from the `Cryostat` `CR`'s status fields: image-name="cryostat-resource-status.png" %} -Or, we can open the application link from the OpenShift Console Topology view: +Or, we can open the application link from the **OpenShift** Console *Topology* view: {% include howto_step.html details-attributes="open" @@ -169,7 +168,7 @@ Or, we can open the application link from the OpenShift Console Topology view: image-name="topology-view.png" %} -We can also find the URL using `oc`: +We can also find the **URL** using `oc`: ```bash $ oc get cryostat -o jsonpath='{$.items[0].status.applicationUrl}' ``` @@ -177,9 +176,8 @@ $ 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. +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" @@ -191,19 +189,19 @@ access to the Cryostat instance and the namespace that it is deployed within. 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 +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 +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, ```bash $ curl -v -H "Authorization: Bearer $(oc whoami -t | base64)" https://cryostat.example.com:8181/api/v1/targets @@ -211,18 +209,18 @@ $ curl -v -H "Authorization: Bearer $(oc whoami -t | base64)" https://cryostat.e ##### [Other Platforms Authentication](#other-platforms-authentication) -In non-OpenShift environments, Cryostat will default to no 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 +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. +**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** 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 @@ -239,7 +237,7 @@ would therefore be entered as `user:d74ff0ee8da3b9806b18c877dbf29bbde50b5bd8e4dad7a3a725000feb82e8f1`. This mechanism only supports fully-privileged user definitions, authorized to -perform any action within the Cryostat API. +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 @@ -248,8 +246,8 @@ 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 +**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 @@ -257,29 +255,29 @@ $ 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 +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: +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) 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. +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) [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. -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. +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. -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), +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 @@ -323,9 +321,9 @@ 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. +**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: +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 ... @@ -335,9 +333,9 @@ COPY target/dependency/cryostat-agent.jar /deployments/app/ 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 Kubernetes registry, then modify your application `Deployment` to supply JVM system properties or environment variables configuring -the Cryostat Agent: +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 Kubernetes registry, then modify your application `Deployment` to supply JVM system properties or environment variables configuring +the **Cryostat Agent**: ```yaml apiVersion: apps/v1 @@ -390,12 +388,12 @@ spec: 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 a Kubernetes `Service Account` for +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 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`. -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 @@ -409,10 +407,10 @@ spec: ... ``` -More details about the configuration options for the Cryostat Agent [are available here](https://github.com/cryostatio/cryostat-agent/blob/{{site.data.versions.cryostat.release-branch}}/README.md#configuration). +More details about the configuration options for the **Cryostat Agent** [are available here](https://github.com/cryostatio/cryostat-agent/blob/{{site.data.versions.cryostat.release-branch}}/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 +**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: ``` @@ -423,7 +421,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 -It is recommended that you 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 @@ -451,7 +449,7 @@ spec: ... ``` -Next, we need to configure a Kubernetes `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 @@ -466,8 +464,8 @@ spec: ... ``` -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) +**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) @@ -476,9 +474,9 @@ The two prior sections have discussed: - 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 `Service`s with specially-named or specially-numbered ports. +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 `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). @@ -609,25 +607,25 @@ spec: ### [Alternate Setup](#alternate-setup) #### [Using ClusterCryostats](#using-clustercryostats) -In [Deploying Cryostat](#deploying-cryostat), you created a single-namespace `Cryostat` Custom Resource +In [Deploying Cryostat](#deploying-cryostat), you created a single-namespace **Cryostat** Custom Resource (`CR`) instance. -Single-namespace `Cryostat` `CR`s instruct the Operator to deploy restricted Cryostat instances which are only able -to see target applications deployed in the same namespace as the Cryostat instance, which is the same Namespace that +Single-namespace **Cryostat CR\`s** instruct the Operator to deploy restricted **Cryostat** instances which are only able +to see target applications deployed in the same namespace as the **Cryostat** instance, which is the same Namespace that the `CR` is created within. -If you chose to install the Operator in **All Namespaces** mode as assumed in this guide, you may also be interested in -creating `CluterCryostat` `CR`s. In this configuration, the Operator is able to see `Cryostat` and `ClusterCryostat` -`CR`s in any project (`Namespace`) and create Cryostat deployments corresponding to either `CR` kind in each of their -respective `Namespaces`. Both of these `CRs` are `Namespace`-specific, and the `Namespace` is used to determine which -OpenShift users are able to access the Cryostat instance. For more information, please see the following documents: +If you chose to install the **Operator** in **All Namespaces** mode as assumed in this guide, you may also be interested in +creating **CluterCryostat CR\`s**. In this configuration, the **Operator** is able to see **Cryostat** and **ClusterCryostat +CR\`s** in any project (`Namespace`) and create **Cryostat** deployments corresponding to either `CR` kind in each of their +respective **Namespaces**. Both of these **CRs** are **Namespace**-specific, and the **Namespace** is used to determine which +**OpenShift** users are able to access the **Cryostat** instance. For more information, please see the following documents: - [Multi-namespace](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/multi-namespace.md). - [Authorization Properties](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#authorization-properties) -`ClusterCryostat` `CR`s instruct the Operator to deploy cross-namespace Cryostat instances. A `ClusterCryostat` has -an `installNamespace`, which is the namespace where the Cryostat `Deployment` will reside, and a list of -`targetNamespaces`, which are all of the namespaces that the Cryostat server will watch for target applications. -The `targetNamespaces` list does not necessarily need to contain the `installNamespace`, if you do not want Cryostat +**ClusterCryostat CR\`s** instruct the Operator to deploy cross-namespace **Cryostat** instances. A **ClusterCryostat** has +an `installNamespace`, which is the namespace where the **Cryostat Deployment** will reside, and a list of +`targetNamespaces`, which are all of the namespaces that the **Cryostat** server will watch for target applications. +The `targetNamespaces` list does not necessarily need to contain the `installNamespace`, if you do not want **Cryostat** to see itself in the target applications that it watches. ```yaml @@ -652,15 +650,15 @@ spec: ``` ## [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 +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 guides through various common actions and workflows. ## [Uninstalling Cryostat Operator](#uninstalling-cryostat-operator) Reference [Operator Lifecycle Manager's](https://olm.operatorframework.io/docs/tasks/uninstall-operator/#combine-steps-2-and-3) -guide on uninstalling Operators. Please be sure to delete all `Cryostat` and `ClusterCryostat` Custom Resources before -uninstalling the Cryostat Operator. -- If your Cryostat Operator was installed in **All Namespaces** mode, then its `ClusterServiceVersion` and -`Subscription` can be found in the `Namespace` `openshift-operators`. -- If your Cryostat Operator was installed in **A specific Namespace**, then the `ClusterServiceVersion` and -`Subscription` will be in that same `Namespace.` +guide on uninstalling Operators. Please be sure to delete all **Cryostat** and **ClusterCryostat** Custom Resources before +uninstalling the **Cryostat Operator**. +- If your **Cryostat Operator** was installed in **All Namespaces** mode, then its **ClusterServiceVersion** and +`Subscription` can be found in the **Namespace** **openshift-operators**. +- If your **Cryostat Operator** was installed in **A specific Namespace**, then the **ClusterServiceVersion** and +`Subscription` will be in that same **Namespace**. From 4060cb389c978a35c8be1be20895fb03b1b0350f Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Fri, 3 Nov 2023 11:12:10 -0400 Subject: [PATCH 2/7] fixed consistency --- get-started/index.md | 107 ++++++++++++++++++++++--------------------- 1 file changed, 54 insertions(+), 53 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 1529ff42..e0c63dea 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -12,13 +12,13 @@ Cryostat {{ site.data.versions.cryostat.version }} {:toc} ## [Installing Cryostat Operator](#installing-cryostat-operator) -Follow the steps below to install the **Cryostat Operator** via [OperatorHub](https://operatorhub.io/operator/cryostat-operator). +Follow the steps below to install the **Cryostat Operator** via [**OperatorHub**](https://operatorhub.io/operator/cryostat-operator). ### [Install cert-manager](#install-cert-manager) The **Cryostat Operator** requires [cert-manager](https://cert-manager.io/) to run. If not already installed in your cluster, please [install](https://cert-manager.io/docs/installation/) it using your preferred method. -Once installed, proceed with the Operator installation steps below. +Once installed, proceed with the **Operator** installation steps below. **Warning**: Although it is possible to [disable cert-manager integration](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#disabling-cert-manager-integration), it is NOT recommended to do so unless cert-manager is unavailable AND one of the following applies to you: @@ -26,9 +26,9 @@ do so unless cert-manager is unavailable AND one of the following applies to you - You trust everything running in the same cluster where the **Cryostat Operator** is deployed ### [Install via OperatorHub](#install-via-operatorhub) -See below for a summary of the installation steps from the **Cryostat Operator** page on [OperatorHub](https://operatorhub.io/cryostat-operator). For more details, visit [Installing the Cryostat Operator from OperatorHub](https://developers.redhat.com/articles/2022/01/20/install-cryostat-operator-kubernetes-operatorhubio#). +See below for a summary of the installation steps from the **Cryostat Operator** page on [**OperatorHub**](https://operatorhub.io/cryostat-operator). For more details, visit [Installing the **Cryostat Operator** from OperatorHub](https://developers.redhat.com/articles/2022/01/20/install-cryostat-operator-kubernetes-operatorhubio#). -1. Install the Operator Lifecycle Manager **(OLM)**: +1. Install the **Operator** Lifecycle Manager **(OLM)**: Check if **OLM** is already installed: ```bash $ operator-sdk olm status @@ -39,7 +39,7 @@ See below for a summary of the installation steps from the **Cryostat Operator** **If Operator Lifecycle Manager (OLM) and OperatorHub are already installed and available on your cluster, skip to Step 3:** - Install Operator Lifecycle Manager: + Install **Operator** Lifecycle Manager: ```bash $ operator-sdk olm install @@ -69,10 +69,10 @@ Use the search bar to find the **Red Hat build of Cryostat** catalog item. summary="Select the Cryostat Operator and click the Install button" image-name="`cryostat-operatorhub-install.png`" %} -Choose your Operator installation mode: +Choose your **Operator** installation mode: 1. In **All Namespaces** installation mode, the **Cryostat Operator** instance will watch for **Cryostat** or -**ClusterCryostat** Custom Resources (`CR`s) created in any Namespace and create corresponding Cryostat instances. -2. In the **A specific namespace** installation mode, you must also select an installation Namespace, and the **Cryostat Operator** instance will only watch for **Cryostat** or **ClusterCryostat** instances created in that same Namespace. +**ClusterCryostat** Custom Resources (**CR**s) created in any `Namespace` and create corresponding **Cryostat** instances. +2. In the **A specific namespace** installation mode, you must also select an installation `Namespace`, and the **Cryostat Operator** instance will only watch for **Cryostat** or **ClusterCryostat** instances created in that same `Namespace`. {% include howto_step.html summary="Install the Operator" image-name="cryostat-operatorhub-install-in-progress.png" @@ -83,8 +83,8 @@ Continue to [Setup](#setup). ## [Setup](#setup) -**Note:** An alternative setup using the multi-namespace **ClusterCryostat** `CR` is described in -[Alternate Setup](#alternate-setup). For simplicity we will continue with the single-namespace **Cryostat** `CR`. +**Note:** An alternative setup using the multi-namespace **ClusterCryostat CR** is described in +[Alternate Setup](#alternate-setup). For simplicity we will continue with the single-namespace **Cryostat CR**. ### [Deploying Cryostat](#deploying-cryostat) @@ -92,16 +92,16 @@ Continue to [Setup](#setup). summary="Create a Cryostat instance" image-name="cryostat-operatorhub-install-complete.png" %} -Once the installation is complete, click ***Create Cryostat*** to create a **Cryostat** `CR` instance in an **OpenShift -Project** (Kubernetes `Namespace`) of your choice. This provides configuration information for the **Operator** to know the +Once the installation is complete, click *Create Cryostat* to create a **Cryostat CR** instance in an **OpenShift +Project** (**Kubernetes** `Namespace`) of your choice. This provides configuration information for the **Operator** to know the specifics of how to deploy your **Cryostat** instance. For full details on how to configure the **Cryostat** deployment, see -[Configuring Cryostat](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md). +[Configuring **Cryostat**](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md). If running **Cryostat** on **Kubernetes** and not **OpenShift**, you will also need to add **Ingress** configurations to your **Cryostat** -custom resource (`CR`). +custom resource (**CR**). See the [Network Options](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#network-options) section of Configuring **Cryostat** for examples. -You can create the `CR` graphically in the **OperatorHub** UI after following [Install via OperatorHub](#install-via-operatorhub): +You can create the **CR** graphically in the **OperatorHub** UI after following [Install via OperatorHub](#install-via-operatorhub): {% include howto_step.html details-attributes="open" @@ -121,7 +121,7 @@ You can create the `CR` graphically in the **OperatorHub** UI after following [I image-name="cryostat-resources-after.png" %} -You can also create the `CR` manually using a **YAML** definition like the following: +You can also create the **CR** manually using a **YAML** definition like the following: ```yaml apiVersion: operator.cryostat.io/v1beta1 @@ -152,7 +152,7 @@ $ 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** `CR`'s status fields: +We can get there from the **Cryostat** **CR**'s status fields: {% include howto_step.html details-attributes="open" @@ -176,7 +176,8 @@ $ 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 +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 @@ -189,7 +190,7 @@ access to the **Cryostat** instance and the namespace that it is deployed within summary="OpenShift Service Account Permissions" image-name="permissions-auth-page.png" %} -Once you have authenticated through the **cluster's SSO login** you will be +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 @@ -197,7 +198,7 @@ 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. +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 @@ -246,8 +247,8 @@ 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 +**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 @@ -255,29 +256,29 @@ $ 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 +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: +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) -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) +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. ##### [Using the Cryostat Agent](#using-the-cryostat-agent) -[The Cryostat Agent](/guides/#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. -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. +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), +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 @@ -321,9 +322,9 @@ 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. +**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**: +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 ... @@ -334,7 +335,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 Kubernetes 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 @@ -410,7 +411,7 @@ spec: More details about the configuration options for the **Cryostat Agent** [are available here](https://github.com/cryostatio/cryostat-agent/blob/{{site.data.versions.cryostat.release-branch}}/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 +**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: ``` @@ -426,7 +427,7 @@ 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 -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 @@ -450,7 +451,7 @@ spec: ``` 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. +and connect to this application **JMX** port. ```yaml apiVersion: v1 @@ -465,21 +466,21 @@ spec: ``` **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. +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. - - How to use Kubernetes `Service` configurations for discovery and JMX to expose data. + - 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 +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 `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). +the previous two sections on [using the **Cryostat Agent**](#using-the-cryostat-agent) and [using **JMX**](#using-jmx). Add dependency configurations to `pom.xml`: ```xml @@ -607,22 +608,22 @@ spec: ### [Alternate Setup](#alternate-setup) #### [Using ClusterCryostats](#using-clustercryostats) -In [Deploying Cryostat](#deploying-cryostat), you created a single-namespace **Cryostat** Custom Resource -(`CR`) instance. +In [Deploying **Cryostat**](#deploying-cryostat), you created a single-namespace **Cryostat** Custom Resource +(**CR**) instance. -Single-namespace **Cryostat CR\`s** instruct the Operator to deploy restricted **Cryostat** instances which are only able -to see target applications deployed in the same namespace as the **Cryostat** instance, which is the same Namespace that -the `CR` is created within. +Single-namespace **Cryostat CR\`s** instruct the **Operator** to deploy restricted **Cryostat** instances which are only able +to see target applications deployed in the same namespace as the **Cryostat** instance, which is the same `Namespace` that +the **CR** is created within. If you chose to install the **Operator** in **All Namespaces** mode as assumed in this guide, you may also be interested in creating **CluterCryostat CR\`s**. In this configuration, the **Operator** is able to see **Cryostat** and **ClusterCryostat -CR\`s** in any project (`Namespace`) and create **Cryostat** deployments corresponding to either `CR` kind in each of their +CR\`s** in any project (`Namespace`) and create **Cryostat** deployments corresponding to either **CR** kind in each of their respective **Namespaces**. Both of these **CRs** are **Namespace**-specific, and the **Namespace** is used to determine which **OpenShift** users are able to access the **Cryostat** instance. For more information, please see the following documents: - [Multi-namespace](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/multi-namespace.md). - [Authorization Properties](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#authorization-properties) -**ClusterCryostat CR\`s** instruct the Operator to deploy cross-namespace **Cryostat** instances. A **ClusterCryostat** has +**ClusterCryostat CR\`s** instruct the **Operator** to deploy cross-namespace **Cryostat** instances. A **ClusterCryostat** has an `installNamespace`, which is the namespace where the **Cryostat Deployment** will reside, and a list of `targetNamespaces`, which are all of the namespaces that the **Cryostat** server will watch for target applications. The `targetNamespaces` list does not necessarily need to contain the `installNamespace`, if you do not want **Cryostat** @@ -655,8 +656,8 @@ Now that you have installed and deployed **Cryostat** and know how to access its guides through various common actions and workflows. ## [Uninstalling Cryostat Operator](#uninstalling-cryostat-operator) -Reference [Operator Lifecycle Manager's](https://olm.operatorframework.io/docs/tasks/uninstall-operator/#combine-steps-2-and-3) -guide on uninstalling Operators. Please be sure to delete all **Cryostat** and **ClusterCryostat** Custom Resources before +Reference [**Operator** Lifecycle Manager's](https://olm.operatorframework.io/docs/tasks/uninstall-operator/#combine-steps-2-and-3) +guide on uninstalling **Operators**. Please be sure to delete all **Cryostat** and **ClusterCryostat** Custom Resources before uninstalling the **Cryostat Operator**. - If your **Cryostat Operator** was installed in **All Namespaces** mode, then its **ClusterServiceVersion** and `Subscription` can be found in the **Namespace** **openshift-operators**. From 46b76401d44714b2bd527e97d36e2c1083357cda Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Fri, 3 Nov 2023 16:27:43 -0400 Subject: [PATCH 3/7] fixed more inconsistencies --- 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 e0c63dea..6e593c87 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -28,7 +28,7 @@ do so unless cert-manager is unavailable AND one of the following applies to you ### [Install via OperatorHub](#install-via-operatorhub) See below for a summary of the installation steps from the **Cryostat Operator** page on [**OperatorHub**](https://operatorhub.io/cryostat-operator). For more details, visit [Installing the **Cryostat Operator** from OperatorHub](https://developers.redhat.com/articles/2022/01/20/install-cryostat-operator-kubernetes-operatorhubio#). -1. Install the **Operator** Lifecycle Manager **(OLM)**: +1. Install the Operator Lifecycle Manager **(OLM)**: Check if **OLM** is already installed: ```bash $ operator-sdk olm status @@ -70,9 +70,9 @@ Use the search bar to find the **Red Hat build of Cryostat** catalog item. image-name="`cryostat-operatorhub-install.png`" %} Choose your **Operator** installation mode: -1. In **All Namespaces** installation mode, the **Cryostat Operator** instance will watch for **Cryostat** or +1. In `All Namespaces` installation mode, the **Cryostat Operator** instance will watch for **Cryostat** or **ClusterCryostat** Custom Resources (**CR**s) created in any `Namespace` and create corresponding **Cryostat** instances. -2. In the **A specific namespace** installation mode, you must also select an installation `Namespace`, and the **Cryostat Operator** instance will only watch for **Cryostat** or **ClusterCryostat** instances created in that same `Namespace`. +2. In the `A specific namespace` installation mode, you must also select an installation `Namespace`, and the **Cryostat Operator** instance will only watch for **Cryostat** or **ClusterCryostat** instances created in that same `Namespace`. {% include howto_step.html summary="Install the Operator" image-name="cryostat-operatorhub-install-in-progress.png" @@ -93,7 +93,7 @@ Continue to [Setup](#setup). image-name="cryostat-operatorhub-install-complete.png" %} Once the installation is complete, click *Create Cryostat* to create a **Cryostat CR** instance in an **OpenShift -Project** (**Kubernetes** `Namespace`) of your choice. This provides configuration information for the **Operator** to know the +Project** (**Kubernetes Namespace**) of your choice. This provides configuration information for the **Operator** to know the specifics of how to deploy your **Cryostat** instance. For full details on how to configure the **Cryostat** deployment, see [Configuring **Cryostat**](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md). From 8eb2019181b7b91fd17b1884e54d1baedd4eb28a Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Mon, 6 Nov 2023 10:32:57 -0500 Subject: [PATCH 4/7] resolved issues --- get-started/index.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/get-started/index.md b/get-started/index.md index 6e593c87..a678b470 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -39,7 +39,7 @@ See below for a summary of the installation steps from the **Cryostat Operator** **If Operator Lifecycle Manager (OLM) and OperatorHub are already installed and available on your cluster, skip to Step 3:** - Install **Operator** Lifecycle Manager: + Install **OLM**: ```bash $ operator-sdk olm install @@ -176,7 +176,7 @@ $ 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** +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. @@ -202,7 +202,7 @@ 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 +requests using the `Authorization: Bearer` header. The token must be `base64` encoded. For example, ```bash $ curl -v -H "Authorization: Bearer $(oc whoami -t | base64)" https://cryostat.example.com:8181/api/v1/targets @@ -269,7 +269,7 @@ There are three methods of configuring your Java applications so that **Cryostat 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. +is built with **Maven**, packaged into an image with a `Dockerfile`, and running in **Kubernetes**, but the procedure will be similar for other toolchains and platforms as well. ##### [Using the Cryostat Agent](#using-the-cryostat-agent) @@ -334,7 +334,7 @@ COPY target/dependency/cryostat-agent.jar /deployments/app/ 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 .`. +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 Kubernetes registry, then modify your application `Deployment` to supply **JVM** system properties or environment variables configuring the **Cryostat Agent**: @@ -391,7 +391,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 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 +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**: @@ -611,19 +611,19 @@ spec: In [Deploying **Cryostat**](#deploying-cryostat), you created a single-namespace **Cryostat** Custom Resource (**CR**) instance. -Single-namespace **Cryostat CR\`s** instruct the **Operator** to deploy restricted **Cryostat** instances which are only able +Single-namespace **Cryostat CRs** instruct the **Operator** to deploy restricted **Cryostat** instances which are only able to see target applications deployed in the same namespace as the **Cryostat** instance, which is the same `Namespace` that the **CR** is created within. If you chose to install the **Operator** in **All Namespaces** mode as assumed in this guide, you may also be interested in -creating **CluterCryostat CR\`s**. In this configuration, the **Operator** is able to see **Cryostat** and **ClusterCryostat +creating **CluterCryostat CRs**. In this configuration, the **Operator** is able to see **Cryostat** and **ClusterCryostat CR\`s** in any project (`Namespace`) and create **Cryostat** deployments corresponding to either **CR** kind in each of their respective **Namespaces**. Both of these **CRs** are **Namespace**-specific, and the **Namespace** is used to determine which **OpenShift** users are able to access the **Cryostat** instance. For more information, please see the following documents: - [Multi-namespace](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/multi-namespace.md). - [Authorization Properties](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#authorization-properties) -**ClusterCryostat CR\`s** instruct the **Operator** to deploy cross-namespace **Cryostat** instances. A **ClusterCryostat** has +**ClusterCryostat CRs** instruct the **Operator** to deploy cross-namespace **Cryostat** instances. A **ClusterCryostat** has an `installNamespace`, which is the namespace where the **Cryostat Deployment** will reside, and a list of `targetNamespaces`, which are all of the namespaces that the **Cryostat** server will watch for target applications. The `targetNamespaces` list does not necessarily need to contain the `installNamespace`, if you do not want **Cryostat** @@ -656,7 +656,7 @@ Now that you have installed and deployed **Cryostat** and know how to access its guides through various common actions and workflows. ## [Uninstalling Cryostat Operator](#uninstalling-cryostat-operator) -Reference [**Operator** Lifecycle Manager's](https://olm.operatorframework.io/docs/tasks/uninstall-operator/#combine-steps-2-and-3) +Reference [**OLM**](https://olm.operatorframework.io/docs/tasks/uninstall-operator/#combine-steps-2-and-3) guide on uninstalling **Operators**. Please be sure to delete all **Cryostat** and **ClusterCryostat** Custom Resources before uninstalling the **Cryostat Operator**. - If your **Cryostat Operator** was installed in **All Namespaces** mode, then its **ClusterServiceVersion** and From 74cd6635690ea7f5d1aad49664c43a51a83a1894 Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Mon, 6 Nov 2023 11:56:54 -0500 Subject: [PATCH 5/7] correct link for configuring applications --- 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 a678b470..ce8f7884 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -249,7 +249,7 @@ auth implementation. 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). +applications, feel free to [continue to the next step](#configuring-applications). ```bash $ oc new-app --docker-image=quay.io/andrewazores/quarkus-test:0.0.10 From 7b8e636e7b45a728724670b43b81e788888b8d4c Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Mon, 6 Nov 2023 13:42:48 -0500 Subject: [PATCH 6/7] resolved more issues --- 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 ce8f7884..89a0cd45 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -15,7 +15,7 @@ Cryostat {{ site.data.versions.cryostat.version }} Follow the steps below to install the **Cryostat Operator** via [**OperatorHub**](https://operatorhub.io/operator/cryostat-operator). ### [Install cert-manager](#install-cert-manager) -The **Cryostat Operator** requires [cert-manager](https://cert-manager.io/) to run. +The **Cryostat Operator** requires [**cert-manager**](https://cert-manager.io/) to run. If not already installed in your cluster, please [install](https://cert-manager.io/docs/installation/) it using your preferred method. Once installed, proceed with the **Operator** installation steps below. @@ -67,7 +67,7 @@ packageserver-8cccc99dd-g7lkh 1/1 Running 0 3m3s Use the search bar to find the **Red Hat build of Cryostat** catalog item. {% include howto_step.html summary="Select the Cryostat Operator and click the Install button" - image-name="`cryostat-operatorhub-install.png`" + image-name="cryostat-operatorhub-install.png" %} Choose your **Operator** installation mode: 1. In `All Namespaces` installation mode, the **Cryostat Operator** instance will watch for **Cryostat** or @@ -335,7 +335,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 Kubernetes 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 From 5baa68b953488021feaf4bf0917fd7a9020e0f35 Mon Sep 17 00:00:00 2001 From: Atif Ali Date: Thu, 9 Nov 2023 12:59:04 -0500 Subject: [PATCH 7/7] resolved more issues --- 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 89a0cd45..4503e64a 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -20,8 +20,8 @@ If not already installed in your cluster, please [install](https://cert-manager.io/docs/installation/) it using your preferred method. Once installed, proceed with the **Operator** installation steps below. -**Warning**: Although it is possible to [disable cert-manager integration](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#disabling-cert-manager-integration), it is NOT recommended to -do so unless cert-manager is unavailable AND one of the following applies to you: +**Warning**: Although it is possible to [disable **cert-manager** integration](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#disabling-cert-manager-integration), it is NOT recommended to +do so unless **cert-manager** is unavailable AND one of the following applies to you: - You have another solution for encrypting traffic - You trust everything running in the same cluster where the **Cryostat Operator** is deployed @@ -617,7 +617,7 @@ the **CR** is created within. If you chose to install the **Operator** in **All Namespaces** mode as assumed in this guide, you may also be interested in creating **CluterCryostat CRs**. In this configuration, the **Operator** is able to see **Cryostat** and **ClusterCryostat -CR\`s** in any project (`Namespace`) and create **Cryostat** deployments corresponding to either **CR** kind in each of their +CRs** in any project (`Namespace`) and create **Cryostat** deployments corresponding to either **CR** kind in each of their respective **Namespaces**. Both of these **CRs** are **Namespace**-specific, and the **Namespace** is used to determine which **OpenShift** users are able to access the **Cryostat** instance. For more information, please see the following documents: - [Multi-namespace](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/multi-namespace.md).