forked from pivotal-cf/docs-apigee
-
Notifications
You must be signed in to change notification settings - Fork 0
/
proxying-org.html.md.erb
171 lines (130 loc) · 8.85 KB
/
proxying-org.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
---
title: Proxying a PCF App with Apigee Edge ("org" plan)
owner: Partners
---
<strong><%= modified_date %></strong>
This topic describes how to push a sample app to Pivotal Cloud Foundry (PCF), create an Apigee Edge service instance, and bind the application to it. After binding the application to the Apigee Edge service instance, requests to the app will be forwarded to an Apigee Edge API proxy for management.
Before performing the procedures in this topic, you must [install and configure](installing.html) the Apigee Edge Service Broker for PCF tile.
## <a id="push-sample"></a>Step 1: Push the Sample App
Perform the following steps to push a sample application to PCF.
1. Clone the Apigee Edge GitHub repo:
<pre class="terminal">$ git clone <span>https:</span>//github.com/apigee/cloud-foundry-apigee.git</pre>
1. Change into the `sample-api` directory of the cloned repo:
<pre class="terminal">$ cd cloud-foundry-apigee/samples/org-and-microgateway-sample</pre>
1. In the `org-and-microgateway-sample` directory, open `manifest.yml`.
1. Edit `manifest.yml` to change the `name` and `host` properties to values specific to your deployment. See the following example:
```
applications:
- name: sample-api
memory: 128M
instances: 1
host: sample-api-apigee
path: .
buildpack: nodejs_buildpack
```
1. Save the edited file.
1. Set your API endpoint to the Cloud Controller of your deployment.
<pre class="terminal">
$ cf api api.YOUR-SYSTEM-DOMAIN
Setting api endpoint to api.YOUR-SYSTEM-DOMAIN...
OK
API endpoint: <span>https:</span>//api.YOUR-SYSTEM-DOMAIN (API version: 2.59.0)
Not logged in. Use 'cf login' to log in.
</pre>
1. Log in to your deployment and select an org and a space.
<pre class="terminal">
$ cf login
API endpoint: <span>https:</span>//api.YOUR-SYSTEM-DOMAIN
Email> user<span>@</span>example.com
Password>
</pre>
1. Push the sample app to PCF:
<pre class="terminal">$ cf push YOUR-SAMPLE-APP</pre>
1. Use `curl` to send a test request to the app you pushed:
<pre class="terminal">
$ curl YOUR-SAMPLE-APP.YOUR-SYSTEM-DOMAIN
{"hello":"hello from cf app"}
</pre>
If you receive the above response, the sample app is running successfully.
## <a id="create-instance"></a>Step 2: Create a Service Instance
Perform the following steps to create an instance of the Apigee Edge service:
1. List the Marketplace services and locate the Apigee Edge service:
<pre class="terminal">
$ cf marketplace
Getting services from marketplace in org example / space development as user<span>@</span>example.com...
OK
service plans description
apigee-edge org, microgateway Apigee Edge API Platform
</pre>
1. Create an instance of the Apigee Edge service. Select either the `org` service plan.
<pre class="terminal">$ cf create-service apigee-edge org YOUR-SERVICE-INSTANCE -c \
'{"org":"YOUR-ORG", "env":"YOUR-ENV"}'
cf service YOUR-SERVICE-INSTANCE</pre>
1. Use the `cf service` command to display information about the service instance:
<pre class="terminal">
$ cf service apigee-service
Service instance: apigee-service
Service: apigee-edge
Bound apps:
Tags:
Plan: org
Description: Apigee Edge API Platform
Documentation url: http://apigee.com/docs/
Dashboard: https://enterprise.apigee.com/platform/#/
Last Operation
Status: create succeeded
Message:
Started: 2016-10-27T20:47:43Z
Updated:
</pre>
## <a id="bind-app-route"></a>Step 3: Bind the App Route to the Service Instance
Perform the following steps to bind the route of your app to your Apigee Edge service instance.
1. Download the Apigee Edge scripts:
<pre class="terminal">$ curl <span>https:</span>//login.apigee.com/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"</pre>
1. Unzip the `ssocli-bundle.zip` file. This includes `get_token`, a script that gets or updates a token that you use to authenticate with your Apigee Edge organization. You need this token to bind the Apigee Edge route service to your app.
<pre class="terminal">$ tar xvf ssocli-bundle.zip</pre>
1. Create a `.sso-cli` directory in your user directory:
<pre class="terminal">$ mkdir ~/.sso-cli</pre>
1. Use the `get_token` script to create a token. When prompted, enter the Apigee Edge username and password you use to log in to your organization.
<pre class="terminal">$ ./get\_token</pre>
The `get_token` script writes the token file into `~/.sso-cli`. For more about `get_token`, see the [Apigee documentation](http://docs.apigee.com/api-services/content/using-oauth2-security-apigee-edge-management-api).
1. Use the `bind-route-service` command to create an Apigee Edge API proxy and bind your Cloud Foundry app to the proxy. This tells the Gorouter to redirect requests to the Apigee Edge proxy before sending them to the Cloud Foundry application. (See the reference on this page for more about this command.)
<pre class="terminal">
$ cf bind-route-service cfapps.pivotal.io APIGEE-SERVICE --hostname SAMPLE-APP-APIGEE -c '{"org":"my_edge_org","env":"my_edge_env", "bearer":"'$(cat ~/.sso-cli/valid_token.dat)'", "action":"proxy bind", "protocol":"https"}'
Binding route sample-api-apigee.cfapps.pivotal.io to service instance apigee-service in org apigee / space test as admin...
OK
</pre>
* For APIGEE-SERVICE, use the name of the Apigee Edge service instance you created earlier
* For SAMPLE-APP-APIGEE, use the name of the host you specified in your manifest.yml
The output from `bind-route-service` should confirm that you have bound the route of your app to your Apigee Edge service instance.
### bind-route-service reference
When binding to an Apigee API proxy, the `bind-route-service` command follows this form (be sure to use quotes and command expansion, as shown here):
<pre class="terminal">
$ cf bind-route-service YOUR-APP-DOMAIN SERVICE-INSTANCE [--hostname HOSTNAME] \
-c '{"org":"YOUR-EDGE-ORG","env":"YOUR-EDGE-ENV",
"bearer":"'AUTHENTICATION-TOKEN-FILE'" | "basic":"ENCODED-USERNAME-PASSWORD" | "USERNAME:PASSWORD",
"action":"proxy"|"bind"|"proxy bind",
["protocol":"http"|"https"]}'
</pre>
Parameters for the `-c` argument specify connection details:
Parameter | Description | Allowed Values
---- | ---- | ----
`org` | Apigee Edge organization hosting the API proxy to be called | Your organization (must be reachable via the authentication token specified in he `bearer` parameter)
`env` | Apigee Edge environment to which the API proxy is (or will be) deployed | Your environment.
`bearer` | Path to a file containing an authentication token valid for your organization | An authentication token, such as one generated with Apigee's get_token command. The broker does not store any data; it requires credentials and other parameters for each individual `cf` command. Instead of a `bearer` token, credentials can also be expressed as:<ul><li>`basic`: standard HTTP Base-64 encoded username and password for `Authorization: Basic`. Note that this is *not encrypted* and easily converted to clear text. But a jumble of digits and letters may provide some protection in case of momentary exposure (but no better than if the password is already a jumble of digits, letters, and symbols)</li><li>username and password in clear text</li></ul>
`action` | A value specifying whether to create or bind an API proxy | `proxy` to generate an API proxy; `bind` to bind the service with the proxy; `proxy bind` to generate the proxy and bind with a single command.
`protocol` | The protocol through which the proxy's target endpoint should be accessed by Cloud Foundry | `http` or `https`; default is `https`.
## <a id="test-binding"></a>Step 4: Test the Binding
Once you've bound your app's path to the Apigee service (creating an Apigee proxy in the process), you can try it out with the sample app you invoked earlier.
1. Open the Apigee Edge management console.
1. In the management console, under **APIs > API proxies**, locate the name of the proxy you just created with `bind-route-service`. It's likely to have a name that ends with your domain value, such as `cfapps.pivotal.io`.
1. Click the new proxy's name to view its **Overview** page.
1. Click the **Trace** tab, then click the **Start Trace Session** button.
1. Back at the command line, run the `curl` command you ran earlier to make a request to your Cloud Foundry app you pushed, such as:
<pre class="terminal">
$ curl <span>https:</span>//sample-api-apigee.cfapps.pivotal.io
{"hello":"hello from cf app"}
</pre>
As before, the console outputs the app's response.
1. Return to the Apigee Edge management console to see that your request has now been routed through the Edge proxy you created.
The new proxy is just a pass-through, but it is now ready for you or someone on your team to add policies to define security, traffic management, and more.