diff --git a/README.md b/README.md index 6ce5026..d8ac0fa 100644 --- a/README.md +++ b/README.md @@ -8,43 +8,18 @@ SusQL is a Kubernetes operator that aggregates energy data from pods tagged with SusQL is an operator that can be deployed in a Kubernetes/OpenShift cluster. You can use [kind](https://sigs.k8s.io/kind) or [minikube](https://minikube.sigs.k8s.io/) to get a local cluster for testing, or run against a remote cluster. -**NOTE:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows). ### Prerequisites -Kepler is assumed to be installed in the cluster. `helm`, `kubectl`, and `go` are also required to deploy. +Kepler is assumed to be installed in the cluster. ### Installation -To install SusQL go to the `deployment` directory and run the command `bash deploy.sh`. This script does a few actions: +Follow these instructions to install the SusQL Operator with Helm. +- [Installation with Helm](doc/helm-installation.md) +Follow these instructions to install the SusQL Operator from [OperatorHub.](https://operatorhub.io). +- [Installation with OperatorHub](doc/operatorhub-installation.md) -* Check if Kepler is installed and exposing metrics through Prometheus - * In general, Kepler metrics are exposed, clusterwide, at: - - ``` - http://..:9090 - ``` - - The deployment script assumes `PROMETHEUS_SERVICE=prometheus-k8s`, `PROMETHEUS_NAMESPACE=monitoring`, and `PROMETHEUS_DOMAIN=svc.cluster.local`. If this is not the case, use the deployment script as: - - ``` - $ PROMETHEUS_SERVICE= PROMETHEUS_NAMESPACE= PROMETHEUS_DOMAIN= bash deploy.sh - ``` - - Or for example, the following works for a 4.12 single node OpenShift local cluster: - - ``` - $ PROMETHEUS_PROTOCOL=https PROMETHEUS_PORT=9091 PROMETHEUS_NAMESPACE=openshift-monitoring PROMETHEUS_SERVICE=thanos-querier SUSQL_ENHANCED=true bash deploy.sh - ``` - -* Create the namespace `openshift-kepler-operator` - -* Install the SusQL operator in the namespace `openshift-kepler-operator` - * This installation also deploys the CRD and sets the cluster permissions - -* Install a separate Prometheus instance in the namespace `openshift-kepler-operator` - -**NOTE**: This set of ***actions*** can be controlled by calling `bash deploy.sh susql-deploy`, for example, if only the SusQL deployment is needed. Check the script for all possible options or run it with the default set of actions. ## Using SusQL diff --git a/doc/helm-installation.md b/doc/helm-installation.md new file mode 100644 index 0000000..b38b122 --- /dev/null +++ b/doc/helm-installation.md @@ -0,0 +1,81 @@ +# SusQL Operator Installation via Helm + +Instructions to install SusQL via Helm. + +**NOTE:** Your controller will automatically use the context in your kubeconfig file at the time of installation (i.e. whatever cluster `kubectl cluster-info` shows). + +### Prerequisites + +Kepler is assumed to be installed in the cluster. `helm`, `kubectl`, and `go` are also required to deploy. + +### Installation + +To install SusQL via Helm go to the `deployment` directory and run the command `bash deploy.sh`. This script does a few actions: + +* Check if Kepler is installed and exposing metrics through Prometheus + * In general, Kepler metrics are exposed, clusterwide, at: + + ``` + http://..:9090 + ``` + + The deployment script assumes `PROMETHEUS_SERVICE=prometheus-k8s`, `PROMETHEUS_NAMESPACE=monitoring`, and `PROMETHEUS_DOMAIN=svc.cluster.local`. If this is not the case, use the deployment script as: + + ``` + $ PROMETHEUS_SERVICE= PROMETHEUS_NAMESPACE= PROMETHEUS_DOMAIN= bash deploy.sh + ``` + + Or for example, the following works for a 4.12 single node OpenShift local cluster: + + ``` + $ PROMETHEUS_PROTOCOL=https PROMETHEUS_PORT=9091 PROMETHEUS_NAMESPACE=openshift-monitoring PROMETHEUS_SERVICE=thanos-querier SUSQL_ENHANCED=true bash deploy.sh + ``` + +* Create the namespace `openshift-kepler-operator` + +* Install the SusQL operator in the namespace `openshift-kepler-operator` + * This installation also deploys the CRD and sets the cluster permissions + +* Install a separate Prometheus instance in the namespace `openshift-kepler-operator` + +**NOTE**: This set of ***actions*** can be controlled by calling `bash deploy.sh susql-deploy`, for example, if only the SusQL deployment is needed. Check the script for all possible options or run it with the default set of actions. + +### Installation Configuration Options + +The following environment variables will influence the way that the SusQL Operator is installed via Helm. + +| Environment Variable | Default Value | Description | +|:---------------------------:|:-----------------------------:|:------------------------------------------------:| +| SUSQL_NAMESPACE | openshift-kepler-operator | namespace that SusQL resources run in | +| KEPLER_PROMETHEUS_NAMESPACE | openshift-monitoring | namespace that Kepler Prometheus runs in | +| PROMETHEUS_PROTOCOL | http | Either http or https for Kepler Prometheus access| +| PROMETHEUS_SERVICE | prometheus-k8s | service name for the Kepler Prometheus | +| PROMETHEUS_NAMESPACE | monitoring | namespace used by the Kepler Prometheus | +| PROMETHEUS_DOMAIN | svc.cluster.local | Domain used by the Kepler Prometheus | +| PROMETHEUS_PORT | 9090 | Port used by the Kepler Prometheus | +| KEPLER_PROMETHEUS_URL | http://prometheus-k8s.monitoring.svc.cluster.local:9090 | A shortcut to specify final Kepler Prometheus URL | +| KEPLER_METRIC_NAME | kepler_container_joules_total | Metric queried in the Kepler Prometheus | +| SUSQL_PROMETHEUS_URL | http://prometheus-susql.openshift-kepler-operator.svc.cluster.local:9090 | SusQL Prometheus URL | +| SUSQL_SAMPLING_RATE | 2 | Sampling rate in seconds | +| SUSQL_ENHANCED | | If set to any string, then use enhanced RBAC and SMON configuration | +| SUSQL_REGISTRY | quay.io/sustainable_computing_io | Container registry that SusQL is stored in | +| SUSQL_IMAGE_NAME | susql_operator | Image name used on SusQL container registry | +| SUSQL_IMAGE_TAG | latest | Tag for SusQL container | + + +## License + +Copyright 2024. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + diff --git a/doc/operatorhub-installation.md b/doc/operatorhub-installation.md new file mode 100644 index 0000000..4bca945 --- /dev/null +++ b/doc/operatorhub-installation.md @@ -0,0 +1,73 @@ +# SusQL Operator Installation via OperatorHub + +Installation of the SusQL Operator via OperatorHub is fairly easy. + +## Prerequisites + +Kepler is assumed to be installed in the cluster. `oc` is assumed to be installed, and you are assumed to be logged in to the cluster in your CLI environment. +Installation of the SusQL Operator has been extensively used with Red Hat OpenShift clusters 4.14 and higher. +Other flavors and versions of Kubernetes clusters are also expected to function. + +## Installation + +Create a file called `catalogsource.yaml` as follows: + +``` +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: operatorhubio-catalog + namespace: openshift-marketplace +spec: + sourceType: grpc + image: quay.io/operatorhubio/catalog:latest + displayName: Community Operators + publisher: OperatorHub.io + updateStrategy: + registryPoll: + interval: 10m +``` + +Apply this file with these commands: +``` +oc apply -f catalogsource.yaml +oc patch -n openshift-marketplace OperatorHub cluster --type merge -p '{"spec":{"sources":[{"name":"operatorhubio-catalog","disabled":false},{"name":"community-operators","disabled":false}]}}' +``` + +Next, use the OpenShift web console to install the SusQL Operator: +- Click on "Operator->OperatorHub" +- Search for "SusQL" +- Click on it, and follow the GUI prompts to install. + +# Post Install Customization + +After installation, click "Operators->Installed Operators->SusQL->YAML", then edit one of the values under =spec.install.spec.deployments.labels.spec.template.spec.containers.resources.env.name.values` and save the YAML file when finished. +The operator will automatically restart with the newly specified value(s). + +Currently the following variables can be modified. Searching directly for these variables may be more efficient than perusing the entire YAML. + +- `KEPLER-PROMETHEUS-URL` +- `KEPLER-METRIC-NAME` +- `SUSQL-PROMETHEUS-DATABASE-URL` +- `SUSQL-PROMETHEUS-METRICS-URL` +- `SAMPLING-RATE` +- `LEADER-ELECT` +- `HEALTH-PROBE-BIND-ADDRESS` +- `METRICS-BIND-ADDRESS` + +## License + +Copyright 2024. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +