Kong Academyを日本語でお届け！#4

THE CLOUD CONNECTIVITY COMPANY
1
© Kong Inc.
THE CLOUD
CONNECTIVITY COMPANY
Kong Academyを日本語でお届け！#4
KPLL-102 - Kong Developer Portal
施文翰(Wenhan Shi) – Solutions Engineer
July 28th, 2022

View Slide

2
© Kong Inc. 2
Who am I
施文翰(シブンカン) Wenhan Shi
• 日立製作所 - Linux kernel module development/Support
• Red Hat K.K. - GlusterFS/OpenShift Support
• Canonical Japan K.K. - Ubuntu/OpenStack/Kubernetes Support
• Rancher Lab/SUSE - Rancher Support
• Kong Inc. - Solutions Engineer
@shi_wenhan
[email protected]

View Slide

3
© Kong Inc. 3
本セッションについて
Kong Academy KPLL-102 Kong Developer Portal をベースに日本語でお届けします
- https://education.konghq.com/
- 全てレベル100、無償でオンライン受講可能（自習形式）
- レベル200以上は有償で提供（サブスクリプション）
- 講師によるトレーニングを実施
- Kong認定証を授与

View Slide

4
© Kong Inc.
● Deployment Kong for Dev portal
● Enable Kong Dev portal
● Customization
● Publish Specs to Portal
● Developer Experience
● DevOps Portal Management
Agenda

View Slide

5
© Kong Inc. 5
Kong Developer Portal
https://docs.konghq.com/gateway/latest/install-and-run/

View Slide

6
© Kong Inc. 6
Kong Gateway Deployment
For Dev portal

View Slide

7
© Kong Inc. 7
Install Kong Gateway
https://docs.konghq.com/gateway/latest/install-and-run/

View Slide

8
© Kong Inc. 8
Need Database for Dev portal
DB Less DB
Conﬁg store Declarative conﬁguration Database
mode Available for OSS, Enterprise
Pros Easy and quick Fully customizable
Component
s
Proxy Yes Yes
Admin API No Yes
Manager (GUI) No Yes
Dev Portal No Yes
Vitals No Yes

View Slide

9
© Kong Inc. 9
Deploying Kong gateway on VM
Install the package
For RHEL system, import the repo and install the package via yum
Setup Database License deploy
Start Kong Gateway
curl $(rpm --eval "https://download.konghq.com/gateway-2.x-rhel-%{rhel}/config.repo") | sudo tee　
/etc/yum.repos.d/kong.repo
sudo yum install kong-enterprise-edition-2.8.1.2

View Slide

10
© Kong Inc. 10
Install the package
Create User and Database for Kong Gateway
Setup kong.conf to let Kong Gateway can connect to your database.
A example ﬁle is at /etc/kong/kong.conf.default
https://docs.konghq.com/gateway/2.8.x/reference/conﬁguration/#datastore-section
Initialize the database by running the Kong Gateway migrations
Setup Database Start Kong Gateway License deploy
CREATE USER kong WITH PASSWORD 'super_secret';
CREATE DATABASE kong OWNER kong;
kong migrations bootstrap -c {PATH_TO_KONG.CONF_FILE}

View Slide

11
© Kong Inc. 11
Install the package
Create User and Database for Kong Gateway
Setup kong.conf to let Kong Gateway can connect to your database.
A example ﬁle is at /etc/kong/kong.conf.default
https://docs.konghq.com/gateway/2.8.x/reference/conﬁguration/#datastore-section
Initialize the database by running the Kong Gateway migrations
CREATE USER kong WITH PASSWORD 'super_secret';
CREATE DATABASE kong OWNER kong;
kong migrations bootstrap -c {PATH_TO_KONG.CONF_FILE}

View Slide

12
© Kong Inc. 12
Deploying Kong on VM
Install the package
Start Kong Gateway with the conﬁg ﬁle.
You should have a 200 response from port 8001
kong start -c {PATH_TO_KONG.CONF_FILE}
curl -i http://localhost:8001

View Slide

13
© Kong Inc. 13
Deploying Kong on VM
Install the package
Apply the license using the Admin API.
curl -i -X POST http://localhost:8001/licenses \
-d payload='{"license":{"payload":{"admin_seats":"1","customer":"Example Company,
Inc","dataplanes":"1","license_creation_date":"2017-07-20","license_expiration_date":"2017-07-20","license_k
ey":"00141000017ODj3AAG_a1V41000004wT0OEAU","product_subscription":"Konnect
Enterprise","support_plan":"None"},"signature":"6985968131533a967fcc721244a979948b1066967f1e9cd65dbd8eeabe06
0fc32d894a2945f5e4a03c1cd2198c74e058ac63d28b045c2f1fcec95877bd790e1b","version":"1"}}'

View Slide

14
© Kong Inc. 14
Overview
EC2 node
Kong Gateway
Admin API
8001
Dev portal
8003
Kong Proxy
8000

View Slide

15
© Kong Inc. 15
Enable Kong Dev portal

View Slide

16
© Kong Inc. 16
Dev portal is NOT enable by default.

View Slide

17
© Kong Inc.
- Set “portal = on” in kong conﬁguration and restart Kong Gateway service.
17
Step 1. Enable Dev Portal in the Kong Conﬁguration

View Slide

18
© Kong Inc. 18
Step 2. Enable Dev Portal in Kong Manager
Click on Developer
Portals in the Kong
Manager
Click on Set up
Dev Portal
Click on Enable
Developer
Portal
Developer
Portal
Dashboard
Launch
Developer
Portal

View Slide

19
© Kong Inc. 19
Click on Developer
Portals in the Kong
Manager
Click on Set up
Dev Portal
Click on Enable
Developer
Portal
Developer
Portal
Dashboard
Launch
Developer
Portal

View Slide

20
© Kong Inc. 20
Click on Developer
Portals in the Kong
Manager
Click on Set up
Dev Portal
Click on Enable
Developer
Portal
Developer
Portal
Dashboard
Launch
Developer
Portal

View Slide

21
© Kong Inc. 21
Click on Developer
Portals in the Kong
Manager
Click on Set up
Dev Portal
Click on Enable
Developer
Portal
Developer
Portal
Dashboard
Launch
Developer
Portal

View Slide

22
© Kong Inc. 22
Click on Developer
Portals in the Kong
Manager
Click on Set up
Dev Portal
Click on Enable
Developer
Portal
Developer
Portal
Dashboard
Launch
Developer
Portal

View Slide

23
© Kong Inc. 23
Step 3. Enable Basic Authentication (Optional)
- In Kong Manager > Dev Portal > Settings > Authentication,
select Basic Authentication under the Authentication Plugin
- This will require users to register and login for using Dev portal

View Slide

24
© Kong Inc. 24
Step 4. Enable Auto Approve Access (Optional)
- With this setting, a developer will automatically be marked as "approved" after completing
registration.

View Slide

25
© Kong Inc. 25
Customization

View Slide

26
© Kong Inc. 26
Customize Logo and Styles
- Conﬁrm and update theme In Kong Manager > Dev Portal > Appearance

View Slide

27
© Kong Inc. 27
Customize Web Content
- Click Kong Manager > Dev Portal > Editor to enter editor mode

View Slide

28
© Kong Inc. 28
- Update Title of index page

View Slide

29
© Kong Inc. 29
- Index page get updated.

View Slide

30
© Kong Inc. 30
- Modify footer

View Slide

31
© Kong Inc. 31
- Modify ﬁlter

View Slide

32
© Kong Inc. 32
- Modify Client

View Slide

33
© Kong Inc. 33
Publish Specs to Portal

View Slide

34
© Kong Inc. 34
Publish Open API speciﬁcation from Kong Manager
- 3 specs are already present by default

View Slide

35
© Kong Inc. 35
- Create a new ﬁle by clicking the New File option, and select spec in the File Type

View Slide

36
© Kong Inc. 36
- Copy the API Speciﬁcation to the stock-0.1.yaml ﬁle, and click “Save Changes”

View Slide

37
© Kong Inc. 37
- The Stock API is available in the developer portal

View Slide

38
© Kong Inc. 38
Add Tags in Open API Spec to Categorize and Filter
- Tags and description can be used to ﬁlter the speciﬁcations.

View Slide

39
© Kong Inc. 39
Add Tags in Open API Spec to Categorize and Filter
-

View Slide

40
© Kong Inc. 40
Using RBAC to control access to API content
- Kong's Developer Portal can setup Role Based Access Control (RBAC) to control access to
published content.
- In this section, we will setup two roles,
- internal developers
- external developers
- Either Kong Manager or the Admin API can be used to manage Developer and Roles.

View Slide

41
© Kong Inc. 41
- Create 2 roles
❯ http post :31001/developers/roles
name=Internal-Developers Kong-Admin-Token:kong
HTTP/1.1 201 Created
…
{
"comment": null,
"created_at": 1658726280,
"id": "611498b8-d51f-4234-902a-4c4940e4d113",
"name": "Internal-Developers",
"permissions": {}
}
❯ http post :31001/developers/roles
name=External-Developers Kong-Admin-Token:kong
HTTP/1.1 201 Created
…
{
"comment": null,
"created_at": 1658726281,
"id": "79d23b0c-2573-45f0-a33a-cc3805d36b69",
"name": "External-Developers",
"permissions": {}
}

View Slide

42
© Kong Inc. 42
- Create 2 Developers
$ http post :31004/register
Content-Type:'application/json' \
[email protected] \
password=Kong123 meta="{\"full_name\":\"Internal
Developer\"}" Kong-Admin-Token:kong
HTTP/1.1 200 OK
…
Vary: Origin{
"developer": {
"consumer": {
"id": "c186489d-94fa-41e7-a65d-514294ba2765"
},
"created_at": 1590118499,
"email": "[email protected]",
"id": "4fe3ee80-c114-4191-b075-eada26b2d2e4",
"meta": "{\"full_name\":\"Internal Developer\"}",
"status": 0,
"updated_at": 1590118499
}
}
$ http post :31004/register
Content-Type:'application/json' \
[email protected] \
password=Kong123 meta="{\"full_name\":\"External
Developer\"}" Kong-Admin-Token:kong
HTTP/1.1 200 OK
…
Vary: Origin{
"developer": {
"consumer": {
"id": "3e2807c1-1a16-4af6-a69c-a5bee5e34b73"
},
"created_at": 1590118509,
"id": "5052f5b1-fa6d-40ba-a38c-bb621c07f3de",
"meta": "{\"full_name\":\"External Developer\"}",
"status": 0,
"updated_at": 1590118509
}
}

View Slide

43
© Kong Inc. 43
- Assign Roles to Developer
$ http patch
:31001/developers/[email protected]
roles:='["Internal-Developers"]' Kong-Admin-Token:kong
HTTP/1.1 200 OK
...
{
"developer": {
"consumer": {
"id": "d6b9c444-1398-497a-9068-2bb724177f68"
},
"created_at": 1587650139,
"id": "a6fe186d-bf16-41e8-b431-b53b61a316e3",
"meta": "{\"full_name\":\"Internal Developer\"}",
"rbac_user": {
"id": "3f83d6cb-c338-4855-be78-364d6906861a"
},
"roles": [
"Internal-Developers"
],
"status": 0,
"updated_at": 1587650696
}
}
$ http patch
:31001/developers/[email protected]
roles:='["External-Developers"]' Kong-Admin-Token:kong
HTTP/1.1 200 OK
...
{
"developer": {
"consumer": {
"id": "8e064119-538e-4149-85c5-48875b4f6814"
},
"created_at": 1587650218,
"id": "39c6af17-3514-4286-a14f-9a88abfcf5ee",
"meta": "{\"full_name\":\"External Developer\"}",
"rbac_user": {
"id": "57517f51-2a07-4698-b876-864ab874f143"
},
"roles": [
"External-Developers"
],
"status": 0,
"updated_at": 1587650722
}
}

View Slide

44
© Kong Inc. 44
- Conﬁg Developer Permissions, by click Permission under Dev Portal and click Content tab

View Slide

45
© Kong Inc. 45
- Under specs, ﬁnd petstore and select Internal-Developers role then update
- This will remove the default permission and only grants the Internal-Developers role.

View Slide

46
© Kong Inc. 46
- Now petstore API can only be seen when login as an internal user.

View Slide

47
© Kong Inc. 47
Publish Additional content (new header to a new page.)
- Create the header
- Under theme, create a new ﬁle base/layouts/custom_pg_layout.html.And add the
following contents to it.
{% layout = "layouts/_page.html" %}
{-content-}

{* page.body *}

{-content-}

View Slide

48
© Kong Inc. 48
- Create the new Products page
- Under content, create a new ﬁle products/index.md. And add the following contents.
---
layout: custom_pg_layout.html
---
Our API Products
Here are some of the API Products we offer

Finance Package
eCommerce Package
Utilities Package

Paid
Paid
Free

Monthly plan
Monthly plan
NA

Learn more
Learn more
Learn more

View Slide

49
© Kong Inc. 49
- Link the Products page and the header menu.
- Go to /base/partials/menu.html under themes. And add below item inside
- API Products

View Slide

50
© Kong Inc. 50
- Now you should see a public page for API Products added to menu and when you click on it, you should
see the products page:

View Slide

51
© Kong Inc. 51
Developer Experience

View Slide

52
© Kong Inc. 52
Test an API in the dev portal page
- Click Petstore API and Select “/pet/ﬁndByStatus” GET method

View Slide

56
© Kong Inc. 56
- Add a new code snippets Java
- Kong can provide code snippet
for over ten languages.
- Go to
base/layouts/system/spec-rend
erer.html under Themes
- Replace the theme(Line 64),
- This is changing the default on
which doesn’t specify any
languages.

View Slide

58
© Kong Inc. 58
Application Registration
- In this section we will setup services for registration by Developers through the
Developer Portal.
- This allows Developers to obtain unique credentials to access the registered APIs.
- Create a service, route, and an “application-registration” plugin.
# Setup Stock API service
http :31001/services name=Stock-Service url='http://httpbin.org/anything' Kong-Admin-Token:kong
# Setup route and application-registration plugin
http -f :31001/services/Stock-Service/routes name='getStockQuote' paths="/stock/historical"
Kong-Admin-Token:kong
# Enable Application Plugin for service
http -f :31001/services/Stock-Service/plugins name=application-registration \
config.display_name=Stock-API config.auto_approve=true Kong-Admin-Token:kong
# Enable Oauth2 for service
http -f :31001/services/Stock-Service/plugins name=oauth2 config.enable_client_credentials=true
Kong-Admin-Token:kong

View Slide

60
© Kong Inc. 60
- Create an Application as a Developer
- Login to Dev Portal as [email protected]/Kong123
- Click My Apps and Click + New Application.
- Enter the following details for the Application.
- Name: Finance Mobile App
- Redirect URI: http://test.com/redirect
- Description: Finance Mobile App

View Slide

61
© Kong Inc. 61
- Create an Application as a Developer
- Click Create and you should see a conﬁrmation as shown below:

View Slide

62
© Kong Inc. 62
- Activate the Stock API Service for the Application
- Then the stock-API service can be used in this Application.

View Slide

63
© Kong Inc. 63
- Get the OAuth2 access token by the “client_id” and “client_secret”. We will then use the
access token to test the Stock API.

View Slide

64
© Kong Inc. 64
- Post a request to the secured Kong proxy as shown below
- Then the stock-API service can be used in this Application.
$ export CLIENT_ID='ILljp6dBmo5IBQYEzt2lXG6QnTb9SnRw'
$ export CLIENT_SECRET='lTptRAIPp2bwFKorUVSfTRvQFSQ7ILSt'
$ http --verify=no POST
"https://localhost:31443/stock/historical/oauth2/token?grant_type=client_credentials&client_id=$CLI
ENT_ID&client_secret=$CLIENT_SECRET" content-type:multipart/form-data Kong-Admin-Token:kong
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 91
Content-Type: application/json; charset=utf-8
Date: Thu, 28 Jul 2022 05:29:14 GMT
Server: kong/2.8.1.2-enterprise-edition
X-Kong-Response-Latency: 129
cache-control: no-store
pragma: no-cache
{
"access_token": "q5K4VKWoNsUj5zekLwgq4SCKPl3psqfl",
"expires_in": 7200,
"token_type": "bearer"
}

View Slide

65
© Kong Inc. 65
- For simplicity we will get another access token, and save it in a variable:
❯ ACCESS_TOKEN=`http --verify=no POST
"https://localhost:31443/stock/historical/oauth2/token?grant_type=client_credentials&client_id=$CLI
ENT_ID&client_secret=$CLIENT_SECRET" content-type:multipart/form-data Kong-Admin-Token:kong | jq -r
.access_token`
❯ echo $ACCESS_TOKEN
bRNFmdH1ldL99IAlPg4Cy2bLTmKWL9iS

View Slide

66
© Kong Inc. 66
- Call the Stock API with the access token
❯ http --verify=no GET https://localhost:31443/stock/historical\?tickers\=AAPL "authorization:Bearer $ACCESS_TOKEN"
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 911
Content-Type: application/json
Date: Thu, 28 Jul 2022 05:36:23 GMT
Server: gunicorn/19.9.0
Via: kong/2.8.1.2-enterprise-edition
X-Kong-Proxy-Latency: 33
X-Kong-Upstream-Latency: 552
{
"args": {
"tickers": "AAPL"
},
"data": "",
"files": {},
"form": {},
"headers": {
"Accept": "*/*",
"Accept-Encoding": "gzip, deflate",
…

View Slide

67
© Kong Inc. 67
Configure Mocking Plugin
- Mocking allows a sample response from a spec to be returned when an API is queried.
This is helpful to Developers when interact and confirm responses from APIs before the
API was built.
- Setup Mocking plugin on the route and specify the stock specification(stock-0.1.yaml).
http -f :31001/routes/getStockQuote/plugins name=mocking config.api_specification_filename=stock-0.1.yaml

View Slide

68
© Kong Inc. 68
Conﬁgure Mocking Plugin
- Call the Stock API with the access token
again and the mocking plug-in returns
the sample response from the Stock API
speciﬁcation.
HTTP/1.1 200 OK
content-length: 282
content-type: application/json; charset=utf-8
date: Wed, 20 May 2020 04:23:51 GMT
server: kong/1.5.0.2-enterprise-edition
x-kong-mocking-plugin: true
x-kong-response-latency: 3
{
"meta_data": {
"api_name": "historical_stock_price_v2",
"credit_cost": 10,
"end_date": "yesterday",
"num_total_data_points": 1,
"start_date": "yesterday"
},
"result_data": {
"AAPL": [
{
"adj_close": 175.03,
"close": 150.03,
"date": "2000-04-23",
"high": 200.75,
"low": 100.87,
"open": 100.87,
"volume": 12333
}
]
}
}

View Slide

70
© Kong Inc. 70
Dev Ops for Portal - Version Control
- There is a Kong Portal CLI(https://github.com/Kong/kong-portal-cli) which can help you
to integrate Portal conﬁguration/content into source control & DevOps to then
publish/deploy to Portal runtime.
- In this section we will use the portal CLI to view the conﬁguration of the Dev Portal, fetch
the current Dev portal, modify it and deploy it.

View Slide

71
© Kong Inc. 71
- Clone the template repo, and then edit the default conﬁguration:
- The default conﬁg will being printed
git clone https://github.com/Kong/kong-portal-templates.git
cd kong-portal-templates/
sed -i "/^kong_admin_token/ckong_admin_token: 'kong'" workspaces/default/cli.conf.yaml
❯ portal config default
CLI Config:
kong_admin_url: 'http://localhost:8001'
kong_admin_token: kong
Portal Config:
name: Kong Portal
app_version: 2fc6a56
theme:
name: base
redirect:
unauthenticated: login
…

View Slide

72
© Kong Inc. 72
- Fetch the current deployed Portal conﬁguration
❯ portal fetch default
Added: emails/application-service-rejected.txt
Added: specs/stock-0.1.yaml
Modified: content/index.txt
Modified: themes/base/partials/menu.html
Added: content/products/index.md
Added: emails/application-service-revoked.txt
Added: emails/application-service-approved.txt
Modified: portal.conf.yaml
Modified: themes/base/partials/service-catalog/filter.html
Added: emails/application-service-requested.txt
Modified: themes/base/partials/homepage/clients.html
Added: themes/base/assets/js/app-44b7b4e.min.js
Added: themes/base/layouts/custom_pg_layout.html
Added: emails/application-service-pending.txt
Added: themes/base/assets/js/kongponents-44b7b4e.min.js
Modified: themes/base/partials/footer.html
Fetched 112 files
No changes.
Done.

View Slide

73
© Kong Inc. 73
- Modify contents of the Products page
❯ sed -i 's/Utilities/Logistics/g' workspaces/default/content/products/index.md

View Slide

74
© Kong Inc. 74
- Deploy the local change to Portal container (server) ...
❯ portal deploy default
✔ Wiped all Files from default
Deploying default:
Deployed ✔ configs
Deployed ✔ content
Deployed ✔ specs
Deployed ✔ emails
Deployed ✔ themes
✔ Deployed all files to default

View Slide

75
© Kong Inc.
• Deployment Kong for Dev portal
• Enable Kong Dev portal
• Customization
• Publish Specs to Portal
• Publish Specs to Portal
• Categorizing, Tagging and Locating Services
• Role Based Access to Specs
• Publish Additional Content
• Developer Experience
• Test the API and Managing Code Snippets
• Application Registration
• Mocking
• DevOps Portal Management
Summary
75

View Slide

Kong Academyを日本語でお届け！#4

Kong Academyを日本語でお届け！#4

Wenhan Shi

More Decks by Wenhan Shi

Other Decks in Technology

Featured

Transcript