banshee/containers-collection/containers/kubernetes/https/persistent-volume-claims

Kubernetes volume claims, by its API

Returns, for each persistent volume claim of a Kubernetes cluster, or of one namespace, whether it is bound to a volume, waits for one or has lost it, and the capacity of its volume, read from the API server with the token of a read-only service account. Two watches are offered, each one set on the probe.

Versions

Generic: GET /api/v1/persistentvolumeclaims and the fields read (status.phase, status.capacity) are those of the core API, stable in every Kubernetes still supported. It stays at the common level.

How it works

GET https://<host:address>:6443/api/v1/persistentvolumeclaims?limit=500, or /api/v1/namespaces/<namespace>/persistentvolumeclaims when the variable kubernetes:namespace names one, the token in the header Authorization: Bearer <token>, page by page, following metadata.continue to the last page.

{"items": [{"metadata": {"namespace": "shop", "name": "data-db-0"}, "status": {"phase": "Bound", "capacity": {"storage": "10Gi"}}}], "metadata": {"continue": ""}}

A claim is named <namespace>/<claim> (shop/data-db-0).
The phase is Kubernetes's: Pending, waiting for a volume; Bound; Lost, its volume gone.
The capacity is that of the volume bound, as Kubernetes writes it (10Gi); a claim not bound returns none.
A code 401 (the token refused) or 403 (the account may not list the claims) stops the collector misconfigured; any other code but 200 stops it unreachable. No claim at all is an answer.

The token comes from protocol:http:token, a secret variable: it only goes in the header. The answer is not secret.

Prerequisites

The address of the API server, its port and its certificate, as for the collector of the nodes.
A service account allowed to list the claims and nothing else, and its long-lived token in protocol:http:token. The service account and its token Secret are those of the documentation of the collector of the nodes; the rule:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: banshee-volume-claims
rules:
  - apiGroups: [""]
    resources: ["persistentvolumeclaims"]
    verbs: ["list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: banshee-volume-claims
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: banshee-volume-claims
subjects:
  - kind: ServiceAccount
    name: banshee
    namespace: monitoring

For one namespace only, set in kubernetes:namespace, a Role and a RoleBinding in that namespace, the same rule, in place of the ClusterRole and its binding.

Variables

Name	Label	Says	Default
`kubernetes:port`	API port	the port of the API server	`6443`
`kubernetes:namespace`	Namespace	only the claims of this namespace	empty: all namespaces

Outputs

Name	Label	Unit	Per instance
`phase`	Phase	—	yes, per claim
`capacity`	Capacity	—	yes, per claim

Watches

Name	Title	Kind	Defaults	Checked by default
`lost`	Volume lost	state to avoid, on `phase`	critical on `Lost`	yes
`pending`	Claim not bound	state to avoid, on `phase`	warning on `Pending`, for 15 min	yes

A storage class whose binding waits for the first consumer (volumeBindingMode: WaitForFirstConsumer, the default of many) leaves a claim Pending until a pod uses it: such a claim, made ahead, raises pending until then; the selection of the probe leaves it out.

Limits

How full a volume is is not served by the API server: it is the kubelet's, or the storage's own collector.
The persistent volumes themselves (Released, Failed) are not read: a claim is what a workload depends on.
The address is written into the URL as is: an IPv6 address must be given as a name.
Sources: the phases Pending, Bound, Lost and capacity, "the actual resources of the underlying volume", are those of the Kubernetes API reference (PersistentVolumeClaim, core/v1). Not run against a cluster.