Skip to content

Commit 1ce1ddd

Browse files
sdodsleysdodsley
authored
Merge pull request #86 from james-laing/add-deployment-options
Add deployment examples
2 parents c8660c2 + 7489603 commit 1ce1ddd

File tree

2 files changed

+339
-1
lines changed

2 files changed

+339
-1
lines changed

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ To monitor your Pure Storage appliances, you will need to create a new dedicated
2121

2222
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.
2323

24+
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).
25+
2426
---
2527

2628
#### The official docker images are available at Quay.io
@@ -49,7 +51,7 @@ git clone [email protected]:PureStorage-OpenConnect/pure-fa-openmetrics-exporter.gi
4951
# modify the code and build the package
5052
cd pure-fa-openmetrics-exporter
5153
...
52-
make build
54+
make build .
5355
```
5456

5557
The newly built exporter executable can be found in the <kbd>./out/bin</kbd> directory.

‎docs/deployment-examples.md‎

Lines changed: 336 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,336 @@
1+
# Example Deployment Methods
2+
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.
3+
4+
## Contents
5+
- [Prerequisites](#prerequisites)
6+
- [Container Deployment](#container-deployment)
7+
- [Container - default - http passing API token with query](#container---default---http-passing-api-token-with-query)
8+
- [Container - Tokens File - http with API tokens file embedded in exporter](#container---tokens-file---http-with-api-tokens-file-embedded-in-exporter)
9+
- [Container - TLS - https passing API token with query](#container---tls---https-passing-api-token-with-query)
10+
- [Executable Binary Deployment](#executable-binary-deployment)
11+
- [Binary Specific Prerequisites](#binary-specific-prerequisites)
12+
- [Binary - default - http passing API token with query](#binary---default---http-passing-api-token-with-query)
13+
- [Binary - Tokens File - http with API tokens file embedded in exporter](#binary---tokens-file---http-with-api-tokens-file-embedded-in-exporter)
14+
- [Binary - TLS - https passing API token with query](#binary---tls---https-passing-api-token-with-query)
15+
16+
# Prerequisites
17+
All deployments will require an API token to authenticate with the array. Read-only only user access is recommended.
18+
19+
Generate an API token from your chosen user account or create a new readonly user.
20+
API token can be retrieved from either Purity GUI ot CLI.
21+
22+
<details>
23+
<summary>Expand for CLI example</summary>
24+
25+
```console
26+
pureuser@arrayname01> pureadmin create --role readonly o11y-readonly
27+
Name Type Role
28+
o11y-readonly local readonly
29+
30+
pureuser@arrayname01> pureadmin create --api-token o11y-readonly
31+
Name Type API Token Created Expires
32+
o11y-readonly local 11111111-1111-1111-1111-111111111111 2022-11-30 08:58:40 EST -
33+
```
34+
35+
</details>
36+
37+
<details>
38+
<summary>Expand for GUI example</summary>
39+
40+
![Alt text](../extra/images/purefa_create_api_token.png)
41+
</details>
42+
43+
---
44+
45+
# Container Deployment
46+
## Container - default - http passing API token with query
47+
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.
48+
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.
49+
50+
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.
51+
52+
1. **Run and pull the image**
53+
```console
54+
$ docker run --detach --publish 9490:9490 --name pure-fa-om-exporter --restart unless-stopped quay.io/purestorage/pure-fa-om-exporter:latest
55+
```
56+
In this guide we will not be covering Docker troubleshooting.
57+
58+
2. **Check the container is running**
59+
```console
60+
$ docker ps
61+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
62+
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
63+
```
64+
65+
3. **Test the exporter**
66+
Use `curl` to test the exporter returns results.
67+
```console
68+
$ curl -H 'Authorization: Bearer 11111111-1111-1111-1111-111111111111' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info
69+
purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="11111111-1111-1111-1111-111111111111",version="6.5.0"} 1
70+
```
71+
72+
We expect to return a single line displaying `purefa_info` returning the name, Purity OS, system ID and the Purity version.
73+
You can remove the `-silent | grep ^purefa_info` from the command to see a list of all results.
74+
75+
## Container - Tokens File - http with API tokens file embedded in exporter
76+
77+
1. Create a tokens.yaml file to pass to the exporter.
78+
```console
79+
$ cat /directorypath/tokens.yaml
80+
# alias: of the array to be used in the exporter query
81+
array01:
82+
# FQDN or IP address of the array
83+
address: 'array01.fqdn.com'
84+
# API token of a user on the array
85+
api_token: '11111111-1111-1111-1111-111111111111'
86+
87+
# Example of a second array
88+
array02:
89+
address: 'array02.fqdn.com'
90+
api_token: '22222222-2222-2222-2222-222222222222'
91+
```
92+
93+
2. **Run the container**
94+
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.
95+
The container expects to see the file here: `/etc/pure-fa-om-exporter/tokens.yaml`
96+
97+
```console
98+
$ 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
99+
```
100+
3. **Check the container is running**
101+
```console
102+
$ docker ps
103+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
104+
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
105+
```
106+
107+
4. **Test the exporter**
108+
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.
109+
```console
110+
$ curl -X GET 'http://localhost:9490/metrics/array?endpoint=array01 ' -silent | grep ^purefa_info
111+
purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="11111111-1111-1111-1111-111111111111",version="6.5.0"} 1
112+
```
113+
114+
## Container - TLS - https passing API token with query
115+
TLS with Docker image is currently not supported. Please use executable binary only for this feature.
116+
117+
# Executable Binary Deployment
118+
## Binary Specific Prerequisites
119+
120+
Deploying the binary requires [go](https://go.dev) to compile the code and running the binary in a Linux environment.
121+
1. **Install go**: Go is required: to compile the build into an executable binary
122+
123+
Clear instructions: can be found here: [https://go.dev/doc/install](https://go.dev/doc/install)
124+
125+
2. **Install git**
126+
Install git for your specific operating system [https://github.com/git-guides/install-git](https://github.com/git-guides/install-git).
127+
128+
3. **Clone git repo**
129+
130+
```console
131+
$ git clone https://github.com/PureStorage-OpenConnect/pure-fa-openmetrics-exporter.git
132+
```
133+
134+
4. **Build the package**
135+
136+
```console
137+
$ cd pure-fa-openmetrics-exporter
138+
$ make build .
139+
```
140+
141+
## Binary - Default - http passing API token with query
142+
143+
1. **Binary - Default - http passing API token with query**
144+
```console
145+
$ ls out/bin
146+
$ .out/bin/pure-fa-openmetrics-exporter
147+
Start Pure FlashArray exporter v1.0.11 on 0.0.0.0:9490
148+
```
149+
150+
2. **Test the exporter**
151+
Use `curl` to test the exporter returns results.
152+
```console
153+
$ curl -H 'Authorization: Bearer 11111111-1111-1111-1111-111111111111' -X GET 'http://localhost:9490/metrics/array?endpoint=array01' -silent | grep ^purefa_info
154+
purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="11111111-1111-1111-1111-111111111111",version="6.5.0"} 1
155+
```
156+
157+
We expect to return a single line displaying `purefa_info` returning the name, Purity OS, system ID and the Purity version.
158+
You can remove the `' -silent | grep ^purefa_info` from the command to see a list of all results.
159+
160+
3. **Build it as a service**
161+
162+
Copy binary to `/usr/bin`
163+
```console
164+
$ cp .out/bin/pure-fa-openmetrics-exporter /usr/bin
165+
```
166+
167+
Create a `.servicefile` in `/etc/systemd/system/`
168+
```console
169+
$ cat /etc/systemd/system/purefa-ome.service
170+
```
171+
172+
Example:
173+
```console
174+
[Unit]
175+
Description=Pure Storage FlashArray OpenMetrics Exporter
176+
After=network.target
177+
StartLimitIntervalSec=0
178+
[Service]
179+
Type=simple
180+
Restart=always
181+
RestartSec=1
182+
183+
# Start OME
184+
ExecStart=/usr/bin/pure-fa-om-exporter --port 9490
185+
186+
# Start OME with TLS
187+
# 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
188+
189+
[Install]
190+
WantedBy=multi-user.target
191+
```
192+
193+
4. **Start, enable and test the service**
194+
Reload the system daemon to read in changes to services
195+
196+
```console
197+
$ systemctl daemon-reload
198+
```
199+
200+
Start the service and check the status is successful
201+
202+
```console
203+
$ systemctl start purefa-ome
204+
$ systemctl status purefa-ome
205+
```
206+
207+
Enable the service to start on OS startup
208+
```console
209+
$ systemctl enable purefa-ome
210+
```
211+
212+
## Binary - Tokens File - http with API tokens file embedded in exporter
213+
Similar steps as basic but we just need to cover a couple of minor changes to running and testing the deployment
214+
Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the following steps for executing and testing.
215+
216+
1. **Create a tokens.yaml file to pass to the exporter**
217+
218+
```console
219+
$ cat /directorypath/tokens.yaml
220+
# alias: of the array to be used in the exporter query
221+
array01:
222+
# FQDN or IP address of the array
223+
address: 'array01.fqdn.com'
224+
# API token of a user on the array
225+
api_token: '11111111-1111-1111-1111-111111111111'
226+
227+
# Example of a second array
228+
array02:
229+
address: 'array02.fqdn.com'
230+
api_token: '22222222-2222-2222-2222-222222222222'
231+
```
232+
233+
2. **Run the binary**
234+
```console
235+
$ ls out/bin
236+
$ .out/bin/pure-fa-openmetrics-exporter --tokens /directorypath/tokens.yaml
237+
Start Pure FlashArray exporter v1.0.11 on 0.0.0.0:9490
238+
```
239+
240+
3. **Test the exporter**
241+
Use `curl` to test the exporter returns results.
242+
```console
243+
$ curl -X GET 'http://localhost:9490/metrics/array?endpoint=gse-array01' -silent | grep ^purefa_info
244+
purefa_info{array_name="ARRAY01",os="Purity//FA",system_id="11111111-1111-1111-1111-111111111111",version="6.5.0"} 1
245+
```
246+
247+
## Binary - TLS - https passing API token with query
248+
Similar steps as basic but we just need to cover a couple of minor changes to running and testing the deployment
249+
Follow steps 1-4 and 7-8 of the default binary deployment, but substitute the following steps for executing and testing.
250+
251+
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.
252+
253+
1. **Pass the certificate and private key to the exporter**
254+
255+
```console
256+
$ pure-fa-om-exporter --port 9490 -c /etc/pki/tls/certs/purefa-ome/pure-ome.crt -k /etc/pki/tls/private/pure-ome.key
257+
```
258+
259+
2. **Test the exporter**
260+
261+
Use `curl` to test the exporter returns results.
262+
263+
Please note to use `https` in the queries.
264+
265+
**TLS https - skipping SSL verification**
266+
267+
cURL with -k skips SSL verification.
268+
```console
269+
$ curl -k -H 'Authorization: Bearer 11111111-1111-1111-1111-111111111111' -X GET 'https://localhost:9490/metrics/array?endpoint=array01' --silent | grep ^purefa_info
270+
```
271+
272+
**TLS https - with SSL verification**
273+
274+
Run the following commands from the server with the certificates installed.
275+
276+
A basic check of the certificate is installed and the exporter is responding correctly.
277+
```console
278+
$ curl https://pure-ome.fqdn.com:9490
279+
<html>
280+
<body>
281+
<h1>Pure Storage FlashArray OpenMetrics Exporter</h1>
282+
<table>
283+
<thead>
284+
<tr>
285+
<td>Type</td>
286+
<td>Endpoint</td>
287+
<td>GET parameters</td>
288+
<td>Description</td>
289+
</tr>
290+
</thead>
291+
<tbody>
292+
<tr>
293+
<td>Full metrics</td>
294+
<td><a href="/metrics?endpoint=host">/metrics</a></td>
295+
<td>endpoint</td>
296+
<td>All array metrics. Expect slow response time.</td>
297+
</tr>
298+
<tr>
299+
<td>Array metrics</td>
300+
<td><a href="/metrics/array?endpoint=host">/metrics/array</a></td>
301+
<td>endpoint</td>
302+
<td>Provides only array related metrics.</td>
303+
</tr>
304+
<tr>
305+
<td>Volumes metrics</td>
306+
<td><a href="/metrics/volumes?endpoint=host">/metrics/volumes</a></td>
307+
<td>endpoint</td>
308+
<td>Provides only volumes related metrics.</td>
309+
</tr>
310+
<tr>
311+
<td>Hosts metrics</td>
312+
<td><a href="/metrics/hosts?endpoint=host">/metrics/hosts</a></td>
313+
<td>endpoint</td>
314+
<td>Provides only hosts related metrics.</td>
315+
</tr>
316+
<tr>
317+
<td>Pods metrics</td>
318+
<td><a href="/metrics/pods?endpoint=host">/metrics/pods</a></td>
319+
<td>endpoint</td>
320+
<td>Provides only pods related metrics.</td>
321+
</tr>
322+
<tr>
323+
<td>Directories metrics</td>
324+
<td><a href="/metrics/directories?endpoint=host">/metrics/directories</a></td>
325+
<td>endpoint</td>
326+
<td>Provides only directories related metrics.</td>
327+
</tr>
328+
</tbody>
329+
</table>
330+
</body>
331+
```
332+
333+
Full check using certificate.
334+
```console
335+
$ 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'
336+
```

0 commit comments

Comments
 (0)