Documentation

• 1: Concepts
• 1.1: CAP Operator Overview
• 1.1.1: Controller
• 1.1.2: Subscription Server
• 1.2: CAP Application Components
• 2: What's New
• 3: Installation
• 3.1: Prerequisites
• 3.2: Using Helm
• 3.2.1: Configuration
• 3.2.2: Helm Values
• 3.3: Using CAP Operator Manager
• 3.4: Kyma Cluster
• 4: Configuration
• 5: Usage
• 5.1: Prerequisites
• 5.2: Deploying a CAP Application
• 5.3: Domain Management
• 5.3.1: Custom DNS Templates
• 5.3.2: Configuring Additional CA Certificates
• 5.3.3: Configuring cert-manager Certificates
• 5.4: Tenant Subscription
• 5.5: Application Upgrade
• 5.6: Service Exposure
• 5.7: Rollout on Credential Update
• 5.8: Version Monitoring
• 5.9: Operator Metrics
• 5.10: Security
• 5.11: Resources
• 5.11.1: CAPApplication
• 5.11.2: CAPApplicationVersion
• 5.11.3: SubscriptionProvider
• 5.11.4: Subscription
• 5.11.5: CAPTenant
• 5.11.6: CAPTenantOperation
• 5.11.7: CAPTenantOutput
• 5.11.8: Domain
• 5.11.9: ClusterDomain
• 6: Troubleshooting
• 7: Support
• 8: Reference

1 - Concepts

Provisioning and operating an SAP Cloud Application Programming Model (CAP) application on a Kubernetes cluster requires deploying various components in addition to the CAP application server (see a list of typical components). Some of these components can be created during initial system provisioning, while others need to be created or updated at different points in the application lifecycle (Day 2 operations).

Using Helm charts to manage the deployment of a CAP application supports initial system provisioning, but further lifecycle operations (such as tenant provisioning) triggered by external components (SAP BTP) require manual adjustment of the deployed resources. For example, Istio VirtualService resources must be created during tenant provisioning to route incoming HTTP requests on the new tenant subdomain to the application server. Another limitation of Helm charts is the lack of control over the order in which resources are created.

You can gain greater control over deployment and automate lifecycle operations by extending the Kubernetes API with custom resources that describe CAP application components and their configuration, along with controllers to reconcile them. Like standard Kubernetes controllers, these custom controllers watch for changes in custom resource objects and work to bring the cluster state to the desired state.

CAP Operator comprises custom resource definitions that describe CAP application components, a controller that reconciles these resources, and additional components that support lifecycle management.

1.1 - CAP Operator Overview

CAP Operator consists of the following components:

1. CAP Controller: A native Kubernetes controller that reconciles custom resources defined as part of the operator.
2. Webhooks: Validating webhooks that ensure consistency of custom resource objects submitted to the Kubernetes API server.
3. Subscription Server: A web server that handles HTTP requests submitted by SAP BTP saas-registry service instances during tenant subscription and unsubscription.

The following diagram shows how the main components interact when deployed to a cluster:

For more details about each component, see the following pages.

1.1.1 - Controller

The CAP controller uses client-go from Kubernetes, which provides the tools and utilities needed to interact with the Kubernetes API server and manage the custom resources defined by CAP Operator.

The controller uses Informers to watch certain resources and invokes registered event handlers when these resources are modified. To streamline the processing of such notifications, rate-limiting queues are implemented that store changes and allow processing of items in independent reconciliation threads (goroutines). This design enables sequential processing of changed items and avoids conflicts.

The following namespaced custom resources are reconciled by the CAP controller:

• CAPApplication: Defines a high-level application, its domains, and the consumed SAP BTP services.
• CAPApplicationVersion: A child resource of CAPApplication that contains container images used to deploy application components (workloads) of a specific version.
• CAPTenant: A child resource of CAPApplication that corresponds to an SAP BTP subaccount subscribed to the application.
• CAPTenantOperation: Represents a provisioning, deprovisioning, or upgrade operation on a tenant, scheduled as a child resource of a CAPTenant and executed as a sequence of specified steps.

Parent-child relationships between custom resources are established by defining owner references for the children.

1.1.2 - Subscription Server

The Subscription Server handles HTTP requests from the SAP Software-as-a-Service Provisioning service for tenant subscription operations on SAP Cloud Application Programming Model applications installed in the cluster.

During the creation of a saas-registry service instance (in the provider subaccount), callback URLs are configured to point to the subscription server routes. Additionally, the getDependencies URLs can also be configured to point to the subscription server routes.

When a consumer tenant subscribes to an application managed by the operator, the subscription server receives the callback, validates the request using credentials from the corresponding SubscriptionProvider resource, and creates a Subscription resource in the namespace of the identified CAPApplication. The controller then creates the CAPTenant and drives it through the provisioning flow.

The subscription server returns an Accepted (202) response and starts a background routine that polls Subscription.status while the Subscription and CAPTenant resources are independently reconciled by the controller.

Once the tenant provisioning process completes (or fails), the tracking routine returns the appropriate status to the SaaS Registry via an asynchronous callback.

(More details about asynchronous tenant subscription)

This asynchronous approach avoids timeouts during synchronous calls and enables the scheduling of dedicated jobs (via CAPTenantOperation) for completing the subscription and performing any additional cluster tasks (for example, creating an Istio VirtualService for the tenant subdomain).

1.2 - CAP Application Components

A full-stack application built with the SAP Cloud Application Programming Model has the following components:

SAP BTP Service Instances

Multi-tenant CAP-based applications consume services from SAP BTP such as SAP Authorization and Trust Management Service and SAP Software-as-a-Service Provisioning service. You need to create these service instances within an SAP BTP provider account along with service keys (bindings) that generate the credentials used by the application to access these services.

CAP Application Server

The application provides data models that are deployed to the connected database. An HTTP server exposes defined services and handles server-side application logic. For more details, see the SAP Cloud Application Programming Model documentation. It is also possible to split the application into multiple servers (services) that work together.

CAP Components to Support Multitenancy

CAP provides the module @sap/cds-mtxs, which can be operated as a sidecar (a component running independently from the application server). This component handles requests related to tenant management, such as onboarding, which creates the required schema in the connected database. This module also supports triggering tenant management tasks as CLI commands.

Approuter

The Approuter, or an extended version of it, authenticates requests (using the SAP Authorization and Trust Management Service) and routes them to the application servers or related services (for example, SAP HTML5 Application Repository service for SAP BTP).

SAP Fiori Applications

Multiple SAP Fiori front-end applications can connect to the CAP application back end. These UI5 applications are deployed to the SAP HTML5 Application Repository service for SAP BTP and served from there. Similarly, the application can have content specific to other services that needs to be deployed.

2 - What's New

Recent updates

Previous updates

3 - Installation

This page provides an overview of available methods to install CAP Operator on a Kubernetes cluster.

3.1 - Prerequisites

We recommend using a “Gardener” managed cluster to deploy CAP applications managed with CAP Operator.

Set up the following prerequisites in the Kubernetes cluster before installing CAP Operator:

Istio (version >= 1.22)

The Istio service mesh is used for HTTP traffic management. CAP Operator creates Istio resources to manage incoming HTTP requests to the application and to route requests on specific (tenant) subdomains.

Determine the public ingress gateway subdomain and the overall shoot domain for the system, and specify them in the chart values. See here for an example.

Note: Istio promoted many of its APIs to v1 in the 1.22 release. As of CAP Operator release v0.11.0, Istio version >= 1.22 is therefore a prerequisite.

sap-btp-service-operator or cf-service-operator

These operators manage SAP BTP service instances and service bindings from within the Kubernetes cluster.

If some SAP BTP services are not available for Kubernetes platforms, you can use cf-service-operator, which creates the services for a Cloud Foundry space and inserts the required access credentials as Secrets into the Kubernetes cluster.

Service credentials added as Kubernetes Secrets by these operators support additional metadata. If you do not use this feature, set secretKey: credentials in the spec to ensure that service credentials retain JSON data as-is. We recommend using secretKey even when credential metadata is available, to reduce the overhead of parsing multiple JSON attributes.

Gardener certificate management

This component is available in “Gardener” managed clusters and is used to manage TLS certificates and issuers. Alternatively, you can use cert-manager.io cert-manager.

3.2 - Using Helm

To install CAP Operator components, use the Helm chart published as an OCI package at oci://ghcr.io/sap/cap-operator-lifecycle/helm/cap-operator.

Installation

Create a namespace and install the Helm chart in that namespace by specifying the domain and dnsTarget for your subscription server, either:

• As command line parameters:

  kubectl create namespace cap-operator-system
  helm upgrade -i -n cap-operator-system cap-operator oci://ghcr.io/sap/cap-operator-lifecycle/helm/cap-operator --set subscriptionServer.domain=cap-operator.<CLUSTER-DOMAIN> --set subscriptionServer.dnsTarget=public-ingress.<CLUSTER-DOMAIN>
  

• As a YAML values file:

  kubectl create namespace cap-operator-system
  helm upgrade -i -n cap-operator-system cap-operator oci://ghcr.io/sap/cap-operator-lifecycle/helm/cap-operator -f my-cap-operator-values.yaml
  

  The values file my-cap-operator-values.yaml can have the following content:

  subscriptionServer:
    dnsTarget: public-ingress.<CLUSTER-DOMAIN>
    domain: cap-operator.<CLUSTER-DOMAIN>
  

3.2.1 - Configuration

Optional Configuration

• Enable Service Monitors for metrics

  To enable monitoring via metrics emitted by CAP Operator components, set the following value:

  monitoring:
    enabled: true # <-- enables creation of service monitors for metrics emitted by CAP Operator components
  

  To enable detailed operational metrics for the controller:

  controller:
      detailedOperationalMetrics: true
  

• Set up Prometheus integration for Version Monitoring

  To use the Version Monitoring feature, provide a Prometheus server URL to the CAP Operator. When installing with the Helm chart, specify the following values:

  controller:
    versionMonitoring:
      prometheusAddress: "http://prometheus-operated.monitoring.svc.cluster.local:9090" # <-- example of a Prometheus server running inside the same cluster
      promClientAcquireRetryDelay: "2h"
      metricsEvaluationInterval: "30m" # <-- interval at which version metrics are evaluated
  

  On startup, the controller attempts to connect to the Prometheus server and fetch runtime information to verify the connection. If the connection fails, the controller retries after the delay specified in controller.versionMonitoring.promClientAcquireRetryDelay. See default values here.

  Note

  • When connecting the controller to a Prometheus server running inside the cluster, ensure that the NetworkPolicy resources required for connecting to the service in the Prometheus namespace are also created.
  • If the Prometheus service is configured to use TLS, mount the relevant CA root certificates as volumes on the controller.

• Configure maximum concurrent reconciles

  The controller reconciles each resource type with a built-in default concurrency. To override these defaults, configure the values explicitly:

  controller:
    maxConcurrentReconciles:
      capApplication: "1"        # default: 1
      capApplicationVersion: "3" # default: 3
      capTenant: "10"            # default: 10
      capTenantOperation: "10"   # default: 10
      domain: "1"                # default: 1
      clusterDomain: "1"         # default: 1
      subscription: "10"          # default: 10 or <value of capTenant config, if specified>
  

• Configure controller client rate limiting

  To control the rate at which the controller client sends requests to the Kubernetes API server, configure the QPS (queries per second) and burst values:

  controller:
    clientRateLimiting:
      qps: "20"    # <-- maximum queries per second
      burst: "30"  # <-- maximum burst for throttle
  

• Configure controller rollout delay

  To introduce a delay before the controller rolls out workloads of relevant application versions on credential update (e.g. to allow a safe rollout window), set the rollout delay:

  controller:
    rolloutDelay: "1h" # <-- duration to wait before rolling out version workloads on credential update
  

3.2.2 - Helm Values

3.3 - Using CAP Operator Manager

To install the CAP Operator using CAP Operator Manager, run the following command:

kubectl apply -f https://github.com/SAP/cap-operator-lifecycle/releases/latest/download/manager_manifest.yaml

This creates the cap-operator-system namespace with CAP Operator Manager installed. Once the CAP Operator Manager pod is running, install the CAP Operator by running:

kubectl apply -n cap-operator-system -f https://github.com/SAP/cap-operator-lifecycle/releases/latest/download/manager_default_CR.yaml

This works only if the ingressGatewayLabels in your cluster match the following values:

ingressGatewayLabels:
  - name: istio
    value: ingressgateway
  - name: app
    value: istio-ingressgateway

If not, you must create the CAPOperator resource manually. For details, see the documentation.

3.4 - Kyma Cluster

See installation steps here: https://sap.github.io/cap-operator-lifecycle/docs/installation/kyma-cluster/

4 - Configuration

The following environment variables are used to configure CAP Operator.

Controller

• CERT_MANAGER: The certificate manager used for TLS certificates. Possible values:
  • gardener: “Gardener” certificate management
  • cert-manager.io: cert-manager.io cert-manager
• DNS_MANAGER: The external DNS manager to use. Possible values:
  • gardener: “Gardener” external DNS manager
  • kubernetes: External DNS management from Kubernetes
• PROMETHEUS_ADDRESS: URL of the Prometheus server for executing PromQL queries, for example http://prometheus-operated.monitoring.svc.cluster.local:9090. If not set, the controller still runs the version cleanup loop; however, only versions whose workloads have no deletionRules defined are eligible for cleanup — versions that have deletionRules are skipped until a Prometheus connection becomes available.
• PROM_ACQUIRE_CLIENT_RETRY_DELAY: Time delay between retries when Prometheus client creation or connection check fails.
• METRICS_EVAL_INTERVAL: Time interval between iterations where outdated versions are identified and queued for evaluation.
• MAX_CONCURRENT_RECONCILES_CAP_APPLICATION: Maximum number of concurrent reconciles for CAPApplication (for example, 1).
• MAX_CONCURRENT_RECONCILES_CAP_APPLICATION_VERSION: Maximum number of concurrent reconciles for CAPApplicationVersion (for example, 3).
• MAX_CONCURRENT_RECONCILES_CAP_TENANT: Maximum number of concurrent reconciles for CAPTenant (for example, 10).
• MAX_CONCURRENT_RECONCILES_CAP_TENANT_OPERATION: Maximum number of concurrent reconciles for CAPTenantOperation (for example, 10).
• MAX_CONCURRENT_RECONCILES_DOMAIN: Maximum number of concurrent reconciles for Domain (for example, 1).
• MAX_CONCURRENT_RECONCILES_CLUSTER_DOMAIN: Maximum number of concurrent reconciles for ClusterDomain (for example, 1).
• MAX_CONCURRENT_RECONCILES_SUBSCRIPTION: Maximum number of concurrent reconciles for Subscription (for example, 10).
• CLIENT_QPS: Maximum queries per second for the Kubernetes client-side rate limiter (for example, 25). Defaults to 25.
• CLIENT_BURST: Maximum burst size for the Kubernetes client-side rate limiter (for example, 50). Defaults to 50.
• ROLLOUT_DELAY: Delay window used to batch credential-rotation work triggered by BTP service secret changes. Accepts Go duration strings (for example, 30m, 2h). Defaults to 1h. Values below 30s are clamped to 30s.

5 - Usage

5.1 - Prerequisites

Prepare the SAP BTP global account and provider subaccount

CAP-based applications use various SAP BTP services created in a provider subaccount. Before deploying the application, create a global account and entitle the required services, then create a provider subaccount where the service instances can be created. See the SAP BTP account administration documentation for details.

Create service instances and bindings

A multi-tenant CAP-based application consumes the following SAP BTP services. Some parameters require special attention during service instance creation. Service keys (bindings) generate access credentials that must be provided as Kubernetes Secrets in the namespace where the application is deployed.

Other services (not listed here) may also be required depending on your application (for example, SAP HTML5 Application Repository service for SAP BTP, Business Logging, and others).

Note: If some SAP BTP services are not available on Kubernetes, enable Cloud Foundry for the provider subaccount. In such cases, use the cf-service-operator to manage service instances and bindings directly from within the Kubernetes cluster. It automatically generates Secrets containing service access credentials based on the service bindings.

SAP Authorization and Trust Management Service

The parameter oauth2-configuration.redirect-uris must include the domain used by the application. For example, if the application is hosted in a “Gardener” managed cluster, the entry may have the form https://*<application-specific-prefix>.<cluster-id>.<gardener-project-id>.shoot.url.k8s.example.com/**.

Scopes required for asynchronous tenant subscription operations must also be included. Additionally, check the CAP Multitenancy documentation for additional required scopes.

parameters:
  authorities:
    - $XSAPPNAME.mtcallback
    - $XSAPPNAME.mtdeployment
  oauth2-configuration:
    redirect-uris:
      - https://*my-cap-app.cluster-x.my-project.shoot.url.k8s.example.com/**
  role-collections:
    ...
  role-templates:
    ...
  scopes:
    - description: UAA
      name: uaa.user
    - description: With this scope set, the callbacks for tenant onboarding, offboarding, and getDependencies can be called
      grant-as-authority-to-apps:
        - $XSAPPNAME(application,sap-provisioning,tenant-onboarding)
      name: $XSAPPNAME.Callback
    - description: Async callback to update the saas-registry (provisioning succeeded/failed)
      name: $XSAPPNAME.subscription.write
    - description: Deploy applications
      name: $XSAPPNAME.mtdeployment
    - description: Subscribe to applications
      grant-as-authority-to-apps:
        - $XSAPPNAME(application,sap-provisioning,tenant-onboarding)
      name: $XSAPPNAME.mtcallback
    ...

When using multiple SAP Authorization and Trust Management Service instances in the application (for example, one for application and another for apiaccess), set the primary instance using the annotation sme.sap.com/primary-xsuaa with the name of the service instance:

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplication
metadata:
  annotations:
    "sme.sap.com/primary-xsuaa": "my-cap-app-uaa" # Tells CAP Operator which UAA instance to use for the application
  name: test-cap-01
  ...
spec:
  btp:
    services:
      - class: xsuaa
        name: my-cap-app-uaa-api
        secret: my-cap-app-uaa-api-bind-cf
      - class: xsuaa
        name: my-cap-app-uaa
        secret: my-cap-app-uaa-bind-cf
      - class: saas-registry
        name: my-cap-app-saas-registry
        secret: my-cap-app-saas-bind-cf
      ...
  btpAppName: my-cap-app
  ...

SAP Software-as-a-Service Provisioning service

When creating an instance of the SaaS Provisioning service, configure asynchronous tenant subscription callbacks. See Register Your Multi-Tenant Application/Service in SaaS Provisioning for details.

parameters:
  appName: <short-application-name>
  appUrls:
    callbackTimeoutMillis: 300000 # <-- fails the subscription process when no response is received within this timeout
    getDependencies: https://<cap-operator-subscription-server-domain>/dependencies/<providerSubaccountId>/<btpAppName>/ # the /getDependencies route is forwarded directly to CAP Operator (Subscription Server) and must be specified as such
    onSubscription: https://<cap-operator-subscription-server-domain>/provision/tenants/{tenantId} # <-- the /provision route is forwarded directly to CAP Operator (Subscription Server) and must be specified as such
    onSubscriptionAsync: true
    onUnSubscriptionAsync: true

SAP HANA Cloud

An SAP HANA Cloud instance (preferably shared and accessible from the provider subaccount) is required. Note the instance ID of the database for use in relevant workloads. The SAP HANA Schemas & HDI Containers service must also be entitled for the provider subaccount.

SAP Service Manager service

The SAP Service Manager service allows CAP to retrieve schema-specific (tenant-specific) credentials for connecting to the SAP HANA Cloud database.

5.2 - Deploying a CAP Application

Deploying a multi-tenant CAP application involves defining several key resources provided by CAP Operator. These resources manage the application’s runtime components and external traffic routing.

Key Resources

1. CAPApplication (capapplications.sme.sap.com): A namespaced resource that represents the application.

2. CAPApplicationVersion (capapplicationversions.sme.sap.com): A namespaced resource that specifies the version of the application being deployed. It ensures that all runtime components (Deployments, Services, and Jobs) are created with the specified image version in the same namespace.

3. Domain resources: These resources determine how external traffic reaches the application and how DNS and TLS settings are applied. You can choose between:

   • Domain (domains.sme.sap.com): A namespaced resource for a single application.
   • ClusterDomain (clusterdomains.sme.sap.com): A cluster-scoped resource that can be shared across multiple applications.

Deployment Process

Create the CAPApplication and CAPApplicationVersion resources in the same namespace. This allows CAP Operator to manage all associated runtime components. For external traffic management, define either a Domain or ClusterDomain resource.

apiVersion: sme.sap.com/v1alpha2
kind: Domain
metadata:
  namespace: cap-app-01
  name: cap-app-01-primary
spec:
  domain: my.cluster.shoot.url.k8s.example.com
  ingressSelector:
    app: istio-ingressgateway
    istio: ingressgateway
  tlsMode: Simple
  dnsMode: Wildcard

The ClusterDomain resource is cluster-scoped and suited for global or shared domain configurations — for example, when multiple applications share the same external domain. See API Reference.

apiVersion: sme.sap.com/v1alpha2
kind: ClusterDomain
metadata:
  name: common-external-domain
spec:
  domain: my.example.com
  ingressSelector:
    app: istio-ingressgateway
    istio: ingressgateway
  tlsMode: Simple
  dnsMode: Subdomain

The CAPApplication resource describes the high-level attributes of an application: the SAP BTP account where it is hosted, the consumed SAP BTP services, and references to Domain and ClusterDomain resources. See API Reference.

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplication
metadata:
  name: cap-app-01
  namespace: cap-app-01
spec:
  btpAppName: cap-app-01 # <-- short name (equivalent to SAP BTP XSAPPNAME)
  btp:
    services:
      - class: xsuaa # <-- SAP BTP service technical name
        name: app-uaa # <-- name of the service instance
        secret: cap-app-01-uaa-bind-cf # <-- secret containing credentials for accessing the service (must exist in the same namespace)
      - class: saas-registry
        name: app-saas-registry
        secret: cap-app-01-saas-bind-cf
      - class: service-manager
        name: app-service-manager
        secret: cap-app-01-svc-man-bind-cf
      - class: destination
        name: app-destination
        secret: cap-app-01-dest-bind-cf
      - class: html5-apps-repo
        name: app-html5-repo-host
        secret: cap-app-01-html5-repo-bind-cf
      - class: html5-apps-repo
        name: app-html5-repo-runtime
        secret: cap-app-01-html5-rt-bind-cf
      - class: some-content-service
        name: app-some-content-service
        secret: cap-app-01-some-content-service-bind-cf
  domainRefs:
  - kind: Domain
    name: cap-app-01-primary # <-- reference to Domain resource in the same namespace
  - kind: ClusterDomain
    name: common-external-domain # <-- reference to ClusterDomain resource in the cluster
  providerSubaccountId: provider-subaccount-id

The CAPApplicationVersion describes the components of an application version, including the container images to use and the services consumed by each component. It must be created in the same namespace as the CAPApplication and must reference it. See API Reference.

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplicationVersion
metadata:
  name: cav-cap-app-01-1
  namespace: cap-app-01
spec:
  capApplicationInstance: cap-app-01 # <-- reference to CAPApplication in the same namespace
  version: "1" # <-- semantic version
  registrySecrets:
    - regcred
  workloads:
    - name: cap-backend
      consumedBTPServices: # <-- services used by the application server (defined in CAPApplication). Credential secrets are mounted as volumes on component pods.
        - app-uaa
        - app-service-manager
        - app-saas-registry
      deploymentDefinition:
        type: CAP # <-- indicates the CAP application server
        image: app.some.repo.example.com/srv/server:0.0.1
        env:
          - name: CDS_ENV
            value: production
          - name: CDS_CONFIG
            value: '{ "requires":{"cds.xt.DeploymentService":{"hdi": { "create":{ "database_id": "16e25c51-5455-4b17-a4d7-43545345345" } } } } }'
    - name: app-router
      consumedBTPServices:
        - app-uaa
        - app-destination
        - app-saas-registry
        - app-html5-repo-runtime
        - app-some-content-service
      deploymentDefinition:
        type: Router
        image: app.some.repo.example.com/approuter/approuter:0.0.1
        env:
          - name: PORT
            value: "4000"
          - name: TENANT_HOST_PATTERN
            value: "^(.*).(my.cluster.shoot.url.k8s.example.com|my.example.com)"
    - name: service-content
      consumedBTPServices:
        - app-uaa
        - app-html5-repo-host
        - app-some-content-service
      jobDefinition:
        type: Content
        image: app.some.repo.example.com/approuter/content:0.0.1
        backoffLimit: 1
    - name: tenant-op
      consumedBTPServices:
        - app-uaa
      jobDefinition:
        type: TenentOperation
        image: app.some.repo.example.com/srv/mtxs:0.0.1
        backoffLimit: 1

NOTE: The example above shows a minimal CAPApplicationVersion. For a complete configuration with explanations, see here.

The CAP Operator controller reacts to these objects and creates additional resources that constitute a running application:

• Deployment (and Service) for the application server, with SAP BTP service credentials injected as the VCAP_SERVICES environment variable
• Deployment (and Service) for the Approuter, with destination mappings to the application server
• Job for the version content deployer and tenant operation
• TLS certificates for the specified domains using either “Gardener” cert-management or cert-manager.io cert-manager
• Istio Gateway resource for the application domains

The content deployer deploys content or configuration to SAP BTP services before they are consumed.

Once these resources are available, the CAPApplicationVersion status changes to Ready. The controller reconciles tenants once subscriptions are triggered for the application. See tenant subscription for details on how the CAPTenant resource is reconciled.

The CAPApplicationVersion resource is immutable — its spec must not be modified after deployment. This is enforced by webhooks, which we recommend keeping active (the default).

NOTE: Follow the recommended security measures to safeguard exposed workloads.

NOTE: If SAP BTP service credentials are rotated after deployment, CAP Operator can automatically restart affected workloads. See Rollout on Credential Update to learn how to enable this.

5.3 - Domain Management

CAP Operator manages networking for CAP applications through Domain and ClusterDomain resources. These resources control TLS handling, ingress routing, and DNS setup for your application’s domains. A CAPApplication references them via domainRefs.

Domain Resources

Use a Domain resource for a domain that belongs to a specific application namespace. The operator creates the Gateway and DNSEntry in that namespace. The Certificate placement depends on the certificate manager in use — see the Domain resource reference for details.

apiVersion: sme.sap.com/v1alpha2
kind: Domain
metadata:
  namespace: cap-app-01
  name: cap-app-01-primary
spec:
  domain: my.cluster.shoot.url.k8s.example.com
  ingressSelector:
    app: istio-ingressgateway
    istio: ingressgateway
  tlsMode: Simple    # Simple (default), Mutual, or OptionalMutual
  dnsMode: Wildcard  # None (default), Wildcard, Subdomain, or Custom

The dnsTarget field is optional. If omitted, the target is derived from the Istio Ingress Gateway selected by ingressSelector.

ClusterDomain Resources

Use a ClusterDomain resource for a domain shared across multiple applications or namespaces. The operator creates the Gateway and DNSEntry in the CAP Operator installation namespace. The Certificate placement depends on the certificate manager in use — see the ClusterDomain resource reference for details.

apiVersion: sme.sap.com/v1alpha2
kind: ClusterDomain
metadata:
  name: common-external-domain
spec:
  domain: my.example.com
  ingressSelector:
    app: istio-ingressgateway
    istio: ingressgateway
  tlsMode: Simple      # Simple (default) or Mutual
  dnsMode: Subdomain   # None (default), Wildcard, Subdomain, or Custom

When X509 client authentication is required (tlsMode: Mutual or OptionalMutual), provide additional CA certificates for Istio to verify client certificates via certConfig.additionalCACertificate.

Referencing Domains in CAPApplication

Once your Domain and ClusterDomain resources are defined, reference them in the CAPApplication spec using domainRefs:

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplication
metadata:
  name: cap-app-01
  namespace: cap-app-01
spec:
  domainRefs:
  - kind: Domain
    name: cap-app-01-primary     # Namespaced Domain resource
  - kind: ClusterDomain
    name: common-external-domain # Shared ClusterDomain resource

The first entry in domainRefs is treated as the primary domain. You can mix Domain and ClusterDomain references in the same application.

Migration

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplication
metadata:
  name: cap-app-01
  namespace: cap-app-01
spec:
  domains:
    istioIngressGatewayLabels:
    - name: app
      value: istio-ingressgateway
    - name: istio
      value: ingressgateway
    primary: my.cluster.shoot.url.k8s.example.com
    secondary:
      - my.example.com

kubectl get capapplication -n <your-app-namespace> <your-ca-name> -o yaml

5.3.1 - Custom DNS Templates

When dnsMode is set to Custom, the operator creates DNS entries according to the dnsTemplates field instead of the fixed patterns used by Wildcard and Subdomain modes. This lets you generate multiple DNS records per domain, map subdomains to external names, or combine wildcard and per-subdomain entries in one resource.

Templates

Each entry in dnsTemplates produces one or more DNS records. Up to 10 templates are allowed per resource. The name and target fields are rendered using Go templates. A template has two fields:

Available variables

The following variables are available in both name and target:

Functions from the Slim Sprig library are available in all templates.

Subdomain expansion

When {{.subDomain}} appears in a template’s name, the operator expands that template once for each subdomain observed across all CAPApplication resources that reference the domain. A template whose name does not contain {{.subDomain}} is rendered exactly once.

Subdomains are collected from two sources and tracked in CAPApplication.status.observedSubdomains:

• CAPTenant.spec.subDomain — each tenant’s subdomain
• CAPApplicationVersion.spec.serviceExposures[].subDomain — subdomains declared in version service exposures

{{.subDomain}} may also be used in target, but only when name also contains {{.subDomain}}.

Example

The following configuration combines a wildcard record with per-subdomain records on the primary domain, and a CNAME chain that maps each subdomain on an external domain to the corresponding subdomain on the primary domain:

apiVersion: sme.sap.com/v1alpha2
kind: Domain                 # also applies to ClusterDomain
metadata:
  namespace: cap-app-01
  name: cap-app-01-primary
spec:
  domain: my.cluster.shoot.url.k8s.example.com
  ingressSelector:
    app: istio-ingressgateway
    istio: ingressgateway
  dnsMode: Custom
  dnsTemplates:
  - name: '*.{{ .domain }}'
    target: '{{ .dnsTarget }}'
  - name: '{{ .subDomain }}.{{ .domain }}'
    target: '{{ .dnsTarget }}'
  - name: '{{ .subDomain }}.myapp.com'
    target: '{{ .subDomain }}.{{ .domain }}'

For an application with subdomains tenant-a and tenant-b, this produces five DNS records:

5.3.2 - Configuring Additional CA Certificates

When tlsMode is set to Mutual or OptionalMutual on a Domain or ClusterDomain, Istio requires a CA certificate to verify client certificates presented during the TLS handshake. Provide this certificate via certConfig.additionalCACertificate.

The operator stores the certificate as a Kubernetes Secret (key: ca.crt) in the Istio Ingress Gateway namespace, where Istio reads it.

apiVersion: sme.sap.com/v1alpha2
kind: ClusterDomain          # also applies to Domain
metadata:
  name: cap-example-domain
spec:
  domain: myapp.example.com
  ingressSelector:
    app: istio-ingressgateway
    istio: ingressgateway
  tlsMode: Mutual
  certConfig:
    additionalCACertificate: |
      -----BEGIN CERTIFICATE-----
      MIIFZjCCA06gAwIBAgIQGHcPvmUGa79M6pM42bGFYjANBgkqhkiG9w0BAQsFADBN
      ...
      -----END CERTIFICATE-----

Removing certConfig.additionalCACertificate from the spec causes the operator to delete the corresponding secret.

5.3.3 - Configuring cert-manager Certificates

When the operator is installed with the cert-manager certificate manager (configured via the CERT_MANAGER environment variable), it creates a cert-manager Certificate resource for each Domain or ClusterDomain. Every Certificate must reference an issuer. By default the operator uses a ClusterIssuer named cluster-ca. Use certConfig.certManager.issuerRef to override this with any issuer available in your cluster.

Default behavior

If certConfig.certManager is not set, the operator uses the following issuer reference:

Configuring a custom issuer

Set certConfig.certManager.issuerRef on a Domain or ClusterDomain to point to any cert-manager issuer:

apiVersion: sme.sap.com/v1alpha2
kind: Domain                 # also applies to ClusterDomain
metadata:
  namespace: cap-app-01
  name: cap-app-01-primary
spec:
  domain: my.cluster.shoot.url.k8s.example.com
  ingressSelector:
    app: istio-ingressgateway
    istio: ingressgateway
  certConfig:
    certManager:
      issuerRef:
        name: my-cluster-issuer   # name of the issuer
        kind: ClusterIssuer       # ClusterIssuer or Issuer
        group: cert-manager.io    # optional; defaults to cert-manager.io

issuerRef fields

5.4 - Tenant Subscription

In CAP Operator, a valid tenant for an application is represented by the CAPTenant resource. It references the CAPApplication it belongs to and specifies the details of the SAP BTP subaccount that represents the tenant.

apiVersion: sme.sap.com/v1alpha2
kind: CAPTenant
metadata:
  name: cap-app-01-consumer
  namespace: cap-app-01
spec:
  capApplicationInstance: cap-app-01 # <-- reference to the CAPApplication
  subDomain: app-consumer
  tenantId: aa2bae55d7b5-1279-456564-a7b0-aa2bae55d7b5
  version: "1.0.0" # <-- expected version of the application
  versionUpgradeStrategy: always # <-- always / never

Tenant Provisioning

Tenant provisioning begins when a consumer subaccount subscribes to the application, either via the SAP BTP cockpit or using the SaaS Provisioning service APIs. This triggers an asynchronous callback from the SaaS Provisioning service into the cluster, which is handled by the subscription server. The subscription server validates the request using credentials from the SubscriptionProvider resource and creates a Subscription resource in the namespace of the identified CAPApplication. The controller, observing the new Subscription, then creates a CAPTenant instance to represent the consumer tenant.

The controller, observing the new CAPTenant (created as a child of the Subscription), initiates the provisioning process by creating a CAPTenantOperation resource representing the provisioning operation.

apiVersion: sme.sap.com/v1alpha2
kind: CAPTenantOperation
metadata:
  name: cap-app-01-consumer-sgz8b
  namespace: cap-app-01
spec:
  capApplicationVersionInstance: cav-cap-app-01-1 # <-- latest CAPApplicationVersion in Ready state
  subDomain: app-consumer
  tenantId: aa2bae55d7b5-1279-456564-a7b0-aa2bae55d7b5
  operation: provisioning # <-- valid values are provisioning, deprovisioning and upgrade
  steps:
    - name: tenant-operation # <-- derived from the workload of type TenantOperation defined in the CAPApplicationVersion
      type: TenantOperation

The CAPTenantOperation is reconciled to create Kubernetes Jobs (steps) derived from the latest CAPApplicationVersion in Ready state. The steps include a TenantOperation job and optional CustomTenantOperation steps. The TenantOperation step uses built-in CLI-based tenant operations from @sap/cds-mtxs to execute tenant provisioning.

The CAPTenant reaches a Ready state only after:

• All CAPTenantOperation steps complete successfully, and
• An Istio VirtualService is created to route HTTP requests on the tenant subdomain to the application.

Get Dependencies

During provisioning, the SaaS Provisioning service calls a getDependencies endpoint to retrieve the list of reuse services that the multitenant application requires. The CAP Operator subscription server exposes this endpoint. The dependency list is pre-computed by the controller at CAPApplication reconciliation time and cached in the SubscriptionProvider resource. The subscription server reads and returns the cached list directly, without re-inspecting CAPApplication service credentials at request time.

The subscription server exposes the following endpoint:

GET /dependencies/{providerSubaccountId}/{appName}/

The providerSubaccountId and appName path parameters identify the corresponding CAPApplication resource. The system authorizes the request using the same mechanism as the provisioning endpoints (Bearer token).

A successful response returns a JSON array of objects. Each object contains the xsappname of a qualifying service:

[
  { "xsappname": "my-destination-service!b42" },
  { "xsappname": "my-auditlog-service!b7" }
]

Service Qualification

The controller iterates over all BTP services listed in CAPApplication.spec.btp.services. For each service, it reads the associated Kubernetes secret, parses the credentials, and determines whether to include the service in the pre-computed dependency list.

The xsappname is read from either the top-level xsappname field or the nested uaa.xsappname field in the service credentials. If not found, the service is excluded from the response.

Configuring Dependencies with subscriptionDependency

Each entry in spec.btp.services can include an optional subscriptionDependency field that controls whether the service is included:

spec:
  btp:
    services:
      - name: my-destination
        class: destination
        secret: my-destination-secret
        subscriptionDependency: Always   # force inclusion
      - name: my-xsuaa
        class: xsuaa
        secret: my-xsuaa-secret
        subscriptionDependency: Never    # force exclusion
      - name: my-auditlog
        class: auditlog
        secret: my-auditlog-secret
        # subscriptionDependency omitted → Auto

Auto qualification rules

When subscriptionDependency is set to Auto or omitted, the system includes the service if any of the following conditions apply:

• The service credentials contain "saasregistryenabled": true
• Service class is destination
• Service class is connectivity
• Service class is auditlog and the credential plan is oauth2

This behavior aligns with the implementation in the @sap/approuter package.

Tenant Deprovisioning

When a tenant unsubscribes from the application, the subscription server receives the request, locates the corresponding Subscription resource, and submits a deletion request to the Kubernetes API server.

The controller processes the deletion by initiating deprovisioning of the owned CAPTenant via a CAPTenantOperation of type deprovisioning. The CAPTenantOperation creates the corresponding Jobs (steps) that execute the tenant deprovisioning. Once deprovisioning completes successfully, the Subscription finalizer is removed, allowing Kubernetes to complete the deletion.

CAPApplication Deletion

As of version 0.34.0, deleting a CAPApplication does not automatically remove existing tenants. Instead, the CAPApplication enters a Deleting state and its deletion is blocked until all associated CAPTenant resources have been removed.

Before a CAPApplication can be fully deleted:

• The provider tenant CAPTenant resource will be automatically deleted.
• All consumer tenants must be removed by unsubscribing from the application (for e.g. via the SAP BTP cockpit or SaaS Provisioning service APIs), which triggers the normal deprovisioning flow for each tenant.

Once all tenants are cleaned up, the operator proceeds to delete the remaining child resources (CAPApplicationVersion instances and other CRs) and completes the CAPApplication deletion.

5.5 - Application Upgrade

An important lifecycle aspect of operating multi-tenant CAP applications is the tenant upgrade process. With CAP Operator, tenant upgrades can be fully automated by providing a new CAPApplicationVersion custom resource.

As covered in initial deployment, the CAPApplicationVersion resource describes the workloads of an application version, including the container image and services consumed by each component. To upgrade the application, create a new CAPApplicationVersion with updated image values for each component and a higher semantic version in the version field. See API Reference.

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplicationVersion
metadata:
  name: cav-cap-app-01-2
  namespace: cap-app-01
spec:
  capApplicationInstance: cap-cap-app-01 # <-- reference to CAPApplication in the same namespace
  version: "2.0.1" # <-- semantic version
  registrySecrets:
    - regcred
  workloads:
    - name: cap-backend
      consumedBTPServices:
        - app-uaa
        - app-service-manager
        - app-saas-registry
      deploymentDefinition:
        type: CAP # <-- indicates the CAP application server
        image: app.some.repo.example.com/srv/server:0.0.2
        env:
          - name: CDS_ENV
            value: production
          - name: CDS_CONFIG
            value: '{ "requires":{"cds.xt.DeploymentService":{"hdi": { "create":{ "database_id": "16e25c51-5455-4b17-a4d7-43545345345" } } } } }'
    - name: app-router
      consumedBTPServices:
        - app-uaa
        - app-destination
        - app-saas-registry
        - app-html5-repo-runtime
        - app-some-content-service
      deploymentDefinition:
        type: Router
        image: app.some.repo.example.com/approuter/approuter:0.0.2
        env:
          - name: PORT
            value: 4000
          - name: TENANT_HOST_PATTERN
            value: "^(.*).(my.cluster.shoot.url.k8s.example.com|my.example.com)"
    - name: service-content
      consumedBTPServices:
        - app-uaa
        - app-html5-repo-host
        - app-some-content-service
      jobDefinition:
        type: Content
        image: app.some.repo.example.com/approuter/content:0.0.2
        backoffLimit: 1
    - name: tenant-operation
      consumedBTPServices:
        - app-uaa
        - app-service-manager
        - app-saas-registry
      jobDefinition:
        type: TenantOperation
        image: app.some.repo.example.com/approuter/content:0.0.2
        env:
          - name: CDS_ENV
            value: production
          - name: CDS_CONFIG
            value: '{ "requires":{"cds.xt.DeploymentService":{"hdi": { "create":{ "database_id": "16e25c51-5455-4b17-a4d7-43545345345" } } } } }'
    - name: notify-upgrade
      consumedBTPServices: []
      jobDefinition:
        type: CustomTenantOperation
        image: app.some.repo.example.com/approuter/content:0.0.2
        command: ["npm", "run", "notify:upgrade"]
        backoffLimit: 1
        env:
          - name: TARGET_DL
            value: group_xyz@sap.com
  tenantOperations:
    upgrade:
      - workloadName: tenant-operation
      - workloadName: notify-upgrade
        continueOnFailure: true

Note that compared to version “1” used for initial deployment, new workloads of type TenantOperation and CustomTenantOperation have been added.

The CAP Operator controller reacts to the new CAPApplicationVersion resource by triggering a new Deployment for the application server and router, and running the content deployment Job. Once the new CAPApplicationVersion is Ready, the controller automatically upgrades all relevant tenants by updating the version attribute on the CAPTenant resources.

CAPTenant reconciliation changes the tenant state to Upgrading and creates a CAPTenantOperation resource of type upgrade.

apiVersion: sme.sap.com/v1alpha2
kind: CAPTenantOperation
metadata:
  name: cap-app-01-provider-fgdfg
  namespace: cap-app-01
spec:
  capApplicationVersionInstance: cav-cap-app-01-2
  subDomain: cap-provider
  tenantId: aa2bae55d7b5-1279-456564-a7b0-aa2bae55d7b5
  operation: upgrade # possible values are provisioning / upgrade / deprovisioning
  steps:
    - name: "tenant-operation"
      type: TenantOperation
    - name: "notify-upgrade"
      type: CustomTenantOperation
      continueOnFailure: true # <-- indicates that the overall operation may proceed even if this step fails

The CAPTenantOperation creates Jobs for each step and executes them sequentially until all Jobs complete or one fails. The CAPTenant is notified of the result and updates its state accordingly.

When the CAPTenantOperation completes successfully, the VirtualService managed by the CAPTenant is updated to route HTTP traffic to the Deployments of the newer CAPApplicationVersion. Once all tenants are upgraded, the outdated CAPApplicationVersion can be deleted.

Version Affinity during Upgrade (Experimental)

You can optionally enable Version Affinity for multi-tenant applications by adding the annotation sme.sap.com/enable-version-affinity: "true" to the CAPApplication resource. With this experimental feature, users remain on their currently active CAPApplicationVersion during an upgrade until their session expires or they log out.

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplication
metadata:
  name: test-ca-01
  namespace: default
  annotations:
    sme.sap.com/enable-version-affinity: "true" # <-- enable version affinity
spec:
  btp:
    services:
      - class: xsuaa
        name: cap-uaa
        secret: cap-cap-01-uaa-bind-cf
    ....
  ....

By default, CAP Operator recognizes logout and logoff as logout endpoints. If your application uses a different endpoint, specify it using the sme.sap.com/logout-endpoint annotation on your CAPApplicationVersion resource (without a leading slash).

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplicationVersion
metadata:
  name: cav-cap-app-01-2
  namespace: cap-app-01
  annotations:
    sme.sap.com/logout-endpoint: "custom-logout" # <-- specify custom logout endpoint
spec:
  capApplicationInstance: cap-cap-app-01
  version: "2.0.1"
  registrySecrets:
    - regcred

5.6 - Service Exposure

Exposing Service Workloads

This guide explains how to deploy applications with tenant-agnostic service workloads. These workloads can be part of multi-tenant applications or standalone applications that are entirely tenant-agnostic.

Configuration

Service Exposure Setup

The serviceExposures section in the CAPApplicationVersion configuration is used to expose workloads. Each entry in the serviceExposures array specifies a subdomain under which workloads are accessible, with support for multiple routes per subdomain.

For details on configuring routes, see the Route API reference.

Example Configuration

spec:
  workloads:
    - name: cap-backend-service
      consumedBTPServices:
        - cap-uaa
        - cap-saas-reg
      deploymentDefinition:
        type: CAP # <-- possible values are CAP / Router / Additional / Service
        image: some.repo.example.com/cap-app/server:3.22.11
        env:
          - name: HOME
            value: "SAP"
        replicas: 3
        ports:
          - name: app-port
            port: 4004
          - name: tech-port
            port: 4005
          - name: api
            port: 8000
          - name: api-v2
            port: 8001
            appProtocol: http
    - name: router
      consumedBTPServices:
        - cap-uaa
        - cap-apps-repo
      deploymentDefinition:
        type: Router
        image: some.repo.example.com/cap-app/app-router:1.0.1
        ports:
          - name: router-port
            port: 5000
    - name: app
      consumedBTPServices:
        - cap-uaa
        - cap-db
      deploymentDefinition:
        type: Service
        image: some.repo.example.com/cap-app/app:4.0.1
        ports:
          - name: app-port
            port: 5000
    - name: service-content
      consumedBTPServices:
        - app-uaa
        - app-html5-repo-host
        - app-some-content-service
      jobDefinition:
        type: Content
        image: some.repo.example.com/cap-app/content:0.0.1
        backoffLimit: 1
  serviceExposures:
    - subDomain: service
      routes:
        - workloadName: cap-backend-service
          port: 4004
    - subDomain: api
      routes:
        - workloadName: cap-backend-service
          port: 8001
          path: /api/v2
        - workloadName: cap-backend-service
          port: 8000
          path: /api
    - subDomain: app
      routes:
        - workloadName: app
          port: 5000

Result:

For a cluster domain like my.cluster.shoot.url.k8s.example.com, the configuration generates URLs like:

• service.my.cluster.shoot.url.k8s.example.com for cap-backend-service on port 4004.
• api.my.cluster.shoot.url.k8s.example.com/api/v2 for cap-backend-service on port 8001.
• api.my.cluster.shoot.url.k8s.example.com/api for cap-backend-service on port 8000
• app.my.cluster.shoot.url.k8s.example.com for app on port 5000.

In the example above, the router workload is not exposed through serviceExposures. However, in multi-tenant scenarios, it may be exposed per tenant subdomain as usual.

Route Ordering

Ensure routes are ordered correctly to prevent routing errors. When multiple routes are defined for a subdomain, more specific paths must come before more general ones. For example, in the configuration above, the api subdomain requires /api/v2 to be defined before /api.

Deploying Services-Only Applications

Services-only applications do not require tenant-specific configurations. Therefore, the provider section is omitted from the CAPApplication resource. The CAPApplicationVersion may include only Content jobs and no tenant-related jobs. The rest of the configuration for your services-only application remains the same.

Application Configuration

Create a CAPApplication resource without a provider section:

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplication
metadata:
  name: test-ca-01
  namespace: default
spec:
  btp:
    services:
      - class: xsuaa
        name: cap-uaa
        secret: cap-cap-01-uaa-bind-cf
      - class: xsuaa
        name: cap-uaa2
        secret: cap-cap-01-uaa2-bind-cf
      - class: service-manager
        name: cap-service-manager
        secret: cap-cap-01-svc-man-bind-cf
  btpAppName: test-cap-01
  domainRefs:
  - kind: Domain
    name: cap-app-01-primary
  - kind: ClusterDomain
    name: common-external-domain
  providerSubaccountId: provider-subaccount-id

Version Configuration

Create a CAPApplicationVersion in the same namespace as the CAPApplication with service workloads and any content jobs.

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplicationVersion
metadata:
  name: cav-ca-app-01-1
  namespace: default # Same namespace as CAPApplication
spec:
  capApplicationInstance: test-ca-01 # Reference to the CAPApplication
  version: "0.0.1"
  registrySecrets:
    - regcred
  workloads:
    - name: cap-backend-service
      consumedBTPServices: # Services used by this workload
        - app-uaa
        - app-db
        - app-saas-registry
      deploymentDefinition:
        type: CAP
        image: app.some.repo.example.com/srv/server:0.0.1
        env:
          - name: CDS_ENV
            value: production
        ports:
          - name: server
            port: 4004
            appProtocol: http
          - name: api
            port: 8000
            appProtocol: http
          - name: metrics
            port: 4005
            appProtocol: http
    - name: api
      consumedBTPServices: # Services used by this workload
        - app-uaa
        - app-db
      deploymentDefinition:
        type: Service
        image: app.some.repo.example.com/srv/api:0.0.1
        env:
          - name: CDS_ENV
            value: production
        ports:
          - name: apiv2
            port: 8000
            appProtocol: http
          - name: api
            port: 8001
            appProtocol: http
    - name: service-content # Example content job
      consumedBTPServices:
        - app-uaa
        - app-html5-repo-host
        - app-some-content-service
      jobDefinition:
        type: Content
        image: app.some.repo.example.com/approuter/content:0.0.1
        backoffLimit: 1
  serviceExposures:
    - subDomain: service
      routes:
        - workloadName: cap-backend-service
          port: 4004
    - subDomain: api
      routes:
        - workloadName: api
          port: 8000
          path: /api/v2
        - workloadName: api
          port: 8001
          path: /api

Important Considerations

• No tenant-related resources are created for services-only applications.
• A successful upgrade of the CAPApplicationVersion causes any service-related VirtualService resources to route HTTP traffic to the workloads of that CAPApplicationVersion.
• Choose the appropriate application mode from the start: services-only or multi-tenant. Switching modes later is not possible.
• Follow the recommended security measures to safeguard any exposed workloads.

5.7 - Rollout on Credential Update

When SAP BTP service credentials are rotated — for example, by a credential rotation tool or by re-binding a service instance — the Kubernetes Secrets holding those credentials are updated. By default, running application workloads are not restarted and continue to use the old credentials until the next deployment or a manual rollout.

Enabling rolloutOnCredentialUpdate on a CAPApplication resource instructs CAP Operator to watch the referenced BTP service credential Secrets and automatically trigger a rolling restart of affected Deployments whenever their credentials change.

Benefits

Enabling the Feature

Set rolloutOnCredentialUpdate: true in the CAPApplication spec:

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplication
metadata:
  name: cap-app-01
  namespace: cap-app-01
spec:
  rolloutOnCredentialUpdate: true # opt-in to automatic rollout on credential rotation
  btpAppName: cap-app-01
  btp:
    services:
      - class: xsuaa
        name: app-uaa
        secret: cap-app-01-uaa-bind-cf
      - class: saas-registry
        name: app-saas-registry
        secret: cap-app-01-saas-bind-cf
      - class: service-manager
        name: app-service-manager
        secret: cap-app-01-svc-man-bind-cf
  domainRefs:
    - kind: ClusterDomain
      name: common-external-domain
  providerSubaccountId: provider-subaccount-id

The field is optional and defaults to false. See the API Reference for the full spec.

How It Works

Once enabled, the operator follows this flow whenever a watched Secret changes:

1. Secret watch — CAP Operator watches all Kubernetes Secrets in the namespace of any CAPApplication that has rolloutOnCredentialUpdate: true. When a Secret is updated, the namespace is scheduled for processing after a configurable batching window (see Operator Configuration).

2. Batching — any additional Secret changes arriving in the same namespace within the batching window are accumulated. When the window expires, all collected changes are processed together in a single pass, preventing redundant rollouts when multiple services are rotated at once.

3. Affected workload detection — for each CAPApplicationVersion currently in use (the latest ready version, plus any version still serving active tenants), the operator checks which Deployments declare the rotated service in their consumedBTPServices list.

4. VCAP secret comparison — the operator rebuilds the VCAP_SERVICES data for each affected Deployment using the new credential data. If the payload is identical to the existing one, the Deployment is left untouched and no restart is triggered.

5. Rolling restart — when the data has changed, a new VCAP_SERVICES secret is created and the Deployment’s envFrom reference is updated to point to it. Kubernetes detects the change and performs a rolling restart of the pods, ensuring zero downtime.

Note: Only Deployments are restarted. Job workloads (content deployers, tenant operation jobs) are not affected by this feature.

Note: The rollout covers all ready CAPApplicationVersion resources currently serving tenants, not only the latest version. This ensures credentials are refreshed consistently across all active versions during an upgrade transition.

Operator Configuration

The batching window duration is configurable via an environment variable on the CAP Operator deployment.

If the configured value cannot be parsed, the operator logs an error and falls back to the default (1h). If the parsed value is below the minimum (30s), the operator logs an error and clamps it to 30s.

Recommendations

Keep Old Credentials Valid Long After Rotation

When rotating credentials, do not invalidate the old Secret immediately. CAP Operator needs time to:

1. detect the Secret change,
2. wait out the batching window (ROLLOUT_DELAY),
3. rebuild and compare the VCAP_SERVICES payload, and
4. wait for Kubernetes to complete the rolling restart of every affected Deployment.

Only once all pods are running with the new credentials is it safe to revoke the old ones.

As a rule of thumb, keep the old credentials valid for at least 24 hours after issuing the new ones. This provides a generous buffer that covers the batching delay, the rollout duration, and any transient failures or retries in the operator’s reconciliation loop.

Revoking credentials too soon risks pods being restarted mid-rollout with no valid credentials available, which causes application downtime.

5.8 - Version Monitoring

In a continuous delivery environment where new application versions are deployed frequently, monitoring and cleaning up older unused versions is important for conserving cluster resources (compute, memory, storage) and keeping the system manageable. CAP Operator allows application developers and operations teams to define how an application version is monitored for usage.

Integration with Prometheus

Prometheus is the industry standard for monitoring application metrics and provides a wide variety of tools for managing and reporting metrics. The CAP Operator controller can be connected to a Prometheus server by setting the PROMETHEUS_ADDRESS environment variable (see Configuration). The controller then queries application-related metrics based on the workload specification of CAPApplicationVersion resources. Prometheus is only required to evaluate workloads that declare deletionRules. When PROMETHEUS_ADDRESS is not set, or the configured server is unreachable, the cleanup loop still runs. Versions whose deployment workloads declare no deletionRules can still be cleaned up in that case. Versions that do declare deletionRules are skipped — they are neither deleted nor surfaced as errors — and will be re-evaluated on the next cycle once Prometheus becomes available again.

Configure CAPApplication

Version cleanup monitoring must be explicitly enabled for a CAP application using the annotation sme.sap.com/enable-cleanup-monitoring. The annotation accepts the following values:

Configure CAPApplicationVersion

For each deployment workload in a CAPApplicationVersion, you can define:

1. Deletion rules: Criteria based on metrics that, when satisfied, mark the workload as eligible for removal.
2. Scrape configuration: Defines how metrics are scraped from the workload service.

Deletion Rules (Variant 1) Based on Metric Type

The following example shows a workload named backend configured with deletion rules based on multiple metrics.

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplicationVersion
metadata:
  namespace: demo
  name: cav-demo-app-1
spec:
  workloads:
    - name: backend
      deploymentDefinition:
        monitoring:
          deletionRules:
            metrics:
              - calculationPeriod: 90m
                name: current_sessions
                thresholdValue: "0"
                type: Gauge
              - calculationPeriod: 2h
                name: total_http_requests
                thresholdValue: "0.00005"
                type: Counter

This tells CAP Operator that workload backend provides two metrics that can be monitored for usage.

• Metric current_sessions is of type Gauge, representing an absolute value at any point in time. CAP Operator queries Prometheus with a PromQL expression that calculates the average value over the specified calculation period. The average values from each time series are summed to get the evaluated value, which is then compared against the threshold to determine eligibility for cleanup.

  Evaluation steps for metric type Gauge
  Execute PromQL expression sum(avg_over_time(current_sessions{job="cav-demo-app-1-backend-svc",namespace="demo"}[90m])) to get the evaluated value
  Check whether evaluated value <= 0 (the specified thresholdValue)

• Metric total_http_requests is of type Counter, representing a cumulative value that can only increase. CAP Operator queries Prometheus with a PromQL expression that calculates the rate of increase over the specified period. The rates from each time series are summed to get the evaluated value, which is compared against the threshold.

  Evaluation steps for metric type Counter
  Execute PromQL expression sum(rate(total_http_requests{job="cav-demo-app-1-backend-svc",namespace="demo"}[2h])) to get the evaluated value
  Check whether evaluated value <= 0.00005 (the specified thresholdValue)

All specified metrics of a workload must satisfy the evaluation criteria for the workload to be eligible for cleanup.

Deletion Rules (Variant 2) as a PromQL Expression

You can also specify deletion criteria for a workload by providing a PromQL expression that returns a boolean scalar.

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplicationVersion
metadata:
  namespace: demo
  name: cav-demo-app-1
spec:
  workloads:
    - name: backend
      deploymentDefinition:
        monitoring:
          deletionRules:
            expression: scalar(sum(avg_over_time(current_sessions{job="cav-demo-app-1-backend-svc",namespace="demo"}[2h]))) <= bool 5

The PromQL expression is executed as a Prometheus query. The expected result is a scalar boolean (0 or 1). Use comparison binary operators with the bool modifier to produce the expected result. If the evaluation result is true (1), the workload is eligible for removal.

This variant is useful when:

• The predefined metric-type evaluation is insufficient for determining workload usage.
• Custom scraping configurations are used where the job label in the collected time series data does not match the name of the Kubernetes Service created for the workload.

Scrape Configuration

Prometheus Operator is a popular Kubernetes operator for managing Prometheus and related monitoring components. A common way to set up scrape targets is by creating the ServiceMonitor resource, which specifies which services (and ports) to scrape for application metrics.

CAP Operator can automatically create ServiceMonitor resources targeting the services created for version workloads. The following sample shows how to configure this.

kind: CAPApplicationVersion
metadata:
  namespace: demo
  name: cav-demo-app-1
spec:
  workloads:
    - name: backend
      deploymentDefinition:
        ports:
          - appProtocol: http
            name: metrics-port
            networkPolicy: Cluster
            port: 9000
        monitoring:
          deletionRules:
            expression: scalar(sum(avg_over_time(current_sessions{job="cav-demo-app-1-backend-svc",namespace="demo"}[2h]))) <= bool 5
          scrapeConfig:
            interval: 15s
            path: /metrics
            port: metrics-port

With this configuration, CAP Operator creates a ServiceMonitor targeting the workload service. The scrapeConfig.port must match the name of one of the ports specified on the workload.

Evaluating CAPApplicationVersion Resources for Cleanup

At specified intervals (controlled by the controller environment variable METRICS_EVAL_INTERVAL), CAP Operator selects versions as candidates for evaluation.

• Only versions for CAPApplication resources with the annotation sme.sap.com/enable-cleanup-monitoring are considered.
• Versions with a spec.version higher than the highest Ready version are excluded from evaluation. If no version has Ready status, no versions are evaluated.
• Versions linked to a CAPTenant are excluded. This includes versions referenced by the following CAPTenant fields:
  • status.currentCAPApplicationVersionInstance — the tenant’s current version.
  • spec.version — the version a tenant is upgrading to.

Workloads from the identified versions are then evaluated against their deletionRules. Workloads without deletionRules are automatically eligible for cleanup regardless of whether Prometheus is configured or reachable. All deployment workloads of a version must satisfy the evaluation criteria for the version to be deleted.

When a workload declares deletionRules and the Prometheus client is currently unavailable — either because no PROMETHEUS_ADDRESS has been configured, or because the Runtimeinfo probe against the configured server is failing — that workload is treated as not eligible and the version is left untouched until the next evaluation cycle. Reachability is re-checked at most once per PROM_ACQUIRE_CLIENT_RETRY_DELAY interval, so a recovered Prometheus server will be detected and used on the next cycle after that delay elapses.

5.9 - Operator Metrics

Overview

CAP Operator includes built-in Prometheus metrics that enable you to effectively monitor and analyze the operator’s performance. These metrics provide insights into resource usage, potential issues, and overall operator health. The metrics are accessible at the /metrics endpoint on port 9090 of both the Controller and the Subscription Server.

Controller Metrics

The Controller emits several types of metrics, including:

• Standard Go Metrics: These metrics are provided by the Prometheus Go client and include runtime statistics.
• Workqueue Metrics: These metrics are relevant to the resources being reconciled and are based on the MetricsProvider.
• Specific metrics: mentioned below.

Specific Metrics

1. Reconcile Errors – cap_op_reconcile_errors, e.g.:

cap_op_reconcile_errors{kind="CAPApplication",name="my-app",namespace="app"} 11

• Type: Counter
• Description: This metric tracks the total number of resources that failed to reconcile for each resource kind, such as CAPApplication.

2. Tenant Operations – cap_op_tenant_operations, e.g.

cap_op_tenant_operations{app="<hash>",operation="provisioning"} 83

• Type: Counter
• Description: This metric provides insights into overall tenant operations being performed.

Detailed Operational Metrics

To gain deeper insights, you can enable more granular metrics by setting the environment variable DETAILED_OPERATIONAL_METRICS to "true".

1. Failed Tenant Operations – cap_op_tenant_operation_failures, e.g.:

cap_op_tenant_operation_failures{app="<hash>",operation="upgrade",tenant_id="<guid>",namespace="app",name="my-app-tenant-op-xxyyz"} 2

• Type: Counter
• Description: This metric reveals the number of failed tenant operations, categorized by application, tenant ID, and specific operation details.

2. Last Tenant Operation Duration – cap_op_last_tenant_operation_duration_seconds, e.g.:

cap_op_last_tenant_operation_duration_seconds{app="<hash>",tenant_id="<guid>"} 17

• Type: Gauge
• Description: This metric measures the duration (in seconds) of the last tenant operation for a specified application and tenant.

Subscription Server Metrics

The Subscription Server emits the following metrics:

• Standard Go Metrics: These metrics are provided by the Prometheus Go client and include runtime statistics.
• Specific metrics: mentioned below.

Specific Metrics

1. Subscription Requests Total – cap_op_subscription_requests_total, e.g.:

cap_op_subscription_requests_total{code="202",method="POST"} 2024

• Type: Counter
• Description: This metric tracks the total number of subscription requests that were processed, categorized by HTTP method and response code.

2. Inflight Subscription Requests – cap_op_subscription_requests_inflight, e.g.:

cap_op_subscription_requests_inflight{} 4

• Type: Gauge
• Description: This metric indicates the number of subscription requests currently being processed by the server.

Conclusion

CAP Operator provides a rich set of metrics to facilitate monitoring and operational insights. By leveraging these metrics, you can monitor and ensure the reliability and performance of your applications. For further details, explore the Prometheus documentation and integrate these metrics into your monitoring systems.

5.10 - Security

Securing Applications

We strongly recommend that applications implement the necessary authentication and authorization mechanisms to safeguard exposed workloads. This includes implicitly exposed tenant workloads and explicitly exposed service workloads.

When using SAP Authorization and Trust Management Service in the application, this can be done as explained in this guide.

Istio

You may also consider using Istio’s security features, for instance using specific workload selectors to secure exposed workloads.

5.11 - Resources

5.11.1 - CAPApplication

Here’s an example of a fully configured CAPApplication:

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplication
metadata:
  name: cap-app
  namespace: cap-ns
spec:
  btp:
    services:
      - class: xsuaa
        name: cap-uaa
        secret: cap-uaa-bind
      - class: saas-registry
        name: cap-saas-reg
        secret: cap-saas-reg-bind
      - class: service-manager
        name: cap-service-manager
        secret: cap-svc-man-bind
      - class: destination
        name: cap-destination
        secret: cap-bem-02-dest-bind
      - class: html5-apps-repo
        name: cap-html5-repo-host
        secret: cap-html5-repo-bind
      - class: html5-apps-repo
        name: cap-html5-repo-runtime
        secret: cap-html5-rt-bind
      - class: some-content-service
        name: cap-some-content-service
        secret: cap-some-content-service-bind
      - class: business-logging
        name: cap-business-logging
        secret: cap-business-logging-bind
  btpAppName: cap-app
  domainRefs:
  - kind: Domain
    name: cap-app-01-primary
  - kind: ClusterDomain
    name: common-external-domain
  providerSubaccountId: 7a49218f-c750-4e1f-a248-7f1cefa13010

The btp.services array specifies all SAP BTP service instances and their corresponding Kubernetes Secrets (containing credentials) required by the application. These service instances are assumed to exist in the provider subaccount. You can use operators such as cf-service-operator or sap-btp-service-operator to declaratively create these service instances and their credentials as Kubernetes resources.

The providerSubaccountId identifies the provider subaccount linked to the application. The combination of providerSubaccountId and btpAppName (equivalent to XSAPPNAME) must be unique, as it is used in various SAP BTP service and application constructs.

The provider section is deprecated and may be completely ommited as of version 0.31.0 even for multi-tenant applications, this also skips the creation of a provider tenant.

The domainRefs section references one or more Domain or ClusterDomain resources.

NOTE: While the same secondary domain can technically be shared across applications using ClusterDomain, tenant subdomains must be unique across all applications sharing that domain.

NOTE: The provider section must always be omitted for services-only applications.

The optional rolloutOnCredentialUpdate field enables automatic rolling restarts of affected Deployments when the referenced BTP service credential Secrets are updated. See Rollout on Credential Update for details.

5.11.2 - CAPApplicationVersion

The CAPApplicationVersion has the following high-level structure:

apiVersion: sme.sap.com/v1alpha2
kind: CAPApplicationVersion
metadata:
  name: cav-cap-app-v1
  namespace: cap-ns
spec:
  version: 3.2.1 # <-- semantic version (must be unique within the versions of a CAP application)
  capApplicationInstance: cap-app
  registrySecrets: # <-- image pull secrets to be used in the workloads
    - regcred
  workloads: # <-- define deployments and jobs used for this application version
    - name: "cap-backend"
      deploymentDefinition: # ...
      consumedBTPServices: # ...
    - name: "app-router"
      deploymentDefinition: # ...
      consumedBTPServices: # ...
    - name: "service-content"
      jobDefinition: # ...
      consumedBTPServices: # ...
    - name: "tenant-operation"
      jobDefinition: # ...
      consumedBTPServices: # ...
  tenantOperations: # ... <-- (optional)

• A CAPApplicationVersion is always associated with a CAPApplication in the same namespace, referenced via the capApplicationInstance attribute.
• The workloads array defines the software components of the application. Examples include a deployment for the CAP application server or a job for tenant operations. Each workload must have either a deploymentDefinition or a jobDefinition. See the next section for details.
• The optional tenantOperations attribute defines a sequence of steps (jobs) to execute during tenant operations (provisioning, upgrade, or deprovisioning).

The CAPApplicationVersion resource is immutable — its spec must not be modified after deployment. This is enforced by webhooks, which we recommend keeping active (the default).

Workloads with deploymentDefinition

name: cap-backend
consumedBTPServices: # <-- an array of service instance names referencing the SAP BTP services defined in the CAPApplication resource
  - cap-uaa
  - cap-saas-reg
deploymentDefinition:
  type: CAP # <-- possible values are CAP / Router / Additional / Service
  image: some.repo.example.com/cap-app/server:3.22.11 # <-- container image
  env: # <-- (optional) same as in core v1 pod.spec.containers.env
    - name: SAY
      value: "I'm GROOT"
  replicas: 3 # <-- (optional) replicas for scaling
  ports:
    - name: app-port
      port: 4004
      routerDestinationName: cap-server-url
    - name: tech-port
      port: 4005
  monitoring:
    scrapeConfig:
      port: tech-port
    deletionRules:
      expression: scalar(sum(avg_over_time(current_sessions{job="cav-cap-app-v1-cap-backend-svc",namespace="cap-ns"}[2h]))) <= bool 5

The type of the deployment indicates how the operator handles this workload (for example, injection of destinations used by the Approuter). Valid values are:

• CAP to indicate a CAP application server. Only one workload of this type is allowed.
• Router to indicate a version of the Approuter. Only one workload of this type is allowed.
• Additional to indicate supporting components deployed alongside the CAP application server.
• Service to indicate workloads that are tenant-agnostic.

You can define optional attributes such as replicas, env, resources, probes, securityContext, initContainers, and ports to configure the deployment.

Port configuration

You can define which ports (and how many) exposed by a deployment container are made available inside the cluster (via Services of type ClusterIP). The port definition includes a name in addition to the port number being exposed.

For deploymentDefinition types other than Router, you can specify a routerDestinationName that is used as a named destination injected into the Approuter.

The port configurations are not mandatory and can be omitted. When omitted, the operator applies the following defaults:

• For workloads of type CAP, the default port 4004 is added to the Service, and a destination named srv-api is added to the Approuter referencing this service port (any existing destinations environment configuration for this workload is preserved, with only the URL overwritten).
• For workloads of type Router, port 5000 is exposed in the Service. This Service is used as the target for HTTP traffic reaching the application domain (domains are specified in the CAPApplication resource).

NOTE: If multiple ports are configured for a workload of type Router, the first port is used to target external traffic to the application domain.

Monitoring configuration

For each deployment workload in a CAPApplicationVersion, you can define:

1. Deletion rules: Criteria based on metrics that, when satisfied, indicate the workload can be removed.
2. Scrape configuration: Defines how metrics are scraped from the workload service.

Details of how to configure workload monitoring can be found here.

Workloads with jobDefinition

workloads:
  # ... deployment workloads have been omitted in this example
  - name: "content-deployer"
    consumedBTPServices: # ...
    jobDefinition:
      type: Content
      image: some.repo.example.com/cap-app/content:1.0.1
  - name: "tenant-operation"
    consumedBTPServices: # ...
    jobDefinition:
      type: TenantOperation
      image: some.repo.example.com/cap-app/server:3.22.11
      backoffLimit: 2 # <-- determines retry attempts for the job on failure (default is 6)
      ttlSecondsAfterFinished: 300 # <-- the job will be cleaned up after this duration
      env:
        - name: CDS_ENV
          value: production
        - name: CDS_CONFIG
          value: '{ "requires":{"cds.xt.DeploymentService":{"hdi": { "create":{ "database_id": "16e25c51-5455-4b17-a4d7-43545345345" } } } } }'
  - name: "notify-upgrade"
    consumedBTPServices: # ...
    jobDefinition:
      type: CustomTenantOperation
      image: # ...
      command: ["npm", "run", "notify:upgrade"] # <-- custom entry point for the container allows reuse of a container image with multiple entry points
      backoffLimit: 1
  - name: "create-test-data"
    consumedBTPServices: # ...
    jobDefinition:
      type: CustomTenantOperation
      image: # ...
      command: ["npm", "run", "deploy:testdata"]