release / release (push) Successful in 7m6s
The new Cairn OBS: a self-hosted monitor for networks, hosts and services. Licensed AGPLv3.
299 lines
8.7 KiB
Go
299 lines
8.7 KiB
Go
// Package purerest asks a Pure Storage array's REST API 2, read only, as
|
|
// FlashArray and FlashBlade both offer it (docs/pure.md): the newest 2.x
|
|
// the array has, an API token traded for a session, lists paged with
|
|
// continuation tokens. Only GET is asked, after logging in.
|
|
package purerest
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"io"
|
|
"net/http"
|
|
"net/url"
|
|
"os"
|
|
"sort"
|
|
"strconv"
|
|
"strings"
|
|
"time"
|
|
|
|
"github.com/cairnobs/cairnobs/internal/tlspin"
|
|
)
|
|
|
|
// Config is one array in the agent's pure: section.
|
|
type Config struct {
|
|
// Type is what it is: flasharray (the default) or flashblade.
|
|
Type string `yaml:"type"`
|
|
// Name is what the array is kept under, beside the agent's name
|
|
// ("mgmt1:fa-prod-01"): default its host name.
|
|
Name string `yaml:"name"`
|
|
URL string `yaml:"url"` // https://fa-prod-01 (its management address)
|
|
TokenFile string `yaml:"token_file"` // a readonly user's API token, alone in the file
|
|
CAFile string `yaml:"ca_file"` // the array's CA, PEM; else the system's
|
|
// Fingerprint pins the array's certificate (SHA-256, hex, colons or
|
|
// not) when it isn't signed by a CA the agent trusts: the self-signed
|
|
// one it ships with.
|
|
Fingerprint string `yaml:"fingerprint"`
|
|
Every time.Duration `yaml:"every"` // between reads: 60s
|
|
}
|
|
|
|
// Defaults fills in what's left out.
|
|
func (c *Config) Defaults() {
|
|
if c.Type == "" {
|
|
c.Type = FlashArray
|
|
}
|
|
if c.Every == 0 {
|
|
c.Every = time.Minute
|
|
}
|
|
if c.Name == "" {
|
|
if u, err := url.Parse(c.URL); err == nil {
|
|
c.Name = strings.ToLower(u.Hostname())
|
|
}
|
|
}
|
|
}
|
|
|
|
// The two kinds of array.
|
|
const (
|
|
FlashArray = "flasharray"
|
|
FlashBlade = "flashblade"
|
|
)
|
|
|
|
// Client asks one array, read only. It logs in when it has no session and
|
|
// again when the array forgets it. One goroutine uses it.
|
|
type Client struct {
|
|
kind string // FlashArray or FlashBlade: its errors say which
|
|
base string // https://host
|
|
name string
|
|
token string
|
|
hc *http.Client
|
|
version string // the REST version used: the newest 2.x the array offers
|
|
session string // x-auth-token
|
|
}
|
|
|
|
// New checks cfg and reads the token and the CA; it doesn't connect yet.
|
|
func New(cfg Config) (*Client, error) {
|
|
cfg.Defaults()
|
|
k := cfg.Type
|
|
if k != FlashArray && k != FlashBlade {
|
|
return nil, fmt.Errorf("pure: type %q: want flasharray or flashblade", cfg.Type)
|
|
}
|
|
u, err := url.Parse(strings.TrimRight(cfg.URL, "/"))
|
|
if err != nil || u.Scheme != "https" || u.Host == "" {
|
|
return nil, fmt.Errorf("%s: url %q: want https://array", k, cfg.URL)
|
|
}
|
|
b, err := os.ReadFile(cfg.TokenFile)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("%s: the API token: %w", k, err)
|
|
}
|
|
tok := strings.TrimSpace(string(b))
|
|
if tok == "" {
|
|
return nil, fmt.Errorf("%s: the token file is empty", k)
|
|
}
|
|
tc, err := tlspin.Config(cfg.CAFile, cfg.Fingerprint)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("%s: %w", k, err)
|
|
}
|
|
tr := &http.Transport{TLSClientConfig: tc, MaxIdleConns: 4, IdleConnTimeout: time.Minute}
|
|
return &Client{kind: k, base: u.Scheme + "://" + u.Host, name: cfg.Name, token: tok,
|
|
hc: &http.Client{Transport: tr, Timeout: 30 * time.Second}}, nil
|
|
}
|
|
|
|
// Name is what the array is kept under.
|
|
func (c *Client) Name() string { return c.name }
|
|
|
|
// Version is the REST version in use, once logged in.
|
|
func (c *Client) Version() string { return c.version }
|
|
|
|
// StatusError is the array refusing a call.
|
|
type StatusError struct {
|
|
Kind string
|
|
Code int
|
|
Msg string
|
|
}
|
|
|
|
func (e *StatusError) Error() string { return fmt.Sprintf("%s: %d %s", e.Kind, e.Code, e.Msg) }
|
|
|
|
// pickVersion is the newest 2.x the array offers, from /api/api_version.
|
|
func (c *Client) pickVersion(ctx context.Context) (string, error) {
|
|
var v struct {
|
|
Version []string `json:"version"`
|
|
}
|
|
if err := c.do(ctx, http.MethodGet, "/api/api_version", nil, &v); err != nil {
|
|
return "", err
|
|
}
|
|
best, bestMinor := "", -1
|
|
for _, s := range v.Version {
|
|
major, minor, ok := strings.Cut(s, ".")
|
|
if !ok || major != "2" {
|
|
continue
|
|
}
|
|
if m, err := strconv.Atoi(minor); err == nil && m > bestMinor {
|
|
best, bestMinor = s, m
|
|
}
|
|
}
|
|
if best == "" {
|
|
need := "Purity 6.0 or later"
|
|
if c.kind == FlashBlade {
|
|
need = "Purity//FB 3.0 or later"
|
|
}
|
|
return "", fmt.Errorf("%s: the array offers no REST 2 (it offers %s): %s is needed", c.kind, strings.Join(v.Version, ", "), need)
|
|
}
|
|
return best, nil
|
|
}
|
|
|
|
// loginPath is where the token is traded: a FlashArray's is under the
|
|
// version, a FlashBlade's isn't.
|
|
func (c *Client) loginPath(what string) string {
|
|
if c.kind == FlashBlade {
|
|
return "/api/" + what
|
|
}
|
|
return "/api/" + c.version + "/" + what
|
|
}
|
|
|
|
// login trades the API token for a session.
|
|
func (c *Client) login(ctx context.Context) error {
|
|
if c.version == "" {
|
|
v, err := c.pickVersion(ctx)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
c.version = v
|
|
}
|
|
req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.base+c.loginPath("login"), nil)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
req.Header.Set("api-token", c.token)
|
|
resp, err := c.hc.Do(req)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer resp.Body.Close()
|
|
if resp.StatusCode != http.StatusOK {
|
|
msg := "logging in: " + apiError(resp)
|
|
if resp.StatusCode == http.StatusNotFound {
|
|
other := map[string]string{FlashArray: FlashBlade, FlashBlade: FlashArray}[c.kind]
|
|
msg += " (is it a " + other + "? then say type: " + other + ")"
|
|
}
|
|
return &StatusError{Kind: c.kind, Code: resp.StatusCode, Msg: msg}
|
|
}
|
|
_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 1<<16))
|
|
s := resp.Header.Get("x-auth-token")
|
|
if s == "" {
|
|
return fmt.Errorf("%s: logged in, but no x-auth-token came back", c.kind)
|
|
}
|
|
c.session = s
|
|
return nil
|
|
}
|
|
|
|
// pageSize is how many items a list asks for at once.
|
|
const pageSize = 500
|
|
|
|
// maxPages stops a list that never ends: a million of anything.
|
|
const maxPages = 2000
|
|
|
|
// List reads every page of a REST 2 list into out. query is extra
|
|
// parameters (a filter, destroyed=false).
|
|
func List[T any](ctx context.Context, c *Client, path string, query url.Values, out *[]T) error {
|
|
token := ""
|
|
for range maxPages {
|
|
q := url.Values{"limit": {strconv.Itoa(pageSize)}}
|
|
for k, v := range query {
|
|
q[k] = v
|
|
}
|
|
if token != "" {
|
|
q.Set("continuation_token", token)
|
|
}
|
|
var env struct {
|
|
Items []T `json:"items"`
|
|
ContinuationToken string `json:"continuation_token"`
|
|
}
|
|
if err := c.get(ctx, path+"?"+q.Encode(), &env); err != nil {
|
|
return err
|
|
}
|
|
*out = append(*out, env.Items...)
|
|
if env.ContinuationToken == "" || len(env.Items) == 0 {
|
|
return nil
|
|
}
|
|
token = env.ContinuationToken
|
|
}
|
|
return fmt.Errorf("%s %s: over %d pages", c.kind, path, maxPages)
|
|
}
|
|
|
|
// get reads /api/<version><path> into v, logging in first when there's no
|
|
// session and once more when the array has forgotten it.
|
|
func (c *Client) get(ctx context.Context, path string, v any) error {
|
|
if c.session == "" {
|
|
if err := c.login(ctx); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
err := c.do(ctx, http.MethodGet, "/api/"+c.version+path, map[string]string{"x-auth-token": c.session}, v)
|
|
var se *StatusError
|
|
if errors.As(err, &se) && se.Code == http.StatusUnauthorized {
|
|
c.session = ""
|
|
if err := c.login(ctx); err != nil {
|
|
return err
|
|
}
|
|
err = c.do(ctx, http.MethodGet, "/api/"+c.version+path, map[string]string{"x-auth-token": c.session}, v)
|
|
}
|
|
return err
|
|
}
|
|
|
|
func (c *Client) do(ctx context.Context, method, path string, headers map[string]string, v any) error {
|
|
req, err := http.NewRequestWithContext(ctx, method, c.base+path, nil)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
for k, h := range headers {
|
|
req.Header.Set(k, h)
|
|
}
|
|
req.Header.Set("Accept", "application/json")
|
|
resp, err := c.hc.Do(req)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer resp.Body.Close()
|
|
if resp.StatusCode != http.StatusOK {
|
|
return &StatusError{Kind: c.kind, Code: resp.StatusCode, Msg: apiError(resp)}
|
|
}
|
|
if err := json.NewDecoder(io.LimitReader(resp.Body, 256<<20)).Decode(v); err != nil {
|
|
return fmt.Errorf("%s %s: %w", c.kind, strings.SplitN(path, "?", 2)[0], err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// Logout ends the session, when the agent stops.
|
|
func (c *Client) Logout(ctx context.Context) {
|
|
if c.session == "" || c.version == "" {
|
|
return
|
|
}
|
|
_ = c.do(ctx, http.MethodPost, c.loginPath("logout"), map[string]string{"x-auth-token": c.session}, &struct{}{})
|
|
c.session = ""
|
|
}
|
|
|
|
// apiError is the message in a REST 2 error, or the status.
|
|
func apiError(resp *http.Response) string {
|
|
b, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
|
|
var e struct {
|
|
Errors []struct {
|
|
Message string `json:"message"`
|
|
Context string `json:"context"`
|
|
} `json:"errors"`
|
|
}
|
|
if json.Unmarshal(b, &e) == nil && len(e.Errors) > 0 {
|
|
var m []string
|
|
for _, x := range e.Errors {
|
|
if x.Message != "" {
|
|
m = append(m, x.Message)
|
|
}
|
|
}
|
|
sort.Strings(m)
|
|
if len(m) > 0 {
|
|
return strings.Join(m, "; ")
|
|
}
|
|
}
|
|
return strings.TrimSpace(resp.Status)
|
|
}
|