This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Domain Management

Enhancing Domain Management with CAP Operator

1: Custom DNS Templates
2: Configuring Additional CA Certificates

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/v1alpha1
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/v1alpha1
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/v1alpha1
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

Migrating from the deprecated domains section

Update Your Application Manifests

Earlier versions of CAP Operator used an inline domains section directly in CAPApplication. This section is deprecated and no longer supported. If you are still using it, migrate to domainRefs as described below.

Before: deprecated `domains` section

apiVersion: sme.sap.com/v1alpha1
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

After: `domainRefs` with explicit resources

Create the Domain and ClusterDomain resources manually (see sections above), then update your CAPApplication to use domainRefs.

Mutation Webhook

A mutation webhook ensures consistency: if a CAPApplication is submitted with a domains section, the webhook converts it to Domain/ClusterDomain resources and populates domainRefs automatically.

Warning

The webhook rejects updates that reintroduce the deprecated domains section. If you add or modify the domains section in your manifest, the webhook rejects the change and provides an error message instructing you to use domainRefs instead.

Automatic Migration (v0.15.0 – v0.25.0)

Note

The automatic migration routine was available from v0.15.0 through v0.25.0 and has been removed as of v0.26.0. If you need this migration, first upgrade to v0.25.0 (or lower), allow the migration to complete, and then upgrade to the latest release.

Upgrading to CAP Operator v0.15.0 through v0.25.0 triggered an automatic migration routine that:

Scanned existing CAPApplication resources.
Removed network-related resources (Gateways, DNSEntries, Certificates) linked to the deprecated domains.
Created equivalent Domain or ClusterDomain resources.
Updated CAPApplication resources to use domainRefs.

Verify Migration

After migrating, confirm the resources are in the expected state:

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

Ensure that:

The domains section is absent.
The domainRefs entries are present.
The corresponding Domain or ClusterDomain resources exist in the cluster.

1 - Custom DNS Templates

How to configure Custom DNS mode for Domain or ClusterDomain

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.

Prerequisite

DNS entry creation requires the Gardener external-dns-management controller. When using the Kubernetes DNS manager, dnsMode is ignored and no DNS entries are created regardless of the mode chosen.

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:

Field	Description
`name`	DNS name for the record — rendered as a Go template
`target`	DNS target (hostname or IP) — rendered as a Go template

Available variables

The following variables are available in both name and target:

Variable	Value
`{{.domain}}`	The value of `spec.domain`
`{{.dnsTarget}}`	The effective ingress target: `spec.dnsTarget`, or `DNS_TARGET` env var, or the load balancer service annotation on the Istio Ingress Gateway
`{{.subDomain}}`	A subdomain collected from referencing applications — see Subdomain expansion

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}}.

Subdomain conflicts

If the same subdomain appears in two different CAPApplication resources that both reference the same domain, that subdomain is skipped for the second application and a SubdomainAlreadyInUse warning event is raised on it.

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/v1alpha1
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:

DNS name	Target
`*.my.cluster.shoot.url.k8s.example.com`	`<ingress target>`
`tenant-a.my.cluster.shoot.url.k8s.example.com`	`<ingress target>`
`tenant-b.my.cluster.shoot.url.k8s.example.com`	`<ingress target>`
`tenant-a.myapp.com`	`tenant-a.my.cluster.shoot.url.k8s.example.com`
`tenant-b.myapp.com`	`tenant-b.my.cluster.shoot.url.k8s.example.com`

2 - Configuring Additional CA Certificates

How to configure Additional CA Certificates for Domain or ClusterDomain

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/v1alpha1
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.