cap-operator

CAP Operator Skill

Manages the lifecycle of multi-tenant SAP Cloud Application Programming Model (CAP) applications on Kubernetes via the CAP Operator controller.

Response rule: Always include a link to the relevant page on https://sap.github.io/cap-operator/docs/ when answering any question. Match the topic to the most specific page available (resource reference, usage guide, troubleshooting, configuration, etc.).

Full docs & API reference: website/content/en/docs/ | https://sap.github.io/cap-operator/docs/

Custom Resources

Resource	Scope	Purpose
CAPApplication	Namespaced	High-level app: BTP services, domain refs, provider subaccount
CAPApplicationVersion	Namespaced	Immutable version: images, workloads, tenant operation steps
CAPTenant	Namespaced	A subscribed consumer tenant — controller-managed only
CAPTenantOperation	Namespaced	Orchestrates provisioning/upgrade/deprovisioning — auto-created
Subscription	Namespaced	Represents one consumer subscription — created by subscription server
SubscriptionProvider	Namespaced	Caches subscription credentials and dependency info — auto-created by controller
Domain	Namespaced	Istio Gateway + TLS + DNS for one application
ClusterDomain	Cluster	Shared domain config across applications

Critical rules:

• CAPApplicationVersion is immutable after creation. To upgrade, create a new resource with a higher semantic version.
• Subscription must never be created or deleted manually — managed exclusively by the subscription server in response to SaaS Provisioning service callbacks.
• CAPTenant must never be created or deleted manually — created by the controller as a child of Subscription.
• CAPTenantOperation is auto-created by the controller — do not create or delete manually.
• SubscriptionProvider is auto-created and kept in sync by the controller for each CAPApplication — do not create, modify, or delete manually.
• Never remove finalizers from CAP Operator resources manually.
• CAPApplication.spec.provider is deprecated. It previously caused the controller to auto-create a provider CAPTenant, but that behavior has been removed. All tenants (including the provider) must now be subscribed to explicitly. If kubectl get captenant -n <namespace> returns empty, this is expected for apps with no active subscriptions.

Common Operations

Deploy a new application

1. Create Domain or ClusterDomain
2. Create CAPApplication (references BTP services + domain)
3. Create CAPApplicationVersion (images + workloads)

See deploy reference for full YAML examples.

Upgrade to a new version

Create a new CAPApplicationVersion with a higher semantic version — do not edit the existing one. The controller automatically upgrades all tenants and updates Istio VirtualService routing.

See upgrade reference for details and tenantOperations / contentJobs configuration.

Check status

kubectl get capapplication,capapplicationversion,captenant,captenantoperation,subscription -n <namespace>
kubectl describe capapplication <name> -n <namespace>
kubectl get domain,clusterdomain -A

Status flows:

• CAPApplicationVersion: Processing → Ready | Error
• CAPTenant: Provisioning → Ready | Upgrading → Ready | Deleting
• CAPTenantOperation: Processing → Completed | Failed
• Subscription: Processing → Ready | ProcessingError (retryable) | Error (terminal) | Deleting

Domain management

• Domain — namespace-scoped, one application. ClusterDomain — cluster-scoped, shared.
• TLS modes: Simple (default), Mutual, OptionalMutual
• DNS modes: None (default), Wildcard, Subdomain, Custom
• First entry in domainRefs is the primary domain.
• domains inline section in CAPApplication was removed in v0.26.0; use domainRefs instead.

See domain reference.

Service exposures (tenant-agnostic)

Use serviceExposures in CAPApplicationVersion to expose workloads at fixed subdomains independent of tenant routing. Order routes most-specific-first.

See service exposure reference.

Credential rotation rollout

Set rolloutOnCredentialUpdate: true on CAPApplication to auto-restart workloads when BTP service credential Secrets change. Uses rolling restart (zero downtime). Keep old credentials valid for at least 24 hours after issuing new ones.

See credential rotation reference.

Version cleanup (monitoring-based)

Enable with annotation sme.sap.com/enable-cleanup-monitoring: "true" on CAPApplication. Configure deletionRules.expression (PromQL) on a workload's monitoring section; when the expression evaluates to true the version is eligible for deletion.

See Version monitoring (website/content/en/docs/usage/version-monitoring.md).

Key Annotations

Annotation	Resource	Effect
sme.sap.com/enable-cleanup-monitoring: "true"	CAPApplication	Enable monitoring-based version cleanup
sme.sap.com/enable-version-affinity: "true"	CAPApplication	Keep users on current version until logout (experimental)
sme.sap.com/logout-endpoint: "<path>"	CAPApplicationVersion	Custom logout path for version affinity

Troubleshooting

Common symptoms and fixes — CAPApplicationVersion/CAPTenant stuck, WaitingForSecrets, finalizers, @sap/cds-mtxs security context, Approuter destination/timeout issues, credential injection, SAP HANA connection errors, and controller memory limits.

See troubleshooting reference | website/content/en/docs/troubleshoot/_index.md | https://sap.github.io/cap-operator/docs/troubleshoot/

Controller Configuration

Tuned via env vars on the controller deployment. Key variables:

Variable	Purpose
CERT_MANAGER	gardener or cert-manager.io
DNS_MANAGER	gardener or kubernetes
MAX_CONCURRENT_RECONCILES_CAP_APPLICATION	CAPApplication reconciliation concurrency
MAX_CONCURRENT_RECONCILES_CAP_APPLICATION_VERSION	CAPApplicationVersion reconciliation concurrency
MAX_CONCURRENT_RECONCILES_CAP_TENANT	CAPTenant reconciliation concurrency
MAX_CONCURRENT_RECONCILES_CAP_TENANT_OPERATION	CAPTenantOperation reconciliation concurrency
MAX_CONCURRENT_RECONCILES_SUBSCRIPTION	Subscription 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.

Do not run any of these steps on skill invocation. Only start when the user explicitly asks to generate a Helm chart or deploy the app. Merely loading this skill (e.g. via /cap-operator) is not a request — describe the skill's capabilities and wait.

Chart generation and deployment are two separate phases with a gate between them — create just the chart; let the user decide if/when to deploy.

1. Scaffold the chart. Pick the variant by checking for a populated MTX sidecar folder (mtx/sidecar with contents): sidecar present → multitenant → --with-templates; no sidecar → service-only → --with-service-only.
2. Ask whether they want to deploy.
3. Only after a yes, collect the runtime inputs (appName, capOperatorSubdomain, clusterDomain, providerSubaccountId) and generate runtime-values.yaml.
4. Validate before deploying — run helm lint with runtime-values.yaml passed in and confirm no required values are missing.
5. Deploy with helm upgrade -i.

See CAP Operator Plugin reference for more details on plugin usage and configuration.