dudash / openshift-microservices

:memo: Example showcasing how to leverage OpenShift and it's runtimes to do microservices
Apache License 2.0
9 stars 21 forks source link

3scale - automate creation of management artifacts for external APIs #6

Open gbengataylor opened 5 years ago

gbengataylor commented 5 years ago

The external APIs for the microservices will be managed via 3scale. It would be helpful to automate the creation of the 3scale management artifacts for the external APIs. 3scale includes a toolbox, https://github.com/3scale/3scale_toolbox, to manage services via the command line.

  1. Manage via OpenAPI spec Using Apicurio, the external APIs can be created and pushed to the git repo.

  2. Manage via a csv

The toolbox can generate the artifacts from the input source. Need to investigate which of these is more manageable and also generates more of the artifacts

Another alternative would be to write a script/playbook that uses the 3scale Management REST API to create all the management artifacts.

gbengataylor commented 5 years ago

install 3scale toolbox https://github.com/3scale/3scale_toolbox#installation. Requires Ruby 2.3 and above

gem install 3scale_toolbox

**If having issues installing 3scale toolbox, run docker run --rm -it quay.io/gbengataylor/3scale-toolbox:latest This will start a container where you can run the 3scale commands

CSV Test

echo "service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type
Movies ,Movies (Biography),GET,/movies/biography/,api_key,movies_biography,metric
Movies ,Movies (Drama),GET,/movies/drama/,api_key,movies_drama,method" >> svc.csv

set access token and 3scale admin URL ACCESS_TOKEN= THREESCALE_ADMIN_URL= For e.g. ACCESS_TOKEN=d5af6b19da8381014f59e79245ae242dd5ea8dfe1a8a6c0e2bc481366fxxxxx THREESCALE_ADMIN_URL=3scale-demo-admin.3scale.net Run the 3scale import 3scale import csv --destination=https://${ACCESS_TOKEN}@${THREESCALE_ADMIN_URL} --file=svc.csv

What gets installed

  1. Service
  2. Metrics (as defined in csv, in this case two including the default hit metric)
  3. methods (as defined in csv - in this case one method)
  4. mapping rules (in this example, 3 for the two GET REST paths plus the root / path)
  5. API security/auth method specified
  6. By default uses the API gateway included with the 3scale install (on-prem or SaaS)

OpenAPI Spec Test

Create your OpenAPI v 2.0 spec. We like Apicurio (https://www.apicur.io/). This can be run locally in a container or OpenShift. There is also a live SaaS version. Note that the toolbox only supports OpenAPI v2 An example can be found here - https://raw.githubusercontent.com/gbengataylor/3scale-toolbox-image/master/svc.yaml

Documentation for this mode can be found here - https://github.com/3scale/3scale_toolbox/blob/master/docs/openapi.md

To import, set access token and 3scale URL ACCESS_TOKEN= THREESCALE_ADMIN_URL= For e.g. ACCESS_TOKEN=d5af6b19da8381014f59e79245ae242dd5ea8dfe1a8a6c0e2bc481366fxxxxx THREESCALE_ADMIN_URL=3scale-demo-admin.3scale.net Run 3scale import 3scale import openapi -d https://${ACCESS_TOKEN}@${THREESCALE_ADMIN_URL} https://raw.githubusercontent.com/gbengataylor/3scale-toolbox-image/master/svc.yaml

What gets installed

  1. Service
  2. 3scale ActiveDoc Documentation associated with the Service (not published)
  3. API security/auth method. In this case it is the default - API KEY. The method can be changed via command line
  4. 2 methods, one for each URL endpoint
  5. the default hit metric
  6. mapping rules. In this case, 2 were created for the 2 REST paths. The root / path not created
  7. By default uses the API gateway included with the 3scale install (on-prem or SaaS)

Comparison

Both imports are similar, however, the OpenAPI spec also includes the ActiveDoc documentation, while the csv is more flexible in defining metrics and methods. For the purposes of this demo, the OpenAPI spec probably serves us better as a the single source of truth

We will still need to

TODO

add OpenAPI specfor this demo spec this repo create scripts to generate 3scale artifacts using the OpenAPI spec Figure out how to update service integration, publish ActiveDocs, and create Applications Plans via the 3scale toolbox or the 3scale Management REST API or using the 3scale API as code operator that was in Dev last fall

dudash commented 5 years ago

Can this automate or have hooks for SSO integration too? Do you think it's more or less complex for newbs to understand than using the non-toolbox way?

I actually build the API for the boards service using Apicurito. And then automate the endpoint creation using swagger-tools and tagging the YAML with x-swagger-router-controller.

That's for the service API on the inside of the gateway.