Using custom CA certificates

Edit online

Use custom CA certificates when your deployment relies on a certificate authority that is not included in the default container trust store.

Use this information when your deployment uses a TLS certificate signed by a CA that is not included in the default container trust store (for example, a self-signed certificate or a private enterprise CA). AEW provides a command to load CA material into the platform so that internal components can validate TLS connections correctly.

Before you begin

  • AEW must already be deployed and application pods must be in a Ready state.
  • You must have the public certificate or CA bundle used by your deployment. Do not include private keys.
  • asctl must be configured and able to access the cluster.

Enabling custom certificate trust

Run one of the following commands after deployment:


# Most common — AEW builds the trust list automatically
asctl enableCustomCert

# Provide a custom PEM bundle
asctl enableCustomCert /path/to/YourBundle.pem

After running either command, wait for all application pods to return to a Ready state. AEW automatically restarts affected components.

Table 1. Custom certificate commands
Command Description
asctl enableCustomCert Merges the base trust store with the deployed application certificate and distributes the result. Recommended for most scenarios.
asctl enableCustomCert <file.pem> Uses a user-provided PEM file as the trust bundle. Use when a specific CA bundle is required.

Certificate concepts

AEW uses certificates in two distinct ways. It is important to understand the difference:

Table 2. Certificate usage
Concept Purpose Configured via
App certificate (appCert / appKey) The TLS certificate presented by AEW for HTTPS termination during ingress. It is set once during the initial deployment. asctl config or asctl setup
Custom CA bundle Additional CA certificates trusted for outbound TLS validation. It is enabled at runtime after deployment. asctl enableCustomCert

When you run asctl enableCustomCert, AEW automatically adds the public portion of the application certificate to its internal trust store. You do not need to supply it again separately.

Creating a self-signed certificate

If an enterprise CA is not available, you can generate a self-signed certificate. This certificate can serve as both the application certificate and the CA trust input.

Note: Replace the domain names with your own FQDNs.

Single self-signed certificate:


openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout tls.key \
  -out tls.crt \
  -subj "/CN=aew76.asperatest.net" \
  -addext "basicConstraints=critical,CA:TRUE" \
  -addext "subjectAltName=DNS:aew76.asperatest.net,DNS:org76.aew76.asperatest.net,DNS:api.aew76.asperatest.net,DNS:keycloak.aew76.asperatest.net,DNS:logging.aew76.asperatest.net,DNS:monitoring.aew76.asperatest.net"

Full-chain self-signed certificate:


openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout tls.key \
  -out fullchain.crt \
  -subj "/CN=aew76.asperatest.net" \
  -addext "subjectAltName=DNS:aew76.asperatest.net,DNS:org76.aew76.asperatest.net,DNS:api.aew76.asperatest.net,DNS:keycloak.aew76.asperatest.net,DNS:logging.aew76.asperatest.net,DNS:monitoring.aew76.asperatest.net" \
  -addext "basicConstraints=critical,CA:TRUE"

The generated certificate files are provided during initial deployment. After deployment, run asctl enableCustomCert to configure trust.

Building a custom bundle

If required, create a PEM bundle that combines the base CA bundle with your application's public certificate:


docker run --rm registry.access.redhat.com/ubi9/ubi-minimal:latest \
  cat /etc/ssl/certs/ca-bundle.crt > base.crt

cat base.crt tls.crt > CustomCertificate.pem
asctl enableCustomCert /path/to/CustomCertificate.pem
Note: This method requires Docker and internet access to pull the image.

Making your browser trust a self-signed certificate (Mac)

Browser trust is separate from AEW's internal trust. Follow these steps to access AEW in a browser when using a self-signed cert:

  1. Open Keychain Access.
  2. Import your certificate (tls.crt or fullchain.crt).
  3. Double-click it, expand Trust, and set When using this certificate to Always Trust.

Verification

Run the following commands to verify that the custom certificate trust is enabled and that all application pods are running:


kubectl get asperaoperator -n aspera -o yaml | grep customCertBundleMode

kubectl get pods -n aspera

Rotating certificates

If the application certificate is rotated, run asctl enableCustomCert again to update the trust store.

Troubleshooting

Symptom Action
Unknown command: enableCustomCert Update asctl to a version that supports this command.
Pods not becoming Ready Verify that the application certificate secret exists in the namespace.
Services remain untrusted Ensure the PEM bundle includes all issuing CAs and rerun the command.
Browser shows certificate warnings Browser trust must be configured separately.
HSTS / AEJD flows are failing Refer to the official HSTS documentation for TLS settings specific to those flows.