From 59ff1513cb35714d4a79f7215afc9c94a109c35a Mon Sep 17 00:00:00 2001 From: anirudhprasad-sap Date: Mon, 10 Aug 2026 11:09:23 +0200 Subject: [PATCH 1/2] Update SKILL.md description and add CAP Operator Plugin reference documentation --- .agents/skills/cap-operator/SKILL.md | 24 ++- .../references/cap-operator-plugin.md | 187 ++++++++++++++++++ 2 files changed, 210 insertions(+), 1 deletion(-) create mode 100644 .agents/skills/cap-operator/references/cap-operator-plugin.md diff --git a/.agents/skills/cap-operator/SKILL.md b/.agents/skills/cap-operator/SKILL.md index 0550327c..c83346ca 100644 --- a/.agents/skills/cap-operator/SKILL.md +++ b/.agents/skills/cap-operator/SKILL.md @@ -1,6 +1,6 @@ --- name: cap-operator -description: Manage the lifecycle of multi-tenant SAP CAP applications on Kubernetes using CAP Operator custom resources (CAPApplication, CAPApplicationVersion, CAPTenant, Domain, ClusterDomain). Use when deploying, upgrading, configuring domains, rotating credentials, or troubleshooting CAP Operator-managed apps. +description: Manage the lifecycle of multi-tenant SAP CAP applications on Kubernetes using CAP Operator custom resources (CAPApplication, CAPApplicationVersion, CAPTenant, Domain, ClusterDomain). Use when deploying, upgrading, configuring domains, rotating credentials, troubleshooting CAP Operator-managed apps, or generating Helm charts with the CAP Operator Plugin. license: Apache-2.0 compatibility: Requires kubectl access to a Kubernetes cluster with CAP Operator installed (sme.sap.com/v1alpha1 CRDs). If kubectl commands return "No resources found" or "the server doesn't have a resource type", verify CAP Operator is installed by running `kubectl get crd | grep sme.sap.com`. If no CRDs are listed, direct the user to install CAP Operator before proceeding. metadata: @@ -122,3 +122,25 @@ Tuned via env vars on the controller deployment. Key variables: | `MAX_CONCURRENT_RECONCILES_CAP_TENANT_OPERATION` | CAPTenantOperation reconciliation concurrency | Full list: `website/content/en/docs/configuration/_index.md` | https://sap.github.io/cap-operator/docs/configuration/ + +## CAP Operator Plugin (Helm Chart Generation) + +The `@cap-js/cap-operator-plugin` CDS plugin scaffolds the Helm chart for a CAP application, generates runtime values, and builds the final deployable chart. + +**Quick start:** +```sh +npm add @cap-js/cap-operator-plugin -D +cds add cap-operator --with-templates # default +npx cap-op-plugin generate-runtime-values +helm upgrade -i -n chart -f chart/runtime-values.yaml +``` + +**Chart variants:** + +| Command | Use when | +|---|---| +| `cds add cap-operator --with-templates` | Default — includes `chart/templates/`, editable if needed | +| `cds add cap-operator --with-configurable-templates` | You need Helm template functions inside CAP Operator resources | +| `cds add cap-operator --with-service-only` | Tenant-independent service-only application | + +See [CAP Operator Plugin reference](references/cap-operator-plugin.md) for full details: installation, chart variants, `runtime-values.yaml` generation, and deployment commands. diff --git a/.agents/skills/cap-operator/references/cap-operator-plugin.md b/.agents/skills/cap-operator/references/cap-operator-plugin.md new file mode 100644 index 00000000..13f6cd38 --- /dev/null +++ b/.agents/skills/cap-operator/references/cap-operator-plugin.md @@ -0,0 +1,187 @@ +# CAP Operator Plugin + +The [`@cap-js/cap-operator-plugin`](https://github.com/cap-js/cap-operator-plugin) is a CDS plugin that generates the Helm chart (and its supporting files) needed to deploy a multi-tenant CAP application with CAP Operator. Use it to scaffold the chart, generate runtime values, and build the final deployable chart. + +Plugin docs: https://github.com/cap-js/cap-operator-plugin#readme + +--- + +## Installing the Plugin + +```sh +npm add @cap-js/cap-operator-plugin -D +``` + +**Requirements:** `@sap/cds >= 9`, `@sap/cds-dk >= 9`, `@sap/cds-foss >= 5`. + +--- + +## Generating the Helm Chart + +```sh +cds add cap-operator --with-templates +# or, when Helm template functions are needed inside CAP Operator resources: +cds add cap-operator --with-configurable-templates +``` + +This creates a `chart/` folder including a `chart/templates/` folder — the chart is deployment-ready without any further build step. + +### `--with-templates` (default choice) + +```sh +cds add cap-operator --with-templates +``` + +Creates `chart/Chart.yaml`, `chart/values.yaml`, `chart/values.schema.json`, and a `chart/templates/` folder. The templates can be edited directly when more complex scenarios require it. + +What lands in `chart/templates/`: +- `service-binding.yaml` / `service-instance.yaml` — static BTP service operator templates +- `_helpers.tpl` — generated helpers (adjusts for xsuaa vs IAS) +- `domain.yaml` — a `sme.sap.com/v1alpha1` `Domain` resource +- `cap-operator-cros.yaml` — the `CAPApplication` + `CAPApplicationVersion` template, using `range` over `values.workloads` + +### `--with-configurable-templates` + +```sh +cds add cap-operator --with-configurable-templates +``` + +Produces a chart where all CAP Operator resource configuration lives in `templates/cap-operator-cros.yaml` rather than in `values.yaml`. Workload images are the only workload-related values kept in `values.yaml`. This unlocks full Helm template functions (`if`, `range`, custom helpers) inside CAP Operator resources. + +Key differences from `--with-templates`: +- `cap-operator-cros.yaml` is the expanded/explicit variant — each workload type (server, app-router, tenant-job, content-deploy, ams-deployer) is written out individually with Helm conditionals. +- `values.yaml` contains only workload image references; ports, env, `tenantOperations`, `contentJobs`, and `serviceExposures` live in `templates/cap-operator-cros.yaml`. +- `Chart.yaml` carries the annotation `app.kubernetes.io/part-of: cap-operator-configurable-templates`. + +The two flags are mutually exclusive. + +### `--with-service-only` + +```sh +cds add cap-operator --with-service-only +``` + +For tenant-independent ("service-only") applications. Adds only service-related configurations — no tenant provisioning, no saas-registry wiring. See [service-only workloads](https://sap.github.io/cap-operator/docs/usage/services-workload/). + +### Detecting the chart variant + +When working with an existing chart, read `chart/Chart.yaml` annotations to determine the variant: + +| Annotation | Value | Variant | +|---|---|---| +| `app.kubernetes.io/part-of` | `cap-operator-configurable-templates` | `--with-configurable-templates` | +| `app.kubernetes.io/component` | `service-only` | `--with-service-only` | +| *(neither)* | — | `--with-templates` | + +### Where to edit workload configuration + +| What to change | `--with-templates` | `--with-configurable-templates` | +|---|---|---| +| Workload images | `chart/values.yaml` | `chart/values.yaml` | +| Env vars, ports, resource limits | `chart/values.yaml` | `chart/templates/cap-operator-cros.yaml` | +| `tenantOperations`, `contentJobs`, `serviceExposures` | `chart/values.yaml` | `chart/templates/cap-operator-cros.yaml` | +| Service instances / bindings | `chart/values.yaml` | `chart/values.yaml` | + +### Validating the chart + +```sh +helm lint chart/ +``` + +Validation errors for runtime values (fields populated by `runtime-values.yaml`) can be ignored at this stage. + +### Migrating deprecated fields + +To migrate, upgrade the plugin and re-run: + +```sh +cds add cap-operator --with-templates --force +``` + +`--force` overwrites the generated files. Review the diff (`git diff`) and selectively accept the plugin's changes while restoring any of your own customisations that were overwritten. Deploy only after the review is complete. + +| Deprecated field | Deprecated since | Required plugin | Notes | +|---|---|---|---| +| `CAPApplication.spec.provider` (`subdomain`, `tenantId`) | CAP Operator v0.31.0 | v0.17.0+ | Removed from generated chart. Existing provider tenants must be **manually cleaned up** in the cluster. | +| `CAPApplication.spec.globalAccountId` | CAP Operator v0.28.0 | v0.15.0+ | Replaced by `providerSubaccountId`. | + +### Converting an existing chart + +If you already have a basic chart and want to switch to configurable templates: + +```sh +npx cap-op-plugin convert-to-configurable-template-chart +# also migrate runtime-values.yaml: +npx cap-op-plugin convert-to-configurable-template-chart --with-runtime-yaml chart/runtime-values.yaml +``` + +--- + +## Generating `runtime-values.yaml` + +`values.yaml` holds design-time (repo-committable) values. Environment-specific ("runtime") values are kept in `chart/runtime-values.yaml`, which **must not** be committed. + +**Required inputs:** + +| Field | Description | +|---|---| +| `appName` | Lowercase alphanumeric + hyphens only (`^[a-z0-9-]+$`). Used as `xsappname` in saas-registry. | +| `capOperatorSubdomain` | Subdomain where CAP Operator is installed. Kyma default: `cap-op`. | +| `clusterDomain` | Shoot/cluster domain. Kyma: `kubectl get gateway -n kyma-system kyma-gateway -o jsonpath='{.spec.servers[0].hosts[0]}'` | +| `providerSubaccountId` | BTP provider subaccount ID. | +| `hanaInstanceId` *(optional)* | Required only when multiple HANA instances exist in the subaccount. | +| `imagePullSecret` *(optional)* | Kubernetes secret for private image registries. | + +**Interactive mode** — prompts for each value: + +```sh +npx cap-op-plugin generate-runtime-values +``` + +**File mode** — reads values from a YAML file: + +```sh +npx cap-op-plugin generate-runtime-values --with-input-yaml +``` + +Sample input file: + +```yaml +appName: incidentapp +capOperatorSubdomain: cap-op +clusterDomain: abc.com +providerSubaccountId: da37c8e0-74d4-abcd-b5e2-sd8f7d8f7d8f +hanaInstanceId: 46e285d9-abcd-4c7d-8ebb-502sd8f7d8f7d +imagePullSecret: regcred +``` + +What gets written to `chart/runtime-values.yaml`: +- `serviceInstances` parameters — saas-registry/subscription-manager callback URLs (`capOperatorSubdomain.clusterDomain`), xsuaa/identity `xsappname` +- `serviceBindings` (IAS only) +- `app.domains.primary: .` +- `app.istioIngressGatewayLabels` +- `btp.providerSubaccountId` +- `imagePullSecrets` (omitted if not provided) +- For basic charts: `CDS_CONFIG` env var (with `database_id`) merged into relevant workloads +- For configurable-template charts: `hanaInstanceId` as a top-level value + +> When using GitOps tools (e.g. Argo CD) that always render `Release.Revision` as `1`, set `app.version: "1.2.3"` in `runtime-values.yaml` to pin the `CAPApplicationVersion` version explicitly. + +--- + +## Deploying + +```sh +helm upgrade -i -n /chart \ + -f /chart/runtime-values.yaml +``` + +To pass `xs-security.json` as `jsonParameters` for the xsuaa service instance: + +```sh +helm upgrade -i -n /chart \ + --set-file serviceInstances.xsuaa.jsonParameters=/xs-security.json \ + -f /chart/runtime-values.yaml +``` + +> **Environment variable consistency:** Helm does not merge arrays. If `values.yaml` defines env vars for a workload and `runtime-values.yaml` also defines env vars for the same workload, `runtime-values.yaml` must repeat all existing vars plus any new ones. The plugin copies existing env vars automatically when generating `runtime-values.yaml` via the CLI. From c35f843015086220c858a2be6d496b38e809df38 Mon Sep 17 00:00:00 2001 From: anirudhprasad-sap Date: Thu, 13 Aug 2026 11:56:37 +0200 Subject: [PATCH 2/2] skills update --- .agents/skills/cap-operator/SKILL.md | 2 ++ .../references/cap-operator-plugin.md | 17 +++++++++++++---- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/.agents/skills/cap-operator/SKILL.md b/.agents/skills/cap-operator/SKILL.md index c83346ca..04fe37c9 100644 --- a/.agents/skills/cap-operator/SKILL.md +++ b/.agents/skills/cap-operator/SKILL.md @@ -131,6 +131,8 @@ The `@cap-js/cap-operator-plugin` CDS plugin scaffolds the Helm chart for a CAP ```sh npm add @cap-js/cap-operator-plugin -D cds add cap-operator --with-templates # default +# ensure node_modules exists before running the plugin: +npm install npx cap-op-plugin generate-runtime-values helm upgrade -i -n chart -f chart/runtime-values.yaml ``` diff --git a/.agents/skills/cap-operator/references/cap-operator-plugin.md b/.agents/skills/cap-operator/references/cap-operator-plugin.md index 13f6cd38..888ec1f8 100644 --- a/.agents/skills/cap-operator/references/cap-operator-plugin.md +++ b/.agents/skills/cap-operator/references/cap-operator-plugin.md @@ -129,8 +129,15 @@ npx cap-op-plugin convert-to-configurable-template-chart --with-runtime-yaml cha | `capOperatorSubdomain` | Subdomain where CAP Operator is installed. Kyma default: `cap-op`. | | `clusterDomain` | Shoot/cluster domain. Kyma: `kubectl get gateway -n kyma-system kyma-gateway -o jsonpath='{.spec.servers[0].hosts[0]}'` | | `providerSubaccountId` | BTP provider subaccount ID. | -| `hanaInstanceId` *(optional)* | Required only when multiple HANA instances exist in the subaccount. | -| `imagePullSecret` *(optional)* | Kubernetes secret for private image registries. | + +**Optional inputs:** + +| Field | Description | +|---|---| +| `hanaInstanceId` | Required only when multiple HANA instances exist in the subaccount. | +| `imagePullSecret` | Kubernetes secret for private image registries. | + +**Note:** `npx cap-op-plugin` requires `node_modules` to be present. If not already installed, run `npm install` first. **Interactive mode** — prompts for each value: @@ -171,16 +178,18 @@ What gets written to `chart/runtime-values.yaml`: ## Deploying +If `values.yaml` includes an `xsuaa` service instance (the common case), use `--set-file` to pass `xs-security.json` as `jsonParameters`: + ```sh helm upgrade -i -n /chart \ + --set-file serviceInstances.xsuaa.jsonParameters=/xs-security.json \ -f /chart/runtime-values.yaml ``` -To pass `xs-security.json` as `jsonParameters` for the xsuaa service instance: +If there is no xsuaa service instance: ```sh helm upgrade -i -n /chart \ - --set-file serviceInstances.xsuaa.jsonParameters=/xs-security.json \ -f /chart/runtime-values.yaml ```