Deploy Edge Microgateway as service

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Introduction

This topic explains how to run Edge Microgateway in a Kubernetes cluster as a standalone service.

For more information, see Integrate Edge Microgateway with Kubernetes overview.

Before you begin

Complete the steps described in Prerequisites.

Configure Edge Microgateway

The following command configures Edge Microgateway for your Apigee organization and deploys the proxy edgemicro-auth.

Execute the following command:

edgemicro configure -o [org] -e [env] -u [username]

Where:

org: Your Edge organization name (you must be an org administrator).
env: An environment in your org (such as test or prod).
username: The email address associated with your Apigee account.

Example

edgemicro configure -o docs -e test -u jdoe@example.com

The output (example shown below) is saved to the file:

$HOME/.edgemicro/org_name-env_name-config.yaml

current nodejs version is v6.9.1
current edgemicro version is 2.5.25
password:
file doesn't exist, setting up
Give me a minute or two... this can take a while...
App edgemicro-auth deployed.
checking org for existing KVM
KVM already exists in your org
configuring host edgemicroservices.apigee.net for region us-west1

saving configuration information to: /Users/jdoe/.edgemicro/myorg-test-config.yaml

vault info:
 -----BEGIN CERTIFICATE-----
MIICpDCCAYwCCQCV9eBcO9a5WzANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDDAls
b2NhbGhvc3QwHhcNMagwODA5MDAzMDEzWhcNMTgwODEwMDAzMDEzWjAUMRIwEAYD
VQQDDBlsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDh
nAHT7JHX/WvWHRFb8FLm53SPIDld5LyPOUfINdEyhSIEeXoOUKg4EPweJPVSC9Vm
Hw4ZMtEqWJM/XsQWvLe8ylRJa5wgmzmFCqAsuzs9+rmc9KvJqjpOh2uRTUf7KKfT
iXL2UEseprcI5g8zNyqKyEf/ecWIwz3AkkPAZebVTsrdDfIDHvkyhhvlAHZAB9kn
GtqP3N8kOlv4KQto9Gr7GYUGUIDugt7gM1F611+RBS+fYRi32GUAq/UQDkhYL8cp
oIJiF7UYkk2+9t9CdOCDuIUCvJioHJQd0xvDpkC9f6LvwjwnCwku+4F2Q63+av5I
mJoZJQPvW5aP53Qkk+kHAgMBAAEwDKYJKoZIhvcNAQELBQADggEBALyUBolXUFN8
1bf268nR+gS8MOFDTxO1bUz+bKuT/g3K1PuNUJTueT+0L1H2OiZUzazAqwn2sqzN
lQuvLg6LjxjlNkqTJGiJvGDcYVq45dv7UyxAZxhqxTxhlQ+Yu5R9pbQnzujezHpH
6gtCoCkSt/QqiJ3YsmsVu5is+HpIJepMt0CyMh5tK9j87hl46QhHklaVfQ3ycMVm
/wNPR/pjizg1FDUeq4nj/7DBVbMf9net/BDaZLeSW1HJ1vcsCXIcSZfQd4QymGFn
8ADrND7ydVjwO/s23soPDTy0g4yLIZvky2tpT8d7YahNqSv2n7sXsLxruzcyCoQ4
w+e3Z3F7IKI=
-----END CERTIFICATE-----

The following credentials are required to start edge micro
  key: 1a3b2754c7f20614817b86e09895825ecc252d34df6c4be21ae24356f09e6eb4
  secret: 16ad2431de73f07f57a6d44048f08d93b63f783bf1f2ac4221182aa7289c7cef

edgemicro configuration complete!

Deploy Edge Microgateway as a service

Execute the following command to deploy the Edge Microgateway as a service in your Kubernetes cluster:
```
kubectl apply -f <(edgemicroctl -org=org -env=env -key=edgemicro-key
-sec=edgemicro-secret -conf=file path of org-env-config.yaml)
```
where:
- org - The Apigee organization you specified in the edgemicro configure command.
- env - The environment you specified in the edgemicro configure command.
- edgemicro-key - The key returned from the edgemicro configure command.
- edgemicro-secret - The secret returned from the edgemicro configure command.
- file path of org-env-config.yaml - The path to the Edge Micro configuration file returned from the edgemicro configure command.
For example:
```
kubectl apply -f <(edgemicroctl -org=jdoe -env=test -key=989cce9d41cac94e72626d906562a1d76a19445f8901b3508858bb064988eccb -sec=ec92b793178de7b7e88e346f55a951e3fdae05e700e3ddea7d63977826379784 -conf=/Users/jdoe/.edgemicro/jdoe-test-config.yaml)
```
Example output:
```
config/myorg-test-config.yaml)
service "edge-microgateway" created
deployment "edge-microgateway" created
secret "mgwsecret" created
```

Copy and paste the following code into your terminal. The code sets up the Ingress controller to allow external access to the edge-microgateway service. You may need to press Enter after pasting the command into your terminal:

cat <<EOF | kubectl apply -f -
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: edge-microgateway-ingress
  annotations:
    kubernetes.io/ingress.class: "nginx"
spec:
  rules:
  - http:
      paths:
      - path: /
        backend:
          serviceName: edge-microgateway
          servicePort: 8000
EOF

On success, you will see this output:

ingress "edge-microgateway-ingress" created

The Ingress controller is now configured to allow external access to the edge-microgateway service.

Deploy a test service

The following steps deploy a simple test service to your cluster. The Ingress controller does not allow the service to be called from outside the cluster. Later, you will configure Edge Microgateway to call the service as its target. The Ingress controller does allow outside access to the edge-microgateway service.

Deploy the sample helloworld service. Because the Ingress doesn't know about this service, the service cannot be called from outside the cluster.
```
kubectl apply -f samples/helloworld/helloworld-service.yaml
```
Example output:
```
service "helloworld" created deployment "helloworld" created
```

Verify that the deployment succeeded. Note that there is no external IP for the helloworld service. In the following steps, you will configure Edge Microgateway to access the service's internal IP.

kubectl get services -n default

Example output:

NAME                TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
edge-microgateway   NodePort    10.35.247.222   <none>        8000:32000/TCP   12m
helloworld          NodePort    10.35.245.103   <none>        8081:30294/TCP   47s
kubernetes          ClusterIP   10.35.240.1     <none>        443/TCP          47m

Configure Edge Microgateway to proxy for the service

Get the internal IP for the helloworld service, and add it as the target of a "microgateway-aware" proxy. Creating a "microgateway-aware" proxy is a standard Edge Microgateway requirement.

Get the internal IP for the test service

Get the internal Cluster IP and port for the helloworld service:

kubectl get services helloworld

Example output:

NAME         TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
helloworld   NodePort   10.55.254.255   <none>        8081:30329/TCP   3m

Copy the values of the CLUSTER-IP and PORT. For example, in the example above, these values are: 10.55.254.255 and 8081. The values for your system will be different.

Create a microgateway-aware proxy on Edge

Log in to the Edge UI.
Select the same organization that you specified previously when you configured Edge Microgateway.
Select Develop > API Proxies in the side navigation menu.
Click + Proxy. The Build a Proxy wizard opens.
In the first wizard page, select Reverse proxy (most common).
Click Next.
In the Details page of the wizard, configure as follows. Be sure to fill in the wizard exactly as shown. Be sure the proxy name has the prefix edgemicro_.
1. Proxy Name: edgemicro_hello
2. Proxy Base Path: /hello
  
  Important: In the next step, use the Cluster IP and Port number that you obtained previously. This is the target IP of the proxy.
3. Existing API: http://<cluster_ip>:<port>
  
  For example: http://10.55.254.255:8081
Click Next.
In the Security page of the wizard, select Pass through (none).
Click Next.
In the Virtual Hosts page of the wizard, accept the defaults.
Click Next.
In the Build page of the wizard, review your proxy settings. Make sure the test environment is selected.
Click Build and Deploy.

Create a Developer

You can use an existing developer for testing, or create a new one as follows:

Select Publish > Developers in the side navigation menu.
Click + Developer.
Fill out the dialog to create a new developer. You can use any developer name/email that you wish.

Create an API Product

Create an API Product as described below. You will add two proxies to the Product: edgemicro-auth and edgemicro_hello.

You can read more about Product configuration options in What you need to know about the API Product configuration.

Select Publish > API Products in the side navigation menu.
Click + API Product. The Product Details page appears.
Fill out the Product Details page as follows. Do not click Save until instructed to do so.

Name hello-world-product

Display Name Edge Micro hello product

Environment test

Access Public

Key Approval Type Automatic
In the lower half of the page, click + Custom Resource.
Set the resource to / (a single slash).
Select + Custom Resource again and add the path /**.
In the lower part of the page, click + API Proxy.
Select the proxy named edgemicro-auth.
Click + API Proxy again.
Select the microgateway-aware proxy named edgemicro_hello.
Click Save.

Create a Developer App

Select Publish > Apps in the side navigation menu.
Click + App. The Developer App Details page appears.
Fill out the Developer App page as follows. Do not Save until instructed to do so.

Name hello-world-app

Display Name Edge Micro hello app

Developer Select the test developer you created or any developer will be fine.
In the Credentials section, click + Product and select the product you created: hello-world-product.
Click Save.
You're back on the page that lists all the Developer apps.
Select the app you just created, hello-world-app.
Click Show next to the Consumer Key.
Copy the value of the Consumer Key. This value is the API key that you will use to make secure API calls to /hello.
Wait a few minutes. It takes a few minutes for the changes you made on Apigee Edge to sync up with the instance of Edge Microgateway deployed in the cluster.

Note: Edge Microgateway polls for changes made on Apigee Edge every 600 seconds (by default), and pulls down any configuration changes made to proxies, API products, and developer apps. You can change the 600s default by editing the Edge Microgateway configuration file. See the Edge Microgateway documentation for details.

Test the proxy

Get the Ingress IP address

With the External IP for the Ingress, you can call the Edge Microgateway service from outside the cluster.

Get the external IP address of the Ingress controller:

kubectl get ing -o wide

Example output:

NAME                        HOSTS     ADDRESS          PORTS     AGE
edge-microgateway-ingress   *         35.238.249.62    80        37m

Copy the ADDRESS value for the Ingress and export it to a variable. You can set the variable manually:

export GATEWAY_IP=external_ip

For example:

export GATEWAY_IP=35.238.249.62

Or, use this command to set it for you:

export GATEWAY_IP=$(kubectl describe ing edge-microgateway --namespace default | grep "Address" | cut -d ':' -f2 | tr -d "[:space:]")

Verify that the variable was exported. For example:
```
echo $GATEWAY_IP
```
Example output:
```
35.238.249.62
```

Call the API

After the configuration changes are pulled into the microgateway, you can try calling the API. You use the Ingress controller IP (which you saved in the variable GATEWAY_IP to call the API because this IP lets you call the proxy from outside the Kubernetes cluster. The mapping from the Ingress to Edge Microgateway was created when you deployed Edge Microgateway to the cluster.

Call the API without an API key. You will get an error message, as shown below:
```
curl $GATEWAY_IP:80/hello/
```
Expected output:
```
{"error":"missing_authorization","error_description":"Missing Authorization
header"}
```
If you see this message, you may need to wait a little longer until the sync is completed:
```
{"message":"no match found for /hello/","status":404}
```
To make successful API calls, you need the API key.
Get the Consumer key from the Developer app you created. This value is the API key you need to call the test proxy:
```
curl -H 'x-api-key:your-edge-api-key' $GATEWAY_IP:80/hello/
```
For example:
```
curl -H "x-api-key:DeX2eEesYAdRJ5Gdbo77nT9uUfJZql19" $GATEWAY_IP:80/hello/
```
Output:
```
Hello world
```
If you see the "Hello world" response, then you have successfully configured Edge Microgateway to call the helloworld service inside the Kubernetes cluster.

What's next?

See the Tasks section for information on adding custom plugins, scaling deployment, making configuration changes, and other tasks you may wish to perform.

Name	`hello-world-product`
Display Name	`Edge Micro hello product`
Environment	`test`
Access	`Public`
Key Approval Type	`Automatic`

Name	`hello-world-app`
Display Name	`Edge Micro hello app`
Developer	Select the test developer you created or any developer will be fine.