Deploy Edge Microgateway as a sidecar proxy

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

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.

Before you begin

Complete the steps described in Prerequisites.

Deploy a test service

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

Deploy the sample:

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

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: 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.
Delete the test service deployment. You will reinstall it later, after you enable sidecar injection:
```
 kubectl delete -f samples/helloworld/helloworld.yaml --namespace=default
```

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.

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

Inject Edge Microgateway as a sidecar

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

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

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

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

Now, you are ready to test the sidecar deployment of Edge Microgateway. Go to 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

Install the ConfigMap that enables sidecar injection of Edge Microgateway:

kubectl apply -f install/kubernetes/edgemicro-sidecar-injector-configmap-release.yaml

Execute the following script to install the webhook service. The webhook service is required for automatic sidecar injection:

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

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

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

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

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.

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.

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: You can also pass parameters to the script for non-interactive use. See the comments in ./install/kubernetes/webhook-edgemicro-patch.sh for details.
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
```

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

Run this command to enable webhook injection for the webhook:
```
kubectl label namespace default edgemicro-injection=enabled
```

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:

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

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

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:]")

Verify that the variable was exported. For example:
```
echo $GATEWAY_IP
```
Example output:
```
35.238.249.62
```
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

Log in to Apigee Edge.
Select Publish > API Products in the side navigation menu.
Click + API Product. The Product Page Appears.
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
In the Path section, click + Custom Resource.
Add the path /.
Click + Custom Resource again and add the path /**
In the API Proxies section, click + API Proxy and add edgemicro-auth.
Save the API Product.

Create a Developer App

Select 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 a developer from the dropdown menu.
In the Credentials section, click + Product and select the hello-world-product you just created.
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 the helloworld service.
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.

Call the API

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

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

Name	`hello-world-app`
Display Name	`Edge Micro hello app`
Developer	Select a developer from the dropdown menu.