nicolas
/
rhd-3scale
mirror of https://github.com/nmasse-itix/rhd-3scale.git
1
0
Fork 0
Code Issues Releases Wiki Activity
Browse Source

WiP

master
Nicolas Massé 7 years ago
parent
53f1ed3bff
commit
a2fab5bcf3
4 changed files with 316 additions and 68 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 73
      content/hello-world.md
  2. 12
      content/try-it-out.md
  3. 170
      content/tutorials/admin-portal.md
  4. 129
      content/tutorials/deploy-apicast.md

73
content/hello-world.md
View File

@ -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
A fifteen-minute tutorial that shows how to use the 3scale Admin Portal
to manage your APIs.

12
content/try-it-out.md
View File

@ -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

170
content/tutorials/admin-portal.md
View File

@ -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!**

129
content/tutorials/deploy-apicast.md
View File

@ -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 <<EOF
{
"services": [
{
"id": 1234,
"backend_version": 1,
"proxy": {
"api_backend": "http://127.0.0.1:8081",
"hostname_rewrite": "echo",
"hosts": [ "localhost", "127.0.0.1" ],
"credentials_location": "headers",
"auth_user_key": "api-key",
"policy_chain": [
{ "name": "apicast.policy.apicast" }
],
"proxy_rules": [
{ "http_method": "GET", "pattern": "/", "metric_system_name": "hits", "delta": 1 }
]
}
}
]
}
EOF
```
Run APIcast in standalone mode:
```sh
docker run -it --rm --name apicast -p 8080:8080 -e APICAST_CONFIGURATION_CACHE=0 \
-e APICAST_CONFIGURATION_LOADER=lazy -e APICAST_LOG_LEVEL=info \
-v $PWD/config.json:/etc/apicast-config.json -e THREESCALE_CONFIG_FILE=/etc/apicast-config.json \
registry.redhat.io/3scale-amp24/apicast-gateway
```
Confirm APIcast is working with:
```raw
$ curl -H "api-key: 123456" http://localhost:8080/echo
GET /test HTTP/1.1
X-Real-IP: 172.17.0.1
Host: echo
User-Agent: curl/7.54.0
Accept: */*
api-key: 123456
```
## 3) Protect your APIs with APIcast
Update the configuration file for APIcast:
```json
cat > config.json <<EOF
{
"services": [
{
"id": 1234,
"backend_version": 1,
"proxy": {
"api_backend": "http://echo-api.3scale.net",
"hosts": [ "localhost", "127.0.0.1" ],
"credentials_location": "headers",
"auth_user_key": "api-key",
"policy_chain": [
{ "name": "apicast.policy.apicast" }
],
"proxy_rules": [
{ "http_method": "GET", "pattern": "/", "metric_system_name": "hits", "delta": 1 }
]
}
}
]
}
EOF
```
Confirm it works:
```raw
$ curl http://localhost:8080/test -H "api-key: 123456"
{
"method": "GET",
"path": "/test",
"args": "",
"body": "",
"headers": {
"HTTP_VERSION": "HTTP/1.1",
"HTTP_HOST": "echo-api.3scale.net",
"HTTP_ACCEPT": "*/*",
"HTTP_API_KEY": "123456",
"HTTP_USER_AGENT": "curl/7.54.0",
"HTTP_X_REAL_IP": "172.17.0.1",
"HTTP_X_FORWARDED_FOR": "90.79.1.247, 10.0.101.26",
"HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
"HTTP_X_FORWARDED_PORT": "80",
"HTTP_X_FORWARDED_PROTO": "http",
"HTTP_FORWARDED": "for=10.0.101.26;host=echo-api.3scale.net;proto=http"
},
"uuid": "d94aacc8-6a92-4b44-a5a3-94b05fa7e95b"
}
```
Write Preview
Loading…
Cancel
Save