Back to Details

cap-operator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CAP Operator Skill

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/
通过 CAP Operator controller 管理 Kubernetes 上多租户 SAP Cloud Application Programming Model (CAP) 应用程序的生命周期。
响应规则： 回答任何问题时，始终包含指向 https://sap.github.io/cap-operator/docs/ 上相关页面的链接。将主题匹配到可用的最具体页面（资源参考、使用指南、故障排查、配置等）。
完整文档与 API 参考：
website/content/en/docs/
| https://sap.github.io/cap-operator/docs/

Custom Resources

自定义资源

ResourceScopePurpose
CAPApplication
NamespacedHigh-level app: BTP services, domain refs, provider subaccount
CAPApplicationVersion
NamespacedImmutable version: images, workloads, tenant operation steps
CAPTenant
NamespacedA subscribed consumer tenant — controller-managed only
CAPTenantOperation
NamespacedOrchestrates provisioning/upgrade/deprovisioning — auto-created
Subscription
NamespacedRepresents one consumer subscription — created by subscription server
SubscriptionProvider
NamespacedCaches subscription credentials and dependency info — auto-created by controller
Domain
NamespacedIstio Gateway + TLS + DNS for one application
ClusterDomain
ClusterShared 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.
资源作用域用途
CAPApplication
命名空间级高级别应用：BTP 服务、域引用、provider 子账户
CAPApplicationVersion
命名空间级不可变版本：镜像、工作负载、租户操作步骤
CAPTenant
命名空间级已订阅的消费者租户——仅由 controller 管理
CAPTenantOperation
命名空间级编排开通/升级/取消开通——自动创建
Subscription
命名空间级表示一个消费者订阅——由 subscription server 创建
SubscriptionProvider
命名空间级缓存订阅凭据和依赖信息——由 controller 自动创建
Domain
命名空间级为单个应用提供 Istio Gateway + TLS + DNS
ClusterDomain
集群级跨应用共享的域配置
关键规则：
  • CAPApplicationVersion
    创建后不可变。要升级，请创建一个 semantic version 更高的新资源。
  • Subscription
    绝不能手动创建或删除——完全由 subscription server 响应 SaaS Provisioning service 回调来管理。
  • CAPTenant
    绝不能手动创建或删除——由 controller 作为 
    Subscription
    的子资源创建。
  • CAPTenantOperation
    由 controller 自动创建——不要手动创建或删除。
  • SubscriptionProvider
    由 controller 为每个 
    CAPApplication
    自动创建并保持同步——不要手动创建、修改或删除。
  • 绝不要手动移除 CAP Operator 资源上的 finalizers。
  • CAPApplication.spec.provider
    已弃用。它过去曾导致 controller 自动创建 provider 
    CAPTenant
    ，但该行为已被移除。现在所有租户（包括 provider）都必须显式订阅。如果 
    kubectl get captenant -n <namespace>
    返回为空，对于没有活跃订阅的应用来说这是预期结果。

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.
  1. 创建 
    Domain
    或 
    ClusterDomain
  2. 创建 
    CAPApplication
    （引用 BTP 服务 + 域）
  3. 创建 
    CAPApplicationVersion
    （镜像 + 工作负载）
有关完整的 YAML 示例，请参阅部署参考。

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.
创建一个 semantic version 更高的新 
CAPApplicationVersion
——不要编辑现有的那个。
Controller 会自动升级所有租户并更新 Istio 
VirtualService
路由。
有关详细信息以及 
tenantOperations
/ 
contentJobs
配置，请参阅升级参考。

Check status

检查状态

bash
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
bash
kubectl get capapplication,capapplicationversion,captenant,captenantoperation,subscription -n <namespace>
kubectl describe capapplication <name> -n <namespace>
kubectl get domain,clusterdomain -A
状态流转：
  • CAPApplicationVersion
    ：
    Processing
    → 
    Ready
    | 
    Error
  • CAPTenant
    ：
    Provisioning
    → 
    Ready
    | 
    Upgrading
    → 
    Ready
    | 
    Deleting
  • CAPTenantOperation
    ：
    Processing
    → 
    Completed
    | 
    Failed
  • Subscription
    ：
    Processing
    → 
    Ready
    | 
    ProcessingError
    （可重试） | 
    Error
    （终止状态） | 
    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.
  • Domain
    ——命名空间级，面向单个应用。
    ClusterDomain
    ——集群级，共享使用。
  • TLS 模式：
    Simple
    （默认）、
    Mutual
    、
    OptionalMutual
  • DNS 模式：
    None
    （默认）、
    Wildcard
    、
    Subdomain
    、
    Custom
  • domainRefs
    中的第一项是主域。
  • CAPApplication
    中的内联 
    domains
    部分已在 v0.26.0 中移除；请改用 
    domainRefs
    。
请参阅域参考。

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.
在 
CAPApplicationVersion
中使用 
serviceExposures
，以固定子域名暴露工作负载，与租户路由无关。路由按从最具体到最不具体的顺序排列。
请参阅服务暴露参考。

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.
在 
CAPApplication
上设置 
rolloutOnCredentialUpdate: true
，以便在 BTP service credential Secrets 发生变化时自动重启工作负载。采用滚动重启（零停机）。签发新凭据后，旧凭据至少保持有效 24 小时。
请参阅凭据轮换参考。

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
).
通过在 
CAPApplication
上添加注解 
sme.sap.com/enable-cleanup-monitoring: "true"
来启用。在工作负载的 
monitoring
部分配置 
deletionRules.expression
（PromQL）；当该表达式求值为 
true
时，该版本即可删除。
请参阅版本监控（
website/content/en/docs/usage/version-monitoring.md
）。

Key Annotations

关键注解

AnnotationResourceEffect
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
注解资源效果
sme.sap.com/enable-cleanup-monitoring: "true"
CAPApplication
启用基于监控的版本清理
sme.sap.com/enable-version-affinity: "true"
CAPApplication
在用户退出前保持用户使用当前版本（实验性）
sme.sap.com/logout-endpoint: "<path>"
CAPApplicationVersion
为版本亲和性指定自定义退出路径

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/
常见症状及修复方法——
CAPApplicationVersion
/
CAPTenant
卡住、
WaitingForSecrets
、finalizers、
@sap/cds-mtxs
security context、Approuter destination/timeout 问题、凭据注入、SAP HANA 连接错误以及 controller 内存限制。
请参阅故障排查参考 | 
website/content/en/docs/troubleshoot/_index.md
| https://sap.github.io/cap-operator/docs/troubleshoot/

Controller Configuration

Controller 配置

Tuned via env vars on the controller deployment. Key variables:
VariablePurpose
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/
通过 controller 部署上的环境变量进行调优。主要变量：
变量用途
CERT_MANAGER
gardener
或 
cert-manager.io
DNS_MANAGER
gardener
或 
kubernetes
MAX_CONCURRENT_RECONCILES_CAP_APPLICATION
CAPApplication
reconciliation 并发数
MAX_CONCURRENT_RECONCILES_CAP_APPLICATION_VERSION
CAPApplicationVersion
reconciliation 并发数
MAX_CONCURRENT_RECONCILES_CAP_TENANT
CAPTenant
reconciliation 并发数
MAX_CONCURRENT_RECONCILES_CAP_TENANT_OPERATION
CAPTenantOperation
reconciliation 并发数
MAX_CONCURRENT_RECONCILES_SUBSCRIPTION
Subscription
reconciliation 并发数
完整列表：
website/content/en/docs/configuration/_index.md
| https://sap.github.io/cap-operator/docs/configuration/

CAP Operator Plugin (Helm Chart Generation)

CAP Operator Plugin（Helm Chart 生成）

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.
@cap-js/cap-operator-plugin
CDS 插件为 CAP 应用搭建 Helm chart 脚手架，生成运行时值，并构建最终可部署的 chart。
在调用 skill 时不要执行以下任何步骤。 只有当用户明确要求生成 Helm chart 或部署应用时才开始。仅仅加载此 skill（例如通过 
/cap-operator
）并不构成请求——请描述该 skill 的能力并等待。
Chart 生成与部署是两个独立阶段，两者之间设有一道关卡——先生成 chart；由用户决定是否以及何时部署。
  1. 搭建 chart 脚手架。 通过检查是否存在已填充的 MTX sidecar 文件夹（
    mtx/sidecar
    且包含内容）来选择变体：存在 sidecar → 多租户 → 
    --with-templates
    ；不存在 sidecar → 仅服务 → 
    --with-service-only
    。
  2. 询问用户是否希望部署。
  3. **只有在用户确认“是”之后，**才收集运行时输入（
    appName
    、
    capOperatorSubdomain
    、
    clusterDomain
    、
    providerSubaccountId
    ）并生成 
    runtime-values.yaml
    。
  4. 部署前进行验证——传入 
    runtime-values.yaml
    运行 
    helm lint
    ，并确认没有缺少必需值。
  5. 使用 
    helm upgrade -i
    部署。
有关插件使用和配置的更多详细信息，请参阅 CAP Operator Plugin 参考。