From 05f08d8ca480dafd4eef3194dac4833ecb7ef373 Mon Sep 17 00:00:00 2001 From: James Laing <102221031+james-laing@users.noreply.github.com> Date: Thu, 2 Nov 2023 21:27:48 +0000 Subject: [PATCH 1/9] Create deployment.md --- extra/deployment.md | 326 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 326 insertions(+) create mode 100644 extra/deployment.md diff --git a/extra/deployment.md b/extra/deployment.md new file mode 100644 index 0000000..4a44c51 --- /dev/null +++ b/extra/deployment.md @@ -0,0 +1,326 @@ +# Example deployment methods + +There are a number of methods to deploy the OpenMetrics exporter depending on your environment. +- Container Deployment (such as Docker) + - Default - http passing API token with query + - Tokens - http with API tokens file embedded in exporter + - TLS - https passing API token with query +- Executable Binary Deployment + - Default - http passing API token with query + - Tokens - http with API tokens file embedded in exporter + - TLS - https passing API token with query + +# Prerequisites +All deployments will require an API token to authenticate with the array. Read-only only user access is recommended. + +1. Generate an API token from your chosen user account or create a new readonly user. + API token can be retrieved from either Purity GUI ot CLI. + + ```console + pureuser@array01> pureadmin create --role readonly svc-readonly + Name Type Role + svc-readonly local readonly + + pureuser@array01> pureadmin create --api-token svc-readonly + Name Type API Token Created Expires + svc-readonly local a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6 2023-11-02 12:00:00 EST - + ``` + +# Container Deployment +We build container images and publish them to RedHat quay.io. Here they can be continually scanned for vulnerabilities and updated as soon as a new version are available. +You can navigate to [https://quay.io/repository/purestorage/pure-fa-om-exporter](https://quay.io/repository/purestorage/pure-fa-om-exporter) to view the available versions. In this example we will pull a container down using Docker. + +In this example we will use the default port 9490, set the name as pure-fa-om-exporter and pull the latest version of the image from quay.io/purestorage/pure-fa-om-exporter. The `--detach` switch sends the process to the background. + +1. **Run and pull the image** + ```console + > docker run --detach --publish 9490:9490 --name pure-fa-om-exporter --restart unless-stopped quay.io/purestorage/pure-fa-om-exporter:latest + ``` + In this guide we will not be covering Docker troubleshooting. + +2. **Check the container is running** + ```console + > docker ps + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 0076ded8a073 quay.io/purestorage/pure-fa-om-exporter:latest "/pure-fa-om-exporte…" 10 seconds ago Up 10 seconds 0.0.0.0:9490->9490/tcp, :::9490->9490/tcp pure-fa-om-exporter + ``` + +3. **Test the exporter** + Use `curl` to test the exporter returns results. + ```console + > curl -H 'Authorization: Bearer a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info + purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 + ``` + + We expect to return a single line displaying `purefa_info` returning the name, Purity OS, system ID and the Purity version. + You can remove the `-silent | grep ^purefa_info` from the command to see a list of all results. + +## Other deployment examples + +### Conatiner with Tokens File +1. Create a tokens.yaml file to pass to the exporter. + ```console + > cat /directorypath/tokens.yaml + # alias: of the array to be used in the exporter query + array01: + # FQDN or IP address of the array + address: 'array01.fqdn.com' + # API token of a user on the array + api_token: 'a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' + + # Example of a second array + array02: + address: 'array02.fqdn.com' + api_token: 'a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f7' + ``` + +2. **Run the container** + Run the container this time specifying a volume (in our case a single file) to pass the token.yaml file from the host server to the guest container. + The container expects to see the file here: `/etc/pure-fa-om-exporter/tokens.yaml` + + ```console + > docker run -d -p 9490:9490 --name pure-fa-om-exporter --volume /directorypath/tokens.yaml:/etc/pure-fa-om-exporter/tokens.yaml quay.io/purestorage/pure-fa-om-exporter:latest + ``` +3. **Check the container is running** + ```console + > docker ps + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 0076ded8a073 quay.io/purestorage/pure-fa-om-exporter:latest "/pure-fa-om-exporte…" 10 seconds ago Up 10 seconds 0.0.0.0:9490->9490/tcp, :::9490->9490/tcp pure-fa-om-exporter + ``` + +4. **Test the exporter** + Use `curl` to test the exporter returns results. We don't need to pass the bearer (API) token for authorization as the exporter has a record of these which makes queries simpler. + ```console + > curl -X GET 'http://localhost:9490/metrics/array?endpoint=array01 ' -silent | grep ^purefa_info + purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 + ``` +### Container with TLS +TLS with Docker image is currently not supported. Please use executable binary only for this feature. + + +# Executable Binary Deployment +Deploying the binary requires [go](https://go.dev) to compile the code and running the binary in a Linux environment. +1. **Install go**: Go is required: to compile the build into an executable binary + + Clear instructions: can be found here: [https://go.dev/doc/install](https://go.dev/doc/install) + +2. **Install git** + + ```console + > yum install git + ``` + +3. **Clone git repo** + + ```console + > git clone git@github.com:PureStorage-OpenConnect/pure-fa-openmetrics-exporter.git + ``` + +4. **Build the package** + + ```console + > cd pure-fa-openmetrics-exporter + > make build . + ``` + +### Binary - Default - http passing API token with query + +5. **Binary - Default - http passing API token with query** + ```console + > ls out/bin + > .out/bin/pure-fa-openmetrics-exporter + Start Pure FlashArray exporter v1.0.9 on 0.0.0.0:9490 + ``` + +6. **Test the exporter** + Use `curl` to test the exporter returns results. + ```console + > curl -H 'Authorization: Bearer a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info + purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 + ``` + + We expect to return a single line displaying `purefa_info` returning the name, Purity OS, system ID and the Purity version. + You can remove the `' -silent | grep ^purefa_info` from the command to see a list of all results. + +7. **Build it as a service** + + Copy binary to `/usr/bin` + ```console + > cp .out/bin/pure-fa-openmetrics-exporter /usr/bin + ``` + + Create a `.servicefile` in `/etc/systemd/system/` + ```console + > cat /etc/systemd/system/purefa-ome.service + ``` + + Example: + ```console + [Unit] + Description=Pure Storage FlashArray OpenMetrics Exporter + After=network.target + StartLimitIntervalSec=0 + [Service] + Type=simple + Restart=always + RestartSec=1 + + > Start OME + ExecStart=/usr/bin/pure-fa-om-exporter --port 9490 + + > Start OME with TLS + > ExecStart=/usr/bin/pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k /etc/pki/tls/private/pure-ome.key + + [Install] + WantedBy=multi-user.target + ``` + +8. **Start, enable and test the service** + Reload the system daemon to read in changes to services + + ```console + > systemctl daemon-reload + ``` + + Start the service and check the status is successful + + ``` + > systemctl start purefa-ome + > systemctl status purefa-ome + ``` + + Enable the service to start on OS startup + ```console + > systemctl enable purefa-ome + ``` + +## Binary - Tokens File - http with API tokens file embedded in exporter +Similar steps as basic but we just need to cover a couple of minor changes to running and testing the deployment +Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the following steps for executing and testing. + +4. **Create a tokens.yaml file to pass to the exporter** + + ```console + > cat /directorypath/tokens.yaml + # alias: of the array to be used in the exporter query + array01: + # FQDN or IP address of the array + address: 'array01.fqdn.com' + # API token of a user on the array + api_token: 'a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' + + # Example of a second array + array02: + address: 'array02.fqdn.com' + api_token: 'a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f7' + ``` + +5. **Run the binary** + ```console + > ls out/bin + > .out/bin/pure-fa-openmetrics-exporter --tokens /directorypath/tokens.yaml + Start Pure FlashArray exporter v1.0.9 on 0.0.0.0:9490 + ``` + +6. **Test the exporter** + Use `curl` to test the exporter returns results. + ```console + > curl -X GET 'http://localhost:9490/metrics/array?endpoint=gse-array01' -silent | grep ^purefa_info + purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 + ``` + +## Binary - TLS - https passing API token with query +Similar steps as basic but we just need to cover a couple of minor changes to running and testing the deployment +Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the following steps for executing and testing. + +Create the certificate and key and pass the exporter the files. There are many different methods of generating certificates which we won't discuss here as each organizations has different standards and requirements. + +5. **Pass the certificate and private key to the exporter** +```console +pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k /etc/pki/tls/private/pure-ome.key +``` +6. **Test the exporter** + + Use `curl` to test the exporter returns results. + + Please note to use `https` in the queries. + + **TLS https - skipping SSL verification** + + cURL with -k skips SSL verification. + ```console + >curl -k -H 'Authorization: Bearer 12345678-abcd-abcd-abcd-abcdef123456' -X GET 'https://localhost:9490/metrics/array?endpoint=array01' --silent | grep ^purefa_info + ``` + + **TLS https - with SSL verification** + + Run the following commands from the server with the certificates installed. + + A basic check of the certificate is installed and the exporter is responding correctly. + ```console + > curl https://pure-ome.fqdn.com:9490 + + +

Pure Storage FlashArray OpenMetrics Exporter

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeEndpointGET parametersDescription
Full metrics/metricsendpointAll array metrics. Expect slow response time.
Array metrics/metrics/arrayendpointProvides only array related metrics.
Volumes metrics/metrics/volumesendpointProvides only volumes related metrics.
Hosts metrics/metrics/hostsendpointProvides only hosts related metrics.
Pods metrics/metrics/podsendpointProvides only pods related metrics.
Directories metrics/metrics/directoriesendpointProvides only directories related metrics.
+ + ``` + + Full check using certificate. + ```console + > curl --cacert pure-ome.crt -H 'Authorization: Bearer 12345678-abcd-abcd-abcd-abcdef123456' -X GET 'http://pure-ome.fqdn.com:9490/metrics/array?endpoint=array01' + ``` + + + + + + + From 6192ca2038ae6eec9ca85afc613174127c9b33c9 Mon Sep 17 00:00:00 2001 From: James Laing <102221031+james-laing@users.noreply.github.com> Date: Thu, 2 Nov 2023 21:34:23 +0000 Subject: [PATCH 2/9] Update README.md Added link to deployment examples --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c381034..4473e58 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ git clone git@github.com:PureStorage-OpenConnect/pure-fa-openmetrics-exporter.gi # modify the code and build the package cd pure-fa-openmetrics-exporter ... -make build +make build . ``` The newly built exporter executable can be found in the ./out/bin directory. @@ -197,6 +197,7 @@ scrape_configs: See the Kubernetes [examples](examples/config/k8s) for a similar configuration that uses additional configuration items for a simple Prometheus+Kubernetes deployment, or for the more interesting Prometheus operator. ### Usage Examples +Detailed examples of how to deploy several configurations either using Docker or an executable binary can be in [deployment examples](extra/deployment.md). #### Docker In a typical production scenario, it is recommended to use a visual frontend for your metrics, such as [Grafana](https://github.com/grafana/grafana). Grafana allows you to use your Prometheus instance as a datasource, and create Graphs and other visualizations from PromQL queries. Grafana, Prometheus, are all easy to run as docker containers. From 2f5a219e99aa1b50ac6f0af21645ae5bb5cce9c1 Mon Sep 17 00:00:00 2001 From: James Laing <102221031+james-laing@users.noreply.github.com> Date: Thu, 2 Nov 2023 21:44:28 +0000 Subject: [PATCH 3/9] Update deployment.md --- extra/deployment.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/extra/deployment.md b/extra/deployment.md index 4a44c51..b6d775e 100644 --- a/extra/deployment.md +++ b/extra/deployment.md @@ -165,11 +165,11 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni Restart=always RestartSec=1 - > Start OME + # Start OME ExecStart=/usr/bin/pure-fa-om-exporter --port 9490 - > Start OME with TLS - > ExecStart=/usr/bin/pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k /etc/pki/tls/private/pure-ome.key + # Start OME with TLS + # ExecStart=/usr/bin/pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k /etc/pki/tls/private/pure-ome.key [Install] WantedBy=multi-user.target From ddd2842993de2cdd5380f7a8bb345ea1a7410254 Mon Sep 17 00:00:00 2001 From: James Laing <102221031+james-laing@users.noreply.github.com> Date: Thu, 2 Nov 2023 22:08:30 +0000 Subject: [PATCH 4/9] Update deployment.md Added contents --- extra/deployment.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/extra/deployment.md b/extra/deployment.md index b6d775e..e9d927a 100644 --- a/extra/deployment.md +++ b/extra/deployment.md @@ -1,14 +1,17 @@ -# Example deployment methods - -There are a number of methods to deploy the OpenMetrics exporter depending on your environment. -- Container Deployment (such as Docker) - - Default - http passing API token with query - - Tokens - http with API tokens file embedded in exporter - - TLS - https passing API token with query -- Executable Binary Deployment - - Default - http passing API token with query - - Tokens - http with API tokens file embedded in exporter - - TLS - https passing API token with query +# Example Deployment Methods +There are a number of methods to deploy the OpenMetrics exporter depending on your environment. In this document we explore some of the common features and deployment methods and by providing walk through examples. + +## Contents + - [Prerequisites](#prerequisites) + - [Container Deployment](#container-deployment) + - [Container - default - http passing API token with query](#container---default---http-passing-api-token-with-query) + - [Container - Tokens File - http with API tokens file embedded in exporter](#container---tokens-file---http-with-api-tokens-file-embedded-in-exporter) + - [Container - TLS - https passing API token with query](#container---tls---https-passing-api-token-with-query) + - [Executable Binary Deployment](#executable-binary-deployment) + - [Binary Specific Prerequisites](#binary-specific-prerequisites) + - [Binary - default - http passing API token with query](#binary---default---http-passing-api-token-with-query) + - [Binary - Tokens File - http with API tokens file embedded in exporter](#binary---tokens-file---http-with-api-tokens-file-embedded-in-exporter) + - [Binary - TLS - https passing API token with query](#binary---tls---https-passing-api-token-with-query) # Prerequisites All deployments will require an API token to authenticate with the array. Read-only only user access is recommended. @@ -27,6 +30,7 @@ All deployments will require an API token to authenticate with the array. Read-o ``` # Container Deployment +## Container - default - http passing API token with query We build container images and publish them to RedHat quay.io. Here they can be continually scanned for vulnerabilities and updated as soon as a new version are available. You can navigate to [https://quay.io/repository/purestorage/pure-fa-om-exporter](https://quay.io/repository/purestorage/pure-fa-om-exporter) to view the available versions. In this example we will pull a container down using Docker. @@ -55,9 +59,8 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex We expect to return a single line displaying `purefa_info` returning the name, Purity OS, system ID and the Purity version. You can remove the `-silent | grep ^purefa_info` from the command to see a list of all results. -## Other deployment examples +## Container - Tokens File - http with API tokens file embedded in exporter -### Conatiner with Tokens File 1. Create a tokens.yaml file to pass to the exporter. ```console > cat /directorypath/tokens.yaml @@ -94,11 +97,13 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex > curl -X GET 'http://localhost:9490/metrics/array?endpoint=array01 ' -silent | grep ^purefa_info purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 ``` -### Container with TLS -TLS with Docker image is currently not supported. Please use executable binary only for this feature. +## Container - TLS - https passing API token with query +TLS with Docker image is currently not supported. Please use executable binary only for this feature. # Executable Binary Deployment +## Binary Specific Prerequisites + Deploying the binary requires [go](https://go.dev) to compile the code and running the binary in a Linux environment. 1. **Install go**: Go is required: to compile the build into an executable binary From f397f58d76a1455221a6acec8fb49d0feb0c6b1e Mon Sep 17 00:00:00 2001 From: James Laing <102221031+james-laing@users.noreply.github.com> Date: Thu, 2 Nov 2023 22:09:25 +0000 Subject: [PATCH 5/9] Update deployment.md Minor typo --- extra/deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extra/deployment.md b/extra/deployment.md index e9d927a..5ecdccf 100644 --- a/extra/deployment.md +++ b/extra/deployment.md @@ -128,7 +128,7 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni > make build . ``` -### Binary - Default - http passing API token with query +## Binary - Default - http passing API token with query 5. **Binary - Default - http passing API token with query** ```console From fc9b4fb30f1691e9bbc5653b29185d32a209410b Mon Sep 17 00:00:00 2001 From: James Laing <102221031+james-laing@users.noreply.github.com> Date: Thu, 2 Nov 2023 22:15:56 +0000 Subject: [PATCH 6/9] Update deployment.md Replaced command prompt > with $ --- extra/deployment.md | 54 ++++++++++++++++++++++----------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/extra/deployment.md b/extra/deployment.md index 5ecdccf..f077d99 100644 --- a/extra/deployment.md +++ b/extra/deployment.md @@ -38,13 +38,13 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex 1. **Run and pull the image** ```console - > docker run --detach --publish 9490:9490 --name pure-fa-om-exporter --restart unless-stopped quay.io/purestorage/pure-fa-om-exporter:latest + $ docker run --detach --publish 9490:9490 --name pure-fa-om-exporter --restart unless-stopped quay.io/purestorage/pure-fa-om-exporter:latest ``` In this guide we will not be covering Docker troubleshooting. 2. **Check the container is running** ```console - > docker ps + $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 0076ded8a073 quay.io/purestorage/pure-fa-om-exporter:latest "/pure-fa-om-exporte…" 10 seconds ago Up 10 seconds 0.0.0.0:9490->9490/tcp, :::9490->9490/tcp pure-fa-om-exporter ``` @@ -52,7 +52,7 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex 3. **Test the exporter** Use `curl` to test the exporter returns results. ```console - > curl -H 'Authorization: Bearer a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info + $ curl -H 'Authorization: Bearer a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 ``` @@ -63,7 +63,7 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex 1. Create a tokens.yaml file to pass to the exporter. ```console - > cat /directorypath/tokens.yaml + $ cat /directorypath/tokens.yaml # alias: of the array to be used in the exporter query array01: # FQDN or IP address of the array @@ -82,11 +82,11 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex The container expects to see the file here: `/etc/pure-fa-om-exporter/tokens.yaml` ```console - > docker run -d -p 9490:9490 --name pure-fa-om-exporter --volume /directorypath/tokens.yaml:/etc/pure-fa-om-exporter/tokens.yaml quay.io/purestorage/pure-fa-om-exporter:latest + $ docker run -d -p 9490:9490 --name pure-fa-om-exporter --volume /directorypath/tokens.yaml:/etc/pure-fa-om-exporter/tokens.yaml quay.io/purestorage/pure-fa-om-exporter:latest ``` 3. **Check the container is running** ```console - > docker ps + $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 0076ded8a073 quay.io/purestorage/pure-fa-om-exporter:latest "/pure-fa-om-exporte…" 10 seconds ago Up 10 seconds 0.0.0.0:9490->9490/tcp, :::9490->9490/tcp pure-fa-om-exporter ``` @@ -94,7 +94,7 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex 4. **Test the exporter** Use `curl` to test the exporter returns results. We don't need to pass the bearer (API) token for authorization as the exporter has a record of these which makes queries simpler. ```console - > curl -X GET 'http://localhost:9490/metrics/array?endpoint=array01 ' -silent | grep ^purefa_info + $ curl -X GET 'http://localhost:9490/metrics/array?endpoint=array01 ' -silent | grep ^purefa_info purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 ``` @@ -112,35 +112,35 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni 2. **Install git** ```console - > yum install git + $ yum install git ``` 3. **Clone git repo** ```console - > git clone git@github.com:PureStorage-OpenConnect/pure-fa-openmetrics-exporter.git + $ git clone git@github.com:PureStorage-OpenConnect/pure-fa-openmetrics-exporter.git ``` 4. **Build the package** ```console - > cd pure-fa-openmetrics-exporter - > make build . + $ cd pure-fa-openmetrics-exporter + $ make build . ``` ## Binary - Default - http passing API token with query 5. **Binary - Default - http passing API token with query** ```console - > ls out/bin - > .out/bin/pure-fa-openmetrics-exporter + $ ls out/bin + $ .out/bin/pure-fa-openmetrics-exporter Start Pure FlashArray exporter v1.0.9 on 0.0.0.0:9490 ``` 6. **Test the exporter** Use `curl` to test the exporter returns results. ```console - > curl -H 'Authorization: Bearer a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info + $ curl -H 'Authorization: Bearer a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 ``` @@ -151,12 +151,12 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni Copy binary to `/usr/bin` ```console - > cp .out/bin/pure-fa-openmetrics-exporter /usr/bin + $ cp .out/bin/pure-fa-openmetrics-exporter /usr/bin ``` Create a `.servicefile` in `/etc/systemd/system/` ```console - > cat /etc/systemd/system/purefa-ome.service + $ cat /etc/systemd/system/purefa-ome.service ``` Example: @@ -184,19 +184,19 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni Reload the system daemon to read in changes to services ```console - > systemctl daemon-reload + $ systemctl daemon-reload ``` Start the service and check the status is successful - ``` - > systemctl start purefa-ome - > systemctl status purefa-ome + ```console + $ systemctl start purefa-ome + $ systemctl status purefa-ome ``` Enable the service to start on OS startup ```console - > systemctl enable purefa-ome + $ systemctl enable purefa-ome ``` ## Binary - Tokens File - http with API tokens file embedded in exporter @@ -206,7 +206,7 @@ Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the fo 4. **Create a tokens.yaml file to pass to the exporter** ```console - > cat /directorypath/tokens.yaml + $ cat /directorypath/tokens.yaml # alias: of the array to be used in the exporter query array01: # FQDN or IP address of the array @@ -222,15 +222,15 @@ Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the fo 5. **Run the binary** ```console - > ls out/bin - > .out/bin/pure-fa-openmetrics-exporter --tokens /directorypath/tokens.yaml + $ ls out/bin + $ .out/bin/pure-fa-openmetrics-exporter --tokens /directorypath/tokens.yaml Start Pure FlashArray exporter v1.0.9 on 0.0.0.0:9490 ``` 6. **Test the exporter** Use `curl` to test the exporter returns results. ```console - > curl -X GET 'http://localhost:9490/metrics/array?endpoint=gse-array01' -silent | grep ^purefa_info + $ curl -X GET 'http://localhost:9490/metrics/array?endpoint=gse-array01' -silent | grep ^purefa_info purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 ``` @@ -263,7 +263,7 @@ pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k A basic check of the certificate is installed and the exporter is responding correctly. ```console - > curl https://pure-ome.fqdn.com:9490 + $ curl https://pure-ome.fqdn.com:9490

Pure Storage FlashArray OpenMetrics Exporter

@@ -320,7 +320,7 @@ pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k Full check using certificate. ```console - > curl --cacert pure-ome.crt -H 'Authorization: Bearer 12345678-abcd-abcd-abcd-abcdef123456' -X GET 'http://pure-ome.fqdn.com:9490/metrics/array?endpoint=array01' + $ curl --cacert pure-ome.crt -H 'Authorization: Bearer 12345678-abcd-abcd-abcd-abcdef123456' -X GET 'http://pure-ome.fqdn.com:9490/metrics/array?endpoint=array01' ``` From 19cd38977e6e6729766c6ebcf69ba0fb1fb22aa1 Mon Sep 17 00:00:00 2001 From: James Laing <102221031+james-laing@users.noreply.github.com> Date: Thu, 2 Nov 2023 22:25:33 +0000 Subject: [PATCH 7/9] Create docs folder and move deployment-examples --- README.md | 3 ++- extra/deployment.md => docs/deployment-examples.md | 0 2 files changed, 2 insertions(+), 1 deletion(-) rename extra/deployment.md => docs/deployment-examples.md (100%) diff --git a/README.md b/README.md index 4473e58..2a62917 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,8 @@ To monitor your Pure Storage appliances, you will need to create a new dedicated The exporter is a Go application based on the Prometheus Go client library and [Resty](https://github.com/go-resty/resty), a simple but reliable HTTP and REST client library for Go . It is preferably built and launched via Docker. You can also scale the exporter deployment to multiple containers on Kubernetes thanks to the stateless nature of the application. +Detailed examples of how to deploy several configurations either using Docker or an executable binary can be in [docs/deployment-examples.md](docs/deployment-examples.md). + --- #### The official docker images are available at Quay.io @@ -197,7 +199,6 @@ scrape_configs: See the Kubernetes [examples](examples/config/k8s) for a similar configuration that uses additional configuration items for a simple Prometheus+Kubernetes deployment, or for the more interesting Prometheus operator. ### Usage Examples -Detailed examples of how to deploy several configurations either using Docker or an executable binary can be in [deployment examples](extra/deployment.md). #### Docker In a typical production scenario, it is recommended to use a visual frontend for your metrics, such as [Grafana](https://github.com/grafana/grafana). Grafana allows you to use your Prometheus instance as a datasource, and create Graphs and other visualizations from PromQL queries. Grafana, Prometheus, are all easy to run as docker containers. diff --git a/extra/deployment.md b/docs/deployment-examples.md similarity index 100% rename from extra/deployment.md rename to docs/deployment-examples.md From 4010cfcac1c820121ac3f1816ef1ed4180d0595b Mon Sep 17 00:00:00 2001 From: James Laing <102221031+james-laing@users.noreply.github.com> Date: Mon, 13 Nov 2023 21:05:29 +0000 Subject: [PATCH 8/9] Update deployment-examples.md Minor updates to formatting and grammar. --- docs/deployment-examples.md | 63 ++++++++++++++++++++++--------------- 1 file changed, 38 insertions(+), 25 deletions(-) diff --git a/docs/deployment-examples.md b/docs/deployment-examples.md index f077d99..567b281 100644 --- a/docs/deployment-examples.md +++ b/docs/deployment-examples.md @@ -1,5 +1,5 @@ # Example Deployment Methods -There are a number of methods to deploy the OpenMetrics exporter depending on your environment. In this document we explore some of the common features and deployment methods and by providing walk through examples. +There are a number of methods to deploy the OpenMetrics exporter. In this document we explore some of the common features and deployment methods by providing walk through examples. ## Contents - [Prerequisites](#prerequisites) @@ -16,18 +16,29 @@ There are a number of methods to deploy the OpenMetrics exporter depending on yo # Prerequisites All deployments will require an API token to authenticate with the array. Read-only only user access is recommended. -1. Generate an API token from your chosen user account or create a new readonly user. - API token can be retrieved from either Purity GUI ot CLI. +Generate an API token from your chosen user account or create a new readonly user. +API token can be retrieved from either Purity GUI ot CLI. - ```console - pureuser@array01> pureadmin create --role readonly svc-readonly - Name Type Role - svc-readonly local readonly +
+Expand for CLI example - pureuser@array01> pureadmin create --api-token svc-readonly - Name Type API Token Created Expires - svc-readonly local a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6 2023-11-02 12:00:00 EST - - ``` +```console +pureuser@arrayname01> pureadmin create --role readonly o11y-readonly +Name Type Role +o11y-readonly local readonly + +pureuser@arrayname01> pureadmin create --api-token o11y-readonly +Name Type API Token Created Expires +o11y-readonly local 11111111-1111-1111-1111-111111111111 2022-11-30 08:58:40 EST - +``` + +
+ +
+Expand for GUI example + +![Alt text](../extra/images/purefa_create_api_token.png) +
# Container Deployment ## Container - default - http passing API token with query @@ -53,7 +64,7 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex Use `curl` to test the exporter returns results. ```console $ curl -H 'Authorization: Bearer a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info - purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 + purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="11111111-1111-1111-1111-111111111111",version="6.5.0"} 1 ``` We expect to return a single line displaying `purefa_info` returning the name, Purity OS, system ID and the Purity version. @@ -74,7 +85,7 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex # Example of a second array array02: address: 'array02.fqdn.com' - api_token: 'a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f7' + api_token: '11111111-1111-1111-1111-111111111111' ``` 2. **Run the container** @@ -95,7 +106,7 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex Use `curl` to test the exporter returns results. We don't need to pass the bearer (API) token for authorization as the exporter has a record of these which makes queries simpler. ```console $ curl -X GET 'http://localhost:9490/metrics/array?endpoint=array01 ' -silent | grep ^purefa_info - purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 + purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="11111111-1111-1111-1111-111111111111",version="6.5.0"} 1 ``` ## Container - TLS - https passing API token with query @@ -118,7 +129,7 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni 3. **Clone git repo** ```console - $ git clone git@github.com:PureStorage-OpenConnect/pure-fa-openmetrics-exporter.git + $ git clone https://github.com/PureStorage-OpenConnect/pure-fa-openmetrics-exporter.git ``` 4. **Build the package** @@ -134,14 +145,14 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni ```console $ ls out/bin $ .out/bin/pure-fa-openmetrics-exporter - Start Pure FlashArray exporter v1.0.9 on 0.0.0.0:9490 + Start Pure FlashArray exporter v1.0.10 on 0.0.0.0:9490 ``` 6. **Test the exporter** Use `curl` to test the exporter returns results. ```console $ curl -H 'Authorization: Bearer a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info - purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 + purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="11111111-1111-1111-1111-111111111111",version="6.5.0"} 1 ``` We expect to return a single line displaying `purefa_info` returning the name, Purity OS, system ID and the Purity version. @@ -217,21 +228,21 @@ Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the fo # Example of a second array array02: address: 'array02.fqdn.com' - api_token: 'a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f7' + api_token: '11111111-1111-1111-1111-111111111111' ``` 5. **Run the binary** ```console $ ls out/bin $ .out/bin/pure-fa-openmetrics-exporter --tokens /directorypath/tokens.yaml - Start Pure FlashArray exporter v1.0.9 on 0.0.0.0:9490 + Start Pure FlashArray exporter v1.0.10 on 0.0.0.0:9490 ``` 6. **Test the exporter** Use `curl` to test the exporter returns results. ```console $ curl -X GET 'http://localhost:9490/metrics/array?endpoint=gse-array01' -silent | grep ^purefa_info - purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="12345678-abcd-abcd-abcd-abcdef123456",version="6.5.0"} 1 + purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="11111111-1111-1111-1111-111111111111",version="6.5.0"} 1 ``` ## Binary - TLS - https passing API token with query @@ -241,9 +252,11 @@ Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the fo Create the certificate and key and pass the exporter the files. There are many different methods of generating certificates which we won't discuss here as each organizations has different standards and requirements. 5. **Pass the certificate and private key to the exporter** -```console -pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k /etc/pki/tls/private/pure-ome.key -``` + + ```console + $ pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k /etc/pki/tls/private/pure-ome.key + ``` + 6. **Test the exporter** Use `curl` to test the exporter returns results. @@ -254,7 +267,7 @@ pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k cURL with -k skips SSL verification. ```console - >curl -k -H 'Authorization: Bearer 12345678-abcd-abcd-abcd-abcdef123456' -X GET 'https://localhost:9490/metrics/array?endpoint=array01' --silent | grep ^purefa_info + $ curl -k -H 'Authorization: Bearer 11111111-1111-1111-1111-111111111111' -X GET 'https://localhost:9490/metrics/array?endpoint=array01' --silent | grep ^purefa_info ``` **TLS https - with SSL verification** @@ -320,7 +333,7 @@ pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k Full check using certificate. ```console - $ curl --cacert pure-ome.crt -H 'Authorization: Bearer 12345678-abcd-abcd-abcd-abcdef123456' -X GET 'http://pure-ome.fqdn.com:9490/metrics/array?endpoint=array01' + $ curl --cacert pure-ome.crt -H 'Authorization: Bearer 11111111-1111-1111-1111-111111111111' -X GET 'http://pure-ome.fqdn.com:9490/metrics/array?endpoint=array01' ``` From 74896034b90d60e15059e6095da24adc51d96889 Mon Sep 17 00:00:00 2001 From: James Laing <102221031+james-laing@users.noreply.github.com> Date: Tue, 14 Nov 2023 10:17:03 +0000 Subject: [PATCH 9/9] Update API tokens & formatting --- docs/deployment-examples.md | 50 ++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 29 deletions(-) diff --git a/docs/deployment-examples.md b/docs/deployment-examples.md index 567b281..6c69ae5 100644 --- a/docs/deployment-examples.md +++ b/docs/deployment-examples.md @@ -40,6 +40,8 @@ o11y-readonly local 11111111-1111-1111-1111-111111111111 2022-11-30 08:58:40 ![Alt text](../extra/images/purefa_create_api_token.png) +--- + # Container Deployment ## Container - default - http passing API token with query We build container images and publish them to RedHat quay.io. Here they can be continually scanned for vulnerabilities and updated as soon as a new version are available. @@ -63,7 +65,7 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex 3. **Test the exporter** Use `curl` to test the exporter returns results. ```console - $ curl -H 'Authorization: Bearer a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info + $ curl -H 'Authorization: Bearer 11111111-1111-1111-1111-111111111111' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="11111111-1111-1111-1111-111111111111",version="6.5.0"} 1 ``` @@ -80,12 +82,12 @@ In this example we will use the default port 9490, set the name as pure-fa-om-ex # FQDN or IP address of the array address: 'array01.fqdn.com' # API token of a user on the array - api_token: 'a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' + api_token: '11111111-1111-1111-1111-111111111111' # Example of a second array array02: address: 'array02.fqdn.com' - api_token: '11111111-1111-1111-1111-111111111111' + api_token: '22222222-2222-2222-2222-222222222222' ``` 2. **Run the container** @@ -121,10 +123,7 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni Clear instructions: can be found here: [https://go.dev/doc/install](https://go.dev/doc/install) 2. **Install git** - - ```console - $ yum install git - ``` + Install git for your specific operating system [https://github.com/git-guides/install-git](https://github.com/git-guides/install-git). 3. **Clone git repo** @@ -141,24 +140,24 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni ## Binary - Default - http passing API token with query -5. **Binary - Default - http passing API token with query** +1. **Binary - Default - http passing API token with query** ```console $ ls out/bin $ .out/bin/pure-fa-openmetrics-exporter - Start Pure FlashArray exporter v1.0.10 on 0.0.0.0:9490 + Start Pure FlashArray exporter v1.0.11 on 0.0.0.0:9490 ``` -6. **Test the exporter** +2. **Test the exporter** Use `curl` to test the exporter returns results. ```console - $ curl -H 'Authorization: Bearer a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info + $ curl -H 'Authorization: Bearer 11111111-1111-1111-1111-111111111111' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="11111111-1111-1111-1111-111111111111",version="6.5.0"} 1 ``` We expect to return a single line displaying `purefa_info` returning the name, Purity OS, system ID and the Purity version. You can remove the `' -silent | grep ^purefa_info` from the command to see a list of all results. -7. **Build it as a service** +3. **Build it as a service** Copy binary to `/usr/bin` ```console @@ -191,7 +190,7 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni WantedBy=multi-user.target ``` -8. **Start, enable and test the service** +4. **Start, enable and test the service** Reload the system daemon to read in changes to services ```console @@ -214,7 +213,7 @@ Deploying the binary requires [go](https://go.dev) to compile the code and runni Similar steps as basic but we just need to cover a couple of minor changes to running and testing the deployment Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the following steps for executing and testing. -4. **Create a tokens.yaml file to pass to the exporter** +1. **Create a tokens.yaml file to pass to the exporter** ```console $ cat /directorypath/tokens.yaml @@ -223,22 +222,22 @@ Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the fo # FQDN or IP address of the array address: 'array01.fqdn.com' # API token of a user on the array - api_token: 'a1b2c3d4-e5f6-1234-5678-a1b2c3d4e5f6' + api_token: '11111111-1111-1111-1111-111111111111' # Example of a second array array02: address: 'array02.fqdn.com' - api_token: '11111111-1111-1111-1111-111111111111' + api_token: '22222222-2222-2222-2222-222222222222' ``` -5. **Run the binary** +2. **Run the binary** ```console $ ls out/bin $ .out/bin/pure-fa-openmetrics-exporter --tokens /directorypath/tokens.yaml - Start Pure FlashArray exporter v1.0.10 on 0.0.0.0:9490 + Start Pure FlashArray exporter v1.0.11 on 0.0.0.0:9490 ``` -6. **Test the exporter** +3. **Test the exporter** Use `curl` to test the exporter returns results. ```console $ curl -X GET 'http://localhost:9490/metrics/array?endpoint=gse-array01' -silent | grep ^purefa_info @@ -251,13 +250,13 @@ Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the fo Create the certificate and key and pass the exporter the files. There are many different methods of generating certificates which we won't discuss here as each organizations has different standards and requirements. -5. **Pass the certificate and private key to the exporter** +1. **Pass the certificate and private key to the exporter** ```console $ pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k /etc/pki/tls/private/pure-ome.key ``` -6. **Test the exporter** +2. **Test the exporter** Use `curl` to test the exporter returns results. @@ -334,11 +333,4 @@ Create the certificate and key and pass the exporter the files. There are many d Full check using certificate. ```console $ curl --cacert pure-ome.crt -H 'Authorization: Bearer 11111111-1111-1111-1111-111111111111' -X GET 'http://pure-ome.fqdn.com:9490/metrics/array?endpoint=array01' - ``` - - - - - - - + ``` \ No newline at end of file