You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/hybrid/v1.10/apigee-deployment-services). 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](https://docs.apigee.com/api-platform/integrations/kubernetes/k8s-introduction).

## Before you begin

Complete the steps described in [Prerequisites](https://docs.apigee.com/api-platform/integrations/kubernetes/k8s-prerequisites).

## Configure Edge Microgateway

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

1. 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.

   > [!NOTE]
   > **Note:** The configure command allows additional parameters. For a complete list, see [Configuring Edge Microgateway for Apigee Edge Cloud](https://docs.apigee.com/api-platform/microgateway/2.5.x/cli-reference-edge-microgateway#configuring-edge-microgateway-for-apigee-edge-cloud).

   **Example**

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

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

   <br />

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

   <br />

       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

1. 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

2. 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.

1. 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

2. 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.

See also [What you need to know about Microgateway-aware
proxies](https://docs.apigee.com/api-platform/microgateway/2.5.x/overview-edge-microgateway#whatyouneedtoknowaboutedgemicrogateway-whatyouneedtoknowaboutedgemicrogatewayawareproxies).

### Get the internal IP for the test service

1. 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

2. 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

1. [Log in](https://login.apigee.com/login) to the Edge UI.
2. Select the same organization that you specified previously when you configured Edge Microgateway.
3. Select **Develop \> API Proxies** in the side navigation menu.
4. Click **+ Proxy**. The Build a Proxy wizard opens.
5. In the first wizard page, select **Reverse proxy (most common)**.
6. Click **Next**.
7. 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]
      > **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**
8. Click **Next**.

9. In the Security page of the wizard, select **Pass through (none)**.

10. Click **Next**.

11. In the Virtual Hosts page of the wizard, accept the defaults.

12. Click **Next**.

13. In the Build page of the wizard, review your proxy settings. Make sure the
    **test** environment is selected.

14. Click **Build and Deploy**.

## Create a Developer

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

1. Select **Publish \> Developers** in the side navigation menu.
2. Click **+ Developer.**
3. 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**.

> [!NOTE]
> **Note:** The `edgemicro-auth` proxy was deployed when you ran the `edgemicro configure` command.

You can read more about
Product configuration options in [What you need to know about the API Product
configuration](https://docs.google.com/document/d/15ZOwSlQ3LAR264yADG5DNbEnqrT3sizCRHkM0lg1N0k/edit#heading=h.x409funbyn1q).

1. Select **Publish \> API Products** in the side navigation menu.
2. Click **+ API Product**. The Product Details page appears.
3. 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` |

4. In the lower half of the page, click **+ Custom Resource**.

5. Set the resource to **`/ `**(a single slash).

6. Select **+ Custom Resource** again and add the path `/**`.

7. In the lower part of the page, click **+ API Proxy**.

8. Select the proxy named **edgemicro-auth**.

9. Click **+ API Proxy** again.

10. Select the microgateway-aware proxy named **edgemicro_hello**.

11. Click **Save**.

## Create a Developer App

1. Select **Publish \> Apps** in the side navigation menu.
2. Click **+ App**. The Developer App Details page appears.
3. 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. |

4. In the Credentials section, click **+ Product** and select the product you
   created: `hello-world-product.`

5. Click **Save**.

6. You're back on the page that lists all the Developer apps.

7. Select the app you just created, **`hello-world-app`**.

8. Click **Show** next to the **Consumer Key**.

9. **Copy the value of the Consumer Key.** This value is the
   **API key** that you will use to make secure API calls to
   `/hello`.

10. 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]
    > **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](https://docs.apigee.com/api-platform/microgateway/2.5.x/operation-and-configuration-reference-edge-microgateway#edgemicrogatewayconfigurationreference-edgemicroattributes) 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.

1. 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

2. 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:]")
   ```
3. 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](https://docs.apigee.com/api-platform/integrations/kubernetes/k8s-service#deploy_edge_microgateway_as_a_service)
to the cluster.

1. 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.
2. 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](https://docs.apigee.com/api-platform/integrations/kubernetes/k8s-tasks) section for information
on adding custom plugins, scaling deployment, making configuration changes, and
other tasks you may wish to perform.