From a2fab5bcf33af7a449392b88f5e1a50190a9634d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicolas=20Mass=C3=A9?= Date: Fri, 8 Mar 2019 16:25:41 +0100 Subject: [PATCH] WiP --- content/hello-world.md | 73 ++---------- content/try-it-out.md | 12 +- content/tutorials/admin-portal.md | 170 ++++++++++++++++++++++++++++ content/tutorials/deploy-apicast.md | 129 +++++++++++++++++++++ 4 files changed, 316 insertions(+), 68 deletions(-) create mode 100644 content/tutorials/admin-portal.md create mode 100644 content/tutorials/deploy-apicast.md diff --git a/content/hello-world.md b/content/hello-world.md index 3e498c6..c0f3977 100644 --- a/content/hello-world.md +++ b/content/hello-world.md @@ -1,72 +1,13 @@ # Hello, World! -## Pre-requisites: Create a token to access the Red Hat registry +Discover how to use Red Hat 3scale API Management to protect your APIs. -You will need to create a token to be able to fetch APIcast from the Red Hat registry. Go to [access.redhat.com/terms-based-registry](https://access.redhat.com/terms-based-registry/), log in with your developer account (if you have not already done so), and click "New Service Account." +## [Deploy APIcast](../tutorials/deploy-apicast/) -Give the token a name (for the rest of this article, we will use "3scale") and a meaningful description. +A ten-minute tutorial that shows how to deploy APIcast (our API Gateway), +and how to configure it. -Click "Create" and the generated token is displayed. Save the username and the token in a safe place for future reference. +## [Use the 3scale Admin Portal](../tutorials/admin-portal/) -Click the "OpenShift Secret" tab and then "3scale-secret.yaml" to download your token in a format OpenShift will understand. Save it somewhere convenient for later use. - -![Download OpenShift Secret](/hello-world/download-openshift-secret.png) - -Click the "Docker Login" tab and copy the "docker login" command somewhere convenient for later use. - -![Copy/paste the Docker login command](/hello-world/docker-login.png) - -## Deploy APIcast on OpenShift - -To install APIcast, you will need an OpenShift instance. If your company has one, use it. If not, we recommend using [Red Hat Container Development Kit (CDK)/minishift](https://developers.redhat.com/products/cdk/hello-world/). Minishift is an OpenShift installation targeted at developers that runs on your laptop. If you need to install CDK/minishift, see [these instructions](https://developers.redhat.com/products/cdk/hello-world/). - -Spin up a minishift instance: - -```raw -$ minishift start -``` - -Create a new project for your APIcast trial: - -```raw -$ oc new-project 3scale -``` - -Inject the token you downloaded in the "Pre-requisites" section in your OpenShift project, as a secret: - -```raw -$ oc create -f ~/Downloads/*_3scale-secret.yaml -``` - -Find the name of your secret: - -```raw -$ oc get secret -NAME TYPE DATA AGE -10072637-3scale-pull-secret kubernetes.io/dockerconfigjson 1 3m -``` - -If you named your token "3scale" as suggested above, your secret should end with "-3scale-pull-secret." In this example, my secret is named "10072637-3scale-pull-secret." - -Link your token with the default service account so that any pod in this project can use it (do not forget to change "10072637-sso-pull-secret" to your token name): - -```raw -$ oc secrets link default 10072637-sso-pull-secret --for=pull -``` - -Import the APIcast ImageStream: -```raw -$ oc create -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/2.4.0.GA/3scale-image-streams.yml -``` - -Import the OpenShift template: - -```raw -$ oc create -f https://raw.githubusercontent.com/3scale/3scale-amp-openshift-templates/2.4.0.GA/apicast-gateway/apicast.yml -``` - - - -### Deploy APIcast on Docker - -TODO \ No newline at end of file +A fifteen-minute tutorial that shows how to use the 3scale Admin Portal +to manage your APIs. diff --git a/content/try-it-out.md b/content/try-it-out.md index 6466baa..6399c91 100644 --- a/content/try-it-out.md +++ b/content/try-it-out.md @@ -1,3 +1,11 @@ -# Try it out! +# Try 3scale for Development Use + +APIcast is packaged as container image that you can fetch from the official +Red Hat registry. + +**[See APIcast on registry.redhat.io](https://access.redhat.com/containers/#/registry.access.redhat.com/3scale-amp24/apicast-gateway)** + +The 3scale Admin Portal can be tried out directly from our SaaS by requesting a free trial account. + +**[Request a trial account on 3scale.net (it's free)](https://www.3scale.net/signup)** -TODO \ No newline at end of file diff --git a/content/tutorials/admin-portal.md b/content/tutorials/admin-portal.md new file mode 100644 index 0000000..0ffd534 --- /dev/null +++ b/content/tutorials/admin-portal.md @@ -0,0 +1,170 @@ +# Use the 3scale Admin Portal to configure and manage APIcast + +In this tutorial, you will connect your APIcast instance to your 3scale Admin +Portal and expose your first API. + +As a pre-requisite, you need to [request a trial account on 3scale.net (it's free)](https://www.3scale.net/signup)! + +## 1) Generate an Access Token for APIcast + +Connect to the 3scale Admin Portal for which you signed up earlier. You can find your Admin Portal URL in the confirmation mail sent during signup. It looks like `https://TENANT-admin.3scale.net` where `TENANT` is the name you chose during signup. + +- Click on the gear in the top right corner, go to **Personal** > **Tokens** and click **Add Access Token**. + +*TODO Screenshot* + +- Fill-in the name with `APIcast` +- Check the **Account Management API** +- Leave the default permission as **Read Only** +- Click **Create Access Token** + +*TODO Screenshot* + +- Copy the generated Access Token and store it a safe place! You will need it in the next part. +- Click **I have copied the token** + +*TODO Screenshot* + +## 2) Connect APIcast to the 3scale Admin Portal + +Start APIcast in verbose mode to check if the connection between APIcast and the 3scale Admin Portal is established: + +```sh +docker run -it --rm --name apicast -p 8080:8080 -e APICAST_CONFIGURATION_CACHE=300 \ + -e APICAST_CONFIGURATION_LOADER=boot -e THREESCALE_DEPLOYMENT_ENV=staging \ + -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@TENANT-admin.3scale.net \ + -e APICAST_LOG_LEVEL=info -e APICAST_RESPONSE_CODES=true \ + registry.redhat.io/3scale-amp24/apicast-gateway +``` + +You will need to replace `ACCESS_TOKEN` with the Access Token you generated +in the previous exercise and `TENANT` with the name of your tenant so that it +matches your 3scale Admin Portal URL. + +In the last lines of the output, you should have something similar to: + +```raw +2019/03/07 14:27:38 [info] 36#36: *26 [lua] configuration_store.lua:124: store(): added service 123456 configuration with hosts: api-789.production.gw.apicast.io, api-789.staging.gw.apicast.io ttl: 300, context: ngx.timer +``` + +If instead, you have such error message, double check the Access Token and Tenant are set correctly: + +```raw +2019/03/07 14:21:00 [warn] 31#31: *2 [lua] remote_v2.lua:170: call(): failed to get list of services: invalid status: 403 (Forbidden) url: https://TENANT-admin.3scale.net/admin/api/services.json, context: ngx.timer +``` + +Hit `Ctrl-C` to stop APIcast. + +You can now deploy the set of two APIcast instances that is required to use +3scale: + +- one staging APIcast instance +- one production APIcast instance + +Deploy a staging APIcast instance on port 8081: + +```sh +docker run --rm -d --name apicast-staging -p 8081:8080 -e APICAST_CONFIGURATION_CACHE=0 \ + -e APICAST_CONFIGURATION_LOADER=lazy -e THREESCALE_DEPLOYMENT_ENV=staging \ + -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@TENANT-admin.3scale.net \ + -e APICAST_LOG_LEVEL=info -e APICAST_RESPONSE_CODES=true \ + registry.redhat.io/3scale-amp24/apicast-gateway +``` + +Deploy a production APIcast instance on port 8082: + +```sh +docker run --rm -d --name apicast-production -p 8082:8080 -e APICAST_CONFIGURATION_CACHE=60 \ + -e APICAST_CONFIGURATION_LOADER=boot -e THREESCALE_DEPLOYMENT_ENV=production \ + -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS_TOKEN@TENANT-admin.3scale.net \ + -e APICAST_LOG_LEVEL=warn -e APICAST_RESPONSE_CODES=true \ + registry.redhat.io/3scale-amp24/apicast-gateway +``` + +## 3) Deploy your first API + +Connect to the 3scale Admin Portal for which you signed up earlier. You can find your Admin Portal URL in the confirmation mail sent during signup. It looks like `https://TENANT-admin.3scale.net` where `TENANT` is the name you chose during signup. + +- In the dropdown list on the top side, select **Echo API** +- Go to **Integration** > **Configuration** +- Click **edit integration settings** + +*TODO Screenshot* + +- Select **APIcast self-managed** +- Scroll to the bottom and click **Update service** + +*TODO Screenshot* + +- Click **edit APIcast configuration** + +*TODO Screenshot* + +- Leave the Private Base URL to `http://echo-api.3scale.net:80` +- In the **Staging Public Base URL** field, type `http://localhost:8081` +- In the **Production Public Base URL** field, type `http://localhost:8082` + +*TODO Screenshot* + +- Scroll down and click **Update the Staging Environment** + +*TODO Screenshot* + +- Copy the `curl` command and paste it in a terminal (your `user_key` will be different from mine, this is normal): + +```raw +$ curl "http://localhost:8081/echo?user_key=987654321" +{ + "method": "GET", + "path": "/echo", + "args": "user_key=987654321", + "body": "", + "headers": { + "HTTP_VERSION": "HTTP/1.1", + "HTTP_HOST": "echo-api.3scale.net", + "HTTP_ACCEPT": "*/*", + "HTTP_USER_AGENT": "curl/7.54.0", + "HTTP_X_3SCALE_PROXY_SECRET_TOKEN": "Shared_secret_sent_from_proxy_to_API_backend_123456", + "HTTP_X_REAL_IP": "172.17.0.1", + "HTTP_X_FORWARDED_FOR": "10.0.103.54", + "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net", + "HTTP_X_FORWARDED_PORT": "80", + "HTTP_X_FORWARDED_PROTO": "http", + "HTTP_FORWARDED": "for=10.0.103.54;host=echo-api.3scale.net;proto=http" + }, + "uuid": "04b826af-4f69-4140-94ae-42c7181853be" +} +``` + +- Go back to **Integration** > **Configuration** +- Click on **Promote v.X to Production** + +Wait one minute for the production APIcast to pickup changes in its +configuration and run again your `curl` command on port 8082 this time. +Your `user_key` will be different from mine, this is normal. + +```raw +$ curl "http://localhost:8082/echo?user_key=987654321" +{ + "method": "GET", + "path": "/echo", + "args": "user_key=987654321", + "body": "", + "headers": { + "HTTP_VERSION": "HTTP/1.1", + "HTTP_HOST": "echo-api.3scale.net", + "HTTP_ACCEPT": "*/*", + "HTTP_USER_AGENT": "curl/7.54.0", + "HTTP_X_3SCALE_PROXY_SECRET_TOKEN": "Shared_secret_sent_from_proxy_to_API_backend_123456", + "HTTP_X_REAL_IP": "172.17.0.1", + "HTTP_X_FORWARDED_FOR": "10.0.103.54", + "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net", + "HTTP_X_FORWARDED_PORT": "80", + "HTTP_X_FORWARDED_PROTO": "http", + "HTTP_FORWARDED": "for=10.0.103.54;host=echo-api.3scale.net;proto=http" + }, + "uuid": "04b826af-4f69-4140-94ae-42c7181853be" +} +``` + +**Congratulation, you just secured your first API with 3scale!** diff --git a/content/tutorials/deploy-apicast.md b/content/tutorials/deploy-apicast.md new file mode 100644 index 0000000..753455a --- /dev/null +++ b/content/tutorials/deploy-apicast.md @@ -0,0 +1,129 @@ +# Deploy APIcast + +## 1) Get a token to access the Red Hat Registry + +You will need to create a token to be able to fetch APIcast from the Red Hat registry. Go to [access.redhat.com/terms-based-registry](https://access.redhat.com/terms-based-registry/), log in with your developer account (if you have not already done so), and click "New Service Account." + +Give the token a name (for the rest of this article, we will use "3scale") and a meaningful description. + +Click "Create" and the generated token is displayed. Save the username and the token in a safe place for future reference. + +Click the "Docker Login" tab and copy the "docker login" command somewhere convenient for later use. + +![Copy/paste the Docker login command](/hello-world/docker-login.png) + +Paste it in a terminal. This will log you in so that you can docker can pull the APIcast image. + +If everything went fine, you should see something like this: + +```raw +$ docker login -u='123456|3scale' -p=[REDACTED] registry.redhat.io +WARNING! Using --password via the CLI is insecure. Use --password-stdin. +Login Succeeded +``` + +## 2) Deploy APIcast as a standalone API Gateway + +Create a configuration file for APIcast: + +```json +cat > config.json < config.json <