Explain how to workaround the SSL/TLS issues that might arise

[nmasse-itix]

As reported by @torbjorndahlen:

I’m getting into SSL cert problems due to the added domain apicast-staging when running the demo.
I.e. I have a server cert for apps.customer.rhmi.io but since the Jenkins-Toolbox config sets up the apicast router to *.apicast-staging.apps.customer.rhmi.io the SSL connection gets rejected.

The problem could be solved if I instead of using wildcard, could set the name of the Apicast host, for example beer-catalog.apps.customer.rhmi.io
Is this possible? Not sure how the hostname for apicast gets generated.

The other alternative to skip the apicast-staging part doesn’t work since the route *.apps.customer.rhmi.io is already taken.

There are multiple ways to solve the SSL/TLS issues that can arise in such situation:

1. Ignore SSL/TLS issues

Use the "curl -k" command in the integration test phase to workaround the SSL/TLS issue (that's already the case with the supplied sample jenkins pipelines). To showcase the resulting API in the API Developer Portal, you will have to accept the SSL/TLS warning in your browser (once before the demo) and it will work as long as your browser is left open. 

2. Add a valid wildcard certificate to each wildcard route

When creating the wildcard routes for the APIcast gateways, you could pass --key and --cert to provide a valid wildcard certificate.  

oc create route edge apicast-staging --service=apicast-staging --hostname="wildcard.$APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain --key path/to/staging-domain.key --cert path/to/staging-domain.crt
oc create route edge apicast-production --service=apicast-production --hostname="wildcard.$APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain --key path/to/production-domain.key --cert path/to/production-domain.crt

Getting a valid wildcard certificate is a bit out-of-scope for this guide. You can use Let's Encrypt certificates for this purpose but explaining in great details is out-of-scope for this guide (it involves setting up some DNS entries, which depends on your DNS provider...).

However, here is how I generate my wildcard certificates using Let's Encrypt and Gandi: 

brew install lego
GANDIV5_API_KEY=[REDACTED] lego  -d "*.$APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN" -d "*.$APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN" -a -m [email protected] --path $HOME/.lego --dns gandiv5 run

3. Hardcode the staging and production hostnames for each pipeline

Create a staging and production route for each API with a custom hostname:

oc create route edge apicast-api1-staging --service=apicast-staging --hostname="api1-staging.$OPENSHIFT_ROUTER_SUFFIX" --insecure-policy=Allow
oc create route edge apicast-api1-production --service=apicast-production --hostname="api1-production.$OPENSHIFT_ROUTER_SUFFIX" --insecure-policy=Allow

and so on for all the apis you plan to showcase...

Then, you need to fork this repository and slightly modify the pipelines.

Replace :

  stage("Prepare") {
    service = toolbox.prepareThreescaleService(
        openapi: ...
        environment: [ ...
                       publicStagingWildcardDomain: params.PUBLIC_STAGING_WILDCARD_DOMAIN,
                       publicProductionWildcardDomain: params.PUBLIC_PRODUCTION_WILDCARD_DOMAIN ],

with:

  stage("Prepare") {
    service = toolbox.prepareThreescaleService(
        openapi: ...
        environment: [ ...
                       stagingPublicBaseURL: "https://api1-staging." + params.PUBLIC_STAGING_WILDCARD_DOMAIN,
                       productionPublicBaseURL: "https://api1-production." + params.PUBLIC_PRODUCTION_WILDCARD_DOMAIN ],

And in the JenkinsPipeline BuildConfig set the PUBLIC_STAGING_WILDCARD_DOMAIN and PUBLIC_PRODUCTION_WILDCARD_DOMAIN variables to your openshift router wildcard domain (the value of $OPENSHIFT_ROUTER_SUFFIX, that is to say: "apps.customer.rhmi.io").

If you plan to showcase the pipeline creation using the provided template, you will need to reference your forked github repo using -p GIT_REPO=https://github.com/<your-github-username>/3scale-toolbox-jenkins-samples.git and change the PUBLIC_{STAGING,PRODUCTION}_WILDCARD_DOMAIN parameters to $OPENSHIFT_ROUTER_SUFFIX.

For instance, with the hybrid-usecase-open pipeline:

oc process -f hybrid-usecase-open/setup.yaml \
           -p GIT_REPO=https://github.com/<your-github-username>/3scale-toolbox-jenkins-samples.git \
           -p DEVELOPER_ACCOUNT_ID="$SAAS_DEVELOPER_ACCOUNT_ID" \
           -p PRIVATE_BASE_URL="http://$BEER_CATALOG_HOSTNAME" \
           -p TARGET_INSTANCE=3scale-saas \
           -p PUBLIC_STAGING_WILDCARD_DOMAIN="$OPENSHIFT_ROUTER_SUFFIX" \
           -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN="$OPENSHIFT_ROUTER_SUFFIX" \
           -p NAMESPACE="$TOOLBOX_NAMESPACE" |oc create -f -