[cooktheryan]

Add opt-in named-volume creation per workload declaration while retaining existing Podman behavior by default. Raw Volumes entries accept create: true alongside their existing name, destination, and mount options. Kube Pods and controller Pod templates can use fetchit.containers.io/create-volumes: "true" to generate missing PVC declarations for their own claim references. Mounts remain container-specific; existing explicit PVC options take precedence within the manifest.

Existing volumes are reused without changing data or metadata, and workload removal retains volumes. This PR does not add destructive volume recreation. Systemd and Quadlet continue using their native volume creation and mount syntax, documented in the new guide.

Add native GitHub Actions coverage on Ubuntu rootful/rootless and Fedora Podman 5 for missing-volume creation, actual mount paths, retained markers on replay, retained volumes after removal, and successful re-addition. Cover raw, generated PVCs, and explicit PVCs. Unit tests cover mixed/default declarations, deduplication, malformed flags and names, inspection errors, controller templates, and SOPS preparation.

Update README, methods, release notes, and Read the Docs with flags, complete mount examples, ownership/permissions considerations, persistence, and existing systemd/Quadlet syntax.

Validation: full Go suite passed with real SOPS/age tools; focused engine tests passed after adding controller/SOPS cases; Linux integration binary compilation and vet passed; strict Sphinx build and actionlint passed. Native runtime checks run in this PR's GitHub Actions.

Related to #152. Deliberate destructive resets remain outside this change.

Summary by Sourcery

Add opt-in persistent volume provisioning for raw and Kubernetes workloads without changing existing volume lifecycle behavior by default.

New Features:

• Add opt-in creation of missing named volumes for raw workloads and missing PVC declarations for annotated Kubernetes workloads and controller pod templates.

Bug Fixes:

• Ensure existing volumes and explicit PVC declarations are reused without altering their data or metadata.

Enhancements:

• Preserve storage across redeployments, workload removal, and subsequent re-addition while retaining container-specific mounts and existing default behavior.

CI:

• Extend native GitHub Actions lifecycle coverage across rootful, rootless, and Fedora Podman environments for volume creation and retention scenarios.

Documentation:

• Document volume creation flags, mount examples, persistence considerations, and native systemd and Quadlet volume syntax.

Tests:

• Add unit and integration coverage for raw volumes, generated and explicit PVCs, controller templates, validation, deduplication, SOPS preparation, mount paths, and retained storage.

[sourcery-ai]

Sorry @cooktheryan, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 6 days and 17 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

Introduces opt-in, non-destructive named-volume creation for raw workloads and annotation-driven PVC generation for Kubernetes workloads, while preserving existing defaults and explicit manifest settings. The PR adds comprehensive unit and Podman lifecycle coverage for creation, mounts, reuse, retention, removal, and re-addition, and documents configuration, persistence, permissions, and native systemd/Quadlet usage.

Sequence diagram for opt-in named-volume lifecycle

sequenceDiagram
    participant Workload as Workload declaration
    participant Engine
    participant Podman
    participant Container

    Workload->>Engine: applyRawInput()
    Engine->>Engine: ensureRawVolumes()
    Engine->>Podman: volumes.Inspect(name)
    alt volume missing
        Engine->>Podman: volumes.Create(name, local, IgnoreIfExists)
    else volume exists
        Engine-->>Engine: reuse unchanged volume
    end
    Engine->>Podman: create workload with mount
    Podman-->>Container: mount volume at destination

Loading

Sequence diagram for annotation-driven PVC generation

sequenceDiagram
    participant Manifest as Kube manifest
    participant Engine
    participant Podman
    participant Workload as Pod or controller template

    Manifest->>Engine: labelKubeManifest()
    Engine->>Engine: addKubeVolumeDeclarations()
    alt create-volumes is true
        Engine->>Engine: collect missing persistentVolumeClaim references
        Engine->>Engine: append PersistentVolumeClaim declarations
    else annotation absent or false
        Engine-->>Engine: preserve manifest declarations
    end
    Engine->>Podman: apply labeled manifest
    Podman-->>Workload: mount declared PVC references

Loading

Flow diagram for retained-volume redeployment

flowchart LR
    A[Opt in to volume creation] --> B{Named volume exists?}
    B -->|No| C[Create volume]
    B -->|Yes| D[Reuse volume unchanged]
    C --> E[Deploy workload with mount]
    D --> E
    E --> F[Remove workload]
    F --> G[Volume retained]
    G --> H[Re-add workload]
    H --> D

Loading

File-Level Changes

Change	Details	Files
Add opt-in named-volume provisioning while preserving existing default behavior and storage.	Extend raw volume declarations with a create flag. Validate names and absolute destinations, deduplicate creation requests, inspect before creating, and treat only not-found as creatable. Use Podman local volumes with IgnoreIfExists and never recreate, relabel, or remove existing volumes. Invoke raw volume preparation before image handling.	pkg/engine/raw.go pkg/engine/volumes.go
Generate missing PVC declarations for opted-in Kubernetes workloads without altering explicit claims or mount configuration.	Recognize the fetchit.containers.io/create-volumes annotation on Pods and Deployment, DaemonSet, and Job templates. Collect PVC references, validate claim names and flags, deduplicate and sort generated claims, and preserve existing PVC documents. Run expansion before manifest labeling so generated claims receive normal workload processing. Cover SOPS-prepared manifests and controller templates.	pkg/engine/kube_labels.go pkg/engine/volumes.go pkg/engine/volumes_test.go
Add lifecycle coverage for volume creation, reuse, retention, and remounting across supported Podman environments.	Test raw, generated-PVC, and explicit-PVC workloads. Verify mounts use the requested container path and data survives reapply, removal, and re-addition. Run the volume lifecycle suite in rootful Ubuntu, rootless Ubuntu, and Fedora Podman CI jobs.	pkg/engine/volumes_integration_test.go .github/workflows/sops.yml
Document the new opt-in storage behavior and supported native alternatives.	Add a dedicated volume guide with raw and Kubernetes examples, persistence semantics, and ownership/permission considerations. Update README, methods, index, and release notes with the feature and existing systemd/Quadlet syntax.	README.md docs/index.rst docs/methods.rst docs/release_notes.rst docs/volumes.rst
Expand unit coverage for validation and edge cases.	Cover default and mixed declarations, deduplication, reuse, inspection failures, malformed names and paths, malformed annotation flags, explicit PVC preservation, controller templates, and SOPS preparation.	pkg/engine/volumes_test.go

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.