Skip to content

Commit e069c42

Browse files
deliahudeliahu
authored
Add REST API Gateway guide (#1505)
1 parent fa50db0 commit e069c42

File tree

3 files changed

+198
-0
lines changed

3 files changed

+198
-0
lines changed

‎docs/deployments/networking.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ APIs are deployed with a public API Gateway by default (the API Gateway forwards
88

99
By default, the API load balancer is public. You can configure your API load balancer to be private by setting `api_load_balancer_scheme: internal` in your [cluster configuration](../cluster-management/config.md) file (before creating your cluster). This will force external traffic to go through your API Gateway endpoint, or if you disabled API Gateway for your API, it will make your API only accessible through VPC Peering. Note that if API Gateway is used, endpoints will be public regardless of `api_load_balancer_scheme`. See below for common configurations.
1010

11+
The API Gateway that Cortex creates in AWS is the "HTTP" type. If you need to use AWS's "REST" API Gateway, see [here](../guides/rest-api-gateway.md).
12+
1113
## Common API networking configurations
1214

1315
### Public https endpoint (with API Gateway)

‎docs/guides/rest-api-gateway.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Set up REST API Gateway
2+
3+
_WARNING: you are on the master branch, please refer to the docs on the branch that matches your `cortex version`_
4+
5+
When `api_gateway: public` is set in your API's `networking` configuration (which is the default setting), Cortex will create an "HTTP" API Gateway in AWS for your API (see the [networking docs](../deployments/networking.md) for more information).
6+
7+
However, there may be situations where you need to use AWS's "REST" API Gateway, e.g. to enforce IAM-based auth. Until [#1197](https://github.com/cortexlabs/cortex/issues/1197) is resolved, a REST API Gateway can be used by following these steps.
8+
9+
If your API load balancer is internet-facing (which is the default, or you explicitly set `api_load_balancer_scheme: internet-facing` in your cluster configuration file before creating your cluster), use the [first section](#if-your-api-load-balancer-is-internet-facing) of this guide.
10+
11+
If your API load balancer is internal (i.e. you set `api_load_balancer_scheme: internal` in your cluster configuration file before creating your cluster), use the [second section](#if-your-api-load-balancer-is-internal) of this guide.
12+
13+
## If your API load balancer is internet-facing
14+
15+
### Step 1
16+
17+
Disable the default API Gateway:
18+
19+
* If you haven't created your cluster yet, you can set `api_gateway: none` in your [cluster configuration file](../cluster-management/config.md) before creating your cluster.
20+
* If you have already created your cluster, you can set `api_gateway: none` in the `networking` field of your [Realtime API configuration](../deployments/realtime-api/api-configuration.md) and/or [Batch API configuration](../deployments/batch-api/api-configuration.md), and then re-deploy your API.
21+
22+
### Step 2
23+
24+
Go to the [API Gateway console](https://console.aws.amazon.com/apigateway/home), select "REST API" under "Choose an API type", and click "Build"
25+
26+
![step 1](https://user-images.githubusercontent.com/808475/78293216-18269e80-74dd-11ea-9e68-86922c2cbc7c.png)
27+
28+
### Step 3
29+
30+
Select "REST" and "New API", name your API (e.g. "cortex"), select either "Regional" or "Edge optimized" (depending on your preference), and click "Create API"
31+
32+
![step 2](https://user-images.githubusercontent.com/808475/78293434-66d43880-74dd-11ea-92d6-692158171a3f.png)
33+
34+
### Step 4
35+
36+
Select "Actions" > "Create Resource"
37+
38+
![step 3](https://user-images.githubusercontent.com/808475/80154502-8b6b7f80-8574-11ea-9c78-7d9f277bf55b.png)
39+
40+
### Step 5
41+
42+
Select "Configure as proxy resource" and "Enable API Gateway CORS", and click "Create Resource"
43+
44+
![step 4](https://user-images.githubusercontent.com/808475/80154565-ad650200-8574-11ea-8753-808cd35902e2.png)
45+
46+
### Step 6
47+
48+
Select "HTTP Proxy" and set "Endpoint URL" to "http://<BASE_API_ENDPOINT>/{proxy}". You can get your base API endpoint via `cortex cluster info`; make sure to prepend `http://` and append `/{proxy}`. For example, mine is: `http://a9eaf69fd125947abb1065f62de59047-81cdebc0275f7d96.elb.us-west-2.amazonaws.com/{proxy}`.
49+
50+
Leave "Content Handling" set to "Passthrough" and Click "Save".
51+
52+
![step 5](https://user-images.githubusercontent.com/808475/80154735-13ea2000-8575-11ea-83ca-58f182df83c6.png)
53+
54+
### Step 7
55+
56+
Select "Actions" > "Deploy API"
57+
58+
![step 6](https://user-images.githubusercontent.com/808475/80154802-2c5a3a80-8575-11ea-9ab3-de89885fd658.png)
59+
60+
### Step 8
61+
62+
Create a new stage (e.g. "dev") and click "Deploy"
63+
64+
![step 7](https://user-images.githubusercontent.com/808475/80154859-4431be80-8575-11ea-9305-50384b1f9847.png)
65+
66+
### Step 9
67+
68+
Copy your "Invoke URL"
69+
70+
![step 8](https://user-images.githubusercontent.com/808475/80154911-5dd30600-8575-11ea-9682-1a7328783011.png)
71+
72+
### Using your new endpoint
73+
74+
You may now use the "Invoke URL" in place of your APIs endpoint in your client. For example, this curl request:
75+
76+
```bash
77+
curl http://a9eaf69fd125947abb1065f62de59047-81cdebc0275f7d96.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
78+
```
79+
80+
Would become:
81+
82+
```bash
83+
curl https://31qjv48rs6.execute-api.us-west-2.amazonaws.com/dev/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
84+
```
85+
86+
### Cleanup
87+
88+
Delete the API Gateway before spinning down your Cortex cluster:
89+
90+
![delete api gateway](https://user-images.githubusercontent.com/808475/80155073-bdc9ac80-8575-11ea-99a1-95c0579da79e.png)
91+
92+
## If your API load balancer is internal
93+
94+
### Step 1
95+
96+
Disable the default API Gateway:
97+
98+
* If you haven't created your cluster yet, you can set `api_gateway: none` in your [cluster configuration file](../cluster-management/config.md) before creating your cluster.
99+
* If you have already created your cluster, you can set `api_gateway: none` in the `networking` field of your [Realtime API configuration](../deployments/realtime-api/api-configuration.md) and/or [Batch API configuration](../deployments/batch-api/api-configuration.md), and then re-deploy your API.
100+
101+
### Step 2
102+
103+
Navigate to AWS's EC2 Load Balancer dashboard and locate the Cortex API load balancer. You can determine which is the API load balancer by inspecting the `kubernetes.io/service-name` tag:
104+
105+
![step 1](https://user-images.githubusercontent.com/808475/80142777-961c1980-8560-11ea-9202-40964dbff5e9.png)
106+
107+
Take note of the load balancer's name.
108+
109+
### Step 3
110+
111+
Go to the [API Gateway console](https://console.aws.amazon.com/apigateway/home), click "VPC Links" on the left sidebar, and click "Create"
112+
113+
![step 2](https://user-images.githubusercontent.com/808475/80142466-0c6c4c00-8560-11ea-8293-eb5e5572b797.png)
114+
115+
### Step 4
116+
117+
Select "VPC link for REST APIs", name your VPC link (e.g. "cortex"), select the API load balancer (identified in Step 1), and click "Create"
118+
119+
![step 3](https://user-images.githubusercontent.com/808475/80143027-03c84580-8561-11ea-92de-9ed0a5dfa593.png)
120+
121+
### Step 5
122+
123+
Wait for the VPC link to be created (it will take a few minutes)
124+
125+
![step 4](https://user-images.githubusercontent.com/808475/80144088-bbaa2280-8562-11ea-901b-8520eb253df7.png)
126+
127+
### Step 6
128+
129+
Go to the [API Gateway console](https://console.aws.amazon.com/apigateway/home), select "REST API" under "Choose an API type", and click "Build"
130+
131+
![step 5](https://user-images.githubusercontent.com/808475/78293216-18269e80-74dd-11ea-9e68-86922c2cbc7c.png)
132+
133+
### Step 7
134+
135+
Select "REST" and "New API", name your API (e.g. "cortex"), select either "Regional" or "Edge optimized" (depending on your preference), and click "Create API"
136+
137+
![step 6](https://user-images.githubusercontent.com/808475/78293434-66d43880-74dd-11ea-92d6-692158171a3f.png)
138+
139+
### Step 8
140+
141+
Select "Actions" > "Create Resource"
142+
143+
![step 7](https://user-images.githubusercontent.com/808475/80141938-3cffb600-855f-11ea-9c1c-132ca4503b7a.png)
144+
145+
### Step 9
146+
147+
Select "Configure as proxy resource" and "Enable API Gateway CORS", and click "Create Resource"
148+
149+
![step 8](https://user-images.githubusercontent.com/808475/80142124-80f2bb00-855f-11ea-8e4e-9413146e0815.png)
150+
151+
### Step 10
152+
153+
Select "VPC Link", select "Use Proxy Integration", choose your newly-created VPC Link, and set "Endpoint URL" to "http://<BASE_API_ENDPOINT>/{proxy}". You can get your base API endpoint via `cortex cluster info`; make sure to prepend `http://` and append `/{proxy}`. For example, mine is: `http://a5044e34a352d44b0945adcd455c7fa3-32fa161d3e5bcbf9.elb.us-west-2.amazonaws.com/{proxy}`. Click "Save"
154+
155+
![step 9](https://user-images.githubusercontent.com/808475/80147407-4f322200-8568-11ea-8ef5-df5164c1375f.png)
156+
157+
### Step 11
158+
159+
Select "Actions" > "Deploy API"
160+
161+
![step 10](https://user-images.githubusercontent.com/808475/80147555-86083800-8568-11ea-86af-1b1e38c9d322.png)
162+
163+
### Step 12
164+
165+
Create a new stage (e.g. "dev") and click "Deploy"
166+
167+
![step 11](https://user-images.githubusercontent.com/808475/80147631-a7692400-8568-11ea-8a09-13dbd50b17b9.png)
168+
169+
### Step 13
170+
171+
Copy your "Invoke URL"
172+
173+
![step 12](https://user-images.githubusercontent.com/808475/80147716-c798e300-8568-11ea-9aef-7dd6fdf4a68a.png)
174+
175+
### Using your new endpoint
176+
177+
You may now use the "Invoke URL" in place of your APIs endpoint in your client. For example, this curl request:
178+
179+
```bash
180+
curl http://a5044e34a352d44b0945adcd455c7fa3-32fa161d3e5bcbf9.elb.us-west-2.amazonaws.com/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
181+
```
182+
183+
Would become:
184+
185+
```bash
186+
curl https://lrivodooqh.execute-api.us-west-2.amazonaws.com/dev/iris-classifier -X POST -H "Content-Type: application/json" -d @sample.json
187+
```
188+
189+
### Cleanup
190+
191+
Delete the API Gateway and VPC Link before spinning down your Cortex cluster:
192+
193+
![delete api](https://user-images.githubusercontent.com/808475/80149163-05970680-856b-11ea-9f82-61f4061a3321.png)
194+
195+
![delete vpc link](https://user-images.githubusercontent.com/808475/80149204-1ba4c700-856b-11ea-83f7-9741c78b6b95.png)

‎docs/summary.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@
7272
* [Single node deployment](guides/single-node-deployment.md)
7373
* [Set up kubectl](guides/kubectl-setup.md)
7474
* [Private docker registry](guides/private-docker.md)
75+
* [Set up REST API Gateway](guides/rest-api-gateway.md)
7576
* [Install CLI on Windows](guides/windows-cli.md)
7677

7778
## Contributing

0 commit comments

Comments
 (0)