When installing applications using Replicated Embedded Cluster in environments with --http-proxy, --https-proxy configurations, you may encounter preflight failures that prevent successful installation. This guide walks through common issues and their solutions.
Common Error Symptoms
You might see errors similar to these during installation:
sudo ./app install --license license.yaml --https-proxy=https://proxy.example.com:3129
✔ Initialization complete
✗ 2 host preflights failed
• Error connecting to https://replicated.app. Ensure your firewall is properly configured, and use --http-proxy, --https-proxy, and --no-proxy if there is a proxy server.
• Error connecting to https://registry.replicated.com. Ensure your firewall is properly configured, and use --http-proxy, --https-proxy, and --no-proxy if there is a proxy server.
Root Cause Analysis
The most common root cause for these failures is certificate validation issues with the HTTPS proxy, particularly when using self-signed certificates or certificates that don’t follow modern standards.
Step 1: Verify Basic Connectivity
First, test basic connectivity through your proxy using curl:
curl -v https://replicated.app --proxy https://your-proxy.example.com:3129
If this works, the issue is likely related to how the preflight checks handle certificate validation.
Step 2: Check Your Embedded Cluster Version
Ensure you’re using Embedded Cluster version 2.6.0 or later, which includes improved support for private certificate authorities:
./your-app version
Starting with version 2.6.0, Embedded Cluster automatically detects the system CA bundle and mounts it into components that require trust validation.
Step 3: Run Detailed Preflight Diagnostics
Create a test preflight specification to get detailed error information, update the proxy field to your proxy address:
# preflight-test.yaml
apiVersion: troubleshoot.sh/v1beta2
kind: HostPreflight
metadata:
name: proxy-test
spec:
collectors:
- http:
collectorName: http-replicated-app
get:
url: 'https://replicated.app'
timeout: 5s
proxy: 'https://your-proxy.example.com:3129'
- http:
collectorName: http-proxy-replicated-com
get:
url: 'https://proxy.replicated.com/v2/'
timeout: 5s
proxy: 'https://your-proxy.example.com:3129'
analyzers:
- http:
checkName: API Access
collectorName: http-replicated-app
outcomes:
- fail:
when: error
message: >
Error connecting to https://replicated.app.
Check proxy configuration and certificate trust.
- pass:
when: 'statusCode == 200'
message: 'Connected to https://replicated.app'
- http:
checkName: Registry Access
collectorName: http-proxy-replicated-com
outcomes:
- fail:
when: error
message: >
Error connecting to https://proxy.replicated.com.
Check proxy configuration and certificate trust.
- pass:
when: 'statusCode == 401'
message: 'Connected to https://proxy.replicated.com'
Run the diagnostic:
/var/lib/embedded-cluster/bin/kubectl-preflight -v=5 --interactive=0 preflight-test.yaml
# or <--data-dir>/bin/kubectl-preflight
Step 4: Analyze Certificate Issues
Look for specific error messages in the verbose output. Common issues include:
Legacy Common Name Issue
Request failed: proxyconnect tcp: tls: failed to verify certificate: x509: certificate relies on legacy Common Name field, use SANs instead
Solution: Update your proxy certificate to include Subject Alternative Names (SANs) instead of relying solely on the Common Name field.
Self-Signed Certificate Issues
Request failed: proxyconnect tcp: tls: failed to verify certificate: x509: certificate signed by unknown authority
Solution: Ensure your proxy’s CA certificate is installed in the system trust store.
If the issue persists after following these troubleshooting steps, reach out to Replicated support with outputs from all commands above.