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

CAP Operator introduced an update to domain management: the deprecated domains section in CAPApplication resources has been replaced by the more flexible domainRefs. This allows you to reference Domain or ClusterDomain resources, giving greater control over networking behavior, including TLS handling, ingress routing, and DNS setup.

Update Your Application Manifests

If your CAP applications still use the deprecated domains section, migrate to the domainRefs format by defining Domain or ClusterDomain resources explicitly.

Using the 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
  ...

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     # Refers to a namespaced Domain resource
  - kind: ClusterDomain
    name: common-external-domain # Refers to a shared ClusterDomain resource
  ...

Define the referenced domain resources:

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
  dnsMode: Wildcard

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
  dnsMode: Subdomain

Migration Support

Automatic Migration During Upgrade

Details (v0.15.0 – v0.25.0)

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

  • Scans existing CAPApplication resources.
  • Removes network-related resources (Gateways, DNSEntries, Certificates) linked to the deprecated domains.
  • Creates equivalent Domain or ClusterDomain resources.
  • Updates CAPApplication resources to use domainRefs.

Mutation Webhook

A mutation webhook ensures consistency by converting CAPApplication resources that still use the deprecated domains section into Domain or ClusterDomain resources and populating domainRefs.

Post-Migration Steps

Verify Migrated Resources

After upgrading, verify your CAPApplication resources to confirm that domainRefs have been added:

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

Ensure that:

  • the domains section is removed
  • the domainRefs entries exist
  • the corresponding Domain or ClusterDomain resources are present

1 - A Guide to Flexible DNS Configuration

How to configure Custom DNS mode for Domain or ClusterDomain

Overview

Custom DNS mode lets you use Go templates to generate DNS entries dynamically, giving you precise control over complex DNS configurations. Specify your desired setup in the dnsTemplates field.

You can use functions from the Slim Sprig library in your templates.

What is Custom DNS Mode?

Custom DNS mode uses Go templates to generate DNS entries. Specify your configuration in the dnsTemplates field.

Available Variables in DNS Templates

  • {{.domain}}: The value of spec.domain.
  • {{.dnsTarget}}: The effective ingress target, specified by spec.dnsTarget or derived from spec.istioIngressSelector.
  • {{.subDomain}}: The subdomain of a CAPTenant or a tenant-agnostic workload.

DNS Record Behavior

  • Each template typically produces one DNS record.
  • If the name contains {{.subDomain}}, a DNS record is created for each valid subdomain from tenants or service exposures.
  • {{.subDomain}} may appear in the target only if it also appears in the name.

Example Configuration

The following example configures Custom DNS mode for a Domain resource:

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
  dnsMode: Custom
  dnsTemplates:
  - name: '*.{{ .domain }}'
    target: '{{ .dnsTarget }}'
  - name: '{{ .subDomain }}.{{ .domain }}'
    target: '{{ .dnsTarget }}'
  - name: '{{ .subDomain }}.myapp.com'
    target: '{{ .subDomain }}.{{ .domain }}'

This configuration applies to both Domain and ClusterDomain resources.

2 - Configuring Additional CA Certificates

How to configure Additional CA Certificates for Domain or ClusterDomain

Overview

When using X509 client authentication on the Istio Gateway, setting tlsMode to Mutual or OptionalMutual requires additional CA certificates. These certificates are essential for verifying client certificates, ensuring secure communication between services.

Configuration Steps

Understanding the Configuration

The certConfig.additionalCACertificate field is where you specify the additional CA certificates. This configuration is crucial for environments where mutual TLS is enforced, as it allows Istio to authenticate incoming client requests.

Example Configuration

Below is an example of how to configure additional CA certificates for a ClusterDomain resource:

apiVersion: sme.sap.com/v1alpha1
kind: ClusterDomain
metadata:
  namespace: my-ns
  name: cap-example-domain
spec:
  domain: myapp.example.com
  ingressSelector:
    app: istio-ingressgateway
    istio: ingressgateway
  tlsMode: Mutual
  certConfig:
    additionalCACertificate: |
      -----BEGIN CERTIFICATE-----
      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
      -----END CERTIFICATE-----

This configuration can be applied to both Domain and ClusterDomain resources.