From 535333af0bc57ddf23de3483a70ec1ba6dd0ddfd Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Thu, 9 Apr 2026 11:00:55 -0400 Subject: [PATCH 1/4] update apikey var --- docusaurus.config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 5f3c75c6..3989bf9b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -212,7 +212,7 @@ const config = { }, algolia: { appId: "4OZX85VEXQ", - apiKey: "9f96702edcf79d7097bedfce2813d49e", + apiKey: process.env.ALGOLIA_API_KEY || "9f96702edcf79d7097bedfce2813d49e", indexName: "upbound", contextualSearch: true, searchPagePath: "search", From 755c647a94d9e7481b3df8d5585362fe174e4e0d Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Thu, 9 Apr 2026 13:55:58 -0400 Subject: [PATCH 2/4] update sidebars --- .../version-1.13-sidebars.json | 116 ++++++++++++++++ .../version-1.14-sidebars.json | 116 ++++++++++++++++ .../version-1.15-sidebars.json | 115 +++++++++++++++ .../version-1.16-sidebars.json | 131 ++++++++++++++++++ 4 files changed, 478 insertions(+) create mode 100644 self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json create mode 100644 self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json create mode 100644 self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json create mode 100644 self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json diff --git a/self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json new file mode 100644 index 00000000..5e6d3cbe --- /dev/null +++ b/self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json @@ -0,0 +1,116 @@ +{ + "sidebar": [ + { + "type": "doc", + "id": "overview/index", + "label": "Overview" + }, + { + "type": "doc", + "id": "self-hosted-spaces-quickstart" + }, + { + "type": "category", + "label": "Concepts", + "items": [ + "concepts/control-planes", + "concepts/groups", + "concepts/deployment-modes" + ] + }, + { + "type": "category", + "label": "Deploy", + "items": [ + "howtos/deployment-reqs", + "howtos/self-hosted-spaces-deployment", + "howtos/certs", + "howtos/proxies-config", + "howtos/attach-detach" + ] + }, + { + "type": "category", + "label": "Configure", + "items": [ + "howtos/configure-ha", + "howtos/administer-features", + "howtos/oidc-configuration", + "howtos/scaling-resources", + "howtos/spaces-management" + ] + }, + { + "type": "category", + "label": "Control Planes", + "items": [ + "howtos/managed-service", + "howtos/control-plane-topologies", + "howtos/auto-upgrade", + "howtos/declarative-ctps", + "howtos/controllers", + "howtos/migrating-to-mcps", + "howtos/simulations" + ] + }, + { + "type": "category", + "label": "Connect", + "items": [ + "howtos/api-connector", + "howtos/ctp-connector", + "howtos/mcp-connector-guide", + "howtos/query-api" + ] + }, + { + "type": "category", + "label": "Observe & Debug", + "items": [ + "howtos/observability", + "howtos/space-observability", + "howtos/debugging-a-ctp", + "howtos/troubleshooting" + ] + }, + { + "type": "category", + "label": "GitOps & Automation", + "items": [ + "howtos/automation-and-gitops/overview", + "howtos/gitops-with-argocd", + "howtos/use-argo" + ] + }, + { + "type": "category", + "label": "Data & Security", + "items": [ + "howtos/backup-and-restore", + "howtos/dr", + "howtos/secrets-management", + { + "type": "category", + "label": "Workload Identity", + "items": [ + "howtos/workload-id/backup-restore-config", + "howtos/workload-id/billing-config", + "howtos/workload-id/eso-config" + ] + } + ] + }, + { + "type": "category", + "label": "Billing & Licensing", + "items": [ + "howtos/billing" + ] + }, + { + "type": "doc", + "id": "reference/index", + "label": "API Reference" + } + ] +} diff --git a/self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json new file mode 100644 index 00000000..5e6d3cbe --- /dev/null +++ b/self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json @@ -0,0 +1,116 @@ +{ + "sidebar": [ + { + "type": "doc", + "id": "overview/index", + "label": "Overview" + }, + { + "type": "doc", + "id": "self-hosted-spaces-quickstart" + }, + { + "type": "category", + "label": "Concepts", + "items": [ + "concepts/control-planes", + "concepts/groups", + "concepts/deployment-modes" + ] + }, + { + "type": "category", + "label": "Deploy", + "items": [ + "howtos/deployment-reqs", + "howtos/self-hosted-spaces-deployment", + "howtos/certs", + "howtos/proxies-config", + "howtos/attach-detach" + ] + }, + { + "type": "category", + "label": "Configure", + "items": [ + "howtos/configure-ha", + "howtos/administer-features", + "howtos/oidc-configuration", + "howtos/scaling-resources", + "howtos/spaces-management" + ] + }, + { + "type": "category", + "label": "Control Planes", + "items": [ + "howtos/managed-service", + "howtos/control-plane-topologies", + "howtos/auto-upgrade", + "howtos/declarative-ctps", + "howtos/controllers", + "howtos/migrating-to-mcps", + "howtos/simulations" + ] + }, + { + "type": "category", + "label": "Connect", + "items": [ + "howtos/api-connector", + "howtos/ctp-connector", + "howtos/mcp-connector-guide", + "howtos/query-api" + ] + }, + { + "type": "category", + "label": "Observe & Debug", + "items": [ + "howtos/observability", + "howtos/space-observability", + "howtos/debugging-a-ctp", + "howtos/troubleshooting" + ] + }, + { + "type": "category", + "label": "GitOps & Automation", + "items": [ + "howtos/automation-and-gitops/overview", + "howtos/gitops-with-argocd", + "howtos/use-argo" + ] + }, + { + "type": "category", + "label": "Data & Security", + "items": [ + "howtos/backup-and-restore", + "howtos/dr", + "howtos/secrets-management", + { + "type": "category", + "label": "Workload Identity", + "items": [ + "howtos/workload-id/backup-restore-config", + "howtos/workload-id/billing-config", + "howtos/workload-id/eso-config" + ] + } + ] + }, + { + "type": "category", + "label": "Billing & Licensing", + "items": [ + "howtos/billing" + ] + }, + { + "type": "doc", + "id": "reference/index", + "label": "API Reference" + } + ] +} diff --git a/self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json new file mode 100644 index 00000000..c932d0ac --- /dev/null +++ b/self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json @@ -0,0 +1,115 @@ +{ + "sidebar": [ + { + "type": "doc", + "id": "overview/index", + "label": "Overview" + }, + { + "type": "doc", + "id": "self-hosted-spaces-quickstart" + }, + { + "type": "category", + "label": "Concepts", + "items": [ + "concepts/control-planes", + "concepts/groups" + ] + }, + { + "type": "category", + "label": "Deploy", + "items": [ + "howtos/deployment-reqs", + "howtos/self-hosted-spaces-deployment", + "howtos/certs", + "howtos/attach-detach" + ] + }, + { + "type": "category", + "label": "Configure", + "items": [ + "howtos/configure-ha", + "howtos/oidc-configuration", + "howtos/scaling-resources", + "howtos/spaces-management" + ] + }, + { + "type": "category", + "label": "Control Planes", + "items": [ + "howtos/managed-service", + "howtos/control-plane-topologies", + "howtos/auto-upgrade", + "howtos/declarative-ctps", + "howtos/controllers", + "howtos/migrating-to-mcps", + "howtos/simulations" + ] + }, + { + "type": "category", + "label": "Connect", + "items": [ + "howtos/api-connector", + "howtos/ctp-connector", + "howtos/mcp-connector-guide", + "howtos/query-api" + ] + }, + { + "type": "category", + "label": "Observe & Debug", + "items": [ + "howtos/observability", + "howtos/space-observability", + "howtos/ctp-audit-logs", + "howtos/debugging-a-ctp", + "howtos/troubleshooting" + ] + }, + { + "type": "category", + "label": "GitOps & Automation", + "items": [ + "howtos/automation-and-gitops/overview", + "howtos/gitops-with-argocd", + "howtos/use-argo" + ] + }, + { + "type": "category", + "label": "Data & Security", + "items": [ + "howtos/backup-and-restore", + "howtos/dr", + "howtos/secrets-management", + { + "type": "category", + "label": "Workload Identity", + "items": [ + "howtos/workload-id/backup-restore-config", + "howtos/workload-id/billing-config", + "howtos/workload-id/eso-config" + ] + } + ] + }, + { + "type": "category", + "label": "Billing & Licensing", + "items": [ + "howtos/billing", + "howtos/capacity-licensing" + ] + }, + { + "type": "doc", + "id": "reference/index", + "label": "API Reference" + } + ] +} diff --git a/self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json new file mode 100644 index 00000000..b3429579 --- /dev/null +++ b/self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json @@ -0,0 +1,131 @@ +{ + "sidebar": [ + { + "type": "doc", + "id": "overview/index", + "label": "Overview" + }, + { + "type": "doc", + "id": "self-hosted-spaces-quickstart" + }, + { + "type": "category", + "label": "Concepts", + "items": [ + "concepts/control-planes", + "concepts/groups", + "concepts/deployment-modes" + ] + }, + { + "type": "category", + "label": "Deploy", + "items": [ + "howtos/deployment-reqs", + "howtos/self-hosted-spaces-deployment", + "howtos/certs", + "howtos/proxies-config", + "howtos/ingress", + "howtos/ingress-nginx-migration", + "howtos/mirror-images", + "howtos/attach-detach" + ] + }, + { + "type": "category", + "label": "Configure", + "items": [ + "howtos/configure-ha", + "howtos/administer-features", + "howtos/oidc-configuration", + "howtos/scaling-resources", + "howtos/spaces-management" + ] + }, + { + "type": "category", + "label": "Control Planes", + "items": [ + "howtos/managed-service", + "howtos/control-plane-topologies", + "howtos/auto-upgrade", + "howtos/declarative-ctps", + "howtos/controllers", + "howtos/migrating-to-mcps", + "howtos/simulations" + ] + }, + { + "type": "category", + "label": "Connect", + "items": [ + "howtos/api-connector", + "howtos/ctp-connector", + "howtos/mcp-connector-guide", + "howtos/query-api", + "howtos/deploy-query-api" + ] + }, + { + "type": "category", + "label": "Observe & Debug", + "items": [ + "howtos/observability", + "howtos/space-observability", + { + "type": "category", + "label": "Tracing", + "items": [ + "howtos/tracing/overview", + "howtos/tracing/query-api", + "howtos/tracing/spaces-api", + "howtos/tracing/spaces-router" + ] + }, + "howtos/ctp-audit-logs", + "howtos/debugging-a-ctp", + "howtos/troubleshooting" + ] + }, + { + "type": "category", + "label": "GitOps & Automation", + "items": [ + "howtos/gitops", + "howtos/use-argo" + ] + }, + { + "type": "category", + "label": "Data & Security", + "items": [ + "howtos/backup-and-restore", + "howtos/dr", + "howtos/secrets-management", + { + "type": "category", + "label": "Workload Identity", + "items": [ + "howtos/workload-id/backup-restore-config", + "howtos/workload-id/billing-config", + "howtos/workload-id/eso-config" + ] + } + ] + }, + { + "type": "category", + "label": "Billing & Licensing", + "items": [ + "howtos/billing", + "howtos/capacity-licensing" + ] + }, + { + "type": "doc", + "id": "reference/index", + "label": "API Reference" + } + ] +} From c9659999213ed11bfa288814a2394038d496a390 Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Thu, 9 Apr 2026 13:57:31 -0400 Subject: [PATCH 3/4] Revert "update sidebars" This reverts commit 755c647a94d9e7481b3df8d5585362fe174e4e0d. --- .../version-1.13-sidebars.json | 116 ---------------- .../version-1.14-sidebars.json | 116 ---------------- .../version-1.15-sidebars.json | 115 --------------- .../version-1.16-sidebars.json | 131 ------------------ 4 files changed, 478 deletions(-) delete mode 100644 self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json delete mode 100644 self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json delete mode 100644 self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json delete mode 100644 self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json diff --git a/self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json deleted file mode 100644 index 5e6d3cbe..00000000 --- a/self-hosted-spaces_versioned_sidebars/version-1.13-sidebars.json +++ /dev/null @@ -1,116 +0,0 @@ -{ - "sidebar": [ - { - "type": "doc", - "id": "overview/index", - "label": "Overview" - }, - { - "type": "doc", - "id": "self-hosted-spaces-quickstart" - }, - { - "type": "category", - "label": "Concepts", - "items": [ - "concepts/control-planes", - "concepts/groups", - "concepts/deployment-modes" - ] - }, - { - "type": "category", - "label": "Deploy", - "items": [ - "howtos/deployment-reqs", - "howtos/self-hosted-spaces-deployment", - "howtos/certs", - "howtos/proxies-config", - "howtos/attach-detach" - ] - }, - { - "type": "category", - "label": "Configure", - "items": [ - "howtos/configure-ha", - "howtos/administer-features", - "howtos/oidc-configuration", - "howtos/scaling-resources", - "howtos/spaces-management" - ] - }, - { - "type": "category", - "label": "Control Planes", - "items": [ - "howtos/managed-service", - "howtos/control-plane-topologies", - "howtos/auto-upgrade", - "howtos/declarative-ctps", - "howtos/controllers", - "howtos/migrating-to-mcps", - "howtos/simulations" - ] - }, - { - "type": "category", - "label": "Connect", - "items": [ - "howtos/api-connector", - "howtos/ctp-connector", - "howtos/mcp-connector-guide", - "howtos/query-api" - ] - }, - { - "type": "category", - "label": "Observe & Debug", - "items": [ - "howtos/observability", - "howtos/space-observability", - "howtos/debugging-a-ctp", - "howtos/troubleshooting" - ] - }, - { - "type": "category", - "label": "GitOps & Automation", - "items": [ - "howtos/automation-and-gitops/overview", - "howtos/gitops-with-argocd", - "howtos/use-argo" - ] - }, - { - "type": "category", - "label": "Data & Security", - "items": [ - "howtos/backup-and-restore", - "howtos/dr", - "howtos/secrets-management", - { - "type": "category", - "label": "Workload Identity", - "items": [ - "howtos/workload-id/backup-restore-config", - "howtos/workload-id/billing-config", - "howtos/workload-id/eso-config" - ] - } - ] - }, - { - "type": "category", - "label": "Billing & Licensing", - "items": [ - "howtos/billing" - ] - }, - { - "type": "doc", - "id": "reference/index", - "label": "API Reference" - } - ] -} diff --git a/self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json deleted file mode 100644 index 5e6d3cbe..00000000 --- a/self-hosted-spaces_versioned_sidebars/version-1.14-sidebars.json +++ /dev/null @@ -1,116 +0,0 @@ -{ - "sidebar": [ - { - "type": "doc", - "id": "overview/index", - "label": "Overview" - }, - { - "type": "doc", - "id": "self-hosted-spaces-quickstart" - }, - { - "type": "category", - "label": "Concepts", - "items": [ - "concepts/control-planes", - "concepts/groups", - "concepts/deployment-modes" - ] - }, - { - "type": "category", - "label": "Deploy", - "items": [ - "howtos/deployment-reqs", - "howtos/self-hosted-spaces-deployment", - "howtos/certs", - "howtos/proxies-config", - "howtos/attach-detach" - ] - }, - { - "type": "category", - "label": "Configure", - "items": [ - "howtos/configure-ha", - "howtos/administer-features", - "howtos/oidc-configuration", - "howtos/scaling-resources", - "howtos/spaces-management" - ] - }, - { - "type": "category", - "label": "Control Planes", - "items": [ - "howtos/managed-service", - "howtos/control-plane-topologies", - "howtos/auto-upgrade", - "howtos/declarative-ctps", - "howtos/controllers", - "howtos/migrating-to-mcps", - "howtos/simulations" - ] - }, - { - "type": "category", - "label": "Connect", - "items": [ - "howtos/api-connector", - "howtos/ctp-connector", - "howtos/mcp-connector-guide", - "howtos/query-api" - ] - }, - { - "type": "category", - "label": "Observe & Debug", - "items": [ - "howtos/observability", - "howtos/space-observability", - "howtos/debugging-a-ctp", - "howtos/troubleshooting" - ] - }, - { - "type": "category", - "label": "GitOps & Automation", - "items": [ - "howtos/automation-and-gitops/overview", - "howtos/gitops-with-argocd", - "howtos/use-argo" - ] - }, - { - "type": "category", - "label": "Data & Security", - "items": [ - "howtos/backup-and-restore", - "howtos/dr", - "howtos/secrets-management", - { - "type": "category", - "label": "Workload Identity", - "items": [ - "howtos/workload-id/backup-restore-config", - "howtos/workload-id/billing-config", - "howtos/workload-id/eso-config" - ] - } - ] - }, - { - "type": "category", - "label": "Billing & Licensing", - "items": [ - "howtos/billing" - ] - }, - { - "type": "doc", - "id": "reference/index", - "label": "API Reference" - } - ] -} diff --git a/self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json deleted file mode 100644 index c932d0ac..00000000 --- a/self-hosted-spaces_versioned_sidebars/version-1.15-sidebars.json +++ /dev/null @@ -1,115 +0,0 @@ -{ - "sidebar": [ - { - "type": "doc", - "id": "overview/index", - "label": "Overview" - }, - { - "type": "doc", - "id": "self-hosted-spaces-quickstart" - }, - { - "type": "category", - "label": "Concepts", - "items": [ - "concepts/control-planes", - "concepts/groups" - ] - }, - { - "type": "category", - "label": "Deploy", - "items": [ - "howtos/deployment-reqs", - "howtos/self-hosted-spaces-deployment", - "howtos/certs", - "howtos/attach-detach" - ] - }, - { - "type": "category", - "label": "Configure", - "items": [ - "howtos/configure-ha", - "howtos/oidc-configuration", - "howtos/scaling-resources", - "howtos/spaces-management" - ] - }, - { - "type": "category", - "label": "Control Planes", - "items": [ - "howtos/managed-service", - "howtos/control-plane-topologies", - "howtos/auto-upgrade", - "howtos/declarative-ctps", - "howtos/controllers", - "howtos/migrating-to-mcps", - "howtos/simulations" - ] - }, - { - "type": "category", - "label": "Connect", - "items": [ - "howtos/api-connector", - "howtos/ctp-connector", - "howtos/mcp-connector-guide", - "howtos/query-api" - ] - }, - { - "type": "category", - "label": "Observe & Debug", - "items": [ - "howtos/observability", - "howtos/space-observability", - "howtos/ctp-audit-logs", - "howtos/debugging-a-ctp", - "howtos/troubleshooting" - ] - }, - { - "type": "category", - "label": "GitOps & Automation", - "items": [ - "howtos/automation-and-gitops/overview", - "howtos/gitops-with-argocd", - "howtos/use-argo" - ] - }, - { - "type": "category", - "label": "Data & Security", - "items": [ - "howtos/backup-and-restore", - "howtos/dr", - "howtos/secrets-management", - { - "type": "category", - "label": "Workload Identity", - "items": [ - "howtos/workload-id/backup-restore-config", - "howtos/workload-id/billing-config", - "howtos/workload-id/eso-config" - ] - } - ] - }, - { - "type": "category", - "label": "Billing & Licensing", - "items": [ - "howtos/billing", - "howtos/capacity-licensing" - ] - }, - { - "type": "doc", - "id": "reference/index", - "label": "API Reference" - } - ] -} diff --git a/self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json b/self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json deleted file mode 100644 index b3429579..00000000 --- a/self-hosted-spaces_versioned_sidebars/version-1.16-sidebars.json +++ /dev/null @@ -1,131 +0,0 @@ -{ - "sidebar": [ - { - "type": "doc", - "id": "overview/index", - "label": "Overview" - }, - { - "type": "doc", - "id": "self-hosted-spaces-quickstart" - }, - { - "type": "category", - "label": "Concepts", - "items": [ - "concepts/control-planes", - "concepts/groups", - "concepts/deployment-modes" - ] - }, - { - "type": "category", - "label": "Deploy", - "items": [ - "howtos/deployment-reqs", - "howtos/self-hosted-spaces-deployment", - "howtos/certs", - "howtos/proxies-config", - "howtos/ingress", - "howtos/ingress-nginx-migration", - "howtos/mirror-images", - "howtos/attach-detach" - ] - }, - { - "type": "category", - "label": "Configure", - "items": [ - "howtos/configure-ha", - "howtos/administer-features", - "howtos/oidc-configuration", - "howtos/scaling-resources", - "howtos/spaces-management" - ] - }, - { - "type": "category", - "label": "Control Planes", - "items": [ - "howtos/managed-service", - "howtos/control-plane-topologies", - "howtos/auto-upgrade", - "howtos/declarative-ctps", - "howtos/controllers", - "howtos/migrating-to-mcps", - "howtos/simulations" - ] - }, - { - "type": "category", - "label": "Connect", - "items": [ - "howtos/api-connector", - "howtos/ctp-connector", - "howtos/mcp-connector-guide", - "howtos/query-api", - "howtos/deploy-query-api" - ] - }, - { - "type": "category", - "label": "Observe & Debug", - "items": [ - "howtos/observability", - "howtos/space-observability", - { - "type": "category", - "label": "Tracing", - "items": [ - "howtos/tracing/overview", - "howtos/tracing/query-api", - "howtos/tracing/spaces-api", - "howtos/tracing/spaces-router" - ] - }, - "howtos/ctp-audit-logs", - "howtos/debugging-a-ctp", - "howtos/troubleshooting" - ] - }, - { - "type": "category", - "label": "GitOps & Automation", - "items": [ - "howtos/gitops", - "howtos/use-argo" - ] - }, - { - "type": "category", - "label": "Data & Security", - "items": [ - "howtos/backup-and-restore", - "howtos/dr", - "howtos/secrets-management", - { - "type": "category", - "label": "Workload Identity", - "items": [ - "howtos/workload-id/backup-restore-config", - "howtos/workload-id/billing-config", - "howtos/workload-id/eso-config" - ] - } - ] - }, - { - "type": "category", - "label": "Billing & Licensing", - "items": [ - "howtos/billing", - "howtos/capacity-licensing" - ] - }, - { - "type": "doc", - "id": "reference/index", - "label": "API Reference" - } - ] -} From 447b7ba92e66700b40cea33eb2e83b55eb28acc1 Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Mon, 27 Apr 2026 20:46:52 -0400 Subject: [PATCH 4/4] initial commit --- docs/getstarted/develop-with-ai.md | 297 +++++++++++++++++++++++++++++ 1 file changed, 297 insertions(+) create mode 100644 docs/getstarted/develop-with-ai.md diff --git a/docs/getstarted/develop-with-ai.md b/docs/getstarted/develop-with-ai.md new file mode 100644 index 00000000..7705ec32 --- /dev/null +++ b/docs/getstarted/develop-with-ai.md @@ -0,0 +1,297 @@ +--- +title: Develop with AI +description: Connect AI coding assistants and AI operations to Upbound using MCP servers. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Upbound provides Model Context Protocol (MCP) servers that give AI tools direct +access to Upbound resources. Use them to connect your AI coding assistant or +Kubernetes CLI to the Upbound Marketplace, or deploy them inside your control +plane to give AI operations access to cluster data at runtime. + +## Marketplace MCP server + +The marketplace MCP server lets your AI coding assistant search and explore the +[Upbound Marketplace][marketplace]. Use it to find packages, browse provider +repositories, and retrieve package metadata including CRDs and usage examples. + +The server requires UP CLI authentication. Log in before starting: + +```shell +up login +``` + +:::info +For kubectl-ai, you also need an LLM API key configured. kubectl-ai uses Gemini +by default. Set `GEMINI_API_KEY` before running any commands. See the +[kubectl-ai docs][kubectl-ai] for other supported providers. +::: + + + + +1. Start the marketplace MCP server: + + ```shell + docker run --name mcp-marketplace --rm -d -p 8765:8765 \ + -v "$HOME/.up:/mcp/.up:ro" \ + xpkg.upbound.io/upbound/marketplace-mcp-server-http:v0.1.0 + ``` + + :::tip + The image is built for `linux/amd64`. On Apple Silicon or other ARM64 hosts, + add `--platform linux/amd64` to the `docker run` command to avoid a platform + mismatch warning. + ::: + +2. Register the server with your MCP client: + + + + +```shell +claude mcp add --scope user --transport http marketplace http://localhost:8765/mcp +``` + + + + +Add the following to `~/.config/kubectl-ai/mcp.yaml`: + +```yaml +servers: + - name: marketplace + url: http://localhost:8765/mcp +``` + +Then run kubectl-ai with MCP client mode enabled: + +```shell +kubectl-ai --mcp-client "find providers for AWS S3" +``` + + + + +```json +{ + "mcpServers": { + "marketplace": { + "transport": "http", + "url": "http://localhost:8765/mcp" + } + } +} +``` + + + + +3. Restart your AI tool to pick up the new server. + +:::tip +Call the `reload_auth` tool in your AI session to refresh marketplace +credentials after running `up login` or switching profiles, without restarting +the server. +::: + + + + +Configure your MCP client to run the server via Docker directly. + + + + +```shell +claude mcp add --scope user marketplace -- \ + docker run --rm -i \ + -v "$HOME/.up:/mcp/.up:ro" \ + xpkg.upbound.io/upbound/marketplace-mcp-server:v0.1.0 +``` + + + + +Add the following to `~/.config/kubectl-ai/mcp.yaml`, replacing `/home/your-username` with your home directory path: + +```yaml +servers: + - name: marketplace + command: docker + args: + - run + - --rm + - -i + - -v + - /home/your-username/.up:/mcp/.up:ro + - xpkg.upbound.io/upbound/marketplace-mcp-server:v0.1.0 +``` + +Then run kubectl-ai with MCP client mode enabled: + +```shell +kubectl-ai --mcp-client "find providers for AWS S3" +``` + + + + +Replace `/home/your-username` with your home directory path: + +```json +{ + "mcpServers": { + "marketplace": { + "command": "docker", + "args": [ + "run", "--rm", "-i", + "-v", "/home/your-username/.up:/mcp/.up:ro", + "xpkg.upbound.io/upbound/marketplace-mcp-server:v0.1.0" + ] + } + } +} +``` + + + + + + + +### Available tools + +| Tool | Description | +|---|---| +| `search_packages` | Search the marketplace with filters for family, type, account, tier, and visibility | +| `get_package_metadata` | Retrieve metadata for a specific package | +| `get_package_assets` | Access documentation, icons, and release notes for a package | +| `get_repositories` | Browse organization repositories | +| `get_package_version_resources` | Get resources for a specific package version | +| `get_package_version_composition_resources` | Retrieve Crossplane composition resources | +| `get_package_version_groupkind_resources` | Access resources filtered by group and kind | +| `get_package_version_examples` | Get usage examples for package resources | +| `reload_auth` | Refresh UP CLI authentication without restarting the server | + +## Control plane AI operations + +The control plane MCP server runs as a sidecar inside your control plane and gives AI functions access to pod logs and events at runtime. It's not a tool you configure in your local AI coding assistant — it's deployed as part of the function pipeline that powers [intelligent control plane operations][intelligentOps]. + +### Available tools + +| Tool | Description | +|---|---| +| `get_pod_logs` | Retrieve container logs for a pod | +| `get_pod_events` | Retrieve events associated with a pod | + +### Configure the control plane MCP server + +Before starting, make sure you have: + + +- A Kubernetes cluster with Crossplane installed and `kubectl` configured to reach it +- Cluster-admin permissions or equivalent to create `ClusterRole`, `ClusterRoleBinding`, and `DeploymentRuntimeConfig` resources +- The `crossplane-system` namespace present on the cluster + + +The control plane MCP server runs as a sidecar container alongside +`function-claude`. Configuring it requires RBAC permissions and a +`DeploymentRuntimeConfig` that injects the sidecar into the function's pod. + +1. Create the RBAC resources. Save the following as `permissions.yaml`: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: log-and-event-reader + rules: + - apiGroups: + - "" + resources: + - events + - pods + - pods/log + verbs: + - get + - list + --- + apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: log-and-event-reader + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: log-and-event-reader + subjects: + - kind: ServiceAccount + name: function-pod-analyzer + namespace: crossplane-system + ``` + + Apply it to your cluster: + + ```shell + kubectl apply -f permissions.yaml + ``` + +2. Create a `DeploymentRuntimeConfig` that deploys the MCP server as a sidecar + and points `function-claude` to it. Save the following as + `deploymentruntimeconfig.yaml`: + + ```yaml + apiVersion: pkg.crossplane.io/v1beta1 + kind: DeploymentRuntimeConfig + metadata: + name: ctp-mcp + spec: + serviceAccountTemplate: + metadata: + name: function-pod-analyzer + deploymentTemplate: + spec: + selector: {} + template: + spec: + containers: + - name: package-runtime + env: + - name: MCP_SERVER_TOOL_CTP1_TRANSPORT + value: http-stream + - name: MCP_SERVER_TOOL_CTP1_BASEURL + value: http://localhost:8080/mcp + - name: controlplane-mcp-server + image: xpkg.upbound.io/upbound/controlplane-mcp-server:{version} + ``` + + Apply it to your cluster: + + ```shell + kubectl apply -f deploymentruntimeconfig.yaml + ``` + +3. Reference the `DeploymentRuntimeConfig` in your `function-claude` `Function` + resource: + + ```yaml + apiVersion: pkg.crossplane.io/v1 + kind: Function + metadata: + name: upbound-function-claude + spec: + package: xpkg.upbound.io/upbound/function-claude:v0.2.0 + runtimeConfigRef: + name: ctp-mcp + ``` + + `MCP_SERVER_TOOL_CTP1_BASEURL` tells `function-claude` where to reach the + sidecar. The `ClusterRoleBinding` grants the `function-pod-analyzer` service + account permission to read pod logs and events. + +[marketplace]: https://marketplace.upbound.io +[intelligentOps]: /manuals/uxp/concepts/operations/intelligent-operations/ +[kubectl-ai]: https://github.com/GoogleCloudPlatform/kubectl-ai