add doc and prepare for transfer

7 years ago · 67cc5fc821
25 changed files with 444 additions and 149 deletions
--- a/README.md
+++ b/README.md
@ -1,114 +1,23 @@
-# API Lifecycle Mockup
+# Code samples using the 3scale toolbox Jenkins shared library

-## Pre-requisites
+This repository holds code samples to showcase the use of the [3scale toolbox Jenkins shared library](https://github.com/rh-integration/3scale-toolbox-jenkins) to automate the delivery of APIs using CI/CD and more specifically Jenkins pipelines.

- OpenShift Cluster
- Linux or Mac Workstation
-
-## Setup
-
-Create an OpenShift project to hold all your artefacts:
-
-```sh
-oc project api-lifecycle
-```
-
-Deploy a Jenkins master:
-
-```sh
-oc new-app --template=jenkins-ephemeral --name=jenkins -p MEMORY_LIMIT=2Gi
-oc set env dc/jenkins JENKINS_OPTS=--sessionTimeout=86400
-```
-
-Create a secret that contains all your [3scale remotes](https://github.com/3scale/3scale_toolbox/blob/master/docs/remotes.md):
-
-```sh
-3scale remote add 3scale-saas https://$TOKEN@$TENANT.3scale.net/
-3scale remote add 3scale-onprem https://$TOKEN@$TENANT.$DOMAIN/
-oc create secret generic 3scale-toolbox --from-file=$HOME/.3scalerc.yaml
-```
-
-Deploy the sample Beer Catalog API Backend (used by the first three usecases):
-
-```sh
-oc project api-lifecycle
-oc new-app -i openshift/redhat-openjdk18-openshift:1.4 https://github.com/microcks/api-lifecycle.git --context-dir=/beer-catalog-demo/api-implementation --name=beer-catalog
-oc expose svc/beer-catalog --hostname=beer-catalog.app.itix.fr
-```
-
-Deploy the sample Red Hat Event API Backend (used by the subsequent usecases):
-
-```sh
-oc project api-lifecycle
-oc new-app -i openshift/nodejs:10 'https://github.com/nmasse-itix/rhte-api.git#085b015' --name=event-api
-oc expose svc/event-api --hostname=event-api.app.itix.fr
-```
-
-Deploy APIcast instances to be used in APIcast self-managed instances:
-
-```sh
-oc create secret generic 3scale-tenant-saas --from-literal=password=https://$TOKEN@$TENANT-admin.3scale.net
-oc create -f https://raw.githubusercontent.com/3scale/apicast/v3.4.0/openshift/apicast-template.yml
-oc new-app --template=3scale-gateway --name=apicast-saas-staging -p CONFIGURATION_URL_SECRET=3scale-tenant-saas -p CONFIGURATION_CACHE=0 -p RESPONSE_CODES=true -p LOG_LEVEL=info -p CONFIGURATION_LOADER=lazy -p APICAST_NAME=apicast-saas-staging -p DEPLOYMENT_ENVIRONMENT=sandbox -p IMAGE_NAME=quay.io/3scale/apicast:v3.4.0
-oc new-app --template=3scale-gateway --name=apicast-saas-production -p CONFIGURATION_URL_SECRET=3scale-tenant-saas -p CONFIGURATION_CACHE=60 -p RESPONSE_CODES=true -p LOG_LEVEL=info -p CONFIGURATION_LOADER=boot -p APICAST_NAME=apicast-saas-production -p DEPLOYMENT_ENVIRONMENT=production -p IMAGE_NAME=quay.io/3scale/apicast:v3.4.0
-oc scale dc/apicast-saas-staging --replicas=1
-oc scale dc/apicast-saas-production --replicas=1
-oc create route edge apicast-saas-staging --service=apicast-saas-staging --hostname=wildcard.saas-staging.app.itix.fr --insecure-policy=Allow --wildcard-policy=Subdomain
-oc create route edge apicast-saas-production --service=apicast-saas-production --hostname=wildcard.saas-production.app.itix.fr --insecure-policy=Allow --wildcard-policy=Subdomain
-```
-
-Add wildcard routes to your existing 3scale on-prem instance:
-
-```sh
-oc project 3scale-25
-oc create route edge apicast-wildcard-staging --service=apicast-staging --hostname=wildcard.onprem-staging.app.itix.fr --insecure-policy=Allow --wildcard-policy=Subdomain
-oc create route edge apicast-wildcard-production --service=apicast-production --hostname=wildcard.onprem-production.app.itix.fr --insecure-policy=Allow --wildcard-policy=Subdomain
-```
+[Full API Lifecycle Management](https://developers.redhat.com/blog/2019/02/25/full-api-lifecycle-management-a-primer/) using the 3scale toolbox Jenkins shared library is showcased in this repository: [IntegrationApp-Automation](https://github.com/rh-integration/IntegrationApp-Automation).

 ## Usecases

-| #                  | Format | Security | Target                           | Notes               |
-|--------------------|--------|----------|----------------------------------|---------------------|
-| [01](testcase-01/) | YAML   | API Key  | SaaS                             | -                   |
-| [02](testcase-02/) | JSON   | Open     | Self-Managed, on-premises        | URL rewriting       |
-| [03](testcase-03/) | JSON   | OIDC     | Self-Managed, on-premises        | URL rewriting       |
-| [04](testcase-04/) | YAML   | API Key  | 3 envs on 1 tenant, self-managed | -                   |
-| [05](testcase-05/) | YAML   | API Key  | 3 envs on 1 tenant, self-managed | Semantic Versioning |
-
-### Usecase 01: Deploy a simple API on 3scale SaaS
-
-```sh
-oc process -f testcase-01/setup.yaml -p DEVELOPER_ACCOUNT_ID=2445582535751 -p PRIVATE_BASE_URL=http://beer-catalog.app.itix.fr |oc create -f -
-```
-
-### Usecase 02: Deploy an API on 3scale SaaS with self-managed APIcast and 3scale on-premises
+Five usecases will be showcased, from the simpler one (API Key on 3scale SaaS), to the most complete one (multi-environment, semantic versioning).

-```sh
-oc process -f testcase-02/setup.yaml -p DEVELOPER_ACCOUNT_ID=2445582535751 -p PRIVATE_BASE_URL=http://beer-catalog.app.itix.fr -p TARGET_INSTANCE=3scale-saas -p PUBLIC_STAGING_WILDCARD_DOMAIN=nmasse-redhat-staging.app.itix.fr -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN=nmasse-redhat-production.app.itix.fr |oc create -f -
-```
+| Usecase                                         | Security            | Target                           | Notes               |
+|-------------------------------------------------|---------------------|----------------------------------|---------------------|
+| [SaaS - API Key](saas-usecase-apikey/)          | API Key             | SaaS                             | -                   |
+| [Hybrid - Open](hybrid-usecase-open/)           | Open                | Self-Managed + on-premises       | URL rewriting       |
+| [Hybrid - OIDC](hybrid-usecase-oidc/)           | OpenID Connect      | Self-Managed + on-premises       | URL rewriting       |
+| [Multi-environment](multi-environment-usecase/) | API Key             | 3 envs on 1 tenant, self-managed | -                   |
+| [Semantic versioning](semver-usecase/)          | Open, API Key, OIDC | 3 envs on 1 tenant, self-managed | Semantic Versioning |

-```sh
-oc process -f testcase-02/setup.yaml -p DEVELOPER_ACCOUNT_ID=5 -p PRIVATE_BASE_URL=http://beer-catalog.app.itix.fr -p TARGET_INSTANCE=3scale-onprem -p PUBLIC_STAGING_WILDCARD_DOMAIN=onprem-staging.app.itix.fr -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN=onprem-production.app.itix.fr -p DISABLE_TLS_VALIDATION=yes |oc create -f -
-```
-
-### Usecase 03: Deploy an API secured with OpenID Connect
-
-```sh
-oc process -f testcase-03/setup.yaml -p DEVELOPER_ACCOUNT_ID=2445582535751 -p PRIVATE_BASE_URL=http://beer-catalog.app.itix.fr -p TARGET_INSTANCE=3scale-saas -p PUBLIC_STAGING_WILDCARD_DOMAIN=nmasse-redhat-staging.app.itix.fr -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN=nmasse-redhat-production.app.itix.fr -p OIDC_ISSUER_ENDPOINT=https://$CLIENT_ID:$CLIENT_SECRET@$SSO_HOSTNAME/auth/realms/$REALM |oc create -f -
-```
-
-```sh
-oc process -f testcase-03/setup.yaml -p DEVELOPER_ACCOUNT_ID=5 -p PRIVATE_BASE_URL=http://beer-catalog.app.itix.fr -p TARGET_INSTANCE=3scale-onprem -p PUBLIC_STAGING_WILDCARD_DOMAIN=onprem-staging.app.itix.fr -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN=onprem-production.app.itix.fr -p DISABLE_TLS_VALIDATION=yes  -p OIDC_ISSUER_ENDPOINT=https://$CLIENT_ID:$CLIENT_SECRET@$SSO_HOSTNAME/auth/realms/$REALM |oc create -f -
-```
-
-### Usecase 04: Deploy an API in three environments, all in one tenant
-
-```sh
-oc process -f testcase-04/setup.yaml -p DEVELOPER_ACCOUNT_ID=2445582535751 -p PRIVATE_BASE_URL=http://event-api.app.itix.fr -p PUBLIC_STAGING_WILDCARD_DOMAIN=nmasse-redhat-staging.app.itix.fr -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN=nmasse-redhat-production.app.itix.fr |oc create -f -
-```
+## Setup

-### Usecase 05: Deploy four versions of an API in three environments, all in one tenant
+Before you can deploy the provided pipelines, you will need to setup your environment accordingly.

-```sh
-oc process -f testcase-05/setup.yaml -p DEVELOPER_ACCOUNT_ID=2445582535751 -p PRIVATE_BASE_URL=http://event-api.app.itix.fr -p PUBLIC_STAGING_WILDCARD_DOMAIN=nmasse-redhat-staging.app.itix.fr -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN=nmasse-redhat-production.app.itix.fr -p OIDC_ISSUER_ENDPOINT=https://$CLIENT_ID:$CLIENT_SECRET@$SSO_HOSTNAME/auth/realms/$REALM |oc create -f -
-```
+**Follow the [SETUP guide](SETUP.md).**
--- a/SETUP.md
+++ b/SETUP.md
@ -0,0 +1,186 @@
+# Environment Setup
+
+## Pre-requisites
+
+- OpenShift Cluster
+- Linux or Mac Workstation
+- [3scale SaaS Tenant](https://www.3scale.net/signup)
+
+## 3scale SaaS Environment
+
+- Go to your 3scale SaaS Admin console
+- [Generate a new Access Token](https://access.redhat.com/documentation/en-us/red_hat_3scale/2-saas/html/accounts/tokens) that has **write access** to the **Account Management API**
+- Save the generated access token for later use:
+
+```sh
+export SAAS_ACCESS_TOKEN=123...456
+```
+
+- Save the name of your 3scale tenant (the string before `-admin.3scale.net` in your Admin Console) for later use
+
+```sh
+export SAAS_TENANT=nmasse-redhat
+```
+
+- Navigate to **Audience** > **Accounts** > **Listing**
+- Click on **Developer**
+- Saver the **Developer** Account ID that is the last part of the URL (after **/buyers/accounts/**)
+
+```sh
+export SAAS_DEVELOPER_ACCOUNT_ID=2445582535751
+```
+
+## 3scale on-prem environment
+
+- [Deploy 3scale 2.5 on your OpenShift environment](https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.5/html/installing_3scale/onpremises-installation)
+- [Generate a new Access Token](https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.5/html/admin_portal_guide/tokens) that has **write access** to the **Account Management API**
+- Save the generated access token for later use:
+
+```sh
+export ONPREM_ACCESS_TOKEN=123...456
+```
+
+- Save the hostname of your 3scale Admin Portal for later use:
+
+```sh
+export ONPREM_ADMIN_PORTAL_HOSTNAME="$(oc get route system-provider-admin -o jsonpath='{.spec.host}')"
+```
+
+- Define your wildcard routes:
+
+```sh
+export OPENSHIFT_ROUTER_SUFFIX=app.openshift.test # Replace me !
+export APICAST_ONPREM_STAGING_WILDCARD_DOMAIN=wildcard.onprem-staging.$OPENSHIFT_ROUTER_SUFFIX
+export APICAST_ONPREM_PRODUCTION_WILDCARD_DOMAIN=wildcard.onprem-production.$OPENSHIFT_ROUTER_SUFFIX
+```
+
+**Note:** You will have to set the value of the `OPENSHIFT_ROUTER_SUFFIX` variable to the suffix of your OpenShift Router (usually something such as `app.openshift.test`).
+
+- Add the wildcard routes to your existing 3scale on-prem instance
+
+```sh
+oc create route edge apicast-wildcard-staging --service=apicast-staging --hostname="$APICAST_ONPREM_STAGING_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain
+oc create route edge apicast-wildcard-production --service=apicast-production --hostname="$APICAST_ONPREM_PRODUCTION_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain
+```
+
+- Navigate to **Audience** > **Accounts** > **Listing**
+- Click on **Developer**
+- Saver the **Developer** Account ID that is the last part of the URL (after **/buyers/accounts/**)
+
+```sh
+export ONPREM_DEVELOPER_ACCOUNT_ID=5
+```
+
+## Deploy Red Hat SSO
+
+Deploy Red Hat SSO 7.3 as explained in [the official documentation](https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.3/html/red_hat_single_sign-on_for_openshift/get_started).
+
+A short sumup is given for convenience:
+
+```sh
+
+oc replace -n openshift --force -f https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/sso73-dev/templates/sso73-image-stream.json
+oc replace -n openshift --force -f https://raw.githubusercontent.com/jboss-container-images/redhat-sso-7-openshift-image/sso73-dev/templates/sso73-x509-postgresql-persistent.json
+oc -n openshift import-image redhat-sso73-openshift:1.0
+oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default
+oc new-app --template=sso73-x509-postgresql-persistent --name=sso -p DB_USERNAME=sso -p SSO_ADMIN_USERNAME=admin -p DB_DATABASE=sso
+```
+
+Save the hostname of your SSO installation for later use:
+
+```sh
+export SSO_HOSTNAME="$(oc get route sso -o jsonpath='{.spec.host}')"
+```
+
+## Configure Red Hat SSO
+
+- Configure Red Hat SSO for 3scale as explained [in the documentation](https://access.redhat.com/documentation/en-us/red_hat_3scale_api_management/2.5/html/using_the_developer_portal/openid-connect)
+- Save the Realm name, client_id and client_secret for later use:
+
+```sh
+export CLIENT_ID=3scale-admin
+export CLIENT_SECRET=123...456
+export REALM=3scale
+```
+
+## Install Jenkins
+
+Create an OpenShift project to hold all your artefacts:
+
+```sh
+oc project api-lifecycle
+```
+
+Save the name of the project for later use:
+
+```sh
+export TOOLBOX_NAMESPACE=api-lifecycle
+```
+
+Deploy a Jenkins master:
+
+```sh
+oc new-app -n "$TOOLBOX_NAMESPACE" --template=jenkins-ephemeral --name=jenkins -p MEMORY_LIMIT=2Gi
+oc set env -n "$TOOLBOX_NAMESPACE" dc/jenkins JENKINS_OPTS=--sessionTimeout=86400
+```
+
+## Generate the 3scale toolbox secret
+
+- First, [install the 3scale toolbox locally](https://github.com/3scale/3scale_toolbox#installation).
+- Then, create a secret that contains all your [3scale remotes](https://github.com/3scale/3scale_toolbox/blob/master/docs/remotes.md):
+
+```sh
+3scale remote add 3scale-saas "https://$SAAS_ACCESS_TOKEN@$SAAS_TENANT-admin.3scale.net/"
+3scale remote add 3scale-onprem "https://$ONPREM_ACCESS_TOKEN@$ONPREM_ADMIN_PORTAL_HOSTNAME/"
+oc create secret generic 3scale-toolbox -n "$TOOLBOX_NAMESPACE" --from-file="$HOME/.3scalerc.yaml"
+```
+
+## Deploy the sample API backends
+
+Deploy the sample Beer Catalog API Backend (used by the first three usecases):
+
+```sh
+oc new-app -n "$TOOLBOX_NAMESPACE" -i openshift/redhat-openjdk18-openshift:1.4 https://github.com/microcks/api-lifecycle.git --context-dir=/beer-catalog-demo/api-implementation --name=beer-catalog
+oc expose -n "$TOOLBOX_NAMESPACE" svc/beer-catalog
+```
+
+Save the Beer Catalog API hostname for later use:
+
+```sh
+export BEER_CATALOG_HOSTNAME="$(oc get route -n "$TOOLBOX_NAMESPACE" beer-catalog -o jsonpath='{.spec.host}')"
+```
+
+Deploy the sample Red Hat Event API Backend (used by the subsequent usecases):
+
+```sh
+oc new-app -n "$TOOLBOX_NAMESPACE" -i openshift/nodejs:10 'https://github.com/nmasse-itix/rhte-api.git#085b015' --name=event-api
+oc expose -n "$TOOLBOX_NAMESPACE" svc/event-api
+```
+
+Save the Event API hostname for later use:
+
+```sh
+export EVENT_API_HOSTNAME="$(oc get route -n "$TOOLBOX_NAMESPACE" event-api -o jsonpath='{.spec.host}')"
+```
+
+## Deploy APIcast instances
+
+- Define your wildcard routes:
+
+```sh
+export APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN=wildcard.saas-staging.$OPENSHIFT_ROUTER_SUFFIX
+export APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN=wildcard.saas-production.$OPENSHIFT_ROUTER_SUFFIX
+```
+
+- Deploy APIcast instances (in the project of your choice) to be used with 3scale SaaS as self-managed instances:
+
+```sh
+oc create secret generic 3scale-tenant --from-literal=password=https://$SAAS_ACCESS_TOKEN@$SAAS_TENANT-admin.3scale.net
+oc create -f https://raw.githubusercontent.com/3scale/apicast/v3.4.0/openshift/apicast-template.yml
+oc new-app --template=3scale-gateway --name=apicast-staging -p CONFIGURATION_URL_SECRET=3scale-tenant -p CONFIGURATION_CACHE=0 -p RESPONSE_CODES=true -p LOG_LEVEL=info -p CONFIGURATION_LOADER=lazy -p APICAST_NAME=apicast-staging -p DEPLOYMENT_ENVIRONMENT=sandbox -p IMAGE_NAME=quay.io/3scale/apicast:v3.4.0
+oc new-app --template=3scale-gateway --name=apicast-production -p CONFIGURATION_URL_SECRET=3scale-tenant -p CONFIGURATION_CACHE=60 -p RESPONSE_CODES=true -p LOG_LEVEL=info -p CONFIGURATION_LOADER=boot -p APICAST_NAME=apicast-production -p DEPLOYMENT_ENVIRONMENT=production -p IMAGE_NAME=quay.io/3scale/apicast:v3.4.0
+oc scale dc/apicast-staging --replicas=1
+oc scale dc/apicast-production --replicas=1
+oc create route edge apicast-staging --service=apicast-staging --hostname="$APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain
+oc create route edge apicast-production --service=apicast-saas-production --hostname="$APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN" --insecure-policy=Allow --wildcard-policy=Subdomain
+```
--- a/hybrid-usecase-oidc/Jenkinsfile
+++ b/hybrid-usecase-oidc/Jenkinsfile
@ -14,8 +14,8 @@ node() {

  stage("Prepare") {
    service = toolbox.prepareThreescaleService(
-        openapi: [filename: "testcase-03/swagger.json"],
-        environment: [ baseSystemName: toolbox.generateRandomBaseSystemName(),
+        openapi: [filename: "hybrid-usecase-oidc/swagger.json"],
+        environment: [ baseSystemName: "hybrid_usecase_oidc",
                       publicBasePath: "/v1",
                       publicStagingWildcardDomain: params.PUBLIC_STAGING_WILDCARD_DOMAIN,
                       publicProductionWildcardDomain: params.PUBLIC_PRODUCTION_WILDCARD_DOMAIN,
--- a/hybrid-usecase-oidc/README.md
+++ b/hybrid-usecase-oidc/README.md
@ -0,0 +1,50 @@
+# Usecase "Hybrid - OIDC": Deploy an API secured with OpenID Connect on self-managed APIcast and 3scale on-premises
+
+In this usecase, a [Jenkins pipeline](Jenkinsfile) will deploy an API described by an [OpenAPI Specification file](swagger.json) on a 3scale SaaS instance with self-managed APIcast and on a 3scale on-prem instance. The API is secured using OpenID Connect as requested in the OAS.
+
+## Pre-requisites
+
+Make sure you completed the [SETUP guide](../SETUP.md).
+
+## Installation
+
+Use the [provided OpenShift template](setup.yaml) to install the Jenkins pipeline configured to target 3scale SaaS:
+
+```sh
+oc process -f hybrid-usecase-oidc/setup.yaml \
+           -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="$APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN" \
+           -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN="$APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN" \
+           -p OIDC_ISSUER_ENDPOINT="https://$CLIENT_ID:$CLIENT_SECRET@$SSO_HOSTNAME/auth/realms/$REALM" \
+           -p NAMESPACE="$TOOLBOX_NAMESPACE" |oc create -f -
+```
+
+Use the [provided OpenShift template](setup.yaml) to install the Jenkins pipeline configured to target 3scale on-prem:
+
+```sh
+oc process -f hybrid-usecase-oidc/setup.yaml \
+           -p DEVELOPER_ACCOUNT_ID="$ONPREM_DEVELOPER_ACCOUNT_ID" \
+           -p PRIVATE_BASE_URL="http://$BEER_CATALOG_HOSTNAME" \
+           -p TARGET_INSTANCE=3scale-onprem \
+           -p PUBLIC_STAGING_WILDCARD_DOMAIN="$APICAST_ONPREM_STAGING_WILDCARD_DOMAIN" \
+           -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN="$APICAST_ONPREM_PRODUCTION_WILDCARD_DOMAIN" \
+           -p OIDC_ISSUER_ENDPOINT="https://$CLIENT_ID:$CLIENT_SECRET@$SSO_HOSTNAME/auth/realms/$REALM" \
+           -p DISABLE_TLS_VALIDATION=yes \
+           -p NAMESPACE="$TOOLBOX_NAMESPACE" |oc create -f -
+```
+
+## Deployment
+
+Deploy the API to 3scale SaaS:
+
+```sh
+oc start-build hybrid-usecase-oidc-3scale-saas
+```
+
+Deploy the API to 3scale on-prem:
+
+```sh
+oc start-build hybrid-usecase-oidc-3scale-onprem
+```
--- a/hybrid-usecase-oidc/setup.yaml
+++ b/hybrid-usecase-oidc/setup.yaml
@ -1,12 +1,12 @@
 apiVersion: v1
 kind: Template
 metadata:
-  name: testcase-03
+  name: hybrid-usecase-oidc
 objects:
 - kind: "BuildConfig"
  apiVersion: "v1"
  metadata:
-    name: "testcase-03-${TARGET_INSTANCE}"
+    name: "hybrid-usecase-oidc-${TARGET_INSTANCE}"
    namespace: ${NAMESPACE}
  spec:
    source:
@ -15,7 +15,7 @@ objects:
    strategy:
      type: "JenkinsPipeline"
      jenkinsPipelineStrategy:
-        jenkinsfilePath: testcase-03/Jenkinsfile
+        jenkinsfilePath: hybrid-usecase-oidc/Jenkinsfile
        env:
          - name: SECRET_NAME
            value: ${SECRET_NAME}
@ -43,7 +43,7 @@ parameters:
 - name: TARGET_INSTANCE
  required: true
 - name: GIT_REPO
-  value: https://github.com/nmasse-itix/API-Lifecycle-Mockup.git
+  value: https://github.com/rh-integration/3scale-toolbox-jenkins-samples.git
 - name: PUBLIC_STAGING_WILDCARD_DOMAIN
  required: true
 - name: PUBLIC_PRODUCTION_WILDCARD_DOMAIN
--- a/hybrid-usecase-oidc/swagger.json
+++ b/hybrid-usecase-oidc/swagger.json
--- a/hybrid-usecase-open/Jenkinsfile
+++ b/hybrid-usecase-open/Jenkinsfile
@ -14,8 +14,8 @@ node() {

  stage("Prepare") {
    service = toolbox.prepareThreescaleService(
-        openapi: [filename: "testcase-02/swagger.json"],
-        environment: [ baseSystemName: toolbox.generateRandomBaseSystemName(),
+        openapi: [filename: "hybrid-usecase-open/swagger.json"],
+        environment: [ baseSystemName: "hybrid_usecase_open",
                       privateBaseUrl: params.PRIVATE_BASE_URL,
                       privateBasePath: "/api",
                       publicStagingWildcardDomain: params.PUBLIC_STAGING_WILDCARD_DOMAIN,
--- a/hybrid-usecase-open/README.md
+++ b/hybrid-usecase-open/README.md
@ -0,0 +1,48 @@
+# Usecase "Hybrid - Open": Deploy an API on 3scale SaaS on self-managed APIcast and 3scale on-premises
+
+In this usecase, a [Jenkins pipeline](Jenkinsfile) will deploy an API described by an [OpenAPI Specification file](swagger.json) on a 3scale SaaS instance with self-managed APIcast and on a 3scale on-prem instance. The API is **not secured** as requested in the OAS.
+
+## Pre-requisites
+
+Make sure you completed the [SETUP guide](../SETUP.md).
+
+## Installation
+
+Use the [provided OpenShift template](setup.yaml) to install the Jenkins pipeline configured to target 3scale SaaS:
+
+```sh
+oc process -f hybrid-usecase-open/setup.yaml \
+           -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="$APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN" \
+           -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN="$APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN" \
+           -p NAMESPACE="$TOOLBOX_NAMESPACE" |oc create -f -
+```
+
+Use the [provided OpenShift template](setup.yaml) to install the Jenkins pipeline configured to target 3scale on-prem:
+
+```sh
+oc process -f hybrid-usecase-open/setup.yaml \
+           -p DEVELOPER_ACCOUNT_ID="$ONPREM_DEVELOPER_ACCOUNT_ID" \
+           -p PRIVATE_BASE_URL="http://$BEER_CATALOG_HOSTNAME" \
+           -p TARGET_INSTANCE=3scale-onprem \
+           -p PUBLIC_STAGING_WILDCARD_DOMAIN="$APICAST_ONPREM_STAGING_WILDCARD_DOMAIN" \
+           -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN="$APICAST_ONPREM_PRODUCTION_WILDCARD_DOMAIN" \
+           -p DISABLE_TLS_VALIDATION=yes \
+           -p NAMESPACE="$TOOLBOX_NAMESPACE" |oc create -f -
+```
+
+## Deployment
+
+Deploy the API to 3scale SaaS:
+
+```sh
+oc start-build hybrid-usecase-open-3scale-saas
+```
+
+Deploy the API to 3scale on-prem:
+
+```sh
+oc start-build hybrid-usecase-open-3scale-onprem
+```
--- a/hybrid-usecase-open/setup.yaml
+++ b/hybrid-usecase-open/setup.yaml
@ -1,12 +1,12 @@
 apiVersion: v1
 kind: Template
 metadata:
-  name: testcase-02
+  name: hybrid-usecase-open
 objects:
 - kind: "BuildConfig"
  apiVersion: "v1"
  metadata:
-    name: "testcase-02-${TARGET_INSTANCE}"
+    name: "hybrid-usecase-open-${TARGET_INSTANCE}"
    namespace: ${NAMESPACE}
  spec:
    source:
@ -15,7 +15,7 @@ objects:
    strategy:
      type: "JenkinsPipeline"
      jenkinsPipelineStrategy:
-        jenkinsfilePath: testcase-02/Jenkinsfile
+        jenkinsfilePath: hybrid-usecase-open/Jenkinsfile
        env:
          - name: SECRET_NAME
            value: ${SECRET_NAME}
@ -41,7 +41,7 @@ parameters:
 - name: TARGET_INSTANCE
  required: true
 - name: GIT_REPO
-  value: https://github.com/nmasse-itix/API-Lifecycle-Mockup.git
+  value: https://github.com/rh-integration/3scale-toolbox-jenkins-samples.git
 - name: PUBLIC_STAGING_WILDCARD_DOMAIN
  required: true
 - name: PUBLIC_PRODUCTION_WILDCARD_DOMAIN
--- a/hybrid-usecase-open/swagger.json
+++ b/hybrid-usecase-open/swagger.json
--- a/multi-environment-usecase/Jenkinsfile
+++ b/multi-environment-usecase/Jenkinsfile
@ -15,8 +15,8 @@ node() {
  stage("Deploy API in Dev") {
    // Prepare
    service = toolbox.prepareThreescaleService(
-        openapi: [filename: "testcase-04/swagger.yaml"],
-        environment: [ baseSystemName: "eventapi-04",
+        openapi: [filename: "multi-environment-usecase/swagger.yaml"],
+        environment: [ baseSystemName: "multi_environment_usecase",
                       publicBasePath: "/api/",
                       environmentName: "dev",
                       publicStagingWildcardDomain: params.PUBLIC_STAGING_WILDCARD_DOMAIN != "" ? params.PUBLIC_STAGING_WILDCARD_DOMAIN : null,
@ -66,8 +66,8 @@ node() {
  stage("Deploy API in Test") {
    // Prepare
    service = toolbox.prepareThreescaleService(
-        openapi: [filename: "testcase-04/swagger.yaml"],
-        environment: [ baseSystemName: "eventapi-04",
+        openapi: [filename: "multi-environment-usecase/swagger.yaml"],
+        environment: [ baseSystemName: "multi_environment_usecase",
                       publicBasePath: "/api/",
                       environmentName: "test",
                       publicStagingWildcardDomain: params.PUBLIC_STAGING_WILDCARD_DOMAIN != "" ? params.PUBLIC_STAGING_WILDCARD_DOMAIN : null,
@ -117,8 +117,8 @@ node() {
  stage("Deploy API in Prod") {
    // Prepare
    service = toolbox.prepareThreescaleService(
-        openapi: [filename: "testcase-04/swagger.yaml"],
-        environment: [ baseSystemName: "eventapi-04",
+        openapi: [filename: "multi-environment-usecase/swagger.yaml"],
+        environment: [ baseSystemName: "multi_environment_usecase",
                       publicBasePath: "/api/",
                       environmentName: "prod",
                       publicStagingWildcardDomain: params.PUBLIC_STAGING_WILDCARD_DOMAIN != "" ? params.PUBLIC_STAGING_WILDCARD_DOMAIN : null,
--- a/multi-environment-usecase/README.md
+++ b/multi-environment-usecase/README.md
@ -0,0 +1,26 @@
+# Usecase "Multi-environment": Deploy an API in three environments, all in one tenant
+
+In this usecase, a [Jenkins pipeline](Jenkinsfile) will deploy an API described by an [OpenAPI Specification file](swagger.yaml) on a 3scale SaaS instance, in three environments: `DEV`, `TEST` and `PROD`. The API is secured using API Keys as described in the OAS.
+
+## Pre-requisites
+
+Make sure you completed the [SETUP guide](../SETUP.md).
+
+## Installation
+
+Use the [provided OpenShift template](setup.yaml) to install the Jenkins pipeline:
+
+```sh
+oc process -f multi-environment-usecase/setup.yaml \
+           -p DEVELOPER_ACCOUNT_ID="$SAAS_DEVELOPER_ACCOUNT_ID" \
+           -p PRIVATE_BASE_URL="http://$EVENT_API_HOSTNAME" \
+           -p PUBLIC_STAGING_WILDCARD_DOMAIN="$APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN" \
+           -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN="$APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN" \
+           -p NAMESPACE="$TOOLBOX_NAMESPACE" |oc create -f -
+```
+
+## Deployment
+
+```sh
+oc start-build multi-environment-usecase
+```
--- a/multi-environment-usecase/setup.yaml
+++ b/multi-environment-usecase/setup.yaml
@ -1,12 +1,12 @@
 apiVersion: v1
 kind: Template
 metadata:
-  name: testcase-04
+  name: multi-environment-usecase
 objects:
 - kind: "BuildConfig"
  apiVersion: "v1"
  metadata:
-    name: "testcase-04-${TARGET_INSTANCE}"
+    name: "multi-environment-usecase"
    namespace: ${NAMESPACE}
  spec:
    source:
@ -15,7 +15,7 @@ objects:
    strategy:
      type: "JenkinsPipeline"
      jenkinsPipelineStrategy:
-        jenkinsfilePath: testcase-04/Jenkinsfile
+        jenkinsfilePath: multi-environment-usecase/Jenkinsfile
        env:
          - name: SECRET_NAME
            value: ${SECRET_NAME}
@ -41,7 +41,7 @@ parameters:
 - name: TARGET_INSTANCE
  value: 3scale-saas
 - name: GIT_REPO
-  value: https://github.com/nmasse-itix/API-Lifecycle-Mockup.git
+  value: https://github.com/rh-integration/3scale-toolbox-jenkins-samples.git
 - name: PUBLIC_STAGING_WILDCARD_DOMAIN
  required: false
 - name: PUBLIC_PRODUCTION_WILDCARD_DOMAIN
--- a/multi-environment-usecase/swagger.yaml
+++ b/multi-environment-usecase/swagger.yaml
--- a/saas-usecase-apikey/Jenkinsfile
+++ b/saas-usecase-apikey/Jenkinsfile
@ -14,8 +14,8 @@ node() {

  stage("Prepare") {
    service = toolbox.prepareThreescaleService(
-        openapi: [filename: "testcase-01/swagger.yaml"],
-        environment: [ baseSystemName: toolbox.generateRandomBaseSystemName(),
+        openapi: [filename: "saas-usecase-apikey/swagger.yaml"],
+        environment: [ baseSystemName: "saas_usecase_apikey",
                       privateBaseUrl: params.PRIVATE_BASE_URL ],
        toolbox: [ openshiftProject: params.NAMESPACE,
                   destination: params.TARGET_INSTANCE,
--- a/saas-usecase-apikey/README.md
+++ b/saas-usecase-apikey/README.md
@ -0,0 +1,24 @@
+# Usecase "SaaS - API Key": Deploy a simple API on 3scale SaaS
+
+In this usecase, a [Jenkins pipeline](Jenkinsfile) will deploy an API described by an [OpenAPI Specification file](swagger.yaml) on a 3scale SaaS instance. The API is secured using API Keys as described in the OAS.
+
+## Pre-requisites
+
+Make sure you completed the [SETUP guide](../SETUP.md).
+
+## Installation
+
+Use the [provided OpenShift template](setup.yaml) to install the Jenkins pipeline:
+
+```sh
+oc process -f saas-usecase-apikey/setup.yaml \
+           -p SAAS_DEVELOPER_ACCOUNT_ID="$SAAS_DEVELOPER_ACCOUNT_ID" \
+           -p PRIVATE_BASE_URL="http://$BEER_CATALOG_HOSTNAME" \
+           -p NAMESPACE="$TOOLBOX_NAMESPACE" |oc create -f -
+```
+
+## Deployment
+
+```sh
+oc start-build saas-usecase-apikey
+```
--- a/saas-usecase-apikey/setup.yaml
+++ b/saas-usecase-apikey/setup.yaml
@ -1,12 +1,12 @@
 apiVersion: v1
 kind: Template
 metadata:
-  name: testcase-01
+  name: saas-usecase-apikey
 objects:
 - kind: "BuildConfig"
  apiVersion: "v1"
  metadata:
-    name: "testcase-01"
+    name: "saas-usecase-apikey"
    namespace: ${NAMESPACE}
  spec:
    source:
@ -15,7 +15,7 @@ objects:
    strategy:
      type: "JenkinsPipeline"
      jenkinsPipelineStrategy:
-        jenkinsfilePath: testcase-01/Jenkinsfile
+        jenkinsfilePath: saas-usecase-apikey/Jenkinsfile
        env:
          - name: SECRET_NAME
            value: ${SECRET_NAME}
@ -35,7 +35,7 @@ parameters:
 - name: TARGET_INSTANCE
  value: 3scale-saas
 - name: GIT_REPO
-  value: https://github.com/nmasse-itix/API-Lifecycle-Mockup.git
+  value: https://github.com/rh-integration/3scale-toolbox-jenkins-samples.git
 - name: DEVELOPER_ACCOUNT_ID
  required: true
 - name: PRIVATE_BASE_URL
--- a/saas-usecase-apikey/swagger.yaml
+++ b/saas-usecase-apikey/swagger.yaml
--- a/semver-usecase/Jenkinsfile
+++ b/semver-usecase/Jenkinsfile
@ -37,8 +37,8 @@ node() {
  stage("Deploy API in Dev") {
    // Prepare
    service = toolbox.prepareThreescaleService(
-        openapi: [filename: "testcase-05/" + params.OPENAPI_SPECIFICATION_FILE ],
-        environment: [ baseSystemName: "eventapi-05",
+        openapi: [filename: "semver-usecase/" + params.OPENAPI_SPECIFICATION_FILE ],
+        environment: [ baseSystemName: "semver_usecase",
                       publicBasePath: "/api/",
                       environmentName: "dev",
                       oidcIssuerEndpoint: params.OIDC_ISSUER_ENDPOINT,
@ -79,8 +79,8 @@ node() {
  stage("Deploy API in Test") {
    // Prepare
    service = toolbox.prepareThreescaleService(
-        openapi: [filename: "testcase-05/" + params.OPENAPI_SPECIFICATION_FILE ],
-        environment: [ baseSystemName: "eventapi-05",
+        openapi: [filename: "semver-usecase/" + params.OPENAPI_SPECIFICATION_FILE ],
+        environment: [ baseSystemName: "semver_usecase",
                       publicBasePath: "/api/",
                       environmentName: "test",
                       oidcIssuerEndpoint: params.OIDC_ISSUER_ENDPOINT,
@ -121,8 +121,8 @@ node() {
  stage("Deploy API in Prod") {
    // Prepare
    service = toolbox.prepareThreescaleService(
-        openapi: [filename: "testcase-05/" + params.OPENAPI_SPECIFICATION_FILE ],
-        environment: [ baseSystemName: "eventapi-05",
+        openapi: [filename: "semver-usecase/" + params.OPENAPI_SPECIFICATION_FILE ],
+        environment: [ baseSystemName: "semver_usecase",
                       publicBasePath: "/api/",
                       environmentName: "prod",
                       oidcIssuerEndpoint: params.OIDC_ISSUER_ENDPOINT,
--- a/semver-usecase/README.md
+++ b/semver-usecase/README.md
@ -0,0 +1,52 @@
+# Usecase "Semantic versioning": Deploy four versions of an API in three environments, all in one tenant
+
+In this usecase, a [Jenkins pipeline](Jenkinsfile) will deploy **four versions of an API** on a 3scale SaaS instance, **in three environments**: `DEV`, `TEST` and `PROD`, using semantic versioning.
+
+- The first version (**v0.9**) is not secured and used as a mock to be used by early adopters
+- The second version (**v1.0**) is the first stable **major** version and secured with API Keys
+- The third version (**v1.1**) is the first **minor** release of the 1.x branch and secured with API Keys
+- The last version (**v2.0**) is the second **major** version and secured with OpenID Connect
+
+## Pre-requisites
+
+Make sure you completed the [SETUP guide](../SETUP.md).
+
+## Installation
+
+Use the [provided OpenShift template](setup.yaml) to install the Jenkins pipeline:
+
+```sh
+oc process -f semver-usecase/setup.yaml \
+           -p DEVELOPER_ACCOUNT_ID="$SAAS_DEVELOPER_ACCOUNT_ID" \
+           -p PRIVATE_BASE_URL="http://$EVENT_API_HOSTNAME" \
+           -p PUBLIC_STAGING_WILDCARD_DOMAIN="$APICAST_SELF_MANAGED_STAGING_WILDCARD_DOMAIN" \
+           -p PUBLIC_PRODUCTION_WILDCARD_DOMAIN="$APICAST_SELF_MANAGED_PRODUCTION_WILDCARD_DOMAIN" \
+           -p OIDC_ISSUER_ENDPOINT="https://$CLIENT_ID:$CLIENT_SECRET@$SSO_HOSTNAME/auth/realms/$REALM" \
+           -p NAMESPACE="$TOOLBOX_NAMESPACE" |oc create -f -
+```
+
+## Deployment
+
+Deploy version 0.9:
+
+```sh
+oc start-build semver-usecase-v0.9
+```
+
+Deploy version 1.0:
+
+```sh
+oc start-build semver-usecase-v1.0
+```
+
+Deploy version 1.1:
+
+```sh
+oc start-build semver-usecase-v1.1
+```
+
+Deploy version 2.0:
+
+```sh
+oc start-build semver-usecase-v2.0
+```
--- a/semver-usecase/openapi-spec-v0.9.yaml
+++ b/semver-usecase/openapi-spec-v0.9.yaml
--- a/semver-usecase/openapi-spec-v1.0.yaml
+++ b/semver-usecase/openapi-spec-v1.0.yaml
--- a/semver-usecase/openapi-spec-v1.1.yaml
+++ b/semver-usecase/openapi-spec-v1.1.yaml
--- a/semver-usecase/openapi-spec-v2.0.yaml
+++ b/semver-usecase/openapi-spec-v2.0.yaml
--- a/semver-usecase/setup.yaml
+++ b/semver-usecase/setup.yaml
@ -1,12 +1,12 @@
 apiVersion: v1
 kind: Template
 metadata:
-  name: testcase-05
+  name: semver-usecase
 objects:
 - kind: "BuildConfig"
  apiVersion: "v1"
  metadata:
-    name: "testcase-05-${TARGET_INSTANCE}-v0.9"
+    name: "semver-usecase-v0.9"
    namespace: ${NAMESPACE}
  spec:
    source:
@ -15,7 +15,7 @@ objects:
    strategy:
      type: "JenkinsPipeline"
      jenkinsPipelineStrategy:
-        jenkinsfilePath: testcase-05/Jenkinsfile
+        jenkinsfilePath: semver-usecase/Jenkinsfile
        env:
          - name: SECRET_NAME
            value: ${SECRET_NAME}
@ -40,7 +40,7 @@ objects:
 - kind: "BuildConfig"
  apiVersion: "v1"
  metadata:
-    name: "testcase-05-${TARGET_INSTANCE}-v1.0"
+    name: "semver-usecase-v1.0"
    namespace: ${NAMESPACE}
  spec:
    source:
@ -49,7 +49,7 @@ objects:
    strategy:
      type: "JenkinsPipeline"
      jenkinsPipelineStrategy:
-        jenkinsfilePath: testcase-05/Jenkinsfile
+        jenkinsfilePath: semver-usecase/Jenkinsfile
        env:
          - name: SECRET_NAME
            value: ${SECRET_NAME}
@ -74,7 +74,7 @@ objects:
 - kind: "BuildConfig"
  apiVersion: "v1"
  metadata:
-    name: "testcase-05-${TARGET_INSTANCE}-v1.1"
+    name: "semver-usecase-v1.1"
    namespace: ${NAMESPACE}
  spec:
    source:
@ -83,7 +83,7 @@ objects:
    strategy:
      type: "JenkinsPipeline"
      jenkinsPipelineStrategy:
-        jenkinsfilePath: testcase-05/Jenkinsfile
+        jenkinsfilePath: semver-usecase/Jenkinsfile
        env:
          - name: SECRET_NAME
            value: ${SECRET_NAME}
@ -108,7 +108,7 @@ objects:
 - kind: "BuildConfig"
  apiVersion: "v1"
  metadata:
-    name: "testcase-05-${TARGET_INSTANCE}-v2.0"
+    name: "semver-usecase-v2.0"
    namespace: ${NAMESPACE}
  spec:
    source:
@ -117,7 +117,7 @@ objects:
    strategy:
      type: "JenkinsPipeline"
      jenkinsPipelineStrategy:
-        jenkinsfilePath: testcase-05/Jenkinsfile
+        jenkinsfilePath: semver-usecase/Jenkinsfile
        env:
          - name: SECRET_NAME
            value: ${SECRET_NAME}
@ -147,7 +147,7 @@ parameters:
 - name: TARGET_INSTANCE
  value: 3scale-saas
 - name: GIT_REPO
-  value: https://github.com/nmasse-itix/API-Lifecycle-Mockup.git
+  value: https://github.com/rh-integration/3scale-toolbox-jenkins-samples.git
 - name: PUBLIC_STAGING_WILDCARD_DOMAIN
  required: false
 - name: PUBLIC_PRODUCTION_WILDCARD_DOMAIN