Updated README.md

kcantrel · kcantrel · commit 8074547f92d7 · 2025-03-28T17:05:22.000-05:00
diff --git a/Monitoring/monitor_fsxn_with_harvest_on_eks/README.md b/Monitoring/monitor_fsxn_with_harvest_on_eks/README.md
@@ -3,7 +3,7 @@
 This subfolder contains a Helm chart to install [NetApp Harvest](https://github.com/NetApp/harvest/blob/main/README.md)
 into an AWS EKS cluster to monitor multiple FSx for ONTAP file systems using the
 Grafana + Prometheus stack. It uses the AWS Secrets Manager to obtain
-credentials for echo of the FSxN file systems so those credentials aren't insecurely stored.
+credentials for each of the FSxN file systems so those credentials aren't insecurely stored.
 
 ## Introduction
 
@@ -15,27 +15,28 @@ Harvest Helm chart installation will result the following:
 * Collecting metrics about your FSxNs and adding existing Grafana dashboards for better visualization.
 
 ### Integration with AWS Secrets Manager
-This Harvest installation uses the AWS Secrets Manager to obtain the credentials for the echo of FSxN file systems.
+This Harvest installation uses the AWS Secrets Manager to obtain the credentials for the each of FSxN file systems.
 The format of the secret string should to be a json structure with a `username` and `password` keys. For example:
 ```json
 {
   "username": "fsxadmin",
   "password": "fsxadmin-password"
 }
 ```
-A service account should be created during the installation with the sufficient permissions to fetch the secrets.
+A service account should be created during the installation of Harvest with the sufficient permissions to fetch the secrets.
 
 ### Prerequisites
 * `Helm` - for resources installation.
 * `kubectl` - for managing Kubernetes resources.
 * `eksctl` - for creating and managing EKS clusters.
+* `jq` - for parsing JSON data in the command line. This is optional but recommended for some of the commands below.
 * An FSx for ONTAP file system deployed in the same VPC as the EKS cluster.
 
 ## Deployment
 
 ### Deployment of Prometheus and Grafana
 If you don't already have Prometheus and Grafana running in your EKS cluster, you can deploy both of them
-from the Prometheus community repository by using the following commands:
+using the Helm chart from the Prometheus community repository by using the following commands:
 
 :memo: **NOTE:** You need to make a substitution in the command below before running it.
 ```bash
@@ -87,9 +88,13 @@ prometheus-kube-prometheus-stack-prometheus-0               2/2     Running   0
 ### Deployment of the Harvest Helm chart
 
 #### 1. Download the Harvest Helm chart
-Download the Harvest helm chart by copying the contents of the 'harvest' directory found in this repo. Put the contents in an empty directory.
-
-The custom Helm chart includes:
+Download the Harvest helm chart by copying the contents of the 'harvest' directory found in this repo. The easiest
+way to do that, is to simply clone the entire repo and change into the `harvest` directory:
+```bash
+git clone https://github.com/NetApp/FSx-ONTAP-samples-scripts.git
+cd FSx-ONTAP-samples-scripts/Monitoring/monitor_fsxn_with_harvest_on_eks/harvest
+```
+This custom Helm chart includes:
 * `deplyment.yaml` - Harvest deployment using Harvest latest version image
 * `harvest-config.yaml` - Harvest backend configuration
 * `harvest-cm.yaml` -  Environment variables configuration for credentials script.
@@ -117,27 +122,20 @@ fsxs:
 ```
 Of course replace the strings within the <> with your own values.
 
-:memo: **NOTE:** Each FSxN cluster should have unique port number for promPort.
+:memo: **NOTE:** Each FSxN cluster must have unique port number for promPort between the range of 12990 and 14000.
 
-#### 3. Create a namespace
-
-If you don't already have a namespace where you want to deploy Harvest, you can create one using the following command:
-```
-kubectl create ns <NAMESPACE>
-```
-
-#### 4. Create AWS Secrets Manager for FSxN credentials
+#### 3. Create AWS Secrets Manager for FSxN credentials
 If you don't already have an AWS Secrets Manager secret with your FSxN credentials, you can create one using the AWS CLI.
 ```
 aws secretsmanager create-secret --region <REGION> --name <SECRET_NAME> \
   --secret-string '{"USERNAME":"fsxadmin", "PASSWORD":"<YOUR_FSX_PASSWORD>"}'
 ```
 Replace `<YOUR_FSX_PASSWORD>` with the actual password for the `fsxadmin` user on your FSxN file system.
 
-#### 5. Create Service Account with permissions to read the AWS Secrets Manager secrets
+#### 4. Create Service Account with permissions to read the AWS Secrets Manager secrets
 
-##### 5a. Create Policy
-The following IAM policy can be used to grant the all permissions required by Harvest to fetch the secrets.
+##### 4a. Create Policy
+The following IAM policy can be used to grant the all the permissions required by Harvest to fetch the secrets.
 Note in this example, it has places to put two AWS Secrets Manager ARNs. You should add all the secret ARNs
 for all the FSxN you plan to monitor. Typically on per FSxN, but it is okay to use the same secret for multiple
 FSxNs as long as the credentials are the same.
@@ -161,7 +159,7 @@ FSxNs as long as the credentials are the same.
     "Version": "2012-10-17"
 }
 ```
-Of course replace the strings within the <> with your own values.
+Of course replace the strings within the <> with your own values. Save the edited policy in a file named `harvest-read-secrets-policy.json`.
 
 You can use the following command to create the policy:
 ```bash
@@ -170,24 +168,28 @@ POLICY_ARN=$(aws iam create-policy --policy-name harvest_read_secrets --policy-d
 Note that this sets a variable named `POLICY_ARN` to the ARN of the policy that is created.
 It is done this way to make it easy to pass that policy ARN when you create the service account in the next step.
 
-##### 5b. Create ServiceAccount
+##### 4b. Create ServiceAccount
 The following command will create a role, associated with the policy created above, and an Kubernettes service account that Harvest will run under:
 ```
 eksctl create iamserviceaccount --name harvest-sa --region=<REGION> --namespace <NAMESPACE> --role-name harvest-role --cluster <YOUR_CLUSTER_NAME> --attach-policy-arn "$POLICY_ARN" --approve
 ```
-Of course replace the strings within the <> with your own values.
+Of course replace all the strings within the <> with your own values. Note that the <NAMESPACE> should
+be where your Prometheus stack is deployed. If you used the command above to install Prometheus
+then the namespace should be `prometheus`.
 
-#### 6. Install Harvest helm chart
-Once you have update the values.yaml file, created the namespace, created the AWS Secrets Manager secrets,
-and created the service account with permissions to read the secrets, you are ready to install the Harvest Helm chart.
+#### 5. Install Harvest helm chart
+Once you have update the values.yaml file, created the AWS Secrets Manager secrets,
+and created the service account with permissions to read the secrets, you are ready to install the Harvest Helm chart
+by running:
 ```text
 helm upgrade --install harvest  -f values.yaml ./ --namespace=<NAMESPACE> --set promethues=<your_promethues_release_name>
 ```
-Where `<NAMESPACE>` is the name of the namespace you created or are using for Harvest and `<your_promethues_release_name>`
-is the name of your Prometheus release (e.g. `kube-prometheus-stack` if you followed the previous steps).
+Note that the <NAMESPACE> should be where your Prometheus stack is deployed. If you used the command above to install Prometheus
+then it will be `prometheus`.
 
 Once the deployment is complete, Harvest should be listed as a target on Prometheus. You can check that by running
-the following command:
+the following commands. The first one sets up a port forwarder for port 9090 on your local machine to the Prometheus server running
+in the EKS cluster as a background job.
 ```bash
 kubectl port-forward -n prometheus prometheus-kube-prometheus-stack-prometheus-0 9090 &
 curl -s http://localhost:9090/api/v1/targets | jq -r '.data.activeTargets[] | select(.labels.service[0:14] == "harvest-poller") | "\(.labels.service) Status = \(.health)"'
@@ -205,14 +207,15 @@ Once you have obtain the status, you don't need the "kubctl port-forward" comman
 ```bash
 kill %?9090
 ```
+That kills any background job that has 9090 in the command line, which the port forwarding command should have.
 
-#### Import FSxN CloudWatch metrics into your monitoring stack using YACE
+### Import FSxN CloudWatch metrics into your monitoring stack using YACE
 AWS CloudWatch provides metrics for the FSx for ONTAP file systems which cannot be collected by Harvest.
-Therefore, we recommend to use yet-another-exporter (by Prometheus community) for collecting these metrics.
-See [YACE](https://github.com/nerdswords/helm-charts) for more information.
+Therefore, we recommend to using the [yet-another-cloudwatch-exporter](https://github.com/prometheus-community/yet-another-cloudwatch-exporter)
+(by Prometheus community) for collecting these metrics.
 
-##### 1. Create ServiceAccount with permissions to AWS CloudWatch
-The following IAM policy can be used to grant the all permissions required by yet-another-exporter to fetch the CloudWatch metrics:
+#### 1. Create Service Account with permissions to get AWS CloudWatch metrics
+The following IAM policy can be used to grant the all permissions required by YACE to fetch the CloudWatch metrics:
 
 ```
 {
@@ -242,27 +245,31 @@ The following IAM policy can be used to grant the all permissions required by ye
   }
 
 ```
-Run the following command in order to create the policy:
-
+The policy shown above is in a file named `yace-export-policy.json` in the repo. You shouldn't
+have to modify the file so just run the following command in order to create the policy:
+```bash
 POLICY_ARN=$(aws iam create-policy --policy-name yace-exporter-policy --policy-document file://yace-exporter-policy.json --query Policy.Arn --output text)
+```
 Note that this sets a variable named `POLICY_ARN` to the ARN of the policy that is created.
 It is done this way to make it easy to pass that policy ARN when you create the service account in the next step.
 
-##### 2. Create ServiceAccount
+#### 2. Create the service account
 The following command will create a role associated with the policy created above, and a Kubernetes service account that YACE will run under:
 
 ```bash
 eksctl create iamserviceaccount --name yace-exporter-sa --region=<REGION> --namespace <NAMESPACE> --role-name yace-cloudwatch-exporter-role --cluster <YOUR_CLUSTER_NAME> --attach-policy-arn "$POLICY_ARN" --approve
 ```
-Of course replace the strings within the <> with your own values.
+Of course replace the strings within the <> with your own values. Note, the overrides file below assumes the account
+name is `yace-exporter-sa` so if you change it, you will need to update the overrides file accordingly.
 
-##### 3. Install yace-exporter helm chart
+#### 3. Install yace-exporter helm chart
 First add the nerdswords Helm repository to your local Helm client. This repository contains the YACE exporter chart.
 
 ```bash
 helm repo add nerdswords https://nerdswords.github.io/helm-charts
+helm repo update
 ```
-Edit the yace-override-values.yaml file by changing the prometheus release name for ServiceMonitor section:
+Edit the `yace-override-values.yaml` file found in this repo by changing the prometheus release name in the ServiceMonitor section:
 ```
 serviceMonitor:
   enabled: true
@@ -271,7 +278,7 @@ serviceMonitor:
 ```
 If you installed Prometheus using the previous steps, the release name will be `kube-prometheus-stack`.
 
-Also update the region name, in both places, to FSxN's region:
+While editing that file, also update the region name, in both places, to FSxN's region in the "config" section:
 ```
   apiVersion: v1alpha1
   sts-region: <Region_Name>
@@ -303,6 +310,7 @@ Finally, run the following command to install the yace-exporter helm chart:
 ```text
 helm install yace-cw-exporter --namespace <NAMESPACE> nerdswords/yet-another-cloudwatch-exporter -f yace-override-values.yaml
 ```
+Of course replace the strings within the <> with your own values.
 
 ### Accessing Grafana
 If you newly installed the Prometheus stack, that includes Grafana, you will need to provide a way of accessing it from the Kubernetes cluster.
@@ -338,16 +346,16 @@ Once you have access to Grafana, you can log in using the default credentials:
 Once you login, you'll want to import some dashboards to visualize the metrics collected by Harvest and YACE. You will find
 some example dashboards in the `dashboards` folder in this repository. You can import these dashboards into Grafana by following these steps:
 1. Log in to your Grafana instance.
-2. Click on the "+" icon on the left-hand side menu and select "Import".
-3. In the "Import via file" section, click on "Upload .json file" and select one of the dashboard JSON files from the `dashboards` folder in this repository.
-4. Once the file is uploaded, Grafana will show a preview of the dashboard. You can change the dashboard name if you want.
-5. Click on the "Import" button to import the dashboard.
-6. After importing the dashboard, you can view it by clicking on the dashboard name in the left-hand side menu.
-7. You can repeat the above steps for each of the dashboard JSON files you want to import.
+2. Click on the "+" icon on the left-hand side menu and select "Import Dashboard".
+3. Click in the box with "Upload dashboard JSON file" and browse to one of the dashboard JSON files from the `dashboards` folder in this repository.
+4. Click "Import."
+
+You can repeat the steps above for each of the dashboard JSON files you want to import.
 
 You can also import the "default" dashboards from the Harvest repo found [here](https://github.com/NetApp/harvest/tree/main/grafana/dashboards).
-Only consider the dashboards in the 'cmode' and 'cmode-details' directories. 
-:memo:**NOTE:** Since the special 'fsxadmin' account doesn't have access to all the metrics that a traditional 'admin' account would have,
+Only consider the dashboards in the `cmode` and `cmode-details` directories. 
+
+:memo: **NOTE:** Since the special 'fsxadmin' account doesn't have access to all the metrics that a traditional 'admin' account would have,
 some of the metrics and dashboards may not be fully applicable or available. The ones with 'fsx' tag are more relevant for FSxN.
 
 ## Author Information
