doc: Add first draft documentation for ArgoCD v2 integration

[flomedja]

Content Description

Adds a new page for v2 of ArgoCD integration.

Preview Link

https://deploy-preview-2071--vcluster-docs-site.netlify.app/docs/platform/next/integrations/argocd/overview

Internal Reference

Closes DOC-1398

AI review: mention @claude in a comment to request a review or changes. See CONTRIBUTING.md for available commands.

FORK LIMITATION: @claude does not work on pull requests opened from forks. GitHub Actions cannot access the required secrets for fork-originated PRs. To use AI review, push your branch directly to this repository.

@netlify /docs

[netlify]

✅ Deploy Preview for vcluster-docs-site ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	aba853c
🔍 Latest deploy log	https://app.netlify.com/projects/vcluster-docs-site/deploys/6a0354efc41eb900083b33c5
😎 Deploy Preview	https://deploy-preview-2071--vcluster-docs-site.netlify.app/docs
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

DOC-1398: First Documentation Draft for enabling feature load testing

[cbron]

Need UI component here, I only see legacy one. And legacy needs to be marked as deprecated.

[djwfyi]

Legacy deprecation is done — legacy.mdx opens with a :::warning Deprecated admonition linking to the new guides. The UI navigation labels (new Connectors tab, ArgoCD Apps tab) still need verification against the actual deployed UI before this merges.

[djwfyi]

I'm going to do a pass. There are some structural issues with the information architecture that need addressing that are really hard to convey in PR comments. I can also weave in fixes for most of the comments from @cbron when I do it.

[djwfyi]

Restructure: single page → focused guides

The original argocd-v2.mdx was trying to be an explanation page, a connector setup guide, an Akuity guide, and an application deployment guide all at once — with three levels of nested tabs as a result. I've split it into a proper folder structure:

platform/integrations/argocd/
  overview.mdx           — explanation: concepts, connectors, registration, when Argo CD vs Akuity
  connect-argocd.mdx     — how-to: standard Argo CD connector end-to-end
  connect-akuity.mdx     — how-to: Akuity connector + agent provisioning
  deploy-applications.mdx — how-to: templates, inline spec, new/existing cluster, target: host
  legacy.mdx             — original project-level integration (deprecated)

The legacy argocd.mdx moves into the folder as legacy.mdx with a deprecation admonition. A netlify.toml redirect sends the old /docs/platform/integrations/argocd URL to the legacy page so existing bookmarks still land somewhere useful.

cbron comments addressed in this pass:

• Control plane cluster added as a fourth feature bullet
• "CLI" tab labels → "Platform UI" / "YAML"
• Agent sizing fields explained with implementation detail (akuityAgentSize is an Akuity API concept; akuityRepoServerMemory sets both requests and limits)
• Disabling warning expanded to explicitly cover vcluster.yaml, VirtualClusterInstance, and Cluster objects (confirmed from controller code)
• "Helm values" replaced with vcluster.yaml throughout
• New-vs-existing cluster tabs added to the UI deployment flow
• target: host given its own subsection with a warning covering access boundaries, prerequisites, and risks
• Legacy doc marked deprecated with links to the new guides

Still needs before merge:

• UI navigation labels (Connectors tab, ArgoCD Apps tab, sidebar label for clusters) need verification against the deployed UI — flagged on the relevant review comments

[djwfyi]

Question for review: platform/how-to/gitops-end-to-end.mdx currently links to the legacy Argo CD integration for the section on enabling ArgoCD on a project and configuring SSO/App Project mapping. I've updated the link to point to legacy.mdx to fix the broken build, but this page likely needs a broader update to cover the new connector-based flow (registering clusters, deploying applications via deploy.argoCD). Should that be in scope for this PR or tracked separately?

[djwfyi]

Question for review: platform/administer/projects/create.mdx has a step that says "there are a couple of other integrations that can be configured" and points to the legacy Argo CD doc. With the new integration, Argo CD connectors are configured at the cluster level rather than the project level, so both the link and the step text are likely stale. Should this step be updated or removed as part of this PR, or tracked separately?

[flomedja]

The options to deploy applications From the UI at creation didn't exist., either for the tenant or the host cluster. Is it something we want to add ?

@cbron @vaidaslamanauskas @andyluak

[cbron]

For tenant clusters yes that is core workflow: I want to deploy this vcluster with this 3 argoApps installed to it.
For host clusters it would just flow through same workflow but with target host. Otherwise I don't think it makes sense to do a direct host cluster deploy tie in at vcluster creation time, those are separate objects.

[andyluak]

This makes sense to me. @vaidaslamanauskas can you also take a look please ?

[djwfyi]

Finding: authType is not a real connector Secret field

While verifying the YAML examples against the controller source, I found that authType is not read by the controller at all. The implementation in pkg/controllers/argocdapplication/helpers.go and argocd_client.go reads token, username, and password directly — if token is set it uses bearer token auth, otherwise it falls back to username/password. There is no authType key in the controller constants.

The original draft included authType: "token"" and authType: "basic"" in both the connect-argocd.mdx and connect-akuity.mdx YAML examples, and listed it as a required field in the reference tables. These have been removed in the latest commit. The conditional language in the token, username, and password table rows has been updated to reflect how the controller actually selects the auth method.

[cbron]

Looks like everything I commented on is resolved except for app deploy at creation time. Feel free to merge when thats added and docs team approves.