Deploy Edge Microgateway as a sidecar proxy

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

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

  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.

    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

  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 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 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 service. The webhook service is required for automatic sidecar injection:

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

  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.

    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
      ********************************************************************************************************
      
  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:

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.

  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

  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.

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 section for information on adding custom plugins, scaling deployment, making configuration changes, and other tasks you may wish to perform.