From c621c53f1c4d3ab3392868f2b04dfdafdf7562b9 Mon Sep 17 00:00:00 2001 From: Florian Medja Date: Thu, 7 May 2026 15:41:52 -0400 Subject: [PATCH 1/5] doc: Add first draft documentation for ArgoCD v2 integration --- package-lock.json | 79 +++- platform/integrations/argocd-v2.mdx | 659 ++++++++++++++++++++++++++++ 2 files changed, 727 insertions(+), 11 deletions(-) create mode 100644 platform/integrations/argocd-v2.mdx diff --git a/package-lock.json b/package-lock.json index 92edb2a48..60382df55 100644 --- a/package-lock.json +++ b/package-lock.json @@ -185,6 +185,7 @@ "resolved": "https://registry.npmjs.org/@algolia/client-search/-/client-search-5.25.0.tgz", "integrity": "sha512-9rUYcMIBOrCtYiLX49djyzxqdK9Dya/6Z/8sebPn94BekT+KLOpaZCuc6s0Fpfq7nx5J6YY5LIVFQrtioK9u0g==", "license": "MIT", + "peer": true, "dependencies": { "@algolia/client-common": "5.25.0", "@algolia/requester-browser-xhr": "5.25.0", @@ -357,6 +358,7 @@ "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.27.3.tgz", "integrity": "sha512-hyrN8ivxfvJ4i0fIJuV4EOlV0WDMz5Ui4StRTgVaAvWeiRCilXgwVvxJKtFQ3TKtHgJscB2YiXKGNJuVwhQMtA==", "license": "MIT", + "peer": true, "dependencies": { "@ampproject/remapping": "^2.2.0", "@babel/code-frame": "^7.27.1", @@ -2139,6 +2141,7 @@ } ], "license": "MIT", + "peer": true, "engines": { "node": ">=18" }, @@ -2161,6 +2164,7 @@ } ], "license": "MIT", + "peer": true, "engines": { "node": ">=18" } @@ -2241,6 +2245,7 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", "license": "MIT", + "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -2604,6 +2609,7 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", "license": "MIT", + "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -3283,6 +3289,7 @@ "resolved": "https://registry.npmjs.org/@docusaurus/core/-/core-3.8.0.tgz", "integrity": "sha512-c7u6zFELmSGPEP9WSubhVDjgnpiHgDqMh1qVdCB7rTflh4Jx0msTYmMiO91Ez0KtHj4sIsDsASnjwfJ2IZp3Vw==", "license": "MIT", + "peer": true, "dependencies": { "@docusaurus/babel": "3.8.0", "@docusaurus/bundler": "3.8.0", @@ -3359,6 +3366,7 @@ "resolved": "https://registry.npmjs.org/@docusaurus/faster/-/faster-3.8.0.tgz", "integrity": "sha512-v9+8rT2gw/4zIRBwc4fIVhrTH/yFVDQgJgyYZjqr3fgojOypdQCOwkN6Z8dOwTei4/zo+b/zDPB4x1UvghJZRg==", "license": "MIT", + "peer": true, "dependencies": { "@docusaurus/types": "3.8.0", "@rspack/core": "^1.3.10", @@ -3487,6 +3495,7 @@ "resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-docs/-/plugin-content-docs-3.8.0.tgz", "integrity": "sha512-fRDMFLbUN6eVRXcjP8s3Y7HpAt9pzPYh1F/7KKXOCxvJhjjCtbon4VJW0WndEPInVz4t8QUXn5QZkU2tGVCE2g==", "license": "MIT", + "peer": true, "dependencies": { "@docusaurus/core": "3.8.0", "@docusaurus/logger": "3.8.0", @@ -4075,6 +4084,7 @@ "resolved": "https://registry.npmjs.org/@docusaurus/theme-common/-/theme-common-3.8.0.tgz", "integrity": "sha512-YqV2vAWpXGLA+A3PMLrOMtqgTHJLDcT+1Caa6RF7N4/IWgrevy5diY8oIHFkXR/eybjcrFFjUPrHif8gSGs3Tw==", "license": "MIT", + "peer": true, "dependencies": { "@docusaurus/mdx-loader": "3.8.0", "@docusaurus/module-type-aliases": "3.8.0", @@ -4204,6 +4214,7 @@ "resolved": "https://registry.npmjs.org/@docusaurus/utils/-/utils-3.8.0.tgz", "integrity": "sha512-2wvtG28ALCN/A1WCSLxPASFBFzXCnP0YKCAFIPcvEb6imNu1wg7ni/Svcp71b3Z2FaOFFIv4Hq+j4gD7gA0yfQ==", "license": "MIT", + "peer": true, "dependencies": { "@docusaurus/logger": "3.8.0", "@docusaurus/types": "3.8.0", @@ -4771,6 +4782,7 @@ "resolved": "https://registry.npmjs.org/@mdx-js/react/-/react-3.1.0.tgz", "integrity": "sha512-QjHtSaoameoalGnKDT3FoIl4+9RwyTmo9ZJGBdLOks/YOiWHoRDI3PUwEzOE7kEmGcV3AFcp9K6dYu9rEuKLAQ==", "license": "MIT", + "peer": true, "dependencies": { "@types/mdx": "^2.0.0" }, @@ -5419,6 +5431,7 @@ "resolved": "https://registry.npmjs.org/@rspack/core/-/core-1.3.12.tgz", "integrity": "sha512-mAPmV4LPPRgxpouUrGmAE4kpF1NEWJGyM5coebsjK/zaCMSjw3mkdxiU2b5cO44oIi0Ifv5iGkvwbdrZOvMyFA==", "license": "MIT", + "peer": true, "dependencies": { "@module-federation/runtime-tools": "0.14.0", "@rspack/binding": "1.3.12", @@ -5719,6 +5732,7 @@ "resolved": "https://registry.npmjs.org/@svgr/core/-/core-8.1.0.tgz", "integrity": "sha512-8QqtOQT5ACVlmsvKOJNEaWmRPmcojMOzCz4Hs2BGG/toAp/K38LcsMRyLp349glq5AzJbCEeimEoxaX6v/fLrA==", "license": "MIT", + "peer": true, "dependencies": { "@babel/core": "^7.21.3", "@svgr/babel-preset": "8.1.0", @@ -5823,6 +5837,7 @@ "integrity": "sha512-g4mThMIpWbNhV8G2rWp5a5/Igv8/2UFRJx2yImrLGMgrDDYZIopqZ/z0jZxDgqNA1QDx93rpwNF7jGsxVWcMlA==", "hasInstallScript": true, "license": "Apache-2.0", + "peer": true, "dependencies": { "@swc/counter": "^0.1.3", "@swc/types": "^0.1.21" @@ -6232,7 +6247,6 @@ "integrity": "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@babel/code-frame": "^7.10.4", "@babel/runtime": "^7.12.5", @@ -6253,7 +6267,6 @@ "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", "dev": true, "license": "MIT", - "peer": true, "engines": { "node": ">=8" } @@ -6264,7 +6277,6 @@ "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==", "dev": true, "license": "MIT", - "peer": true, "engines": { "node": ">=10" }, @@ -6278,7 +6290,6 @@ "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "ansi-regex": "^5.0.1", "ansi-styles": "^5.0.0", @@ -6293,8 +6304,7 @@ "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz", "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==", "dev": true, - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@testing-library/jest-dom": { "version": "6.9.1", @@ -6356,8 +6366,7 @@ "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz", "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==", "dev": true, - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@types/body-parser": { "version": "1.19.5", @@ -7262,6 +7271,7 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", "license": "MIT", + "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -7338,6 +7348,7 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz", "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==", "license": "MIT", + "peer": true, "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", @@ -7383,6 +7394,7 @@ "resolved": "https://registry.npmjs.org/algoliasearch/-/algoliasearch-5.25.0.tgz", "integrity": "sha512-n73BVorL4HIwKlfJKb4SEzAYkR3Buwfwbh+MYxg2mloFph2fFGV58E90QTzdbfzWrLn4HE5Czx/WTjI8fcHaMg==", "license": "MIT", + "peer": true, "dependencies": { "@algolia/client-abtesting": "5.25.0", "@algolia/client-analytics": "5.25.0", @@ -7918,6 +7930,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "baseline-browser-mapping": "^2.9.0", "caniuse-lite": "^1.0.30001759", @@ -8212,6 +8225,33 @@ "url": "https://github.com/sponsors/fb55" } }, + "node_modules/chevrotain": { + "version": "11.1.1", + "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-11.1.1.tgz", + "integrity": "sha512-f0yv5CPKaFxfsPTBzX7vGuim4oIC1/gcS7LUGdBSwl2dU6+FON6LVUksdOo1qJjoUvXNn45urgh8C+0a24pACQ==", + "license": "Apache-2.0", + "peer": true, + "dependencies": { + "@chevrotain/cst-dts-gen": "11.1.1", + "@chevrotain/gast": "11.1.1", + "@chevrotain/regexp-to-ast": "11.1.1", + "@chevrotain/types": "11.1.1", + "@chevrotain/utils": "11.1.1", + "lodash-es": "4.17.23" + } + }, + "node_modules/chevrotain-allstar": { + "version": "0.3.1", + "resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.3.1.tgz", + "integrity": "sha512-b7g+y9A0v4mxCW1qUhf3BSVPg+/NvGErk/dOkrDaHA0nQIQGAtrOjlX//9OQtRlSCy+x9rfB5N8yC71lH1nvMw==", + "license": "MIT", + "dependencies": { + "lodash-es": "^4.17.21" + }, + "peerDependencies": { + "chevrotain": "^11.0.0" + } + }, "node_modules/chokidar": { "version": "3.6.0", "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz", @@ -8779,6 +8819,7 @@ "integrity": "sha512-Sz4PP4ZA+Rq4II21qkNqOEDTDrCvcANId3xpIgB34NDkWc3UduWj2dqEtN9yZIq8Dk3HyPI33x9sqqU5C8sr0g==", "hasInstallScript": true, "license": "MIT", + "peer": true, "funding": { "type": "opencollective", "url": "https://opencollective.com/core-js" @@ -9003,6 +9044,7 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", "license": "MIT", + "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -9370,6 +9412,7 @@ "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.33.3.tgz", "integrity": "sha512-Gej7U+OKR+LZ8kvX7rb2HhCYJ0IhvEFsnkud4SB1PR+BUY/TsSO0dmOW59WEVLu51b1Rm+gQRKoz4bLYxGSZ2g==", "license": "MIT", + "peer": true, "engines": { "node": ">=0.10" } @@ -9779,6 +9822,7 @@ "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz", "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==", "license": "ISC", + "peer": true, "engines": { "node": ">=12" } @@ -10276,8 +10320,7 @@ "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz", "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==", "dev": true, - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/dom-converter": { "version": "0.2.0", @@ -11176,6 +11219,7 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz", "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", "license": "MIT", + "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -13500,6 +13544,7 @@ "integrity": "sha512-Cvc9WUhxSMEo4McES3P7oK3QaXldCfNWp7pl2NNeiIFlCoLr3kfq9kb1fxftiwk1FLV7CvpvDfonxtzUDeSOPg==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "cssstyle": "^4.2.1", "data-urls": "^5.0.0", @@ -14151,7 +14196,6 @@ "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==", "dev": true, "license": "MIT", - "peer": true, "bin": { "lz-string": "bin/bin.js" } @@ -16713,6 +16757,7 @@ "resolved": "https://registry.npmjs.org/mobx/-/mobx-6.13.7.tgz", "integrity": "sha512-aChaVU/DO5aRPmk1GX8L+whocagUUpBQqoPtJk+cm7UOXUk87J4PeWCh6nNmTTIfEhiR9DI/+FnA8dln/hTK7g==", "license": "MIT", + "peer": true, "funding": { "type": "opencollective", "url": "https://opencollective.com/mobx" @@ -17002,6 +17047,7 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz", "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", "license": "MIT", + "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -17763,6 +17809,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", @@ -18666,6 +18713,7 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", "license": "MIT", + "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -19523,6 +19571,7 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz", "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", "license": "MIT", + "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -19596,6 +19645,7 @@ "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz", "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==", "license": "MIT", + "peer": true, "dependencies": { "loose-envify": "^1.1.0" }, @@ -19608,6 +19658,7 @@ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz", "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==", "license": "MIT", + "peer": true, "dependencies": { "loose-envify": "^1.1.0", "scheduler": "^0.23.2" @@ -19664,6 +19715,7 @@ "resolved": "https://registry.npmjs.org/@docusaurus/react-loadable/-/react-loadable-6.0.0.tgz", "integrity": "sha512-YMMxTUQV/QFSnbgrP3tjDzLHRg7vsbMn8e9HAa8o/1iXoiomo48b7sk/kkmWEuWNDPJVlKSJRB6Y2fHqdJk+SQ==", "license": "MIT", + "peer": true, "dependencies": { "@types/react": "*" }, @@ -19692,6 +19744,7 @@ "resolved": "https://registry.npmjs.org/react-router/-/react-router-5.3.4.tgz", "integrity": "sha512-Ys9K+ppnJah3QuaRiLxk+jDWOR1MekYQrlytiXxC1RyfbdsZkS5pvKAzCCr031xHixZwpnsYNT5xysdFHQaYsA==", "license": "MIT", + "peer": true, "dependencies": { "@babel/runtime": "^7.12.13", "history": "^4.9.0", @@ -20672,6 +20725,7 @@ "resolved": "https://registry.npmjs.org/sass/-/sass-1.89.0.tgz", "integrity": "sha512-ld+kQU8YTdGNjOLfRWBzewJpU5cwEv/h5yyqlSeJcj6Yh8U4TDA9UA5FPicqDz/xgRPWRSYIQNiFks21TbA9KQ==", "license": "MIT", + "peer": true, "dependencies": { "chokidar": "^4.0.0", "immutable": "^5.0.2", @@ -21754,6 +21808,7 @@ "resolved": "https://registry.npmjs.org/styled-components/-/styled-components-6.1.18.tgz", "integrity": "sha512-Mvf3gJFzZCkhjY2Y/Fx9z1m3dxbza0uI9H1CbNZm/jSHCojzJhQ0R7bByrlFJINnMzz/gPulpoFFGymNwrsMcw==", "license": "MIT", + "peer": true, "dependencies": { "@emotion/is-prop-valid": "1.2.2", "@emotion/unitless": "0.8.1", @@ -22624,6 +22679,7 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz", "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", "license": "MIT", + "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -22860,6 +22916,7 @@ "resolved": "https://registry.npmjs.org/webpack/-/webpack-5.105.0.tgz", "integrity": "sha512-gX/dMkRQc7QOMzgTe6KsYFM7DxeIONQSui1s0n/0xht36HvrgbxtM1xBlgx596NbpHuQU8P7QpKwrZYwUX48nw==", "license": "MIT", + "peer": true, "dependencies": { "@types/eslint-scope": "^3.7.7", "@types/estree": "^1.0.8", diff --git a/platform/integrations/argocd-v2.mdx b/platform/integrations/argocd-v2.mdx new file mode 100644 index 000000000..17aabf9b8 --- /dev/null +++ b/platform/integrations/argocd-v2.mdx @@ -0,0 +1,659 @@ +--- +title: Argo CD Integration v2 +sidebar_label: Argo CD v2 +sidebar_position: 2 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Flow, { Step } from "@site/src/components/Flow"; +import NavStep from "@site/src/components/NavStep"; +import Button from "@site/src/components/Button"; +import Label from "@site/src/components/Label"; +import FeatureTable from '@site/src/components/FeatureTable'; + + + +The Argo CD Integration v2 connects vCluster Platform to an Argo CD or [Akuity](https://akuity.io) instance using declarative *connectors*. A connector is a Kubernetes Secret stored in the Platform namespace that holds the credentials and endpoint for your Argo CD server. Once a connector exists, vCluster Platform automatically registers tenant clusters and Control Plane Clusters with Argo CD and manages Argo CD Applications on their behalf. + +This enables a fully GitOps-driven workflow with no manual cluster imports or Argo CD UI configuration: + +- **Connector-based cluster registration**: Clusters self-register with Argo CD when you reference a connector by name. No manual import is needed. +- **Akuity support**: In addition to self-hosted Argo CD servers, the integration supports [Akuity](https://akuity.io). Platform fetches and applies the Akuity agent manifest to each registered cluster automatically. +- **Declarative application deployment**: Define Argo CD Applications directly in your vCluster configuration. Platform creates and syncs them without requiring access to the Argo CD UI. + +## Prerequisites + +- vCluster Platform running with admin access +- A self-hosted Argo CD server **or** an Akuity organization with an active Argo CD instance + +### Argo CD API token permissions + +The API token used in the Argo CD connector must have the following RBAC permissions on the Argo CD server. Platform uses these to register clusters and manage Applications on your behalf. + +Create a dedicated role in your Argo CD `argocd-rbac-cm` ConfigMap and generate a token for it: + +```yaml +policy.csv: | + p, role:vcluster-platform, clusters, get, *, allow + p, role:vcluster-platform, clusters, create, *, allow + p, role:vcluster-platform, clusters, update, *, allow + p, role:vcluster-platform, clusters, delete, *, allow + p, role:vcluster-platform, applications, get, */*, allow + p, role:vcluster-platform, applications, create, */*, allow + p, role:vcluster-platform, applications, update, */*, allow + p, role:vcluster-platform, applications, delete, */*, allow +``` + +| Resource | Actions | Why | +|----------|---------|-----| +| `clusters` | `get`, `create`, `update`, `delete` | Register and deregister tenant clusters and Control Plane Clusters | +| `applications` | `get`, `create`, `update`, `delete` | Create and sync Argo CD Applications across all projects (`*/*`) | + +### Akuity API key permissions + +The Akuity API key used in the Akuity connector must have a [custom role](https://docs.akuity.io/organizations/custom-roles/) with the following permissions on the target Argo CD instance. +The built-in **Owner** role satisfies all of these. If you need least-privilege access, create a custom role with only the permissions below. + +| Resource | Permission | Why | +|----------|------------|-----| +| Argo CD Cluster | `Get` | Fetch cluster registration state and agent manifests | +| Argo CD Cluster | `Create` | Register new tenant clusters and Control Plane Clusters | +| Argo CD Cluster | `Update` | Update cluster registration when connector or access key changes | +| Argo CD Cluster | `Delete` | Deregister clusters when the integration is disabled | + +See [Akuity API key documentation](https://docs.akuity.io/organizations/api-keys) for instructions on creating an API key and attaching a custom role to it. + +## Step 1: Create a connector + +A connector is a Kubernetes Secret in the Platform namespace labeled `loft.sh/connector-type: argocd`. Platform discovers connectors by this label and makes them available by name to any cluster in the platform. + + + + + + + Click and select the tab. + + + Click . + + + In the field, enter a human-readable name for the connector. + The is auto-generated from the display name and is used to reference this connector from clusters. + + + **For Akuity only:** enable the toggle, then fill in: + - : your Akuity organization ID + - : the Argo CD instance ID within your organization + - and : your Akuity API key credentials + + + In the field, enter the URL of your Argo CD server. + + + If Argo CD is installed in a namespace other than `argocd`, update the field. + + + Select an authentication method and fill in the credentials: + - : paste your token in the field. + - : fill in and . + + + **For Akuity only:** in the section, select the appropriate for the cluster workload. Optionally override and for the `argocd-repo-server`. + + + Click . + + + + + + + + + +Argo CD supports two authentication methods for the API, controlled by the `authType` field. + + + + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: argocd-main + namespace: loft + labels: + loft.sh/connector-type: argocd +type: Opaque +stringData: + authType: "token" + server: "https://argocd.example.com" + token: "" + namespace: "argocd" + insecure: "false" +``` + + + + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: argocd-main + namespace: loft + labels: + loft.sh/connector-type: argocd +type: Opaque +stringData: + authType: "basic" + server: "https://argocd.example.com" + username: "" + password: "" + namespace: "argocd" + insecure: "false" +``` + + + + +| Field | Required | Description | +|-------|----------|-------------| +| `authType` | Yes | Argo CD authentication method: `"token"` or `"basic"` | +| `server` | Yes | Full URL of the Argo CD API server | +| `token` | If `authType` is `"token"` | Argo CD API bearer token | +| `username` | If `authType` is `"basic"` | Argo CD username | +| `password` | If `authType` is `"basic"` | Argo CD password | +| `namespace` | No | Namespace where Argo CD is installed. Defaults to `argocd` | +| `insecure` | No | Set to `"true"` to skip TLS verification. Defaults to `"false"` | +| `caData` | No | Base64-encoded CA certificate for custom TLS verification | + + + + +Set `connectorType: "akuity"` to use Akuity. Platform contacts the Akuity API to register clusters and fetches the agent manifest for installation on each registered cluster. + +Akuity supports two authentication methods for the Argo CD API, controlled by the `authType` field. + + + + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: akuity-prod + namespace: loft + labels: + loft.sh/connector-type: argocd +type: Opaque +stringData: + connectorType: "akuity" + authType: "token" + server: "https://.cd.akuity.cloud/" + token: "" + namespace: "argocd" + insecure: "false" + akuityOrgId: "" + akuityInstanceId: "" + akuityApiKeyId: "" + akuityApiKeySecret: "" + akuityAgentSize: "CLUSTER_SIZE_MEDIUM" + akuityRepoServerReplicas: "1" + akuityRepoServerMemory: "1Gi" +``` + + + + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: akuity-prod + namespace: loft + labels: + loft.sh/connector-type: argocd +type: Opaque +stringData: + connectorType: "akuity" + authType: "basic" + server: "https://.cd.akuity.cloud/" + username: "" + password: "" + namespace: "argocd" + insecure: "false" + akuityOrgId: "" + akuityInstanceId: "" + akuityApiKeyId: "" + akuityApiKeySecret: "" + akuityAgentSize: "CLUSTER_SIZE_MEDIUM" + akuityRepoServerReplicas: "1" + akuityRepoServerMemory: "1Gi" +``` + + + + +| Field | Required | Description | +|-------|----------|-------------| +| `connectorType` | Yes | Must be `"akuity"` | +| `authType` | Yes | Argo CD authentication method: `"token"` or `"basic"` | +| `server` | Yes | Akuity instance URL. Format: `https://.cd.akuity.cloud/` | +| `token` | If `authType` is `"token"` | Argo CD API bearer token for the Akuity instance | +| `username` | If `authType` is `"basic"` | Argo CD username | +| `password` | If `authType` is `"basic"` | Argo CD password | +| `namespace` | No | Namespace where Argo CD is installed. Defaults to `argocd` | +| `insecure` | No | Set to `"true"` to skip TLS verification. Defaults to `"false"` | +| `akuityOrgId` | Yes | Akuity organization ID | +| `akuityInstanceId` | Yes | Argo CD instance ID within your Akuity organization | +| `akuityApiKeyId` | Yes | Akuity API key ID, used to register and manage clusters via the Akuity API | +| `akuityApiKeySecret` | Yes | Akuity API key secret | +| `akuityAgentSize` | No | Agent sizing for the cluster: `CLUSTER_SIZE_SMALL`, `CLUSTER_SIZE_MEDIUM` (default), or `CLUSTER_SIZE_LARGE` | +| `akuityRepoServerReplicas` | No | Override the `argocd-repo-server` replica count | +| `akuityRepoServerMemory` | No | Memory request/limit for `argocd-repo-server`, e.g. `"1Gi"` | + + + + + + + + +## The Akuity agent + + +When you use an Akuity connector, Argo CD does not connect directly to your cluster's API server. Instead, Akuity uses an agent: a lightweight workload running inside each registered cluster that establishes an outbound connection to the Akuity control plane. The managed Akuity Argo CD instance then communicates with the cluster through that persistent connection. + +This means no external cluster access is required. Your cluster's API server does not need to be publicly reachable: the agent runs inside the cluster and connects back to the Akuity control plane, so private clusters are fully supported without exposing the Kubernetes API server. + + +### What Platform does automatically + + +You do not install or manage the agent manually. When a cluster is registered with an Akuity connector, Platform: + +1. Calls the Akuity API to register the cluster and retrieve the agent installation manifest. +2. Applies the manifest to the cluster. The agent is installed in its own namespace within the cluster. +3. Stores a hash of the applied manifest in a cluster annotation. If the manifest changes (for example, after an Akuity agent version update), Platform detects the drift and applies the updated manifest to the cluster. + +When the integration is disabled or the connector is changed, Platform removes the agent namespace from the cluster and deregisters it from Akuity. + +### Agent sizing + +The `akuityAgentSize` field in the connector Secret controls the resource profile of the agent. Choose a size based on the number of Applications and the sync frequency expected for the cluster. + +| Value | Recommended for | +|-------|----------------| +| `CLUSTER_SIZE_SMALL` | Development or low-traffic clusters with few Applications | +| `CLUSTER_SIZE_MEDIUM` | General-purpose clusters (default) | +| `CLUSTER_SIZE_LARGE` | High-throughput clusters with many Applications or frequent syncs | + +## Step 2: Enable the connector on a cluster + +### On a tenant cluster + +The connector is configured through the tenant cluster's `vcluster.yaml`. +Add the `integrations.argoCD` block to the tenant cluster's `vcluster.yaml`. +The `connector` field references the Secret name from [Step 1](#step-1-create-a-connector). + +```yaml +integrations: + argoCD: + enabled: true + connector: argocd-main +``` + +The connector can also be configured under `spec.template.spec.helmRelease.values` in the VirtualClusterInstance manifest: + +```yaml +apiVersion: management.loft.sh/v1 +kind: VirtualClusterInstance +metadata: + name: app-dev + namespace: p-team-a +spec: + template: + metadata: + name: vcluster + spec: + helmRelease: + values: | + integrations: + argoCD: + enabled: true + connector: argocd-main +``` + +When the VirtualClusterInstance reconciles, Platform registers the tenant cluster with Argo CD +using the Platform proxy as the API server endpoint and a scoped access key as the bearer token. + + +### On a Control Plane Cluster + + +To register a Control Plane Cluster with Argo CD, add `spec.argoCD` to the Cluster object: + +```yaml +apiVersion: management.loft.sh/v1 +kind: Cluster +metadata: + name: my-cluster +spec: + argoCD: + enabled: true + connector: argocd-main +``` + +:::warning Disabling the integration +Disabling `integrations.argoCD.enabled` on a tenant cluster removes it from Argo CD and deletes all managed `ArgoCDApplication` objects. Any applications that were deployed by the integration will be removed from Argo CD. +::: + + +## Step 3: Deploy Argo CD applications + + +Applications are declared under `deploy.argoCD.applications` in the tenant cluster's Helm values. Each entry results in an `ArgoCDApplication` object that Platform creates and syncs to Argo CD. You can use a reusable template or an inline spec. + +### Create an application template + +An ArgoCDApplicationTemplate is a reusable Argo CD ApplicationSpec with named parameters. Create one before referencing it in application entries. + + + + + + + Click in the left sidebar, then select . + + + Click . + + + In the section, enter a for the template. + The is auto-generated from the display name and + is the identifier you will reference in your applications. + Optionally add a . + + + In the section, fill in the YAML editor with the Argo CD ApplicationSpec. + + + Click . + + + + + + +```yaml +apiVersion: storage.loft.sh/v1 +kind: ArgoCDApplicationTemplate +metadata: + name: app-template +spec: + template: + spec: + source: + repoURL: "https://github.com/acme/app-charts" + targetRevision: "main" + path: "app" + project: default + syncPolicy: + automated: + prune: true + selfHeal: true +``` + + + + +### Deploy an application + +Applications can be deployed into a tenant cluster or directly onto a Control Plane Cluster. Each target has its own UI entry point and CLI approach. + +#### On a tenant cluster + +Declare applications in the tenant cluster's Helm values under `deploy.argoCD.applications`. Each entry can target the tenant cluster itself (`target: vcluster`, default) or the Control Plane Cluster it runs on (`target: host`). + + + + + + + Select your project from the projects dropdown at the top of the left navigation bar. + + + Navigate to and open the tenant cluster where you want to deploy an application. + + + Select the tab in the cluster header. + + + Click . + + + In the section, enter a for the application. + The is auto-generated from the display name and uniquely identifies the application in Argo CD. + + + In the section, choose where to deploy: + - Select to deploy into the tenant cluster itself. + - Select to deploy into the Control Plane Cluster the tenant cluster runs on. The Control Plane Cluster must already have an Argo CD connector configured (see [Step 2](#step-2-enable-the-connector-on-a-cluster)). + + Fill in the for the selected destination. + + + In the section, select and choose an ArgoCDApplicationTemplate from the dropdown, or select to define the Argo CD ApplicationSpec directly in the YAML editor. + + + Click . + + + + + + +Add the `deploy.argoCD.applications` block to the tenant cluster's Helm values. Set `target: vcluster` to deploy into the tenant cluster or `target: host` to deploy into the Control Plane Cluster it runs on. + + + + +```yaml +deploy: + argoCD: + applications: + - name: myapp + displayName: "My Application" + target: vcluster # or "host" to target the Control Plane Cluster + destinationNamespace: default + template: + name: app-template # references the ArgoCDApplicationTemplate created above +``` + + + + +```yaml +deploy: + argoCD: + applications: + - name: grafana + displayName: "Grafana" + target: vcluster # or "host" to target the Control Plane Cluster + destinationNamespace: monitoring + inline: + source: + repoURL: "https://github.com/acme/charts" + targetRevision: HEAD + path: grafana + project: default + syncPolicy: + automated: + prune: true + selfHeal: true +``` + + + + + + + +:::warning +Tenant clusters can only deploy applications with `target: host` if the Control Plane Cluster they run on is already registered with an Argo CD connector. +Complete [Step 2 for the Control Plane Cluster](#on-a-control-plane-cluster) first. +::: + + +#### On a Control Plane Cluster + + +Applications deployed directly onto a Control Plane Cluster are created as `ArgoCDApplication` objects in the project namespace. +This is the recommended approach for shared infrastructure that should live on the underlying cluster rather than inside a tenant cluster. + + + + + + + Click in the left sidebar. + + + Click the name of the Control Plane Cluster to open its details page. + + + Select the tab in the cluster header. + + + Click . + + + In the section, enter a for the application. + The is auto-generated from the display name. + + + In the section, enter the on the Control Plane Cluster where the application should be deployed. + Leave it empty to use the namespace defined by the selected template or inline spec. + + + In the section, select and choose an ArgoCDApplicationTemplate from the dropdown, or select to define the Argo CD ApplicationSpec directly in the YAML editor. + + + Click . + + + + + + +Create an `ArgoCDApplication` object in the project namespace. Use `spec.destination.cluster` to target the Control Plane Cluster by name. + + + + +```yaml +apiVersion: storage.loft.sh/v1 +kind: ArgoCDApplication +metadata: + name: shared-infra + namespace: p-my-project # replace with your project namespace +spec: + displayName: "Shared Infrastructure" + destination: + cluster: + name: loft-cluster # replace with your Control Plane Cluster name + namespace: infra # omit to fall back to the namespace defined in the template or inline spec + templateRef: + name: infra-template # references the ArgoCDApplicationTemplate created above +``` + + + + +```yaml +apiVersion: storage.loft.sh/v1 +kind: ArgoCDApplication +metadata: + name: cluster-monitoring + namespace: p-my-project # replace with your project namespace +spec: + displayName: "Cluster Monitoring" + destination: + cluster: + name: loft-cluster # replace with your Control Plane Cluster name + namespace: monitoring # omit to fall back to the namespace defined in the template or inline spec + template: + spec: + source: + repoURL: "https://github.com/acme/charts" + targetRevision: HEAD + path: monitoring + project: default + syncPolicy: + automated: + prune: true + selfHeal: true +``` + + + + + + From 42020aebeb7358db3df17f69b8ad5fe14afe7682 Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 7 May 2026 18:30:22 -0400 Subject: [PATCH 2/5] refactor(argocd): restructure integration docs into focused guides Split the single argocd-v2.mdx page into a folder of four focused files: - overview.mdx: explanation of concepts (connectors, registration, ArgoCDApplication) - connect-argocd.mdx: how-to for standard Argo CD connector - connect-akuity.mdx: how-to for Akuity connector with agent sizing detail - deploy-applications.mdx: how-to for application templates and deployment Move the legacy project-level integration (argocd.mdx) into the folder as legacy.mdx with a deprecation admonition. Add a netlify.toml redirect for the old /docs/platform/integrations/argocd URL to the legacy page. Addresses review feedback: CLI tab labels renamed to YAML, Helm values language replaced with vcluster.yaml, disabling warning expanded to cover VCI and Cluster objects, agent sizing fields explained with implementation detail, target: host given its own section with security warnings, and new-vs-existing cluster tabs added for UI deployment flow. Co-Authored-By: Claude Sonnet 4.6 --- netlify.toml | 10 + platform/integrations/argocd-v2.mdx | 659 ------------------ platform/integrations/argocd/_category_.json | 5 + .../integrations/argocd/connect-akuity.mdx | 270 +++++++ .../integrations/argocd/connect-argocd.mdx | 207 ++++++ .../argocd/deploy-applications.mdx | 356 ++++++++++ .../{argocd.mdx => argocd/legacy.mdx} | 14 +- platform/integrations/argocd/overview.mdx | 66 ++ 8 files changed, 925 insertions(+), 662 deletions(-) delete mode 100644 platform/integrations/argocd-v2.mdx create mode 100644 platform/integrations/argocd/_category_.json create mode 100644 platform/integrations/argocd/connect-akuity.mdx create mode 100644 platform/integrations/argocd/connect-argocd.mdx create mode 100644 platform/integrations/argocd/deploy-applications.mdx rename platform/integrations/{argocd.mdx => argocd/legacy.mdx} (97%) create mode 100644 platform/integrations/argocd/overview.mdx diff --git a/netlify.toml b/netlify.toml index dc649ccc4..1dda69170 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1765,6 +1765,16 @@ to = "/docs/platform/:version/administer/users-permissions/overview" to = "/docs/vcluster/introduction/what-are-virtual-clusters" status = 301 +[[redirects]] + from = "/docs/platform/integrations/argocd" + to = "/docs/platform/integrations/argocd/legacy" + status = 301 + +[[redirects]] + from = "/docs/platform/next/integrations/argocd" + to = "/docs/platform/next/integrations/argocd/legacy" + status = 301 + # AUTO-GENERATED REDIRECTS END # DOC-1321: content negotiation — serve .md siblings when callers send diff --git a/platform/integrations/argocd-v2.mdx b/platform/integrations/argocd-v2.mdx deleted file mode 100644 index 17aabf9b8..000000000 --- a/platform/integrations/argocd-v2.mdx +++ /dev/null @@ -1,659 +0,0 @@ ---- -title: Argo CD Integration v2 -sidebar_label: Argo CD v2 -sidebar_position: 2 ---- - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; -import Flow, { Step } from "@site/src/components/Flow"; -import NavStep from "@site/src/components/NavStep"; -import Button from "@site/src/components/Button"; -import Label from "@site/src/components/Label"; -import FeatureTable from '@site/src/components/FeatureTable'; - - - -The Argo CD Integration v2 connects vCluster Platform to an Argo CD or [Akuity](https://akuity.io) instance using declarative *connectors*. A connector is a Kubernetes Secret stored in the Platform namespace that holds the credentials and endpoint for your Argo CD server. Once a connector exists, vCluster Platform automatically registers tenant clusters and Control Plane Clusters with Argo CD and manages Argo CD Applications on their behalf. - -This enables a fully GitOps-driven workflow with no manual cluster imports or Argo CD UI configuration: - -- **Connector-based cluster registration**: Clusters self-register with Argo CD when you reference a connector by name. No manual import is needed. -- **Akuity support**: In addition to self-hosted Argo CD servers, the integration supports [Akuity](https://akuity.io). Platform fetches and applies the Akuity agent manifest to each registered cluster automatically. -- **Declarative application deployment**: Define Argo CD Applications directly in your vCluster configuration. Platform creates and syncs them without requiring access to the Argo CD UI. - -## Prerequisites - -- vCluster Platform running with admin access -- A self-hosted Argo CD server **or** an Akuity organization with an active Argo CD instance - -### Argo CD API token permissions - -The API token used in the Argo CD connector must have the following RBAC permissions on the Argo CD server. Platform uses these to register clusters and manage Applications on your behalf. - -Create a dedicated role in your Argo CD `argocd-rbac-cm` ConfigMap and generate a token for it: - -```yaml -policy.csv: | - p, role:vcluster-platform, clusters, get, *, allow - p, role:vcluster-platform, clusters, create, *, allow - p, role:vcluster-platform, clusters, update, *, allow - p, role:vcluster-platform, clusters, delete, *, allow - p, role:vcluster-platform, applications, get, */*, allow - p, role:vcluster-platform, applications, create, */*, allow - p, role:vcluster-platform, applications, update, */*, allow - p, role:vcluster-platform, applications, delete, */*, allow -``` - -| Resource | Actions | Why | -|----------|---------|-----| -| `clusters` | `get`, `create`, `update`, `delete` | Register and deregister tenant clusters and Control Plane Clusters | -| `applications` | `get`, `create`, `update`, `delete` | Create and sync Argo CD Applications across all projects (`*/*`) | - -### Akuity API key permissions - -The Akuity API key used in the Akuity connector must have a [custom role](https://docs.akuity.io/organizations/custom-roles/) with the following permissions on the target Argo CD instance. -The built-in **Owner** role satisfies all of these. If you need least-privilege access, create a custom role with only the permissions below. - -| Resource | Permission | Why | -|----------|------------|-----| -| Argo CD Cluster | `Get` | Fetch cluster registration state and agent manifests | -| Argo CD Cluster | `Create` | Register new tenant clusters and Control Plane Clusters | -| Argo CD Cluster | `Update` | Update cluster registration when connector or access key changes | -| Argo CD Cluster | `Delete` | Deregister clusters when the integration is disabled | - -See [Akuity API key documentation](https://docs.akuity.io/organizations/api-keys) for instructions on creating an API key and attaching a custom role to it. - -## Step 1: Create a connector - -A connector is a Kubernetes Secret in the Platform namespace labeled `loft.sh/connector-type: argocd`. Platform discovers connectors by this label and makes them available by name to any cluster in the platform. - - - - - - - Click and select the tab. - - - Click . - - - In the field, enter a human-readable name for the connector. - The is auto-generated from the display name and is used to reference this connector from clusters. - - - **For Akuity only:** enable the toggle, then fill in: - - : your Akuity organization ID - - : the Argo CD instance ID within your organization - - and : your Akuity API key credentials - - - In the field, enter the URL of your Argo CD server. - - - If Argo CD is installed in a namespace other than `argocd`, update the field. - - - Select an authentication method and fill in the credentials: - - : paste your token in the field. - - : fill in and . - - - **For Akuity only:** in the section, select the appropriate for the cluster workload. Optionally override and for the `argocd-repo-server`. - - - Click . - - - - - - - - - -Argo CD supports two authentication methods for the API, controlled by the `authType` field. - - - - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: argocd-main - namespace: loft - labels: - loft.sh/connector-type: argocd -type: Opaque -stringData: - authType: "token" - server: "https://argocd.example.com" - token: "" - namespace: "argocd" - insecure: "false" -``` - - - - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: argocd-main - namespace: loft - labels: - loft.sh/connector-type: argocd -type: Opaque -stringData: - authType: "basic" - server: "https://argocd.example.com" - username: "" - password: "" - namespace: "argocd" - insecure: "false" -``` - - - - -| Field | Required | Description | -|-------|----------|-------------| -| `authType` | Yes | Argo CD authentication method: `"token"` or `"basic"` | -| `server` | Yes | Full URL of the Argo CD API server | -| `token` | If `authType` is `"token"` | Argo CD API bearer token | -| `username` | If `authType` is `"basic"` | Argo CD username | -| `password` | If `authType` is `"basic"` | Argo CD password | -| `namespace` | No | Namespace where Argo CD is installed. Defaults to `argocd` | -| `insecure` | No | Set to `"true"` to skip TLS verification. Defaults to `"false"` | -| `caData` | No | Base64-encoded CA certificate for custom TLS verification | - - - - -Set `connectorType: "akuity"` to use Akuity. Platform contacts the Akuity API to register clusters and fetches the agent manifest for installation on each registered cluster. - -Akuity supports two authentication methods for the Argo CD API, controlled by the `authType` field. - - - - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: akuity-prod - namespace: loft - labels: - loft.sh/connector-type: argocd -type: Opaque -stringData: - connectorType: "akuity" - authType: "token" - server: "https://.cd.akuity.cloud/" - token: "" - namespace: "argocd" - insecure: "false" - akuityOrgId: "" - akuityInstanceId: "" - akuityApiKeyId: "" - akuityApiKeySecret: "" - akuityAgentSize: "CLUSTER_SIZE_MEDIUM" - akuityRepoServerReplicas: "1" - akuityRepoServerMemory: "1Gi" -``` - - - - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: akuity-prod - namespace: loft - labels: - loft.sh/connector-type: argocd -type: Opaque -stringData: - connectorType: "akuity" - authType: "basic" - server: "https://.cd.akuity.cloud/" - username: "" - password: "" - namespace: "argocd" - insecure: "false" - akuityOrgId: "" - akuityInstanceId: "" - akuityApiKeyId: "" - akuityApiKeySecret: "" - akuityAgentSize: "CLUSTER_SIZE_MEDIUM" - akuityRepoServerReplicas: "1" - akuityRepoServerMemory: "1Gi" -``` - - - - -| Field | Required | Description | -|-------|----------|-------------| -| `connectorType` | Yes | Must be `"akuity"` | -| `authType` | Yes | Argo CD authentication method: `"token"` or `"basic"` | -| `server` | Yes | Akuity instance URL. Format: `https://.cd.akuity.cloud/` | -| `token` | If `authType` is `"token"` | Argo CD API bearer token for the Akuity instance | -| `username` | If `authType` is `"basic"` | Argo CD username | -| `password` | If `authType` is `"basic"` | Argo CD password | -| `namespace` | No | Namespace where Argo CD is installed. Defaults to `argocd` | -| `insecure` | No | Set to `"true"` to skip TLS verification. Defaults to `"false"` | -| `akuityOrgId` | Yes | Akuity organization ID | -| `akuityInstanceId` | Yes | Argo CD instance ID within your Akuity organization | -| `akuityApiKeyId` | Yes | Akuity API key ID, used to register and manage clusters via the Akuity API | -| `akuityApiKeySecret` | Yes | Akuity API key secret | -| `akuityAgentSize` | No | Agent sizing for the cluster: `CLUSTER_SIZE_SMALL`, `CLUSTER_SIZE_MEDIUM` (default), or `CLUSTER_SIZE_LARGE` | -| `akuityRepoServerReplicas` | No | Override the `argocd-repo-server` replica count | -| `akuityRepoServerMemory` | No | Memory request/limit for `argocd-repo-server`, e.g. `"1Gi"` | - - - - - - - - -## The Akuity agent - - -When you use an Akuity connector, Argo CD does not connect directly to your cluster's API server. Instead, Akuity uses an agent: a lightweight workload running inside each registered cluster that establishes an outbound connection to the Akuity control plane. The managed Akuity Argo CD instance then communicates with the cluster through that persistent connection. - -This means no external cluster access is required. Your cluster's API server does not need to be publicly reachable: the agent runs inside the cluster and connects back to the Akuity control plane, so private clusters are fully supported without exposing the Kubernetes API server. - - -### What Platform does automatically - - -You do not install or manage the agent manually. When a cluster is registered with an Akuity connector, Platform: - -1. Calls the Akuity API to register the cluster and retrieve the agent installation manifest. -2. Applies the manifest to the cluster. The agent is installed in its own namespace within the cluster. -3. Stores a hash of the applied manifest in a cluster annotation. If the manifest changes (for example, after an Akuity agent version update), Platform detects the drift and applies the updated manifest to the cluster. - -When the integration is disabled or the connector is changed, Platform removes the agent namespace from the cluster and deregisters it from Akuity. - -### Agent sizing - -The `akuityAgentSize` field in the connector Secret controls the resource profile of the agent. Choose a size based on the number of Applications and the sync frequency expected for the cluster. - -| Value | Recommended for | -|-------|----------------| -| `CLUSTER_SIZE_SMALL` | Development or low-traffic clusters with few Applications | -| `CLUSTER_SIZE_MEDIUM` | General-purpose clusters (default) | -| `CLUSTER_SIZE_LARGE` | High-throughput clusters with many Applications or frequent syncs | - -## Step 2: Enable the connector on a cluster - -### On a tenant cluster - -The connector is configured through the tenant cluster's `vcluster.yaml`. -Add the `integrations.argoCD` block to the tenant cluster's `vcluster.yaml`. -The `connector` field references the Secret name from [Step 1](#step-1-create-a-connector). - -```yaml -integrations: - argoCD: - enabled: true - connector: argocd-main -``` - -The connector can also be configured under `spec.template.spec.helmRelease.values` in the VirtualClusterInstance manifest: - -```yaml -apiVersion: management.loft.sh/v1 -kind: VirtualClusterInstance -metadata: - name: app-dev - namespace: p-team-a -spec: - template: - metadata: - name: vcluster - spec: - helmRelease: - values: | - integrations: - argoCD: - enabled: true - connector: argocd-main -``` - -When the VirtualClusterInstance reconciles, Platform registers the tenant cluster with Argo CD -using the Platform proxy as the API server endpoint and a scoped access key as the bearer token. - - -### On a Control Plane Cluster - - -To register a Control Plane Cluster with Argo CD, add `spec.argoCD` to the Cluster object: - -```yaml -apiVersion: management.loft.sh/v1 -kind: Cluster -metadata: - name: my-cluster -spec: - argoCD: - enabled: true - connector: argocd-main -``` - -:::warning Disabling the integration -Disabling `integrations.argoCD.enabled` on a tenant cluster removes it from Argo CD and deletes all managed `ArgoCDApplication` objects. Any applications that were deployed by the integration will be removed from Argo CD. -::: - - -## Step 3: Deploy Argo CD applications - - -Applications are declared under `deploy.argoCD.applications` in the tenant cluster's Helm values. Each entry results in an `ArgoCDApplication` object that Platform creates and syncs to Argo CD. You can use a reusable template or an inline spec. - -### Create an application template - -An ArgoCDApplicationTemplate is a reusable Argo CD ApplicationSpec with named parameters. Create one before referencing it in application entries. - - - - - - - Click in the left sidebar, then select . - - - Click . - - - In the section, enter a for the template. - The is auto-generated from the display name and - is the identifier you will reference in your applications. - Optionally add a . - - - In the section, fill in the YAML editor with the Argo CD ApplicationSpec. - - - Click . - - - - - - -```yaml -apiVersion: storage.loft.sh/v1 -kind: ArgoCDApplicationTemplate -metadata: - name: app-template -spec: - template: - spec: - source: - repoURL: "https://github.com/acme/app-charts" - targetRevision: "main" - path: "app" - project: default - syncPolicy: - automated: - prune: true - selfHeal: true -``` - - - - -### Deploy an application - -Applications can be deployed into a tenant cluster or directly onto a Control Plane Cluster. Each target has its own UI entry point and CLI approach. - -#### On a tenant cluster - -Declare applications in the tenant cluster's Helm values under `deploy.argoCD.applications`. Each entry can target the tenant cluster itself (`target: vcluster`, default) or the Control Plane Cluster it runs on (`target: host`). - - - - - - - Select your project from the projects dropdown at the top of the left navigation bar. - - - Navigate to and open the tenant cluster where you want to deploy an application. - - - Select the tab in the cluster header. - - - Click . - - - In the section, enter a for the application. - The is auto-generated from the display name and uniquely identifies the application in Argo CD. - - - In the section, choose where to deploy: - - Select to deploy into the tenant cluster itself. - - Select to deploy into the Control Plane Cluster the tenant cluster runs on. The Control Plane Cluster must already have an Argo CD connector configured (see [Step 2](#step-2-enable-the-connector-on-a-cluster)). - - Fill in the for the selected destination. - - - In the section, select and choose an ArgoCDApplicationTemplate from the dropdown, or select to define the Argo CD ApplicationSpec directly in the YAML editor. - - - Click . - - - - - - -Add the `deploy.argoCD.applications` block to the tenant cluster's Helm values. Set `target: vcluster` to deploy into the tenant cluster or `target: host` to deploy into the Control Plane Cluster it runs on. - - - - -```yaml -deploy: - argoCD: - applications: - - name: myapp - displayName: "My Application" - target: vcluster # or "host" to target the Control Plane Cluster - destinationNamespace: default - template: - name: app-template # references the ArgoCDApplicationTemplate created above -``` - - - - -```yaml -deploy: - argoCD: - applications: - - name: grafana - displayName: "Grafana" - target: vcluster # or "host" to target the Control Plane Cluster - destinationNamespace: monitoring - inline: - source: - repoURL: "https://github.com/acme/charts" - targetRevision: HEAD - path: grafana - project: default - syncPolicy: - automated: - prune: true - selfHeal: true -``` - - - - - - - -:::warning -Tenant clusters can only deploy applications with `target: host` if the Control Plane Cluster they run on is already registered with an Argo CD connector. -Complete [Step 2 for the Control Plane Cluster](#on-a-control-plane-cluster) first. -::: - - -#### On a Control Plane Cluster - - -Applications deployed directly onto a Control Plane Cluster are created as `ArgoCDApplication` objects in the project namespace. -This is the recommended approach for shared infrastructure that should live on the underlying cluster rather than inside a tenant cluster. - - - - - - - Click in the left sidebar. - - - Click the name of the Control Plane Cluster to open its details page. - - - Select the tab in the cluster header. - - - Click . - - - In the section, enter a for the application. - The is auto-generated from the display name. - - - In the section, enter the on the Control Plane Cluster where the application should be deployed. - Leave it empty to use the namespace defined by the selected template or inline spec. - - - In the section, select and choose an ArgoCDApplicationTemplate from the dropdown, or select to define the Argo CD ApplicationSpec directly in the YAML editor. - - - Click . - - - - - - -Create an `ArgoCDApplication` object in the project namespace. Use `spec.destination.cluster` to target the Control Plane Cluster by name. - - - - -```yaml -apiVersion: storage.loft.sh/v1 -kind: ArgoCDApplication -metadata: - name: shared-infra - namespace: p-my-project # replace with your project namespace -spec: - displayName: "Shared Infrastructure" - destination: - cluster: - name: loft-cluster # replace with your Control Plane Cluster name - namespace: infra # omit to fall back to the namespace defined in the template or inline spec - templateRef: - name: infra-template # references the ArgoCDApplicationTemplate created above -``` - - - - -```yaml -apiVersion: storage.loft.sh/v1 -kind: ArgoCDApplication -metadata: - name: cluster-monitoring - namespace: p-my-project # replace with your project namespace -spec: - displayName: "Cluster Monitoring" - destination: - cluster: - name: loft-cluster # replace with your Control Plane Cluster name - namespace: monitoring # omit to fall back to the namespace defined in the template or inline spec - template: - spec: - source: - repoURL: "https://github.com/acme/charts" - targetRevision: HEAD - path: monitoring - project: default - syncPolicy: - automated: - prune: true - selfHeal: true -``` - - - - - - diff --git a/platform/integrations/argocd/_category_.json b/platform/integrations/argocd/_category_.json new file mode 100644 index 000000000..1d37bdad4 --- /dev/null +++ b/platform/integrations/argocd/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Argo CD", + "position": 1, + "collapsible": true +} diff --git a/platform/integrations/argocd/connect-akuity.mdx b/platform/integrations/argocd/connect-akuity.mdx new file mode 100644 index 000000000..de83c17a6 --- /dev/null +++ b/platform/integrations/argocd/connect-akuity.mdx @@ -0,0 +1,270 @@ +--- +title: Connect to Akuity +sidebar_label: Connect to Akuity +sidebar_position: 3 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Flow, { Step } from "@site/src/components/Flow"; +import Button from "@site/src/components/Button"; +import Label from "@site/src/components/Label"; + +This guide connects vCluster Platform to an [Akuity](https://akuity.io)-managed Argo CD instance. At the end you will have a connector that registers tenant clusters and control plane clusters with Akuity and provisions the Akuity agent inside each cluster automatically. + +For a self-hosted Argo CD server, see [Connect to Argo CD](./connect-argocd.mdx) instead. + +## How the Akuity agent works + +When you use an Akuity connector, Argo CD does not connect directly to your cluster's API server. Instead, Akuity uses a lightweight agent running inside each registered cluster that establishes an outbound connection to the Akuity control plane. The managed Akuity Argo CD instance communicates with the cluster through that persistent connection. + +This means the cluster's API server does not need to be publicly reachable — the agent runs inside the cluster and connects outward — so private clusters are fully supported. + +You do not install or manage the agent manually. When a cluster is registered with an Akuity connector, Platform: + +1. Calls the Akuity API to register the cluster and retrieve the agent installation manifest. +2. Applies the manifest to the cluster. The agent is installed in its own namespace within the cluster. +3. Stores a hash of the applied manifest in a cluster annotation. If the manifest changes (for example, after an Akuity agent version update), Platform detects the drift and applies the updated manifest automatically. + +When the integration is disabled or the connector is changed, Platform removes the agent namespace from the cluster and deregisters it from Akuity. + +## Prerequisites + +- vCluster Platform running with admin access +- An Akuity organization with an active Argo CD instance +- An Akuity API key (see below) + +### Akuity API key permissions + +The Akuity API key must have a [custom role](https://docs.akuity.io/organizations/custom-roles/) with the following permissions on the target Argo CD instance. The built-in **Owner** role satisfies all of these. For least-privilege access, create a custom role with only the permissions below. + +| Resource | Permission | Why | +|----------|------------|-----| +| Argo CD Cluster | `Get` | Fetch cluster registration state and agent manifests | +| Argo CD Cluster | `Create` | Register new tenant clusters and control plane clusters | +| Argo CD Cluster | `Update` | Update cluster registration when connector or access key changes | +| Argo CD Cluster | `Delete` | Deregister clusters when the integration is disabled | + +See the [Akuity API key documentation](https://docs.akuity.io/organizations/api-keys) for instructions on creating an API key and attaching a custom role. + +## Step 1: Create a connector + + + + + + + Click and select the tab. + + + Click . + + + In the field, enter a human-readable name for the connector. + The is auto-generated from the display name and is used to reference this connector from clusters. + + + Enable the toggle, then fill in: + - : your Akuity organization ID + - : the Argo CD instance ID within your organization + - and : your Akuity API key credentials + + + In the field, enter the Akuity instance URL. The format is `https://.cd.akuity.cloud/`. + + + If Argo CD is installed in a namespace other than `argocd`, update the field. + + + Select an authentication method and fill in the credentials: + - : paste your token in the field. + - : fill in and . + + + In the section, select an for the cluster workload. + Optionally override and for the `argocd-repo-server` (see [Agent sizing](#agent-sizing) below). + + + Click . + + + + + + +Set `connectorType: "akuity"` to use Akuity. Akuity supports two authentication methods for the Argo CD API, controlled by the `authType` field. Apply the Secret with `kubectl apply`. + + + + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: akuity-prod + namespace: loft + labels: + loft.sh/connector-type: argocd +type: Opaque +stringData: + connectorType: "akuity" + authType: "token" + server: "https://.cd.akuity.cloud/" + token: "" + namespace: "argocd" + insecure: "false" + akuityOrgId: "" + akuityInstanceId: "" + akuityApiKeyId: "" + akuityApiKeySecret: "" + akuityAgentSize: "CLUSTER_SIZE_MEDIUM" + akuityRepoServerReplicas: "1" + akuityRepoServerMemory: "1Gi" +``` + + + + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: akuity-prod + namespace: loft + labels: + loft.sh/connector-type: argocd +type: Opaque +stringData: + connectorType: "akuity" + authType: "basic" + server: "https://.cd.akuity.cloud/" + username: "" + password: "" + namespace: "argocd" + insecure: "false" + akuityOrgId: "" + akuityInstanceId: "" + akuityApiKeyId: "" + akuityApiKeySecret: "" + akuityAgentSize: "CLUSTER_SIZE_MEDIUM" + akuityRepoServerReplicas: "1" + akuityRepoServerMemory: "1Gi" +``` + + + + +| Field | Required | Description | +|-------|----------|-------------| +| `connectorType` | Yes | Must be `"akuity"` | +| `authType` | Yes | Argo CD authentication method: `"token"` or `"basic"` | +| `server` | Yes | Akuity instance URL. Format: `https://.cd.akuity.cloud/` | +| `token` | If `authType` is `"token"` | Argo CD API bearer token for the Akuity instance | +| `username` | If `authType` is `"basic"` | Argo CD username | +| `password` | If `authType` is `"basic"` | Argo CD password | +| `namespace` | No | Namespace where Argo CD is installed. Defaults to `argocd` | +| `insecure` | No | Set to `"true"` to skip TLS verification. Defaults to `"false"` | +| `akuityOrgId` | Yes | Akuity organization ID | +| `akuityInstanceId` | Yes | Argo CD instance ID within your Akuity organization | +| `akuityApiKeyId` | Yes | Akuity API key ID, used to register and manage clusters via the Akuity API | +| `akuityApiKeySecret` | Yes | Akuity API key secret | +| `akuityAgentSize` | No | Agent size profile: `CLUSTER_SIZE_SMALL`, `CLUSTER_SIZE_MEDIUM` (default), or `CLUSTER_SIZE_LARGE`. See [Agent sizing](#agent-sizing). | +| `akuityRepoServerReplicas` | No | Override the `argocd-repo-server` replica count. See [Agent sizing](#agent-sizing). | +| `akuityRepoServerMemory` | No | Override `argocd-repo-server` memory. Sets both `requests` and `limits`. See [Agent sizing](#agent-sizing). | + + + + +## Agent sizing + +Three fields in the connector Secret control how the Akuity agent is provisioned inside each registered cluster. + +### `akuityAgentSize` + +This field is sent to the Akuity API when the cluster is registered and determines the overall resource profile of the agent as defined by Akuity. It is an Akuity-level concept, not a direct Kubernetes resource value — Akuity translates this into the appropriate CPU and memory requests for the agent workloads on its end. + +| Value | Recommended for | +|-------|----------------| +| `CLUSTER_SIZE_SMALL` | Development or low-traffic clusters with few Applications | +| `CLUSTER_SIZE_MEDIUM` | General-purpose clusters (default) | +| `CLUSTER_SIZE_LARGE` | High-throughput clusters with many Applications or frequent syncs | + +### `akuityRepoServerReplicas` and `akuityRepoServerMemory` + +These fields let you override specific resource settings on the `argocd-repo-server` Deployment inside the cluster, independently of the size profile. Platform applies a kustomization patch to the agent manifest before installing it: + +- `akuityRepoServerReplicas` sets `spec.replicas` on the `argocd-repo-server` Deployment. +- `akuityRepoServerMemory` sets both `resources.requests.memory` and `resources.limits.memory` to the same value on the `argocd-repo-server` container. Accepts standard Kubernetes memory quantity strings, for example `"1Gi"` or `"512Mi"`. + +Both fields are optional and independent of `akuityAgentSize`. Use them when the size profile alone does not give you the control you need over repo server memory or replica count. + +## Step 2: Enable the connector on a cluster + +### On a tenant cluster + +Add the `integrations.argoCD` block to the tenant cluster's `vcluster.yaml`. The `connector` field references the Secret name from Step 1. + +```yaml +integrations: + argoCD: + enabled: true + connector: akuity-prod +``` + +The connector can also be set directly in the `VirtualClusterInstance` manifest: + +```yaml +apiVersion: management.loft.sh/v1 +kind: VirtualClusterInstance +metadata: + name: app-dev + namespace: p-team-a +spec: + template: + metadata: + name: vcluster + spec: + helmRelease: + values: | + integrations: + argoCD: + enabled: true + connector: akuity-prod +``` + +When the `VirtualClusterInstance` reconciles, Platform registers the tenant cluster with Akuity, retrieves the agent manifest, and installs the agent into the cluster. + +### On a control plane cluster + +To register a control plane cluster with Akuity, add `spec.argoCD` to the Cluster object: + +```yaml +apiVersion: management.loft.sh/v1 +kind: Cluster +metadata: + name: my-cluster +spec: + argoCD: + enabled: true + connector: akuity-prod +``` + +:::warning Disabling the integration +Disabling the integration removes the cluster from Akuity, uninstalls the agent namespace from the cluster, and deletes all `ArgoCDApplication` objects managed by Platform. This applies whether the integration is configured via `vcluster.yaml`, a `VirtualClusterInstance` manifest, or a `Cluster` object. Any applications deployed by the integration will be removed from Argo CD. +::: + +## Next step + +With the connector enabled, you can declare Argo CD Applications in your tenant cluster or control plane cluster configuration. See [Deploy applications](./deploy-applications.mdx). diff --git a/platform/integrations/argocd/connect-argocd.mdx b/platform/integrations/argocd/connect-argocd.mdx new file mode 100644 index 000000000..06a2f477c --- /dev/null +++ b/platform/integrations/argocd/connect-argocd.mdx @@ -0,0 +1,207 @@ +--- +title: Connect to Argo CD +sidebar_label: Connect to Argo CD +sidebar_position: 2 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Flow, { Step } from "@site/src/components/Flow"; +import Button from "@site/src/components/Button"; +import Label from "@site/src/components/Label"; + +This guide connects vCluster Platform to a self-hosted Argo CD server. At the end you will have a connector that registers tenant clusters and control plane clusters with Argo CD automatically. + +For Akuity-managed Argo CD, see [Connect to Akuity](./connect-akuity.mdx) instead. + +## Prerequisites + +- vCluster Platform running with admin access +- A self-hosted Argo CD server reachable from the Platform namespace + +### Argo CD API token permissions + +The API token you provide in the connector must have the following RBAC permissions. Create a dedicated role in your Argo CD `argocd-rbac-cm` ConfigMap and generate a token for it: + +```yaml +policy.csv: | + p, role:vcluster-platform, clusters, get, *, allow + p, role:vcluster-platform, clusters, create, *, allow + p, role:vcluster-platform, clusters, update, *, allow + p, role:vcluster-platform, clusters, delete, *, allow + p, role:vcluster-platform, applications, get, */*, allow + p, role:vcluster-platform, applications, create, */*, allow + p, role:vcluster-platform, applications, update, */*, allow + p, role:vcluster-platform, applications, delete, */*, allow +``` + +| Resource | Actions | Why | +|----------|---------|-----| +| `clusters` | `get`, `create`, `update`, `delete` | Register and deregister tenant clusters and control plane clusters | +| `applications` | `get`, `create`, `update`, `delete` | Create and sync Argo CD Applications across all projects (`*/*`) | + +## Step 1: Create a connector + + + + + + + Click and select the tab. + + + Click . + + + In the field, enter a human-readable name for the connector. + The is auto-generated from the display name and is used to reference this connector from clusters. + + + In the field, enter the URL of your Argo CD server. + + + If Argo CD is installed in a namespace other than `argocd`, update the field. + + + Select an authentication method and fill in the credentials: + - : paste your token in the field. + - : fill in and . + + + Click . + + + + + + +Argo CD supports two authentication methods, controlled by the `authType` field. Apply the Secret with `kubectl apply`. + + + + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: argocd-main + namespace: loft + labels: + loft.sh/connector-type: argocd +type: Opaque +stringData: + authType: "token" + server: "https://argocd.example.com" + token: "" + namespace: "argocd" + insecure: "false" +``` + + + + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: argocd-main + namespace: loft + labels: + loft.sh/connector-type: argocd +type: Opaque +stringData: + authType: "basic" + server: "https://argocd.example.com" + username: "" + password: "" + namespace: "argocd" + insecure: "false" +``` + + + + +| Field | Required | Description | +|-------|----------|-------------| +| `authType` | Yes | Authentication method: `"token"` or `"basic"` | +| `server` | Yes | Full URL of the Argo CD API server | +| `token` | If `authType` is `"token"` | Argo CD API bearer token | +| `username` | If `authType` is `"basic"` | Argo CD username | +| `password` | If `authType` is `"basic"` | Argo CD password | +| `namespace` | No | Namespace where Argo CD is installed. Defaults to `argocd` | +| `insecure` | No | Set to `"true"` to skip TLS verification. Defaults to `"false"` | +| `caData` | No | Base64-encoded CA certificate for custom TLS verification | + + + + +## Step 2: Enable the connector on a cluster + +### On a tenant cluster + +Add the `integrations.argoCD` block to the tenant cluster's `vcluster.yaml`. The `connector` field references the Secret name from Step 1. + +```yaml +integrations: + argoCD: + enabled: true + connector: argocd-main +``` + +The connector can also be set directly in the `VirtualClusterInstance` manifest: + +```yaml +apiVersion: management.loft.sh/v1 +kind: VirtualClusterInstance +metadata: + name: app-dev + namespace: p-team-a +spec: + template: + metadata: + name: vcluster + spec: + helmRelease: + values: | + integrations: + argoCD: + enabled: true + connector: argocd-main +``` + +When the `VirtualClusterInstance` reconciles, Platform registers the tenant cluster with Argo CD using the Platform proxy as the API server endpoint and a scoped access key as the bearer token. + +### On a control plane cluster + +To register a control plane cluster with Argo CD, add `spec.argoCD` to the Cluster object: + +```yaml +apiVersion: management.loft.sh/v1 +kind: Cluster +metadata: + name: my-cluster +spec: + argoCD: + enabled: true + connector: argocd-main +``` + +:::warning Disabling the integration +Disabling the integration removes the cluster from Argo CD and deletes all `ArgoCDApplication` objects managed by Platform. This applies whether the integration is configured via `vcluster.yaml`, a `VirtualClusterInstance` manifest, or a `Cluster` object. Any applications deployed by the integration will be removed from Argo CD. +::: + +## Next step + +With the connector enabled, you can declare Argo CD Applications in your tenant cluster or control plane cluster configuration. See [Deploy applications](./deploy-applications.mdx). diff --git a/platform/integrations/argocd/deploy-applications.mdx b/platform/integrations/argocd/deploy-applications.mdx new file mode 100644 index 000000000..1921eb4c1 --- /dev/null +++ b/platform/integrations/argocd/deploy-applications.mdx @@ -0,0 +1,356 @@ +--- +title: Deploy applications +sidebar_label: Deploy applications +sidebar_position: 4 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Flow, { Step } from "@site/src/components/Flow"; +import Button from "@site/src/components/Button"; +import Label from "@site/src/components/Label"; + +This guide covers declaring Argo CD Applications in your Platform configuration after a connector is enabled. Platform reconciles these declarations into `ArgoCDApplication` objects and syncs them to your Argo CD instance. + +## Prerequisites + +- A connector is already configured and enabled on the target cluster. See [Connect to Argo CD](./connect-argocd.mdx) or [Connect to Akuity](./connect-akuity.mdx). + +## Application templates + +An `ArgoCDApplicationTemplate` is a reusable Argo CD ApplicationSpec. Create one when you want to deploy the same application definition across multiple tenant clusters without duplicating configuration. + + + + + + + Click in the left sidebar, then select . + + + Click . + + + In the section, enter a for the template. + The is auto-generated from the display name and is the identifier you reference in your applications. + Optionally add a . + + + In the section, fill in the YAML editor with the Argo CD ApplicationSpec. + + + Click . + + + + + + +```yaml +apiVersion: storage.loft.sh/v1 +kind: ArgoCDApplicationTemplate +metadata: + name: app-template +spec: + template: + spec: + source: + repoURL: "https://github.com/acme/app-charts" + targetRevision: "main" + path: "app" + project: default + syncPolicy: + automated: + prune: true + selfHeal: true +``` + + + + +## Deploy to a tenant cluster + +Applications deployed to a tenant cluster are declared in the cluster's `vcluster.yaml` under `deploy.argoCD.applications`. Each entry can target: + +- **`vcluster`** (default): the tenant cluster itself +- **`host`**: the control plane cluster the tenant cluster runs on (see [Deploying to the control plane cluster](#deploying-to-the-control-plane-cluster)) + + + + + + + + + + Select your project from the projects dropdown at the top of the left navigation bar. + + + Navigate to and click . + + + Optionally select a cluster template, then click . + + + Select the tab in the cluster creation form. + + + Click . + + + In the section, enter a for the application. + The is auto-generated from the display name and uniquely identifies the application in Argo CD. + + + In the section, choose where to deploy: + - Select to deploy into the tenant cluster itself. + - Select to deploy into the control plane cluster the tenant cluster runs on. The control plane cluster must already have an Argo CD connector configured. + + Fill in the for the selected destination. + + + In the section, select and choose an `ArgoCDApplicationTemplate` from the dropdown, or select to define the Argo CD ApplicationSpec directly in the YAML editor. + + + Complete the remaining cluster configuration and click . + + + + + + + + + Select your project from the projects dropdown at the top of the left navigation bar. + + + Navigate to and open the tenant cluster where you want to deploy an application. + + + Select the tab in the cluster detail view. + + + Click . + + + In the section, enter a for the application. + The is auto-generated from the display name and uniquely identifies the application in Argo CD. + + + In the section, choose where to deploy: + - Select to deploy into the tenant cluster itself. + - Select to deploy into the control plane cluster the tenant cluster runs on. The control plane cluster must already have an Argo CD connector configured. + + Fill in the for the selected destination. + + + In the section, select and choose an `ArgoCDApplicationTemplate` from the dropdown, or select to define the Argo CD ApplicationSpec directly in the YAML editor. + + + Click . + + + + + + + + + +Add the `deploy.argoCD.applications` block to the tenant cluster's `vcluster.yaml`. Set `target: vcluster` to deploy into the tenant cluster (this is the default) or `target: host` to deploy into the control plane cluster it runs on. + + + + +```yaml +deploy: + argoCD: + applications: + - name: myapp + displayName: "My Application" + target: vcluster # or "host" to target the control plane cluster + destinationNamespace: default + template: + name: app-template # references an ArgoCDApplicationTemplate +``` + + + + +```yaml +deploy: + argoCD: + applications: + - name: grafana + displayName: "Grafana" + target: vcluster # or "host" to target the control plane cluster + destinationNamespace: monitoring + inline: + source: + repoURL: "https://github.com/acme/charts" + targetRevision: HEAD + path: grafana + project: default + syncPolicy: + automated: + prune: true + selfHeal: true +``` + + + + + + + +### Deploying to the control plane cluster + +Setting `target: host` deploys the application onto the control plane cluster rather than inside the tenant cluster. Use this for shared infrastructure — monitoring agents, logging collectors, or networking components — that belongs on the underlying cluster rather than inside a tenant cluster. + +:::warning Understand the access boundary before using `target: host` +`target: host` allows configuration inside a tenant cluster to affect workloads on the control plane cluster. Before enabling this, consider: + +- **Who controls the tenant cluster configuration?** If tenants can edit `vcluster.yaml` directly, they can deploy arbitrary workloads onto the control plane cluster. Restrict this to platform admins or use cluster templates to limit what values tenants can set. +- **The control plane cluster must have a connector.** If the control plane cluster does not have an Argo CD connector configured, applications with `target: host` will fail to deploy. +- **Applications are deployed into a specific namespace.** The `destinationNamespace` field determines where the application lands on the control plane cluster. Ensure that namespace exists and that deploying into it is intentional. + +This is a platform-admin-level capability. Do not expose it to end users without proper guardrails. +::: + +:::info Prerequisite for `target: host` +The control plane cluster the tenant cluster runs on must already be registered with an Argo CD connector. Complete the connector setup for the control plane cluster first (see [Connect to Argo CD](./connect-argocd.mdx#on-a-control-plane-cluster) or [Connect to Akuity](./connect-akuity.mdx#on-a-control-plane-cluster)). +::: + +## Deploy to a control plane cluster + +Applications deployed directly onto a control plane cluster are created as `ArgoCDApplication` objects in the project namespace. This is the recommended pattern for shared infrastructure that should live on the underlying cluster rather than inside a tenant cluster. + + + + + + + Click in the left sidebar under the infrastructure section. + + + Click the name of the control plane cluster to open its detail page. + + + Select the tab in the cluster header. + + + Click . + + + In the section, enter a for the application. + The is auto-generated from the display name. + + + In the section, enter the on the control plane cluster where the application should be deployed. + Leave it empty to use the namespace defined by the selected template or inline spec. + + + In the section, select and choose an `ArgoCDApplicationTemplate` from the dropdown, or select to define the Argo CD ApplicationSpec directly in the YAML editor. + + + Click . + + + + + + +Create an `ArgoCDApplication` object in the project namespace. Use `spec.destination.cluster` to target the control plane cluster by name. + + + + +```yaml +apiVersion: storage.loft.sh/v1 +kind: ArgoCDApplication +metadata: + name: shared-infra + namespace: p-my-project # replace with your project namespace +spec: + displayName: "Shared Infrastructure" + destination: + cluster: + name: loft-cluster # replace with your control plane cluster name + namespace: infra # omit to fall back to the namespace defined in the template + templateRef: + name: infra-template # references an ArgoCDApplicationTemplate +``` + + + + +```yaml +apiVersion: storage.loft.sh/v1 +kind: ArgoCDApplication +metadata: + name: cluster-monitoring + namespace: p-my-project # replace with your project namespace +spec: + displayName: "Cluster Monitoring" + destination: + cluster: + name: loft-cluster # replace with your control plane cluster name + namespace: monitoring # omit to fall back to the namespace defined in the inline spec + template: + spec: + source: + repoURL: "https://github.com/acme/charts" + targetRevision: HEAD + path: monitoring + project: default + syncPolicy: + automated: + prune: true + selfHeal: true +``` + + + + + + + +:::warning Disabling the integration +Disabling `integrations.argoCD.enabled` on a tenant cluster, or removing `spec.argoCD` from a control plane cluster, removes the cluster from Argo CD and deletes all `ArgoCDApplication` objects managed by Platform. Any applications deployed by the integration will be removed from Argo CD. +::: diff --git a/platform/integrations/argocd.mdx b/platform/integrations/argocd/legacy.mdx similarity index 97% rename from platform/integrations/argocd.mdx rename to platform/integrations/argocd/legacy.mdx index 4becbae65..e67719fa6 100644 --- a/platform/integrations/argocd.mdx +++ b/platform/integrations/argocd/legacy.mdx @@ -1,7 +1,7 @@ --- -title: Argo CD -sidebar_label: Argo CD -sidebar_position: 1 +title: Argo CD (legacy) +sidebar_label: Argo CD (legacy) +sidebar_position: 5 --- import Tabs from "@theme/Tabs"; @@ -12,6 +12,14 @@ import Button from "@site/src/components/Button"; import Label from "@site/src/components/Label"; import FeatureTable from '@site/src/components/FeatureTable'; +:::warning Deprecated +This is the legacy project-level Argo CD integration. It is deprecated and will be removed in a future release. + +For new installations, use the connector-based integration instead: +- [Connect to Argo CD](./connect-argocd.mdx) +- [Connect to Akuity](./connect-akuity.mdx) +::: + diff --git a/platform/integrations/argocd/overview.mdx b/platform/integrations/argocd/overview.mdx new file mode 100644 index 000000000..9a9f3b755 --- /dev/null +++ b/platform/integrations/argocd/overview.mdx @@ -0,0 +1,66 @@ +--- +title: Argo CD +sidebar_label: Overview +sidebar_position: 1 +--- + +import FeatureTable from '@site/src/components/FeatureTable'; + + + +The Argo CD integration connects vCluster Platform to an Argo CD or [Akuity](https://akuity.io) instance using declarative *connectors*. A connector is a Kubernetes Secret stored in the Platform namespace that holds the credentials and endpoint for your Argo CD server. Once a connector exists, Platform automatically registers tenant clusters and control plane clusters with Argo CD and manages Argo CD Applications on their behalf. + +This enables a fully GitOps-driven workflow with no manual cluster imports or Argo CD UI configuration: + +- **Connector-based cluster registration**: Clusters register with Argo CD when you reference a connector by name. No manual import is needed. +- **Akuity support**: In addition to self-hosted Argo CD servers, the integration supports [Akuity](https://akuity.io). Platform fetches and applies the Akuity agent manifest to each registered cluster automatically. +- **Declarative application deployment**: Define Argo CD Applications directly in your tenant cluster configuration. Platform creates and syncs them without requiring access to the Argo CD UI. +- **Control plane cluster registration**: Register control plane clusters with Argo CD directly, and deploy shared infrastructure applications to them alongside tenant cluster applications. + +## Key concepts + +### Connectors + +A connector is a Kubernetes Secret in the Platform namespace labeled `loft.sh/connector-type: argocd`. Platform discovers connectors by this label and makes them available by name to any cluster in the platform. The connector holds the Argo CD server URL, authentication credentials, and — for Akuity — the organization and instance identifiers. + +A single connector can be referenced by many clusters. You create it once and reference it by name from each cluster or tenant cluster configuration. + +### Cluster registration + +When a tenant cluster or control plane cluster references a connector, Platform registers it as a destination cluster in Argo CD using the Platform proxy as the API server endpoint and a scoped access key as the bearer token. This means: + +- The cluster's Kubernetes API server does not need to be publicly reachable from Argo CD. +- Access is scoped per cluster — Argo CD uses the Platform-issued access key, not a long-lived kubeconfig. +- When a tenant cluster is deleted or the integration is disabled, Platform deregisters it from Argo CD automatically. + +For Akuity, registration also provisions an agent inside the cluster (see [Connect to Akuity](./connect-akuity.mdx) for details). + +### ArgoCDApplication and ArgoCDApplicationTemplate + +The integration introduces two Platform-level resources: + +- **`ArgoCDApplication`**: Represents a single Argo CD application with a vCluster-aware destination type — either the tenant cluster itself (`vcluster`) or the control plane cluster it runs on (`host`). Platform reconciles these into actual Argo CD Application objects. +- **`ArgoCDApplicationTemplate`**: A reusable Argo CD ApplicationSpec with named parameters. Templates allow the same application definition to be referenced across many tenant clusters without duplication. + +These resources live in the Platform project namespace and are managed by Platform, not by Argo CD directly. + +## Standard Argo CD vs Akuity + +Use the standard Argo CD integration when you operate your own Argo CD server and want direct API access. Use Akuity when you use Akuity's managed Argo CD service, which uses an in-cluster agent rather than direct API server access. + +| | Standard Argo CD | Akuity | +|---|---|---| +| Argo CD hosting | Self-hosted | Akuity-managed | +| Cluster connectivity | Direct API access from Argo CD | Agent installed inside the cluster | +| Private clusters | Requires API server reachability | Fully supported (outbound agent connection only) | +| Agent management | Not applicable | Platform provisions and updates the agent automatically | + +## Get started + +- [Connect to Argo CD](./connect-argocd.mdx) — set up a standard Argo CD connector and register clusters +- [Connect to Akuity](./connect-akuity.mdx) — set up an Akuity connector with automatic agent provisioning +- [Deploy applications](./deploy-applications.mdx) — declare Argo CD Applications in your tenant cluster configuration + +:::info Legacy integration +If you are using the project-level Argo CD integration from an earlier version of vCluster Platform, see [Legacy Argo CD integration](./legacy.mdx). That integration is deprecated and will be removed in a future release. +::: From 895d573864ddf3c609333a7a047fe7d827cbb51c Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 7 May 2026 18:39:12 -0400 Subject: [PATCH 3/5] fix(argocd): update stale links after argocd docs restructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update three pages that referenced the removed argocd.mdx: - what-are-projects.mdx → argocd/overview.mdx (general integration link) - gitops-end-to-end.mdx → argocd/legacy.mdx (SSO/App Project content is legacy) - projects/create.mdx → argocd/legacy.mdx (project-level integration is legacy) Co-Authored-By: Claude Sonnet 4.6 --- platform/administer/projects/create.mdx | 2 +- platform/how-to/gitops-end-to-end.mdx | 2 +- platform/understand/what-are-projects.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/platform/administer/projects/create.mdx b/platform/administer/projects/create.mdx index c741acdc7..c1c75b6c1 100644 --- a/platform/administer/projects/create.mdx +++ b/platform/administer/projects/create.mdx @@ -42,7 +42,7 @@ Keep templates required for projects where non-admin users create tenant cluster Optionally, there are a couple of other integrations that can be configured. See - the Integrations documentation for further information. + the Integrations documentation for further information. Once all project options have been specified, click the{" "} diff --git a/platform/how-to/gitops-end-to-end.mdx b/platform/how-to/gitops-end-to-end.mdx index b18f28460..9be326af7 100644 --- a/platform/how-to/gitops-end-to-end.mdx +++ b/platform/how-to/gitops-end-to-end.mdx @@ -213,7 +213,7 @@ spec: To sync tenant clusters into ArgoCD as deployment targets, enable the ArgoCD integration on the project. This is configured through the project spec and allows tenant clusters to appear as available clusters in the ArgoCD UI. -See the [ArgoCD integration guide](../integrations/argocd.mdx) for UI-based setup and configuration of SSO integration and App Project mapping. +See the [ArgoCD integration guide](../integrations/argocd/legacy.mdx) for UI-based setup and configuration of SSO integration and App Project mapping. :::info management.loft.sh vs storage.loft.sh Define resources using the `management.loft.sh` API group. The `storage.loft.sh` group is used internally by platform controllers and appears in some spec fields as references to existing resources. diff --git a/platform/understand/what-are-projects.mdx b/platform/understand/what-are-projects.mdx index e7b658d54..480cc5b60 100644 --- a/platform/understand/what-are-projects.mdx +++ b/platform/understand/what-are-projects.mdx @@ -42,4 +42,4 @@ Projects can store secrets that are shared across resources within the project. Projects support integrations with external tools including ArgoCD and Rancher, allowing you to connect tenant cluster lifecycle management with your existing GitOps or platform tooling. -[View integrations →](../integrations/argocd.mdx) +[View integrations →](../integrations/argocd/overview.mdx) From 7939ee34ee75089e2ea3d4153450396d0c381701 Mon Sep 17 00:00:00 2001 From: Florian Medja Date: Fri, 8 May 2026 08:55:18 -0400 Subject: [PATCH 4/5] doc: clarify cluster registration wording and fix prose issues in overview and connect-argocd pages --- platform/integrations/argocd/connect-argocd.mdx | 2 +- .../integrations/argocd/deploy-applications.mdx | 2 +- platform/integrations/argocd/overview.mdx | 14 ++++++++------ 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/platform/integrations/argocd/connect-argocd.mdx b/platform/integrations/argocd/connect-argocd.mdx index 06a2f477c..b62d7941a 100644 --- a/platform/integrations/argocd/connect-argocd.mdx +++ b/platform/integrations/argocd/connect-argocd.mdx @@ -151,7 +151,7 @@ stringData: ### On a tenant cluster -Add the `integrations.argoCD` block to the tenant cluster's `vcluster.yaml`. The `connector` field references the Secret name from Step 1. +Add the `integrations.argoCD` block to the tenant cluster's `vcluster.yaml`. The `connector` field references the Secret name from [Step 1](#step-1-create-a-connector). ```yaml integrations: diff --git a/platform/integrations/argocd/deploy-applications.mdx b/platform/integrations/argocd/deploy-applications.mdx index 1921eb4c1..d804ff66f 100644 --- a/platform/integrations/argocd/deploy-applications.mdx +++ b/platform/integrations/argocd/deploy-applications.mdx @@ -31,7 +31,7 @@ An `ArgoCDApplicationTemplate` is a reusable Argo CD ApplicationSpec. Create one - Click in the left sidebar, then select . + Click in the left sidebar. Click . diff --git a/platform/integrations/argocd/overview.mdx b/platform/integrations/argocd/overview.mdx index 9a9f3b755..bb5bb14b8 100644 --- a/platform/integrations/argocd/overview.mdx +++ b/platform/integrations/argocd/overview.mdx @@ -27,10 +27,12 @@ A single connector can be referenced by many clusters. You create it once and re ### Cluster registration -When a tenant cluster or control plane cluster references a connector, Platform registers it as a destination cluster in Argo CD using the Platform proxy as the API server endpoint and a scoped access key as the bearer token. This means: +When a tenant cluster or control plane cluster references a connector, Platform registers that cluster as +a destination in Argo CD. The registration uses the Platform proxy as the API server endpoint and a +scoped access key as the bearer token. This means: - The cluster's Kubernetes API server does not need to be publicly reachable from Argo CD. -- Access is scoped per cluster — Argo CD uses the Platform-issued access key, not a long-lived kubeconfig. +- Access is scoped per cluster. Argo CD authenticates using a Platform-issued access key, not a long-lived kubeconfig. - When a tenant cluster is deleted or the integration is disabled, Platform deregisters it from Argo CD automatically. For Akuity, registration also provisions an agent inside the cluster (see [Connect to Akuity](./connect-akuity.mdx) for details). @@ -39,15 +41,15 @@ For Akuity, registration also provisions an agent inside the cluster (see [Conne The integration introduces two Platform-level resources: -- **`ArgoCDApplication`**: Represents a single Argo CD application with a vCluster-aware destination type — either the tenant cluster itself (`vcluster`) or the control plane cluster it runs on (`host`). Platform reconciles these into actual Argo CD Application objects. -- **`ArgoCDApplicationTemplate`**: A reusable Argo CD ApplicationSpec with named parameters. Templates allow the same application definition to be referenced across many tenant clusters without duplication. +- **`ArgoCDApplication`**: Represents an Argo CD application targeted at either the tenant cluster (`vcluster`) or its control plane cluster (`host`). Platform creates the corresponding Argo CD Application object and keeps it in sync +- **`ArgoCDApplicationTemplate`**: A reusable Argo CD ApplicationSpec with named parameters. Templates allow the same application definition to be referenced across many tenant clusters and control plane clusters without duplication. These resources live in the Platform project namespace and are managed by Platform, not by Argo CD directly. ## Standard Argo CD vs Akuity -Use the standard Argo CD integration when you operate your own Argo CD server and want direct API access. Use Akuity when you use Akuity's managed Argo CD service, which uses an in-cluster agent rather than direct API server access. - +Use the standard Argo CD integration if you run your own Argo CD server. +Choose the Akuity integration if your Argo CD instance is managed by Akuity. Akuity connects to clusters through an in-cluster agent rather than direct API access. | | Standard Argo CD | Akuity | |---|---|---| | Argo CD hosting | Self-hosted | Akuity-managed | From 265082c613bdacf8dba67750212cf2830fbc294e Mon Sep 17 00:00:00 2001 From: Daryl White Date: Thu, 21 May 2026 13:29:11 -0400 Subject: [PATCH 5/5] docs(argocd): update cross-references and fix authType field for connector integration - Replace legacy argocd link in gitops-end-to-end.mdx with connector-based guidance; add spec.argoCD note for control plane clusters and integrations.argoCD block to VirtualClusterInstance example - Update create.mdx project flow step to link both Argo CD and Vault integration docs instead of legacy-only link - Remove non-existent authType field from connector Secret examples and reference tables in connect-argocd.mdx and connect-akuity.mdx; auth method is determined by presence of token vs username/password - Add legacy integration context to loft.sh/import-argocd and loft.sh/user-managed-destinations annotations in platform-annotations.mdx - Add legacy integration note to preview template example in create-templates.mdx Co-Authored-By: Claude Sonnet 4.6 --- platform/administer/projects/create.mdx | 5 ++-- .../administer/templates/create-templates.mdx | 2 ++ platform/how-to/gitops-end-to-end.mdx | 23 +++++++++++++++---- .../integrations/argocd/connect-akuity.mdx | 11 ++++----- .../integrations/argocd/connect-argocd.mdx | 11 ++++----- platform/reference/platform-annotations.mdx | 6 +++-- 6 files changed, 36 insertions(+), 22 deletions(-) diff --git a/platform/administer/projects/create.mdx b/platform/administer/projects/create.mdx index c1c75b6c1..f172c08a0 100644 --- a/platform/administer/projects/create.mdx +++ b/platform/administer/projects/create.mdx @@ -41,8 +41,9 @@ Keep templates required for projects where non-admin users create tenant cluster section for further information. - Optionally, there are a couple of other integrations that can be configured. See - the Integrations documentation for further information. + Optionally, configure integrations for the project. See the{" "} + Argo CD integration and{" "} + HashiCorp Vault integration documentation for further information. Once all project options have been specified, click the{" "} diff --git a/platform/administer/templates/create-templates.mdx b/platform/administer/templates/create-templates.mdx index f2196382e..963957188 100644 --- a/platform/administer/templates/create-templates.mdx +++ b/platform/administer/templates/create-templates.mdx @@ -466,6 +466,8 @@ spec: The following template creates a temporary preview environment with automatic auto sleep and deletion policies. It includes ingress authentication requirements, scheduled auto sleep and wake cycles, and baseline security policies for short-lived preview deployments. +The `loft.sh/import-argocd: 'true'` label uses the legacy project-level Argo CD integration. For new setups, configure Argo CD registration through the connector-based integration instead. See [Connect to Argo CD](../../integrations/argocd/connect-argocd.mdx). + ```yaml title="Preview environment template" kind: VirtualClusterTemplate apiVersion: management.loft.sh/v1 diff --git a/platform/how-to/gitops-end-to-end.mdx b/platform/how-to/gitops-end-to-end.mdx index 9be326af7..642588ec6 100644 --- a/platform/how-to/gitops-end-to-end.mdx +++ b/platform/how-to/gitops-end-to-end.mdx @@ -177,6 +177,15 @@ spec: title="agent-application.yaml" /> +To also register the control plane cluster with Argo CD so it can receive shared infrastructure applications directly, add `spec.argoCD` to the Cluster object after creating a connector (see [Step 3](#3-create-a-project)): + +```yaml +spec: + argoCD: + enabled: true + connector: argocd-main # name of your connector Secret +``` + For interactive setup methods using the UI or CLI, see the [connect a cluster guide](../administer/clusters/connect-cluster.mdx). ## 3. Create a project @@ -209,11 +218,11 @@ spec: title="project.yaml" /> -### Enable ArgoCD integration on the project +### Connect to Argo CD -To sync tenant clusters into ArgoCD as deployment targets, enable the ArgoCD integration on the project. This is configured through the project spec and allows tenant clusters to appear as available clusters in the ArgoCD UI. +To register tenant clusters with Argo CD, create a connector. A connector is a Kubernetes Secret in the Platform namespace that holds your Argo CD server credentials and endpoint. Once a connector exists, you reference it by name from each cluster you want registered. See [Connect to Argo CD](../integrations/argocd/connect-argocd.mdx) for the full setup, including required RBAC permissions and connector YAML. -See the [ArgoCD integration guide](../integrations/argocd/legacy.mdx) for UI-based setup and configuration of SSO integration and App Project mapping. +If you are using the project-level Argo CD integration from an earlier version of vCluster Platform, see [Argo CD (legacy)](../integrations/argocd/legacy.mdx). :::info management.loft.sh vs storage.loft.sh Define resources using the `management.loft.sh` API group. The `storage.loft.sh` group is used internally by platform controllers and appears in some spec fields as references to existing resources. @@ -252,7 +261,11 @@ spec: backingStore: etcd: deploy: - enabled: true`} + enabled: true + integrations: + argoCD: + enabled: true + connector: argocd-main`} language="yaml" title="virtualclusterinstance.yaml" /> @@ -261,6 +274,8 @@ spec: The namespace follows the pattern `loft-p-`. The platform uses this convention to associate tenant clusters with projects. ::: +When the `VirtualClusterInstance` reconciles, Platform registers the tenant cluster with Argo CD using the connector credentials. You can then declare Argo CD Applications in the tenant cluster configuration. See [Deploy applications](../integrations/argocd/deploy-applications.mdx). + ### Option B: Deploy with Helm chart directly Deploy the vCluster Helm chart through an ArgoCD Application. This approach gives you direct control over the Helm release but does not provide platform lifecycle features unless you [register the tenant cluster afterward](../use-platform/virtual-clusters/add-virtual-clusters.mdx). diff --git a/platform/integrations/argocd/connect-akuity.mdx b/platform/integrations/argocd/connect-akuity.mdx index de83c17a6..25d93725b 100644 --- a/platform/integrations/argocd/connect-akuity.mdx +++ b/platform/integrations/argocd/connect-akuity.mdx @@ -98,7 +98,7 @@ See the [Akuity API key documentation](https://docs.akuity.io/organizations/api- -Set `connectorType: "akuity"` to use Akuity. Akuity supports two authentication methods for the Argo CD API, controlled by the `authType` field. Apply the Secret with `kubectl apply`. +Set `connectorType: "akuity"` to use Akuity. Akuity supports two authentication methods for the Argo CD API. If `token` is set, the controller uses bearer token authentication. Otherwise it falls back to `username` and `password`. Apply the Secret with `kubectl apply`. .cd.akuity.cloud/" token: "" namespace: "argocd" @@ -148,7 +147,6 @@ metadata: type: Opaque stringData: connectorType: "akuity" - authType: "basic" server: "https://.cd.akuity.cloud/" username: "" password: "" @@ -169,11 +167,10 @@ stringData: | Field | Required | Description | |-------|----------|-------------| | `connectorType` | Yes | Must be `"akuity"` | -| `authType` | Yes | Argo CD authentication method: `"token"` or `"basic"` | | `server` | Yes | Akuity instance URL. Format: `https://.cd.akuity.cloud/` | -| `token` | If `authType` is `"token"` | Argo CD API bearer token for the Akuity instance | -| `username` | If `authType` is `"basic"` | Argo CD username | -| `password` | If `authType` is `"basic"` | Argo CD password | +| `token` | If set, bearer token authentication is used | Argo CD API bearer token for the Akuity instance | +| `username` | Required when `token` is not set | Argo CD username | +| `password` | Required when `token` is not set | Argo CD password | | `namespace` | No | Namespace where Argo CD is installed. Defaults to `argocd` | | `insecure` | No | Set to `"true"` to skip TLS verification. Defaults to `"false"` | | `akuityOrgId` | Yes | Akuity organization ID | diff --git a/platform/integrations/argocd/connect-argocd.mdx b/platform/integrations/argocd/connect-argocd.mdx index b62d7941a..2e7c57a5a 100644 --- a/platform/integrations/argocd/connect-argocd.mdx +++ b/platform/integrations/argocd/connect-argocd.mdx @@ -81,7 +81,7 @@ policy.csv: | -Argo CD supports two authentication methods, controlled by the `authType` field. Apply the Secret with `kubectl apply`. +Argo CD supports two authentication methods. If `token` is set, the controller uses bearer token authentication. Otherwise it falls back to `username` and `password`. Apply the Secret with `kubectl apply`. " namespace: "argocd" @@ -122,7 +121,6 @@ metadata: loft.sh/connector-type: argocd type: Opaque stringData: - authType: "basic" server: "https://argocd.example.com" username: "" password: "" @@ -135,11 +133,10 @@ stringData: | Field | Required | Description | |-------|----------|-------------| -| `authType` | Yes | Authentication method: `"token"` or `"basic"` | | `server` | Yes | Full URL of the Argo CD API server | -| `token` | If `authType` is `"token"` | Argo CD API bearer token | -| `username` | If `authType` is `"basic"` | Argo CD username | -| `password` | If `authType` is `"basic"` | Argo CD password | +| `token` | If set, bearer token authentication is used | Argo CD API bearer token | +| `username` | Required when `token` is not set | Argo CD username | +| `password` | Required when `token` is not set | Argo CD password | | `namespace` | No | Namespace where Argo CD is installed. Defaults to `argocd` | | `insecure` | No | Set to `"true"` to skip TLS verification. Defaults to `"false"` | | `caData` | No | Base64-encoded CA certificate for custom TLS verification | diff --git a/platform/reference/platform-annotations.mdx b/platform/reference/platform-annotations.mdx index 330524365..9e9fec04a 100644 --- a/platform/reference/platform-annotations.mdx +++ b/platform/reference/platform-annotations.mdx @@ -1501,7 +1501,9 @@ These annotations and labels configure external integrations. **Set by:** User-configurable -Enables ArgoCD integration for this vCluster or cluster. When set, the platform automatically registers this cluster/vCluster with ArgoCD. +Part of the legacy project-level Argo CD integration. When set to `"true"`, the platform automatically registers this tenant cluster or cluster with Argo CD using the project-level configuration. + +For new setups, use the connector-based integration instead. See [Connect to Argo CD](../integrations/argocd/connect-argocd.mdx). ### loft.sh/user-managed-destinations {#loft-sh-user-managed-destinations} @@ -1513,7 +1515,7 @@ Enables ArgoCD integration for this vCluster or cluster. When set, the platform **Set by:** Platform -Tracks which ArgoCD AppProject destinations are managed by the loft project controller. This prevents the controller from removing destinations managed by vCluster instances when syncing project specifications. +Part of the legacy project-level Argo CD integration. Tracks which Argo CD AppProject destinations are managed by the project controller. This prevents the controller from removing destinations managed by tenant clusters when syncing project specifications. ### loft.sh/argocd-connector {#loft-sh-argocd-connector}