# Volume attributes

A read-only volume is described by its `volumeAttributes`, in the `csi`
block of an inline volume or of a `ReadOnlyMany` `PersistentVolume`. The
driver refuses an unknown attribute, a malformed value, and a volume
without `readOnly: true`, with a message that names the attribute.

| Attribute | Values | Default |
|---|---|---|
| `url` | A URL git accepts: `https://`, `ssh://`, `git://`, `file://`, or `user@host:path`. Required. | none |
| `ref` | A branch or tag name. | `main` |
| `pull` | A Go duration such as `5m` or `30s`, `on-demand`, or `never`. | `5m` |
| `depth` | A whole number of commits, or `0` for a full clone. It applies to the first fetch of a repository on a node. | `0` |
| `offline` | `refuse` or `allowStale`. | `refuse` |
| `webhookSecret` | The name of a `Secret` in the claim's namespace. The controller verifies a forge's push against its `secret` key before it demands a pull on this volume. | none |

`pull` takes one of three values.

| Value | Meaning |
|---|---|
| `never` | No timer and no demand. The volume holds the commit it staged for its whole life. |
| `on-demand` | No timer. The volume pulls only when something demands it. An inline volume refuses this value, because a demand is an annotation on a `PersistentVolume` and an inline volume has none. |
| A duration such as `5m` | The volume pulls at least that often, and it pulls when something demands it. |

Two URL shapes are refused before git sees them. A URL that starts with
a dash reads as an option to git. A URL of the form
`<transport>::<address>` names a helper program git runs. The driver
fetches as root on the node and the URL comes from a pod spec, so
neither is accepted.

## Access modes

The access mode of a `PersistentVolume` decides what the driver stages.
The kubelet sends `ReadWriteOncePod` as the CSI mode
`SINGLE_NODE_SINGLE_WRITER`, and `ReadOnlyMany` as
`MULTI_NODE_READER_ONLY`. The driver also stages a read-only claim under
`SINGLE_NODE_READER_ONLY`, which the kubelet does not send. It refuses
every other mode, and the message names the modes it serves. An inline
volume carries no access mode and is always read-only.

| Access mode | What the driver stages |
|---|---|
| `ReadWriteOncePod` | A writeable volume. |
| `ReadOnlyMany` | A read-only claim, published to every pod on the node that mounts it. |

A read-only claim takes `pull`, `depth`, `offline`, and
`webhookSecret`. A writeable volume refuses all four, because it
follows its ref at stage alone. A pod mounts a read-only claim with
`readOnly: true` on its `persistentVolumeClaim` volume, or the publish
is refused.

## Credentials

An inline volume names its `Secret` with `nodePublishSecretRef`, in the
pod's namespace. A `PersistentVolume` names one `Secret` in both
`nodeStageSecretRef` and `nodePublishSecretRef`. The stage fetches with
the first. The kubelet sends the second with every publish, and again
on each pod sync, which is how a restarted driver takes the credential
back. A publish whose `Secret` differs from the stage's is refused. The
driver reads these keys:

| Key | Use |
|---|---|
| `ssh-privatekey` | The private key for an SSH URL. |
| `known_hosts` | The host keys ssh accepts. With it, the host key must match. Without it, ssh accepts the first key and refuses a change. |
| `token` | The password for an HTTPS URL. |
| `username` | The user for the token. Default `git`. |

A `Secret` with neither `ssh-privatekey` nor `token` is refused.

## Events

| Reason | When |
|---|---|
| `GitVolumeRefused` | The publish was refused. The message says why. |
| `GitVolumeStale` | The fetch failed and `offline: allowStale` published the node's copy. |
| `GitFetchFailed` | A fetch failed after one that worked. Posted once, until a fetch succeeds. |
| `GitFetchRecovered` | A fetch worked after a `GitFetchFailed` or a `GitVolumeStale`. A `Normal` event, which shows when the fault ended. |
| `GitVolumeNoPublishSecret` | The `PersistentVolume` names `nodeStageSecretRef` and no `nodePublishSecretRef`, so a restart of the driver loses the credential. Posted once for each stage and for each restart. |

A repeat of the same event on the same object, with the same message,
within 10 minutes of the last one, increases the count of the event
already posted and posts no new one. The kubelet retries a refused
mount with a backoff that grows to about two minutes, so a pod that is
refused for an hour carries one `GitVolumeRefused` line, such as
`(x37 over 1h)`. The API server deletes an event one hour after its
last change.

## The gauge

`git_csi_volume_abnormal`, labeled `namespace` and `volume`, is one
after a stale publish and after a failed fetch, until a fetch succeeds.
The driver's log says what went wrong when the gauge rises and when it
falls. `NodeGetVolumeStats` reports the tree's size as used.