Skip to content

VSO CSI driver documentation #691

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 67 commits into
base: main
Choose a base branch
from
Draft

VSO CSI driver documentation #691

wants to merge 67 commits into from

Conversation

digivava
Copy link

@digivava digivava commented Aug 5, 2025 •
edited
Loading

This PR contains documentation for a new feature being added to the VSO Helm chart, a HashiCorp-maintained "CSI driver".

(Do not merge until:

  1. the binary and images are released
  2. the Helm chart has been updated to include the feature)

I also updated other relevant pages to link to it for easier discoverability.

@github-actions GitHub Actions
Copy link

github-actions bot commented Aug 5, 2025 •
edited
Loading

Vercel Previews Deployed

Name Status Preview Updated (UTC)
Dev Portal ✅ Ready (Inspect) Visit Preview Fri Sep 5 17:22:58 UTC 2025
Unified Docs API ✅ Ready (Inspect) Visit Preview Fri Sep 5 17:16:58 UTC 2025

@github-actions GitHub Actions
Copy link

github-actions bot commented Aug 5, 2025 •
edited
Loading

Broken Link Checker

No broken links found! 🎉

@digivava digivava marked this pull request as ready for review August 6, 2025 22:18
@digivava digivava requested a review from a team as a code owner August 6, 2025 22:18
@digivava digivava added the Vault Content update for Vault product docs label Aug 6, 2025
@digivava digivava changed the title [Do Not Merge] VSO CSI driver documentation VSO CSI driver documentation Aug 6, 2025
@digivava digivava marked this pull request as draft August 6, 2025 22:59
schavis
schavis requested changes Aug 7, 2025
View reviewed changes
@digivava digivava requested review from benashz and stevealmyHC August 8, 2025 16:18
@digivava digivava requested a review from schavis August 27, 2025 23:50
schavis
schavis requested changes Sep 3, 2025
View reviewed changes
schavis
schavis requested changes Sep 4, 2025
View reviewed changes
schavis
schavis reviewed Sep 4, 2025
View reviewed changes
@digivava digivava requested a review from schavis September 4, 2025 23:41
tvoran
tvoran reviewed Sep 5, 2025
View reviewed changes
content/vault/v1.20.x/content/docs/deploy/kubernetes/comparisons.mdx Outdated

</Tab>

<Tab heading="I/O, CPU, and memory consumption">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe just "Resource consumption"?

content/vault/v1.20.x/content/docs/deploy/kubernetes/comparisons.mdx Outdated
| Low resource consumption. I/O, CPU, Memory | Yes | Yes | No
| Secret data limited to ephemeral volumes | No, except with CSI driver | Yes | Yes
| Pod Autoscaling dependent on Vault availability | No | Yes | Yes
| Adoption of the K8s operator model | Yes | Yes | No
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does the operator model affect the use case recommendation?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah the intent seems to be covered by "Kubernetes-native" above, so I'll remove this row.

content/vault/v1.20.x/content/docs/deploy/kubernetes/comparisons.mdx Outdated
The [Vault Agent Injector](/vault/docs/platform/k8s/injector) injects Vault Agent sidecar containers into pods.
The Agent containers authenticate with Vault and render secrets to a shared memory volume for consumption by application containers.

**Best for:** Applications requiring dynamic secret rotation or direct Vault Agent functionality.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Vault Secrets Operator does a lot with dynamic secret rotation too (and is arguably better in some cases with the rollout-restart functionality), so I'm not sure that's a standout feature of Vault Agent Injector.

The standout things in my mind for Vault Agent Injector are that Agent's templating can reference multiple Vault secrets in one template, and it probably supports the most auth methods through Agent's auto-auth.

content/vault/v1.20.x/content/docs/deploy/kubernetes/comparisons.mdx

| Limitation | Vault Secrets Operator | Vault Secrets Store CSI provider　| Vault Agent Injector
| ------------------------------------------------- | --------------------------------- | ---------------------------- | --------------
| Simple configuration | Yes | Yes | No
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Simple configuration" is pretty subjective here; I consider all of them complicated in their own ways 🙂. I personally find it more complex to tie multiple yaml configs together for Vault Secrets Operator and CSI Provider, vs having all the config in the deployment yaml annotations. Others may find the Agent templating language more complex 🤷.

We could say something about ease of use in applications instead? e.g. being able to read and use k8s volumes vs only reading from a file with Agent Injector.

content/vault/v1.20.x/content/docs/deploy/kubernetes/comparisons.mdx Outdated

</Tab>

<Tab heading="I/O, CPU, and memory consumption">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe just "Resource consumption"?

content/vault/v1.20.x/content/docs/deploy/kubernetes/comparisons.mdx
Comment on lines +101 to +102
- **Vault Secrets Operator** - Low consumption.
- **Vault Secrets Store CSI provider** - Medium consumption.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are the reasons for the difference in consumption for these two?

content/vault/v1.20.x/content/docs/deploy/kubernetes/comparisons.mdx

- **Vault Secrets Operator** - Low consumption.
- **Vault Secrets Store CSI provider** - Medium consumption.
- **Vault Agent Injector** - High consumption due to the number of sidecar containers per pod.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's just one sidecar and/or one init container per Pod, which aren't running simultaneously; maybe just drop the "per pod" bit?

Side note: Do we have data showing high cpu and memory usage for Agent? The default CPU and memory resource requests are pretty high, but they can be tuned down fairly low IIRC.

content/vault/v1.20.x/content/docs/deploy/kubernetes/comparisons.mdx
Comment on lines +87 to +92
Integrations that use ephemeral storage have variable availability because
secret access depends on Vault availability.

- **Vault Secrets Store CSI provider** - Variable availability.
- **Vault Agent Injector** - Variable availability.
- **Vault Secrets Operator** - Best availability. Kubernetes Secrets act as durable cache.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

secret access depends on Vault availability.

Isn't that true for any of these? i.e. nothing can fetch secrets if Vault is down. If a secret is fetched from Vault and rendered, Vault subsequently going down isn't going to clear the rendered secret for CSI provider or Agent, is it?

Integrations using ephemeral storage means the rendered secret lifecycle is tied to the Pod lifecycle, instead of being independent for VSO, maybe re-frame along those lines?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@tvoran tvoran tvoran left review comments

@schavis schavis schavis approved these changes

@benashz benashz Awaiting requested review from benashz

@stevealmyHC stevealmyHC Awaiting requested review from stevealmyHC

Assignees
No one assigned
Labels
Vault Content update for Vault product docs
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@digivava @tvoran @schavis @stevealmyHC