domino_admin_toolkit.checks.test_domino_url_cert module

pydantic model domino_admin_toolkit.checks.test_domino_url_cert.DominoUrlCertExpirationAnalyzer

Bases: AnalyzerBase[DominoUrlCertRow]

Validates Domino control plane URL certificate is not expiring soon.

Checks the certificate expiration date and ensures sufficient time remains before renewal is required.

Fields:
field expiry_threshold_days: int = 30

Minimum days before expiration (FAIL if less)

analyze(data)

Analyzes one row and returns a list of CheckResult instances.

Return type:

list[CheckResult]

Args:

data: One row dict (TRow). The Runner calls this once per DataFrame row.

Returns:

List[CheckResult]: A list containing the results of the analysis.

Raises:

NotImplementedError: If this method is not implemented by subclasses.

name: ClassVar[str] = 'DominoUrlCertExpirationAnalyzer'
class domino_admin_toolkit.checks.test_domino_url_cert.DominoUrlCertRow

Bases: TypedDict

bundle_cert_count: int
bundle_path: str
cert_fingerprint: str
cert_in_bundle: bool
cert_obj: Certificate
cert_pem: str
days_until_expiry: int
hostname: str
issuer: str
not_after: str
not_before: str
serial_number: str
subject: str
url: str
verified: bool
pydantic model domino_admin_toolkit.checks.test_domino_url_cert.DominoUrlCertValidationAnalyzer

Bases: AnalyzerBase[DominoUrlCertRow]

Validates that the Domino URL certificate can be verified using the mounted bundle.

Checks if the certificate is trusted (can be verified via SSL) and provides diagnostic information about bundle contents. The mounted bundle at /etc/ssl/certs/ca-certificates.crt serves as the system trust store for the toolkit.

Fields:

analyze(data)

Analyzes one row and returns a list of CheckResult instances.

Return type:

list[CheckResult]

Args:

data: One row dict (TRow). The Runner calls this once per DataFrame row.

Returns:

List[CheckResult]: A list containing the results of the analysis.

Raises:

NotImplementedError: If this method is not implemented by subclasses.

name: ClassVar[str] = 'DominoUrlCertValidationAnalyzer'
domino_admin_toolkit.checks.test_domino_url_cert.domino_url_cert_data(domino_api_client)

Fixture: Collect Domino URL certificate data for expiration checking.

Returns:

DataFrame with certificate expiration details

domino_admin_toolkit.checks.test_domino_url_cert.test_domino_url_cert_expiration(domino_url_cert_data, runner)
Description:

Validates Domino control plane URL certificate is valid and not expiring soon. Retrieves the TLS certificate from the Domino platform URL and verifies it has sufficient time remaining before expiration. Focuses solely on the validity period, not verification against a trust store (see test_domino_url_cert_validation for that).

Empty Data Behavior (reports PASS, not pytest SKIP):

  • When the certificate cannot be retrieved from the Domino URL (network connectivity issues), the check soft-passes via on_empty=Status.PASS so the report is not blocked

  • This is expected behavior in deployments where the toolkit cannot reach the frontend (e.g., network policies, firewall rules, or isolated network configurations)

Failure Conditions:

  • Certificate has already expired

  • Certificate expires in less than 30 days

Troubleshooting Steps:

  1. Check certificate expiration date: echo | openssl s_client -connect <domino-url>:443 2>/dev/null | openssl x509 -noout -dates

  2. Verify certificate renewal process is functioning correctly

  3. Check if certificate issuer (CA) is still valid and operational

  4. Review DNS resolution for the Domino URL: nslookup <domino-url>

Resolution Steps:

  1. For cert-manager-managed certs: verify the Issuer/ClusterIssuer is Ready, then trigger manual renewal: kubectl annotate certificate -n <ns> <name> cert-manager.io/issueOnce=true

  2. For manually-managed certs: replace the Secret data with a renewed PEM certificate

  3. See test_cert_manager.py to verify cert-manager health before troubleshooting renewal

Required Permissions:

  • Network access to the Domino frontend URL from the toolkit pod

  • kubectl read access to Certificate CRs (if cert-manager is in use)

See also:

  • test_tls_secret_expiration.py — checks in-cluster TLS Secret expiry across all namespaces

  • info/test_certificate_inventory.py — full cert inventory with chain validation and self-signed detection

  • test_cert_manager.py — cert-manager controller and CRD health

domino_admin_toolkit.checks.test_domino_url_cert.test_domino_url_cert_validation(domino_url_cert_data, runner)
Description:

Validates that the Domino URL certificate can be verified via the mounted bundle. Checks if the certificate is trusted using the system trust store at /etc/ssl/certs/ca-certificates.crt. For deployments using private certificate authorities or self-signed certificates, custom CA certificates must be added to Domino’s trust store — especially important for services that connect to the deployment via its public hostname, including services in remote data planes.

The check provides diagnostic information about: - Whether SSL verification succeeds - Whether the cert/CA is found in the bundle - Number of CAs in the bundle

Documentation:

See https://docs.dominodatalab.com/en/cloud/admin_guide/77bb0e/domino-custom-certificates-configmap/ for detailed instructions on managing custom certificates in Domino.

Empty Data Behavior (reports PASS, not pytest SKIP):

  • When the certificate cannot be retrieved from the Domino URL (network connectivity issues), the check soft-passes via on_empty=Status.PASS so the report is not blocked

  • This is expected behavior in deployments where the toolkit cannot reach the frontend (e.g., network policies, firewall rules, or isolated network configurations)

Failure Conditions:

  • Certificate cannot be verified via SSL (cert/CA not in bundle)

  • This typically occurs when using private CAs or self-signed certificates that have not been added to Domino’s custom certificate bundle

  • Certificate bundle file is missing, out of date, or unreadable

  • Certificate is in bundle but verification still fails (chain/expiration issues)

Troubleshooting Steps:

  1. Determine if you are using a private CA or self-signed certificate

  2. Check if domino-custom-certificates ConfigMap exists in the default namespace: kubectl get configmap domino-custom-certificates -n default

  3. Verify domino-generated-certificates ConfigMap exists and contains ca-certificates.crt: kubectl get configmap domino-generated-certificates -n <namespace> -o yaml | grep ca-certificates.crt

  4. Verify the toolkit pod has the bundle mounted: kubectl exec -n <namespace> <toolkit-pod> – ls -la /etc/ssl/certs/ca-certificates.crt

  5. For detailed diagnostics, see the public documentation linked above

Resolution Steps:

  1. Add your custom CA certificate(s) to the domino-custom-certificates ConfigMap in the default namespace in PEM format. The custom-certificates-manager service will automatically sync these to domino-generated-certificates.

  2. Restart affected services (nucleus, keycloak, data-plane-agent, toolkit, etc.) to pick up the updated certificates.

  3. For remote data planes: ensure domino-generated-certificates is copied to the data plane namespace during initial deployment when using custom CAs.

  4. See https://docs.dominodatalab.com/en/cloud/admin_guide/77bb0e/domino-custom-certificates-configmap/ for detailed step-by-step instructions and examples.

See also:

  • test_tls_secret_expiration.py — checks in-cluster TLS Secret expiry across all namespaces

  • info/test_certificate_inventory.py — full cert inventory with chain validation and self-signed detection

  • test_cert_manager.py — cert-manager controller and CRD health