forked from cryostatio/cryostat-operator
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.md
206 lines (164 loc) · 11.9 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
# cryostat-operator
[](https://github.com/cryostatio/cryostat-operator/actions/workflows/build-ci.yml)
[](https://github.com/cryostatio/cryostat-operator/actions/workflows/test-ci-push.yml)
[](https://groups.google.com/g/cryostat-development)
A Kubernetes Operator to automate deployment of
[Cryostat](https://github.com/cryostatio/cryostat).
## SEE ALSO
* [cryostat-core](https://github.com/cryostatio/cryostat-core) for
the core library providing a convenience wrapper and headless stubs for use of
JFR using JDK Mission Control internals.
* [cryostat](https://github.com/cryostatio/cryostat) for the main API
backend to detect JVMs and manage JFR.
* [cryostat-web](https://github.com/cryostatio/cryostat-web) for the React
graphical frontend included as a submodule in Cryostat and built into
Cryostat's OCI images.
* [jfr-datasource](https://github.com/cryostatio/jfr-datasource) for
the JFR datasource for Grafana.
* [cryostat-grafana-dashboard](https://github.com/cryostatio/cryostat-grafana-dashboard)
for the Grafana dashboard.
# Using
Once deployed, the `cryostat` instance can be accessed via web browser
at the URL provided by:
```
kubectl get cryostat -o jsonpath='{$.items[0].status.applicationUrl}'
```
The JMX authentication credentials for Cryostat itself can be obtained with:
```shell
CRYOSTAT_NAME=$(kubectl get cryostat -o jsonpath='{$.items[0].metadata.name}')
# Username
kubectl get secret ${CRYOSTAT_NAME}-jmx-auth -o jsonpath='{$.data.CRYOSTAT_RJMX_USER}' | base64 -d
# Password
kubectl get secret ${CRYOSTAT_NAME}-jmx-auth -o jsonpath='{$.data.CRYOSTAT_RJMX_PASS}' | base64 -d
```
# Building
## Requirements
- `go` v1.21
- [`operator-sdk`](https://github.com/operator-framework/operator-sdk) v1.31.0
- [`cert-manager`](https://github.com/cert-manager/cert-manager) v1.11.5+ (Recommended)
- `podman` or `docker`
- [`jq`](https://stedolan.github.io/jq/) v1.6+
- `ginkgo` (Optional)
## Instructions
`make generate manifests manager` will trigger code/YAML generation and compile
the operator controller manager, along with running some code quality checks.
`make oci-build` will build an OCI image from the generated YAML and compiled
binary to the local registry, tagged as
`quay.io/crystatio/cryostat-operator`. This tag can be overridden by
setting the environment variables `IMAGE_NAMESPACE` and `OPERATOR_NAME`.
`IMAGE_VERSION` can also be set to override the tagged version.
`make bundle` will create an OLM bundle. This will generate a CSV, CRDs and
other manifests, and other required configurations for an OLM bundle versioned
with version `$IMAGE_VERSION` in the `bundle/` directory. `make bundle-build`
will create an OCI image of this bundle, which can then be pushed to an image
repository such as `quay.io`.
`make catalog-build` will build an OCI image of the operator catalog (i.e. index)
with version `$IMAGE_VERSION` that includes the bundle image of the same version.
# Setup / Deployment
## Bundle Deployment
The operator can be deployed using OLM using `make deploy_bundle`. This will
deploy `quay.io/cryostat/cryostat-operator-bundle:$IMAGE_VERSION` to
your configured cluster using `oc` or `kubectl` (`kubeconfig`). You can set the
variables `IMAGE_NAMESPACE` or `IMAGE_VERSION` to deploy different builds of
the bundle. Once this is complete, the Cryostat Operator will be deployed
and running in your cluster.
### Configuration
Once deployed, the operator deployment will be active in the cluster, but no
Cryostat instance will be created. To trigger its creation, add a
Cryostat CR using the UI for operator "provided APIs". Full details on the
configuration options in the Cryostat CRD can be found in
[Configuring Cryostat](docs/config.md). When running on Kubernetes, see
[Network Options](docs/config.md#network-options) for additional
mandatory configuration in order to access Cryostat outside of the cluster.
For convenience, a full deployment can be created using
`kubectl create -f config/samples/operator_v1beta1_cryostat.yaml`, or more
simply, `make create_cryostat_cr`.
The container images used by the operator for the core application,
jfr-datasource, and the Grafana dashboard can be overridden by setting the
`RELATED_IMAGE_CORE`, `RELATED_IMAGE_DATASOURCE`, and `RELATED_IMAGE_GRAFANA`
environment variables, respectively, in the operator deployment.
## Security
By default, the operator expects cert-manager to be available in the cluster.
This allows the operator to deploy Cryostat with all communication
between its internal services done over HTTPS. If you wish to disable this
feature and not use cert-manager, you can set the environment variable
`DISABLE_SERVICE_TLS=true` when you deploy the operator. We provide
`make cert_manager` and `make remove_cert_manager` targets to easily
install/remove cert-manager from your cluster.
### User Authentication
Users can use `oc whoami --show-token | base64` to retrieve their encoded OpenShift OAuth token
for the currently logged in user account. This encoded token can be used when directly
interacting with the deployed Cryostat instance(s).
When using the web-client, users can login with their username and password associated with their OpenShift account. User credentials will be remembered for the duration of the session.
If the current user account does not have sufficient permissions to list
routes, list endpoints, or perform other actions that Cryostat requires,
then the user may also try to authenticate using the Operator's service
account. This, of course, assumes that the user has permission to view this
service account's secrets.
`oc get secrets | grep cryostat-operator-service-account-token` will provide at least one
such operator service account token secret name which can be used - for
example, `cryostat-operator-service-account-token-7tt7l`. The token can then be retrieved
for use in authenticating as the operator service account:
```
$ oc describe secret cryostat-operator-service-account-token-7tt7l
Name: cryostat-operator-service-account-token-7tt7l
Namespace: default
Labels: <none>
Annotations: kubernetes.io/created-by: openshift.io/create-dockercfg-secrets
kubernetes.io/service-account.name: cryostat-operator-service-account
kubernetes.io/service-account.uid: 692aa8c7-081e-4a51-9355-be3eaa8f9fa6
Type: kubernetes.io/service-account-token
Data
====
ca.crt: 7209 bytes
namespace: 7 bytes
service-ca.crt: 8422 bytes
token: eyJhbGciOiJSUzI1NiIsImtpZCI6IkhYZC13eDdGVGwyQzdGNVpZVndScEZ2VmRxWTlzbnBUUG9HRkJpejJkV3cifQ.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJkZWZhdWx0Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZWNyZXQubmFtZSI6ImNyeW9zdGF0LW9wZXJhdG9yLXNlcnZpY2UtYWNjb3VudC10b2tlbi03dHQ3bCIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VydmljZS1hY2NvdW50Lm5hbWUiOiJjcnlvc3RhdC1vcGVyYXRvci1zZXJ2aWNlLWFjY291bnQiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC51aWQiOiI2OTJhYThjNy0wODFlLTRhNTEtOTM1NS1iZTNlYWE4ZjlmYTYiLCJzdWIiOiJzeXN0ZW06c2VydmljZWFjY291bnQ6ZGVmYXVsdDpjcnlvc3RhdC1vcGVyYXRvci1zZXJ2aWNlLWFjY291bnQifQ.M7C1V0bN3aILBflO7TTOTikw7wLGRJ79-OkCDQIZbu71QLdX05jyCxxtlH32lr8jz6HwxfXXweh3ifG_2lbe7_TbM8jxmBoMdLuc4Q_akpmA-GQuDPrRxfHGJApYGQ6CVug3KHSrQwj2M4QrSUz7FoeQGaOH9BnWj1TrHGmOZUPJ6u7JSu2OwoLBda6rF-M4Bl72DmkyMAzikreRgPEk4D7gTCY0yNvsQDuUAwpFwmEukRC2WyTAVTpKPgThZUk-UJ-dXufbhAcqIRt6jeCQ19_Bo0zXc_ELgQydxuTack1ndT3HwRmwwNuZDFv-G3Y0YdjfRh00DqEvSn9ynZzwueDCJUxlHdznytfUWk9PA712JENpFC7b-zSHnjymIcFeUd8s_Zq_-JKrDIPnH0oZDRO_MUpKEC7Jz_8SeFJHLLGfBZt_aP4VwQHEUThiFQPwrfbd8tppUG2TKcekPScKcauy-BCI52odBzapP6meilMQVrmRtu7i30L05vgQiST_OsmSP8CuKW13a-leCCtN_aNQGqlWvLhP81H95ui-PvMzwMIDlfDZ03ycuYg4R4eUG3nUq7-42wrSdFLo8gm9wsl7y1ZRMQwHR1DCVBbHYS0iFOcmwto2Ejlrgvn3Cs0pDS7pDVoFkH2FsTopEw3jXtnkMs15mSmBnHz-UjF-l08
```
or more briefly:
```
$ oc get -o jsonpath='{.data.token}' secret cryostat-operator-service-account-token-7tt7l | base64 -d
eyJhbGciOiJSUzI1NiIsImtpZCI6IkhYZC13eDdGVGwyQzdGNVpZVndScEZ2VmRxWTlzbnBUUG9HRkJpejJkV3cifQ.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJkZWZhdWx0Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZWNyZXQubmFtZSI6ImNyeW9zdGF0LW9wZXJhdG9yLXNlcnZpY2UtYWNjb3VudC10b2tlbi03dHQ3bCIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VydmljZS1hY2NvdW50Lm5hbWUiOiJjcnlvc3RhdC1vcGVyYXRvci1zZXJ2aWNlLWFjY291bnQiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC51aWQiOiI2OTJhYThjNy0wODFlLTRhNTEtOTM1NS1iZTNlYWE4ZjlmYTYiLCJzdWIiOiJzeXN0ZW06c2VydmljZWFjY291bnQ6ZGVmYXVsdDpjcnlvc3RhdC1vcGVyYXRvci1zZXJ2aWNlLWFjY291bnQifQ.M7C1V0bN3aILBflO7TTOTikw7wLGRJ79-OkCDQIZbu71QLdX05jyCxxtlH32lr8jz6HwxfXXweh3ifG_2lbe7_TbM8jxmBoMdLuc4Q_akpmA-GQuDPrRxfHGJApYGQ6CVug3KHSrQwj2M4QrSUz7FoeQGaOH9BnWj1TrHGmOZUPJ6u7JSu2OwoLBda6rF-M4Bl72DmkyMAzikreRgPEk4D7gTCY0yNvsQDuUAwpFwmEukRC2WyTAVTpKPgThZUk-UJ-dXufbhAcqIRt6jeCQ19_Bo0zXc_ELgQydxuTack1ndT3HwRmwwNuZDFv-G3Y0YdjfRh00DqEvSn9ynZzwueDCJUxlHdznytfUWk9PA712JENpFC7b-zSHnjymIcFeUd8s_Zq_-JKrDIPnH0oZDRO_MUpKEC7Jz_8SeFJHLLGfBZt_aP4VwQHEUThiFQPwrfbd8tppUG2TKcekPScKcauy-BCI52odBzapP6meilMQVrmRtu7i30L05vgQiST_OsmSP8CuKW13a-leCCtN_aNQGqlWvLhP81H95ui-PvMzwMIDlfDZ03ycuYg4R4eUG3nUq7-42wrSdFLo8gm9wsl7y1ZRMQwHR1DCVBbHYS0iFOcmwto2Ejlrgvn3Cs0pDS7pDVoFkH2FsTopEw3jXtnkMs15mSmBnHz-UjF-l08
```
## Manual Deployment
`make install` will create CustomResourceDefinitions and do other setup
required to prepare the cluster for deploying the operator, using `oc` or
`kubectl` on whichever OpenShift cluster is configured with the local client.
`make uninstall` destroys the CRDs and undoes the setup.
`make deploy` will deploy the operator in the default namespace
(`cryostat-operator-system`). `make DEPLOY_NAMESPACE=foo-namespace deploy`
can be used to deploy to an arbitrary namespace named `foo-namespace`. For
a convenient shorthand, use
`make DEPLOY_NAMESPACE=$(kubectl config view --minify -o 'jsonpath={.contexts[0].context.namespace}') deploy`
to deploy to the currently active OpenShift project namespace.
`make undeploy` will likewise remove the operator, and also uses the
`DEPLOY_NAMESPACE` variable.
This also respects the `IMAGE_TAG` environment variable, so that different
versions of the operator can be easily deployed.
`make run` can be used to run the operator controller manager as a process on
your local development machine and observing/interacting with your cluster.
This may be useful in some development scenarios, however in this case the
operator process will not have access to certain in-cluster resources such as
environment variables or service account token files.
# Development
An invocation like
`export IMAGE_NAMESPACE=quay.io/some-user` `export IMAGE_VERSION=test-version`
`make generate manifests manager oci-build bundle bundle-build`
`podman image prune -f && podman push $IMAGE_NAMESPACE/cryostat-operator:$IMAGE_VERSION && podman push $IMAGE_NAMESPACE/cryostat-operator-bundle:$IMAGE_VERSION`
`make deploy_bundle`
is handy for local development testing using ex. CodeReady Containers. This
exercises a similar build and deployment path as what end users using OLM and
OperatorHub will eventually receive.
# Testing
## Requirements
- (optional) [oc](https://www.okd.io/download.html)
- (optional) [crc](https://github.com/code-ready/crc)
## Instructions
`make test-envtest` will run controller tests using ginkgo if installed, or go test if
not, requiring no cluster connection.
`make test-scorecard` will run the Operator SDK's scorecard test suite. This requires a
Kubernetes or OpenShift cluster to be available and logged in with your `kubectl` or `oc`
client. The recommended setup for development testing is CodeReady Containers (`crc`).
Before the scorecard tests are run, all cryostat and cryostat-operator
resources will be deleted to ensure a clean slate.
`make test` will run all tests.