You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/envoy-adapter/v1.4.x/example-hybrid). info

> [!CAUTION]
> **DEPRECATED:** Running Edge Microgateway in Kubernetes using the sidecar proxy pattern is supported; however, the `edgemicroctl` and related tooling described in this topic is deprecated. This tooling relies on the Istio sidecar injector, which is no longer supported.

## Introduction

This topic explains how to run Edge Microgateway in a Kubernetes cluster as
a **sidecar proxy**. You have two options for sidecar deployment: manual and automatic
injection. This topic describes both options.

For more information, see [Introduction to Edge Microgateway on Kubernetes](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).

## Deploy a test service

Deploy a simple "hello" service and verify the deployment:

1. Deploy the sample:

   ```
   kubectl apply -f samples/helloworld/helloworld.yaml --namespace=default
   ```
2. Verify that the service is running. You may need to wait a few moments until
   the pod spins up to the running state:

   ```
   kubectl get pods --namespace=default
   ```

   Example output:

       NAME                          READY     STATUS    RESTARTS   AGE
       helloworld-569d6565f9-lwrrv   1/1       Running   0          17m

   > [!NOTE]
   > **Note:** Notice that the READY status of 1/1 means there is "one of one" services running in the pod. In the following steps, you will configure the cluster so that Edge Microgateway is automatically injected as a sidecar into any new pods that you create. When that happens, you will see when you run `kubectl get pods` that there are "two of two" services running in the pod: the service and the sidecar.

3. Delete the test service deployment. You will reinstall it later, after you enable
   sidecar injection:

   <br />

   ```
    kubectl delete -f samples/helloworld/helloworld.yaml --namespace=default
   ```

   <br />

## Using manual sidecar injection

Of the two sidecar injection options, manual sidecar injection is the simpler, more straightforward
approach, and can be done with a single `kubectl` command.

### 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 myorg -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!

### Inject Edge Microgateway as a sidecar

To manually inject Edge Microgateway into a service pod as a sidecar proxy, execute
this command:

<br />

```
kubectl apply -f <(edgemicroctl -org=your_org -env=your_env -key=your_key -sec=your_secret -conf=config_file_path -svc=service_deployment_file)
```

<br />

where:

- `your_org` - The Apigee organization you specified in the `edgemicro configure` command.
- `your_env` - The environment you specified in the `edgemicro configure` command.
- `your_key` - The key returned from the `edgemicro configure` command.
- `your_secret` - The secret returned from the `edgemicro configure` command.
- `config_file_path` - The path to the Edge Micro configuration file returned from the `edgemicro configure` command.
- `service_deployment_file` - The path to the deployment file of the service whose pod will get the companion sidecar service. For example: `samples/helloworld/helloworld.yaml`.

For example:

```
kubectl apply -f <(edgemicroctl -org=myorg -env=test-key=0e3ecea28a64099410594406b30e54439af5265f8 -sec=e3919250bee37c69cb2e5b41170b488e1c1d -conf=/Users/jdoe/.edgemicro/myorg-test-config.yaml -svc=samples/helloworld/helloworld.yaml)
```

### Test the configuration

1. Check the service deployments:

   ```
   kubectl get services -n default
   ```

   Example output:

       NAME         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
       helloworld   NodePort    10.15.254.163   <none>        8081:32401/TCP   56s
       kubernetes   ClusterIP   10.15.240.1     <none>        443/TCP          41m

2. Now, you are ready to test the sidecar deployment of Edge Microgateway. Go to
   [Test the proxy](https://docs.apigee.com/api-platform/integrations/kubernetes/k8s-sidecar#test_the_proxy) for detailed steps.

## Using automatic sidecar injection

In the following steps, you will configure automatic sidecar injection for your
Kubernetes cluster. This setup allows Edge Microgateway to be injected as a sidecar
proxy into Kubernetes.

### Install the sidecar injector

1. Install the [ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/)
   that enables sidecar injection of Edge Microgateway:

   ```
   kubectl apply -f install/kubernetes/edgemicro-sidecar-injector-configmap-release.yaml
   ```
2. Execute the following script to install the [webhook](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#admission-webhooks) service. The webhook service is required for
   automatic sidecar injection:

   > [!NOTE]
   > **Note:** A webhook service requires a signed certificate/key pair. The following script generates a certificate/key pair signed by the Kubernetes Certificate Authority (CA). The resulting certificate/key file is stored as a Kubernetes secret for the sidecar injector webhook to consume. Kubernetes CA approval requires permissions to create and approve the certificate signing request (CSR). See also [Managing tls in a cluster](https://kubernetes.io/docs/tasks/tls/managing-tls-in-a-cluster) and examine the script `install/kubernetes/webhook-create-signed-cert.sh` for more information.

   ```
   ./install/kubernetes/webhook-create-signed-cert.sh \
       --service edgemicro-sidecar-injector \
       --namespace edgemicro-system \
       --secret sidecar-injector-certs
   ```
3. Add the CA bundle to the webhook installation file. The Kubernetes
   api-server uses this file to invoke the webhook:

   ```
   cat install/kubernetes/edgemicro-sidecar-injector.yaml | \
        ./install/kubernetes/webhook-patch-ca-bundle.sh > \
        install/kubernetes/edgemicro-sidecar-injector-with-ca-bundle.yaml
   ```
4. Install the Edge Microgateway sidecar injector webhook:

   ```
   kubectl apply -f install/kubernetes/edgemicro-sidecar-injector-with-ca-bundle.yaml
   ```

   Example output:

       service "edgemicro-sidecar-injector" created
       serviceaccount "edgemicro-sidecar-injector-service-account" created
       deployment "edgemicro-sidecar-injector" created
       mutatingwebhookconfiguration "edgemicro-sidecar-injector" created

5. Verify that the Edge Microgateway sidecar injector webhook is running:

   ```
   kubectl -n edgemicro-system get deployment -ledgemicro=sidecar-injector
   ```

   Example output:

       NAME                         DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
       edgemicro-sidecar-injector   1         1         1            1           12m

6. Verify that the sidecar injection pod is running in your cluster. The namespace
   `edgemicro-system` is where the system services are installed, including the
   Ingress controller, default HTTP backend, and the sidecar injector:

   ```
   kubectl get pods -n edgemicro-system
   ```

   Example output:

       NAME                                            READY     STATUS    RESTARTS   AGE
       default-http-backend-55c6c69b88-gfnfd           1/1       Running   0          1h
       edgemicro-ingress-controller-64444469bf-jhn8b   1/1       Running   3          1h
       edgemicro-sidecar-injector-7d95698fbf-cq84q     1/1       Running   0          3m

### Configure and inject Edge Microgateway

In the next step, you will run an interactive script to create an Edge Microgateway
configuration associated with a Kubernetes namespace. Then, you will inject the
configuration into your Kubernetes cluster.

> [!NOTE]
> **Note:** You can create different configuration profiles based on your Apigee Edge or Edge Microgateway configurations.

1. Run the following interactive script and provide the requested parameters. The
   command generates a configuration profile that you will use in the next step.

   ```
   ./install/kubernetes/webhook-edgemicro-patch.sh
   ```

   For information about the input parameters, see [Reference](https://docs.apigee.com/api-platform/integrations/kubernetes/k8s-reference).

   Sample inputs:
   1. `Namespace to deploy application [default]:`

      Press **Enter**.
   2. `Authenticate with OAuth Token ("n","Y") [N/y]`

      Enter **n**.
   3. `Apigee username [required]:`

      Enter your Apigee username (email address). For example: `jdoe@google.com`.
   4. `Apigee password [required]:`

      Enter you Apigee password.
   5. `Apigee organization [required]:`

      Enter your Apigee organization name.
   6. `Apigee environment [required]:`

      Enter an environment name for your organization. For example "test".
   7. `Virtual Host [default]:`

      Press **Enter**.
   8. `Is this Private Cloud ("n","y") [N/y]:`

      Enter **n** if you are on Public Cloud.
   9. `Edgemicro Key. Press Enter to generate:`

      Press **Enter**.
   10. `Edgemicro Secret. Press Enter to generate:`

       Press **Enter**.
   11. `Edgemicro org-env-config.yaml. Press Enter to generate:`

       Press **Enter**.

       Example output:

           current nodejs version is v6.9.1
           current edgemicro version is 2.5.25
           config initialized to /Users/jdoe/.edgemicro/default.yaml
           Configure for Cloud
           ******************************************************************************************
           Config file is Generated in /Users/jdoe/Work/GITHUB/microgateway_2.5.25_Darwin_x86_64/config directory.

           Please make changes as desired.
           *****************************************************************************************

   12. `Do you agree to proceed("n","y") [N/y]:`

       Enter **y**.

       Example output:

           Configuring Microgateway with

           key:daacf75dd660d160b801c9117fb1ec0935896615479e39dbbae88be81a2d84
           secret:a60fd57c1db9f3a06648173fb541cb9c59188d3b6037a76f490ebf7a6584b0
           config:~/.edgemicro/jdoe-test-config.yaml

           ********************************************************************************************************
           kubectl apply -f install/kubernetes/edgemicro-config-namespace-bundle.yaml
           ********************************************************************************************************

   > [!NOTE]
   > **Note:** You can also pass parameters to the script for non-interactive use. See the comments in `./install/kubernetes/webhook-edgemicro-patch.sh` for details.

2. Execute the command given in the last line of the output. This `kubectl` command
   injects the generated Edge Microgateway configuration profile into Kubernetes:

   ```
   kubectl apply -f install/kubernetes/edgemicro-config-namespace-bundle.yaml
   ```
3. View the status of webhook injection. Note that it is currently not enabled:

   ```
   kubectl get namespace -L edgemicro-injection
   ```

   Example output:

       NAME               STATUS    AGE       EDGEMICRO-INJECTION
       default            Active    1d
       edgemicro-system   Active    1d
       kube-public        Active    1d
       kube-system        Active    1d

4. Run this command to enable webhook injection for the webhook:

   ```
   kubectl label namespace default edgemicro-injection=enabled
   ```
5. View the status of webhook injection again. Note that now it is enabled:

   ```
   kubectl get namespace -L edgemicro-injection
   ```

   Example output:

       NAME               STATUS    AGE       EDGEMICRO-INJECTION
       default            Active    1d        enabled
       edgemicro-system   Active    1d
       kube-public        Active    1d
       kube-system        Active    1d

### Deploy the test service

Now, redeploy the test service. Edge Microgateway will be automatically injected
into the service's pod.

```
kubectl apply -f samples/helloworld/helloworld.yaml --namespace=default
```

Confirm that Edge Microgateway was injected into the pod along with the test
service:

```
kubectl get pods --namespace=default --watch
```

Example output:

> [!NOTE]
> **Note:** The pod spins up with two containers (2/2). One of these is the helloworld service and the other is the Edge Microgateway sidecar.

    NAME                          READY     STATUS            RESTARTS   AGE
    helloworld-6987878fc4-pkw8h   0/2       PodInitializing   0          12s
    helloworld-6987878fc4-pkw8h   2/2       Running           0         26s

When the status changes to `Running`, press `ctrl-c` to exit the command.

Now, you are ready to test the automatic sidecar deployment of Edge Microgateway. Go to
[Test the proxy](https://docs.apigee.com/api-platform/integrations/kubernetes/k8s-sidecar#test_the_proxy) for detailed steps.

## Test the proxy

With sidecar deployment, an API proxy for your service is created for you automatically. You do
not need to create an "Edge Microgateway-aware" proxy.

### Get the Ingress IP address

With the External IP for the Ingress, you can call the 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
       gateway   *         35.238.13.54   80        1m

2. Copy the `EXTERNAL-IP` 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 gateway --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

4. Call the service:

   ```
   curl $GATEWAY_IP
   ```

   Output:

       {"error":"missing_authorization","error_description":"Missing Authorization header"}

   Next, you will address the missing authorization error by configuring an API product and developer app
   on Edge so that you can get a valid API key. When you add the key to an authorization
   header for the API call, the call will succeed, and you will not see this error.

### Create components on Apigee Edge

Next, create an API product and a developer app on Apigee Edge.

### Create an API product

1. Log in to Apigee Edge.
2. Select **Publish \> API Products** in the side navigation menu.
3. Click **+ API Product**. The Product Page Appears.
4. Fill out the Product page as follows. For fields that are not mentioned below, you
   can use the default values. Do not Save until instructed to do so.

   |---|---|
   | **Name** | `hello-world-product` |
   | **Display Name** | `Edge Micro hello product` |
   | **Environment** | `test` |

   <br />

5. In the Path section, click **+ Custom Resource**.

6. Add the path `/`.

7. Click **+ Custom Resource** again and add the path `/**`

8. In the API Proxies section, click **+ API Proxy** and add **edgemicro-auth**.

9. Save the API Product.

### Create a Developer App

1. Select **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 a developer from the dropdown menu. |

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

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
   the `helloworld` service.

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.

### Call the API

After the configuration changes are pulled into the microgateway, you can
perform the following tests.

1. Call the API without an API key. You will get an error message, as shown
   below:

   ```
   curl $GATEWAY_IP
   ```

   Expected output:

       {"error":"missing_authorization","error_description":"Missing Authorization
       header"}

   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
   ```

   For example:

   ```
   curl -H "x-api-key:DeX2eEesYAdRJ5Gdbo77nT9uUfJZql19" $GATEWAY_IP
   ```

   Output:

       Hello world

   The "Hello world" response is returned by the helloworld service deployed
   to the pod. The call to that service passed through Edge Microgateway first,
   where the authentication was performed. If you see the "Hello world"
   response, then you have successfully configured Edge Microgateway to
   function as a sidecar proxy in the helloworld service pod.

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