Chapter 3. Install guide
3.1. OpenShift Login
Log in to the master host machine as the regular user, and use the oc utility to authenticate against OpenShift:
$ oc login -u ocuser --certificate-authority=/etc/origin/master/ca.crt --server=https://apimgmt-master.apimgmt.example.com:8443 Authentication required for https://apimgmt-master.apimgmt.example.com:8443 (openshift) Username: ocuser Password: PASSWORD Login successful. Welcome! See 'oc help' to get started.
3.2. On-premise Installation
Please follow the On-premises Installation Guide to install 3scale API Management Platform (AMP) 2.0 on OpenShift
Create a new project called 3scale-api.
oc new-project 3scale-api --display-name="3scale APM on OpenShift" --description="This project demonstrates the use of 3scale APM on OpenShift"
Next, download amp.yml and proceed with the installation. In the OpenShift environment used for this reference architecture, the wildcard domain is set up as apimgmt.example.com.
oc new-app --file amp.yml --param WILDCARD_DOMAIN=apimgmt.example.com
--> Deploying template "3scale-api/system" for "amp.yml" to project 3scale-api
system
---------
Login on https://3scale-admin.apimgmt.example.com as admin/bptp5gec
* With parameters:
* AMP_RELEASE=2.0.0-CR2-redhat-1
* ADMIN_PASSWORD=bptp5gec # generated
* ADMIN_USERNAME=admin
* APICAST_ACCESS_TOKEN=sjvkpnun # generated
* ADMIN_ACCESS_TOKEN=kc2tdwob1wijaori # generated
* WILDCARD_DOMAIN=apimgmt.example.com
* TENANT_NAME=3scale
* MySQL User=mysql
* MySQL Password=ovixy777 # generated
* MySQL Database Name=system
* MySQL Root password.=hclunkck # generated
* SYSTEM_BACKEND_USERNAME=3scale_api_user
* SYSTEM_BACKEND_PASSWORD=ogboxf8d # generated
* REDIS_IMAGE=rhscl/redis-32-rhel7:3.2-5.7
* MYSQL_IMAGE=rhscl/mysql-56-rhel7:5.6-13.14
* SYSTEM_BACKEND_SHARED_SECRET=sip7ekg4 # generated
* SYSTEM_APP_SECRET_KEY_BASE=b0b2ec645aa60c2d47bebc817dada0dba73ea5183401185e0060728e7e0c4aa52adb72a112cca22568084b502c2212dc78b8e213187dabeb747a0d55c8ec5c87 # generated
* APICAST_MANAGEMENT_API=status
* APICAST_OPENSSL_VERIFY=false
* APICAST_RESPONSE_CODES=true
--> Creating resources ...
persistentvolumeclaim "system-storage" created
persistentvolumeclaim "mysql-storage" created
persistentvolumeclaim "system-redis-storage" created
persistentvolumeclaim "backend-redis-storage" created
deploymentconfig "backend-cron" created
deploymentconfig "backend-redis" created
deploymentconfig "backend-listener" created
service "backend-redis" created
service "backend-listener" created
service "system-provider" created
service "system-developer" created
deploymentconfig "backend-worker" created
service "system-mysql" created
service "system-redis" created
deploymentconfig "system-redis" created
service "system-sphinx" created
deploymentconfig "system-sphinx" created
service "system-memcache" created
deploymentconfig "system-memcache" created
route "system-provider-admin-route" created
route "backend-route" created
route "system-developer-route" created
deploymentconfig "apicast-staging" created
service "apicast-staging" created
deploymentconfig "apicast-production" created
service "apicast-production" created
route "api-apicast-staging-route" created
route "api-apicast-production-route" created
deploymentconfig "system-app" created
deploymentconfig "system-resque" created
deploymentconfig "system-sidekiq" created
deploymentconfig "system-mysql" created
configmap "redis-config" created
configmap "smtp" created
--> Success
Run 'oc status' to view your app.Please record the username (admin) and password, as these will later be used to log in into 3scale API Management Platform Admin Portal.
Below are the commands to reset and clean up, if you ever need to do a re-installation of the 3scale-api project.
oc delete all --all oc delete configmap redis-config smtp oc delete pvc system-storage mysql-storage system-redis-storage backend-redis-storage
3.3. E-Commerce Services
3.3.1. Create Project
Create the new project which will house the E-Commerce Services:
oc new-project ecom-services --display-name="E-Commerce Services Suite" --description="Back-end logic microservice suite"
3.3.2. Template Population
Within the new project, execute the provided YAML template to configure and instantiate the full services suite:
oc new-app -f https://raw.githubusercontent.com/RHsyseng/3scale-apm/master/ecom-svcs/project-template.yaml
3.3.3. Persistence Data Population
Once all services are deployed and running, instantiate the e-commerce data set via a GET request to the gateway service route:
$ curl -i http://ecom.rhmap.example.com/demo/testApi HTTP/1.1 200 OK ...
3.3.4. Set Secret Token
Then use the following command to set the Secret Token for the gateway service.
oc env dc/gateway-service -e GATEWAY_TOKEN_VALUE=Shared_secret_sent_from_proxy_to_API_backend_12345678987654321
3.4. Log in to 3scale AMP Admin Portal
The console URL, username and the generated password are logged during the processing of the application template by OpenShift. Use this information to log in to the 3scale AMP console.
Login on https://3scale-admin.apimgmt.example.com as admin/bptp5gec
3.5. Create new ActiveDocs
ActiveDocs make API documentation user friendly, interactive, intuitive, and clear. With 3scale ActiveDocs, based on the Swagger Framework, developers can explore APIs live, straight from the documentation web pages.
To take advantage of this feature, it is best to set up ActiveDocs before further defining the API. Click on top menu item called API, then select ActiveDocs to bring up the ActiveDocs page. There is one demo service spec, called Echo, already defined.
Click the link to Create a new spec:
After filling out all the required fields and clicking the Update Service button, the exposed services can be viewed and tested on the next preview screen:
Click on each service to reveal details, including the schema and/or model for the request and response, and the newly added user_key, used for 3scale API Management Platform’s authentication.
Use the following values to create three sets of ActiveDocs. For API JSON Spec content, use the corresponding swagger files from the github repository:
Service 1:
Name: Fuse-gateway-internal System Name: Fuse-gateway-internal
Service 2:
Name: Fuse-gateway-partner System Name: Fuse-gateway-partner
Service 3:
Name: Fuse-gateway-public System Name: Fuse-gateway-public
3.6. Configure new APIs
3.6.1. Create new APIs
Used the defined ActiveDocs as references for creating services. Click on the APIs menu, and then click on Create Service.
Figure 3.1. Create Service
Enter Name and System Name, then press the Create Service button. For this reference architecture, the default configuration is valid; keep using APIcast as the gateway choice and API Key (user_key) as the authentication option.
Create three services as follows:
Use the following values:
Service 1:
Name: Fuse-gateway-internal System Name: Fuse-gateway-internal
Service 2:
Name: Fuse-gateway-partner System Name: Fuse-gateway-partner
Service 3:
Name: Fuse-gateway-public System Name: Fuse-gateway-public
3.6.1.1. Add methods
The next step is to add methods for the newly added APIs. Click on the Definition link.
The methods are defined in the Definition page, click on the New method link.
Enter appropriate values for Friendly name and System name.
Based on the Fuse gateway service ActiveDocs, create the following methods for these three APIs:
Fuse-gateway-internal API, no limit, with access to all services:
Fuse-gateway-partner API, limited to only to the product service:
Fuse-gateway-public API, limited to only quries to the product service:
3.6.2. Delete default API
Red Hat 3scale API Management Platform installation configures a default API called echo; delete this default API to make future configuration steps more clear, otherwise all new accounts created will automatically point to the default API’s application plan.
- Click on the APIs menu and then click the API Definition link:
- On the next screen, click the edit link:
- Confirm by clicking the link that says I understand the consequences, proceed to delete 'API' service.
3.6.3. Set up integration
Click on the APIs menu, and then click on Integration for each of the new services.
On the integration screen, click the button to add the base URL.
On this setup page, there are three base URLs:
Staging Public Base URL and Production Public Base URL are two important values that need to be recorded; these two addresses have to be added to the 3scale-api project’s router in order for requests from clients to reach OpenShift’s 3scale API gateway staging and production pod.
po/apicast-production-1-3zv6c 1/1 Running 4 3d po/apicast-staging-1-9kf20 1/1 Running 0 3d
3.6.3.1. Create routes in OpenShift
Use the route option of the oc utility to create all three routes for staging. Setting up the routes for production follows the same pattern.
oc expose service apicast-staging --hostname=fuse-gateway-public-3scale-apicast-staging.apimgmt.example.com --name=fuse-gateway-staging-public-route oc expose service apicast-staging --hostname=fuse-gateway-partner-3scale-apicast-staging.apimgmt.example.com --name=fuse-gateway-staging-partner-route oc expose service apicast-staging --hostname=fuse-gateway-internal-3scale-apicast-staging.apimgmt.example.com --name=fuse-gateway-staging-internal-route
Edit each new route to secure it:
oc edit route/fuse-gateway-staging-public-route oc edit route/fuse-gateway-staging-partner-route oc edit route/fuse-gateway-staging-internal-route
This is done by adding two lines to the spec that defines the TLS requirement:
spec:
host: deploy.example.com
port:
targetPort: gateway
tls: termination: edge
to:
kind: Service
name: apicast-staging
weight: 100
wildcardPolicy: NoneTo avoid creating one route for each service, check out the option to Configure Wildcard Domains. This feature is currently in tech preview and does not have full support yet.
3.6.3.2. Private Base URL
The Private Base URL is the address of the Fuse gateway service. Use CLI commands to get the IP address and port of the OpenShift service:
[czhu@apimgmt-master ~]$ oc projects
You have access to the following projects and can switch between them with 'oc project <projectname>':
* 3scale-api
default
ecom-services
kube-system
lambdaair
management-infra
openshift
openshift-infra
Using project "3scale-api" on server "https://apimgmt-master.apimgmt.example.com:8443".
[czhu@apimgmt-master ~]$ oc get svc -n ecom-services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
.......
gateway-service 172.30.124.155 <none> 8778/TCP,9091/TCP 2d
.......In our reference environment, http://172.30.124.155:9091 is the address of the service and this value can be used as Private Base URL for all three new APIs, since they all point to the same Fuse gateway service.
3.6.3.3. Create Application Plans
Click on the APIs menu, and then click on Create Application Plan for each of the services.
Use the following values to add four plans, including two plans for the Fuse-gateway-internal API:
Name: desktop-plan System Name: desktop-plan
Name: mobile-plan System Name: mobile-plan
One plan for the Fuse-gateway-partner API:
Name: partner-plan System Name: partner-plan
One plan for the Fuse-gateway-public API:
Name: public-plan System Name: public-plan
Also select a Default Plan for APIs. For example, two plans are defined for the Fuse-gateway-internal API. Select desktop-plan as the Default Plan, so that new applications created from this point on, automatically associate with the desktop-plan for this API.
3.6.3.4. Add mapping rules
Next, click the Add a mapping rule link to go to Integration page and add new mapping rules for the methods. This step is quite straight forward; just repeat it for all three APIs.
3.6.3.5. Set up rate limits for public plan
Set up Rate Limits for the public plan, so that anonymous public requests will not overload the infrastructure capacity. Click on Fuse-gateway-public API’s Application Plans link.
Then click on New usage limit for the product-get method and add a Usage limit. For example, set a maximum rate of 5 calls per minute:
3.7. Create new Accounts
Click on the top menu item, titled Developers.
A default developer by the name of John Doe has been created during installation; it is best to remove this developer to avoid future confusion.
Click on the Create link to navigate to the Create new Account page.
With each new user, should an existing API with an application plan exist, the system will create an application to point to them. The created application will select the first available API plan by default, which may not be appropriate, unless a Default Plan is already chosen for the API. Review the corresponding screen and create the needed applications, once the right APIs are defined.
Click on the application name to display detailed information about the application, and make changes.
The API Credentials for this application is also displayed on this page:
Note the associated application plan:
Use below values to create four accounts:
Account 1:
Username: desktop-user Email: desktop-user@test.com Password: password Organization/Group Name: desktop-group
Account 2:
Username: mobile-user Email: mobile-user@test.com Password: password Organization/Group Name: mobile-group
Account 3:
Username: partner-user Email: partner-user@test.com Password: password Organization/Group Name: partner-group
Account 4:
Username: public-user Email: public-user@test.com Password: password Organization/Group Name: public-group
3.7.1. Create Applications using the new APIs
This step is required to create an associated user_key for each API. Click on the top menu item, titled Developers and choose one of the group defined earlier.
Click on Application, then click the Create Application link:
Select the right corresponding application plan and type an application name:
Repeat this step to create the follow applications:
3.8. Finish integration
Finally, click on the top API menu item and from there, go to the Integration section of each defined API. Click to edit APIcast configuration and add two more values.
First, add Shared_secret_sent_from_proxy_to_API_backend_12345678987654321 to Secret Token under AUTHENTICATION SETTINGS. For further explanation of this setting, refer to the next chapter.
Then, add /products?featured=1 to the input field for API test Get request at the bottom of the page. Notice that the curl command will already include the proper user_key at the end of the URL. This is the new application’s user_key.
Press the button to Update & test in staging Environment. If everything is set up properly, the test will go through. The automatically generated curl command can also be used in a shell environment to verify.
[czhu@apimgmt-master ~]$ curl "https://fuse-gateway-service-3scale-apicast-staging.apimgmt.example.com:443/products?featured=1&user_key=032acee45c566dc8b510b0ab7d30be4d"
[{"sku":"5945c1b535c6850001d41aa0","name":"ABC HD32CS5002 32-inch LED TV","description":"HD LED Picture Quality
ConnectShare Movie Wide Color Enhancement Clear Motion Rate 60","length":29.1,"width":3.7,"height":17.5,"weight":17.0,"isFeatured":true,"availability":52,"price":249.99,"image":"TV","keywords":["Electronics","TV"]},........]3.9. Developer Portal setup
The final step is to set up the Developer Portal. The goal is to let users sign up in the developer portal and immediately get access to the APIs, so they can get started using the API interactive documentation (ActiveDocs, based on Swagger spec), with their own application key.
Click on the top menu item, titled Developer Portal, then select Documentation from the left side panel:
Replace the page source with the Documentation content found in the project repository, and save your changes.
Next, click on Homepage in the left side panel.
Replace the page source with the Homepage content found in the project repository, and save your changes.
3.10. Deploy the presentation application
Deploy the Presentation service, which exposes a web tier for the desktop-user to access the application.
Create a new project for this service:
$ oc new-project desktop-project --display-name="Desktop project for Fuse ecom-services" --description="Desktop project for Fuse ecom-services"Next, use OpenShift Source-To-Image (S2I) in this project to deploy the presentation service. The presentation_template.yaml file can be found in the project repository. Note that the SERVICE_ADDRESS is passed in as environment variables, while user_key is referenced as an OpenShift Secret in the template; the value for user_key is passed to the template as a parameter.
$ oc new-app -p USER_KEY_VALUE=9331104b50c0385cc64ebd72a38d4a56 -e SERVICE_ADDRESS=fuse-gateway-internal-3scale-apicast-staging.middleware.ocp.cloud.lab.eng.bos.redhat.com -f https://raw.githubusercontent.com/RHsyseng/3scale-apm/master/template/presentation_template.yaml
Where did the comment section go?
Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.