diff --git a/get-started/index.md b/get-started/index.md index 9ae4eb0..74ab426 100644 --- a/get-started/index.md +++ b/get-started/index.md @@ -70,23 +70,16 @@ 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: -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`. +Click "*Install*" and wait for the installation to complete. {% 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**. 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**. - ### [Deploying Cryostat](#deploying-cryostat) {% include howto_step.html @@ -113,6 +106,10 @@ You can create the **CR** graphically in the **OperatorHub** UI after following summary="Cryostat Resources Before" image-name="cryostat-resources-before.png" %} +This is where you will configure your **Cryostat** installation. The **Target Namespaces** field is worth special attention. If you do not set this, +then the **Cryostat** instance will default to have visibility of other applications within its own (installation) **Namespace** only. By setting a +list of **Target Namespace** names you can create a Cryostat instance which has visibility of applications in other **Namespaces** in the cluster, +which may or may not include Cryostat's own installation **Namespace**. {% include howto_step.html summary="Cryostat Resource Creation" image-name="cryostat-resource-creation.png" @@ -125,13 +122,16 @@ You can create the **CR** graphically in the **OperatorHub** UI after following You can also create the **CR** manually using a **YAML** definition like the following: ```yaml -apiVersion: operator.cryostat.io/v1beta1 +apiVersion: operator.cryostat.io/v1beta2 kind: Cryostat metadata: name: cryostat-sample spec: - minimal: false enableCertManager: true + targetNamespaces: + - cryostat + - apps1 + - apps2 trustedCertSecrets: [] eventTemplates: [] storageOptions: @@ -192,14 +192,7 @@ access to the **Cryostat** instance and the namespace that it is deployed within 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. +redirected back to the **Cryostat web** application. 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 @@ -211,39 +204,16 @@ $ curl -v -H "Authorization: Bearer $(oc whoami -t)" https://cryostat.example.co ##### [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. +Access to the web application and the HTTP API will be unsecured. ###### [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: - -```properties -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. +The **Cryosotat Deployment** includes an `oauth2-proxy` instance which will pass through +all traffic by default, but by using the **Cryostat CR** +*Advanced > Authorization Options > Basic Auth* configuration property you can enable an +`HTTP Basic` authentication system. You will need to create a **Secret** containing an +`htpasswd` file defining the users that should be granted access, then reference this +**Secret** in the **CR** *Authorization Options*. ### [Deploy an Application](#deploy-an-application) For demo purposes, let's go ahead and deploy a sample application to our @@ -252,8 +222,8 @@ deployed **Cryostat** into a `namespace` where you are already running other 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 -$ oc patch svc/quarkus-test -p '{"spec":{"$setElementOrder/ports":[{"port":9097},{"port":8080}],"ports":[{"name":"jfr-jmx","port":9097}]}}' +$ oc new-app --image=quay.io/redhat-java-monitoring/quarkus-cryostat-agent:latest +$ oc patch svc/quarkus-cryostat-agent -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 @@ -355,14 +325,16 @@ spec: valueFrom: fieldRef: fieldPath: metadata.namespace - - name: CRYOSTAT_AGENT_BASEURI # 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 + # if it is not 'cryostat'. + - name: CRYOSTAT_INSTANCE_NAME + value: cryostat + - name: CRYOSTAT_AGENT_BASEURI + # 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: https://cryostat.$(NAMESPACE).svc.cluster.local:8181 + value: https://$(CRYOSTAT_INSTANCE_NAME).$(NAMESPACE).svc.cluster.local:4180 - name: CRYOSTAT_AGENT_API_WRITES_ENABLED # Set this to 'true' to turn on the "write" or "mutation" capabilities of the # Agent's HTTP API. This defaults to 'false', so the Agent HTTP API only exposes @@ -379,12 +351,23 @@ spec: # 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 an authentication token. For example, on OpenShift, - # do 'oc whoami --show-token' in your terminal to retrieve your user account's token. - # You may use this as the token that the Agent will pass to authorize itself - # with the Cryostat server. - - name: CRYOSTAT_AGENT_AUTHORIZATION - value: "Bearer abcd1234" + # This tells the Agent to look for its Kubernetes serviceaccount token mounted to + # its own Pod at the default filesystem path, and use the token there for Bearer + # Authorization to the Cryostat instance. This should be the correct behaviour in + # most scenarios and allows you to configure the serviceaccount's authorization by + # using standard Kubernetes RBAC for the application Pod's serviceaccount. + - name: CRYOSTAT_AGENT_AUTHORIZATION_TYPE + value: kubernetes + + # These two environment variables should not be set in a production environment. + # For development and testing it can be useful to disable TLS trust and hostname + # verification. In practice, you should provide the Agent with the Cryostat instance's + # TLS certificate so that the Agent can trust it and only establish connections to + # that trusted instance. Configuration of the Agent's TLS trust is covered elsewhere. + - name: CRYOSTAT_AGENT_WEBCLIENT_TLS_TRUST_ALL + value: "true" + - name: CRYOSTAT_AGENT_WEBCLIENT_TLS_VERIFY_HOSTNAME + value: "false" ports: - containerPort: 9977 protocol: TCP @@ -393,10 +376,9 @@ 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 -this purpose and replace `abcd1234` with the 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`. +Port number `9977` is the default HTTP port that the **Agent** exposes for its internal webserver that services **Cryostat** requests. +If this port number conflicts with another port used by your application, be sure to change both the `ports.containerPort` spec +as well as the `CRYOSTAT_AGENT_CALLBACK` environment variable. Finally, create a `Service` to enable **Cryostat** to make requests to this **Agent**: @@ -442,7 +424,7 @@ $ kubectl exec \ -i -t -- \ java -jar /tmp/cryostat/cryostat-agent-shaded.jar \ -Dcryostat.agent.baseuri=http://cryostat:8181 \ - -Dcryostat.agent.authorization="Bearer ${MY_AUTH_TOKEN}" \ + -Dcryostat.agent.authorization.type="kubernetes" \ -Dcryostat.agent.callback=http://${POD_IP}:9977 \ -Dcryostat.agent.api.writes-enabled=true ``` @@ -452,8 +434,7 @@ $ kubectl exec \ 3. Replace `mypod` with the name of your application's Pod 4. Replace `mycontainer` with the name of your application's container within its Pod (or remove this if it is the only container in the Pod) 5. Replace `http://cryostat:8181` with the correct internal Service URL for your **Cryostat** server within the same **Kubernetes** cluster -6. Replace `${MY_AUTH_TOKEN}` with your own **Kubernetes** auth token, or one belonging to a Service Account you have created for this purpose -7. Replace `${POD_IP}` with the application Pod's IP Address as found in its Status using `kubectl get -o yaml` +6. Replace `${POD_IP}` with the application Pod's IP Address as found in its Status using `kubectl get -o yaml` By following this procedure you will copy the **Cryostat Agent JAR** into the application's filesystem (`kubectl cp`), then launch the **Agent** as a Java process (`kubectl exec`). When the **Agent** is launched in this manner it will look for other Java processes. If it @@ -560,51 +541,6 @@ application. In this case you may wish to use the [**Cryostat Agent**](#using-th communications over **JMX** rather than HTTP. If you do use the **Cryostat Agent** for discovery and **JMX** for remote management, you may combine both of the `Service` definitions into a single `Service` with two exposed `ports`. -### [Alternate Setup](#alternate-setup) - -#### [Using ClusterCryostats](#using-clustercryostats) -In [Deploying **Cryostat**](#deploying-cryostat), you created a single-namespace **Cryostat** Custom Resource -(**CR**) instance. - -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 CRs**. In this configuration, the **Operator** is able to see **Cryostat** and **ClusterCryostat -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). -- [Authorization Properties](https://github.com/cryostatio/cryostat-operator/blob/{{site.data.versions.cryostat.release-branch}}/docs/config.md#authorization-properties) - -**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** -to see itself in the target applications that it watches. - -```yaml -apiVersion: operator.cryostat.io/v1beta1 -kind: ClusterCryostat -metadata: - name: clustercryostat-sample -spec: - enableCertManager: true - installNamespace: cryostat-testing - minimal: false - reportOptions: - resources: {} - storageOptions: - pvc: - spec: - resources: {} - targetNamespaces: - - cryostat-testing - - my-apps-a - - my-apps-b -``` - ## [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 @@ -612,9 +548,6 @@ guides through various common actions and workflows. ## [Uninstalling Cryostat Operator](#uninstalling-cryostat-operator) 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 -`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**. +- Delete all **Cryostat** Custom Resources before uninstalling the **Cryostat Operator**. +- The **Cryostat Operator**'s **ClusterServiceVersion** and `Subscription` can be found in the **Namespace** **openshift-operators**. diff --git a/images/cryostat-operatorhub-install-complete.png b/images/cryostat-operatorhub-install-complete.png index 6153932..ea8e18a 100644 Binary files a/images/cryostat-operatorhub-install-complete.png and b/images/cryostat-operatorhub-install-complete.png differ diff --git a/images/cryostat-operatorhub-install-in-progress.png b/images/cryostat-operatorhub-install-in-progress.png index e6961e4..164e835 100644 Binary files a/images/cryostat-operatorhub-install-in-progress.png and b/images/cryostat-operatorhub-install-in-progress.png differ diff --git a/images/cryostat-operatorhub-install.png b/images/cryostat-operatorhub-install.png index 63cb311..0537785 100644 Binary files a/images/cryostat-operatorhub-install.png and b/images/cryostat-operatorhub-install.png differ diff --git a/images/cryostat-operatorhub-search.png b/images/cryostat-operatorhub-search.png index c7931ae..fdf8102 100644 Binary files a/images/cryostat-operatorhub-search.png and b/images/cryostat-operatorhub-search.png differ diff --git a/images/cryostat-resource-creation.png b/images/cryostat-resource-creation.png index e24c647..64b3187 100644 Binary files a/images/cryostat-resource-creation.png and b/images/cryostat-resource-creation.png differ diff --git a/images/cryostat-resource-status.png b/images/cryostat-resource-status.png index ae6d3fa..cfd91cb 100644 Binary files a/images/cryostat-resource-status.png and b/images/cryostat-resource-status.png differ diff --git a/images/cryostat-resources-after.png b/images/cryostat-resources-after.png index b2e4b5a..24da15a 100644 Binary files a/images/cryostat-resources-after.png and b/images/cryostat-resources-after.png differ diff --git a/images/cryostat-resources-before.png b/images/cryostat-resources-before.png index d1fb932..e17b976 100644 Binary files a/images/cryostat-resources-before.png and b/images/cryostat-resources-before.png differ diff --git a/images/installed-operators.png b/images/installed-operators.png index b5734c0..fc84891 100644 Binary files a/images/installed-operators.png and b/images/installed-operators.png differ diff --git a/images/topology-view.png b/images/topology-view.png index 790baa8..c120f0a 100644 Binary files a/images/topology-view.png and b/images/topology-view.png differ