From bed79e96dd2e843fcef2fac42ba4b349ffb8edf6 Mon Sep 17 00:00:00 2001 From: Kent Rancourt Date: Thu, 22 Jul 2021 14:10:47 -0400 Subject: [PATCH] update README with more accurate install instructions Signed-off-by: Kent Rancourt --- README.md | 123 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 97 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 5907287..6a69588 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Brigade Metrics: One-Step Monitoring for Brigade 2 +# Brigade Metrics: Monitoring for Brigade 2 Brigade Metrics adds monitoring capabilities to a Brigade 2 installation. It utilizes Brigade APIs to export time series metrics to Prometheus and makes @@ -9,52 +9,123 @@ development, as such, the same is true for this add-on component. ## Getting Started -Comprehensive documentation will become available in conjunction with a future -release. In the meantime, here is a little to get you started. +Follow these steps to get started. ### Prerequisites Since Brigade Metrics aggregates and exposes metrics for a running Brigade 2 -installation, an operation Brigade 2 beta installation is a prerequisite. Please -refer to -[Brigade 2's own getting started documentation](https://github.com/brigadecore/brigade/tree/v2). +installation, an operational Brigade 2 installation is a prerequisite. -Once Brigade 2 is up and running, create a service account, and give it `READ` -permissions: +Note that Brigade Metrics is only compatible with the _beta_ series of Brigade 2 +releases. + +If necessary, please refer to +[Brigade 2's own getting started documentation](https://github.com/brigadecore/brigade/tree/v2) +for guidance in fulfilling this dependency. + +Once Brigade 2 is operational, create a service account for use by Brigade +Metrics: ```console -$ brig sa create -i brigade-metrics -d brigade-metrics -$ brig role grant READER --service-account brigade-metrics +$ brig service-account create \ + --id brigade-metrics \ + --description "Used by Brigade Metrics" ``` -Save the service account token somewhere safe. +This command will display a token that Brigade Metrics can use for +authenticating to the Brigade 2 API server. Take note of this value. It will +be required in subsequent steps and cannot be retrieved later through any other +means. + +Now grant the service account global read permissions: + +```console +$ brig role grant READER --service-account brigade-metrics +``` ### Installing Brigade Metrics -Since this add-on is still very much a prototype, we're not currently publishing -a Helm chart anywhere. You will need to clone this repository to obtain the -chart and install. +For now, we're using the [GitHub Container Registry](https://ghcr.io) (which is +an [OCI registry](https://helm.sh/docs/topics/registries/)) to host our Helm +chart. Helm 3 has _experimental_ support for OCI registries. In the event that +the Helm 3 dependency proves troublesome for users, or in the event that this +experimental feature goes away, or isn't working like we'd hope, we will revisit +this choice before going GA. + +To install Brigade Metrics, begin by pulling the chart from GCR and exporting +it to some location on your local system. Here, we export it to `~/charts`: + +```console +$ export HELM_EXPERIMENTAL_OCI=1 +$ helm chart pull ghcr.io/brigadecore/brigade-metrics:v0.1.0 +$ helm chart export ghcr.io/brigadecore/brigade-metrics:v0.1.0 -d ~/charts +``` + +Use the following command to extract the full set of configuration options from +the chart. Here we're storing a copy at `~/brigade-metrics-values.yaml`: + +```console +$ helm inspect values ~/charts/brigade-metrics > ~/brigade-metrics-values.yaml +``` + +Edit the configuration (`~/brigade-metrics-values.yaml` in this example). At +minimum, you will need to make the following changes: -Once the repository is cloned, open the `values.yaml` file, and paste the -service account token into the `exporter.brigade.apiToken` field. +* Set the value of `exporter.brigade.apiAddress` to the address of your Brigade 2 + API server. This should utilize the _internal_ DNS hostname by which that API + server is reachable _within_ your Kubernetes cluster. This value is defaulted + to `https://brigade-apiserver.brigade.svc.cluster.local`, but may need to be + updated if you installed Brigade 2 in a different namespace. -There are two methods of authentication you can choose from for logging into Grafana. -1. Option to use Grafana's built in user management system. The username and password for the admin account are specified in the `grafana.auth` fields, and the admin can handle user management using the Grafana UI. -2. Option to use an nginx reverse proxy and a shared username/password to access Grafana in anonymous mode. +* Set the value of `exporter.brigade.apiToken` to the service account token that + was generated earlier. -For option 1, set `grafana.auth.proxy` to false in `values.yaml`, and true for option 2. +* Specify a username and password for the metrics dashboard (Grafana) by setting + values for `grafana.auth.username` and `grafana.auth.password`. -In addition, you have the option to enable tls or ingress for grafana, and both options can be configured in `values.yaml`. +Install Brigade Metrics, referencing your edited configuration: + +```console +$ helm install brigade-metrics ~/charts/brigade-metrics \ + --create-namespace \ + --namespace brigade-metrics \ + --values ~/brigade-metrics-values.yaml +``` -Save the file, and run `make hack` from the project's root directory. +### Accessing the Dashboard -Once all three pods of the project are up and running, run the following command to expose the Grafana frontend: +Use the following command to determine when the dashboard (Grafana) is ready: ```console -$ kubectl port-forward service/brigade-metrics-grafana 3000:<80 (tls disabled), 443 (tls enabled)> -n brigade-metrics +$ kubectl get deployment brigade-metrics-grafana --namespace brigade-metrics ``` -Enter your supplied credentials. You can now access the Grafana dashboard! +If you deployed Brigade Metrics on a public cloud _and_ kept the default service +type of `LoadBalancer` for the dashboard, then use the following command to +determine when your dashboard has been assigned a public IP: + +```console +$ kubectl get service brigade-metrics-grafana --namespace brigade-metrics +``` + +The dashboard should be accessible at the public IP using HTTPS. If you used +the default, auto-generated certificate, expect to receive a cert warning. + +If you deployed Brigade Metrics on a local cluster or changed the service type +for the dashboard to something like `ClusterIP`, then use port forwarding to +access the dashboard: + +```console +$ kubectl port-forward \ + service/brigade-metrics-grafana \ + --namespace brigade-metrics \ + 8443:443 +``` + +The dashboard should be accessible at `https://localhost:8443`. Expect to +receive a cert warning. + +Log in using the username and password you selected in the previous section. ## Contributing @@ -68,4 +139,4 @@ We have a slack channel! [Kubernetes/#brigade](https://kubernetes.slack.com/messages/C87MF1RFD) Feel free to join for any support questions or feedback, we are happy to help. To report an issue or to request a feature open an issue -[here](https://github.com/brigadecore/brigade/issues) +[here](https://github.com/brigadecore/brigade-metrics/issues)