docs: expand volumes chapter with storage patterns and advanced topics#4
Merged
Conversation
AS IS: chapter covered basic PVC usage but omitted emptyDir tmpfs, the full accessModes matrix, reclaim policy implications, and had no k9s workflows; the volumeClaimTemplate best practice lacked explanation, and a k9s step incorrectly described a bare Pod as a Deployment TO BE: add emptyDir medium:Memory with its Secret-volume connection, a three-mode accessModes table with backend requirements, a Reclaim policy section comparing Delete vs Retain, step-by-step k9s workflows for PVC inspection and persistence verification, and fix the bare-Pod restart behavior in the k9s steps TASK # N/A
AS IS: prose had minor inaccuracies (Pod restart vs container recreate), accessModes table omitted RWOP, kubectl steps had no wait commands causing potential race conditions, reclaim policy section omitted VolumeBindingMode which is a common source of Pending PVC confusion, and k9s workflows lacked StorageClass inspection and cleanup verification steps TO BE: fix ephemeral filesystem description to mention image layer and container recreation, add RWOP mode with single-writer use case, add kubectl wait commands for reliable sequencing, add VolumeBindingMode section with Immediate vs WaitForFirstConsumer explanation, and extend k9s workflows to cover StorageClass inspection and cleanup verification TASK # N/A
AS IS: chapter had no guidance on resizing a full PVC, leaving readers without recourse when storage runs out in production TO BE: add a Volume expansion section covering how to check if a StorageClass allows expansion, how to patch a PVC to a larger size, what Kubernetes does during the resize, and that shrinking is not supported — so readers can handle capacity issues without recreating their storage TASK # N/A
AS IS: intro used an abstract sentence to describe when Volumes vs PersistentVolumes survive; volume expansion gave no guidance on when a Pod restart is actually needed. TO BE: intro now leads with a survival-layer table and a concrete local/external drive analogy; volume expansion section distinguishes online vs offline expansion and points to FileSystemResizePending as the actionable indicator. TASK # N/A Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
AS IS: the kubeadm StorageClass warning appeared after Volume Expansion, after readers had already tried (and likely failed) the PVC exercise; ConfigMap/Secret volume types were not mentioned; hostPath had no explanation; dynamic vs static provisioning was not covered. TO BE: move the kubeadm warning before the runnable manifest so readers set up a StorageClass first; add ConfigMap/Secret bridging note with subPath live-update caveat; add dynamic vs static provisioning table; add multi-node local-path debugging hints; clarify hostPath definition and add subPath best practice bullet. TASK # N/A Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
AS IS: the chapter dives straight into emptyDir without telling readers what it covers or what to skip; the mental model for Pod→PVC→PV is spread across several paragraphs; the volume expansion section appears at the same visual weight as core concepts. TO BE: add a scope paragraph so readers know what the chapter covers before they start; condense the storage chain into a short bullet list to reinforce the mental model; mark volume expansion as "Advanced" with a skip note; reframe the hostPath best practice positively. TASK # N/A Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
AS IS: both sections only showed abstract YAML snippets without volumeMounts or runnable examples; readers had no way to observe the behaviors being described. TO BE: add a sidecar manifest and three-step exercise for emptyDir that proves volume lifetime (survives container restart, dies with Pod); add a kubectl exec walkthrough for ConfigMap/Secret volumes showing how keys land as files on disk. Move config volumes into their own section so the emptyDir section stays focused. TASK # N/A Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
AS IS: data-pvc.yaml contained both the PVC and the Pod in one file, implying they share a lifecycle — readers applying this pattern in production risk accidentally deleting data when they delete a workload. TO BE: extract the Pod into data-writer.yaml so PVC and workload are managed independently; update all kubectl commands, k9s steps, and cleanup sections in volumes.md and statefulset.md to match. TASK # N/A Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
AS IS: the PVC example omits storageClassName without explanation, leaving readers unsure how StorageClass — described in the flow above — actually appears in a manifest. TO BE: add a comment in the YAML and a short explanation showing that omitting storageClassName uses the cluster default, with an explicit example for when a specific storage tier is needed. TASK # N/A Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
AS IS: the reclaim policy section opens with an abstract definition that doesn't connect to what the reader just observed in the exercise, leaving them unsure why data survived Pod deletion or when it would not. TO BE: open with the exercise result and a survival table covering all four cases (same PVC remounted, no mount, PVC deleted, emptyDir); name local-path's Delete default so readers know cleanup actually destroys data. TASK # N/A Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
AS IS: the note about Deployments was a single sentence that didn't explain the implication — readers could unknowingly deploy a database as a multi-replica Deployment and corrupt data. TO BE: expand into a paragraph with a table contrasting read-only vs write-heavy workloads, and point to StatefulSet volumeClaimTemplates as the correct pattern for workloads that need per-replica storage. TASK # N/A Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
emptyDir medium: Memory(tmpfs) with Secret-volume connectionkubectl waitcommands to prevent race conditions in lab stepsallowVolumeExpansion, patch PVC, shrink limitation)volumeClaimTemplatebest practice with concrete explanationTest plan
manifests/config-and-data/data-pvc.yamland run the lab verification commands:pvc,:pv,:sc) work as describedkubectl waitcommands behave correctly after apply and delete🤖 Generated with Claude Code