Kubernetes integration tasks

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

Adding a custom plugin

You can add new features and capabilities to the microgateway by writing custom plugins. Custom plugins let you interact programmatically with the requests and responses that flow through the microgateway.

This section explains how to package and deploy plugins to an Edge Microgateway instance running in your Kubernetes cluster.

The rest of this section assumes that you are familiar with writing and configuring plugins for a standard Edge Microgateway setup. If not, see Develop custom plugins.

Package your plugin(s)

To package custom plugin(s), follow these steps:

Write and test your plugin, according to the directions in Write a simple plugin.
Place your plugin code in the proper directory structure. Plugin directories must follow a set structure. The following example shows the structure you must follow, where response-uppercase and request-headers are the names of folders containing custom plugin code (these names are examples only, your folder names may differ):
```
plugin
  |
  |-- plugins
    |
    |- response-uppercase
    |     |- index.js
    |     |- package.json
    |- request-headers
    |     | - index.js
          | - package.json
```
cd to the plugin folder.
In the plugin folder, zip the entire plugins folder:
```
zip -r plugins.zip plugins/
```

Create a Docker image

In the same directory where the zip file is located, create a new file called Dockerfile.

Add the following code to Dockerfile and save the file:

FROM gcr.io/apigee-microgateway/edgemicro:latest
RUN apt-get install unzip
COPY plugins.zip /opt/apigee/
RUN chown apigee:apigee /opt/apigee/plugins.zip
RUN su - apigee -c "unzip /opt/apigee/plugins.zip -d /opt/apigee"
EXPOSE 8000
EXPOSE 8443
ENTRYPOINT ["entrypoint"]

Create a new Edge Microgateway Docker image with your plugins and push the image to your docker registry. You can use whichever registry you wish, such as docker.io or gcr.io:
```
docker build -t edgemicroplugins .
docker tag edgemicroplugins container-registry/your-project/edgemicroplugins
docker push container-registry/your-project/edgemicroplugins
```
For example:
```
docker build -t edgemicroplugins .
docker tag edgemicroplugins gcr.io/my-project/edgemicroplugins
docker push   gcr.io/my-project/edgemicroplugins
```
Note: If using Google Container Registry (GCR), be sure the uploaded image has appropriate permissions. For example, to serve the image publicly, make the storage bucket of the Container Registry publicly accessible by running the following command. For example: gsutil iam ch allUsers:objectViewer gs://[BUCKET_NAME]

Update the Edge Microgateway configuration

Add the plugin(s) to your Edge Microgateway configuration file. You can find the config file here:
```
$HOME/.edgemicro/org-env-config.yaml
```
For example:
```
$HOME/.edgemicro/myorg-test-config.yaml
```

In the following sample config, the custom plugin response-uppercase was added. The oauth plugin was already there by default.

  edgemicro:
    ...
    plugins:
      sequence:
        - oauth
        - response-uppercase

Update your Kubernetes cluster

The final step is to apply the configuration change to your Kubernetes cluster. Kubernetes will pull the new image with the plugin code that you pushed to the container registry and use it for any newly created pods.

If you deployed Edge Microgateway as a service

Use the edgemicroctl command to inject the updated Edge Microgateway configuration:

Update the Edge Microgateway deployment with the new image. For example:
```
kubectl apply -f <(edgemicroctl -org=your_organization -env=your_environment -key=configuration_key -sec=configuration_secret -conf=config_file_path -img=container-registry/your_project_name/image_name:latest)
```
where:
- your_organization - The Apigee organization you specified in the edgemicro configure command.
- your_environment - The environment you specified in the edgemicro configure command.
- configuration_key - The key returned from the edgemicro configure command.
- configuration_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.
- container-registry - The Docker registry where you pushed the image. For example, gcr.io or docker.io.
- your_project_name - The project name for the Docker repository where you pushed the Docker image.
- image_name - The name of the Docker image you pushed.
Example:
```
kubectl apply -f <(edgemicroctl -org=jdoe -env=test -key=f2d2eaa52b758493d00cec656e574ac947bee1d701c5c5f3295e5eaa39a3b -sec=0c38cda3fac6c59152f15657052ba1728f8003c1a763cf08da2a -conf=/Users/jdoe/.edgemicro/apigeesearch-test-config.yaml -img=gcr.io/jdoe-project/edgemicroplugins:latest)
```
Test the plugin. Call the API to see if you get the expected behavior. For example, for "response uppercase" plugin, the response text is converted to all uppercase, as shown below:
```
curl $GATEWAY_IP -H 'x-api-key:3eqeedJRFLlCshwWBiXq4xKFoH1Se3xR'
```
Output:
```
HELLO WORLD
```

Manually injecting the new configuration

Manual injection is a straightforward approach, where you inject the new configuration from the command line.

Execute the following command:
```
kubectl apply -f <(edgemicroctl -org=your_org -env=your_env -key=your_key -sec=your_secret -conf=config_file_path -img=container-registry/your_project_name/image_name:latest -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.
- container-registry - The Docker registry where you pushed the image. For example, gcr.io or docker.io.
- your_project_name - The project name for the Docker repository where you pushed the Docker image.
- image_name - The name of the Docker image you pushed.
- service_deployment_file - The path to the deployment file of the service for which the plugin(s) will apply. 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 -img=gcr.io/myproject/edgemicroplugins:latest -svc=samples/helloworld/helloworld.yaml)
```
Test the plugin. Call the service API to see if you get the expected behavior. For example, for "response uppercase" plugin, the response text is converted to all uppercase, as shown below:
```
curl $GATEWAY_IP -H 'x-api-key:3eqeedJRFLlCshwWBiXq4xKFoH1Se3xR'
```
Output:
```
HELLO WORLD
```

Making Edge Microgateway configuration changes

In some cases, you may need to modify your Edge Microgateway configuration. For example, you might want to add a new plugin to Edge Microgateway or change a configuration parameter. This section explains how to make and apply configuration changes to Edge Microgateway running in Kubernetes.

Create a configuration file secret.yaml as shown below:

apiVersion: v1
kind: Secret
metadata:
  name: mgwsecret
type: Opaque
data:
  mgorg: EDGEMICRO_ORG
  mgenv: EDGEMICRO_ENV
  mgkey: EDGEMICRO_KEY
  mgsecret: EDGEMICRO_SECRET
  mgconfig: EDGEMICRO_CONFIG

Specify the base64 encoded value of EDGEMICRO_ORG, EDGEMICRO_ENV, EDGEMICRO_KEY, EDGEMICRO_SECRET:

echo -n "your-org" | base64 | tr -d '\n'
echo -n "your-org-env" | base64 | tr -d '\n'
echo -n "your-mg-key" | base64 | tr -d '\n'
echo -n "your-mg-secret" | base64 | tr -d '\n'

Make your changes to the Edge Microgateway configuration file for your organization and environment:
```
$HOME/.edgemicro/your_org-your_env-config.yaml
```

Base64 Encode twice the contents of config file:

cat $HOME/.edgemicro/org-env-config.yaml | base64 | tr -d '\n' | base64  | tr -d '\n'

Apply changes to kubernetes on the namespace where your service is running.
```
kubectl apply -f secret.yaml -n 
```

These new changes are not picked up automatically by existing microgateway pods; however, the new pods will get the changes. You can delete the existing pod so that deployment creates a new pod that picks up the change.

Service example

The following example illustrates how to update a service deployment with a new

Get the pods.

kubectl get pods

Example output:

NAME                                 READY     STATUS    RESTARTS   AGE
edge-microgateway-57ccc7776b-g7nrg   1/1       Running   0          19h
helloworld-6987878fc4-cltc2          1/1       Running   0          1d

Delete the edge-microgateway pod.

kubectl delete pod edge-microgateway-57ccc7776b-g7nrg

Example output:

pod "edge-microgateway-57ccc7776b-g7nrg" deleted

Get the pods again. A new pod spins up and gets your configuration changes.

kubectl get pods

Example output:

NAME                                 READY     STATUS    RESTARTS   AGE
edge-microgateway-57ccc7776b-7f6tc   1/1       Running   0          5s
helloworld-6987878fc4-cltc2          1/1       Running   0          1d

Scaling your deployment

This section explains how you can use Kubernetes scaling principles to scale your deployments.

Scaling a service deployment

Check the deployments:

kubectl get deployments

Example output:

NAME                DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
edge-microgateway   1         1         1            1           18h
helloworld          1         1         1            1           1d

The output indicates one replica is deployed.

Scale the deployment from 1 to as many replicas as you wish. In this example, the edge-microgateway service is scaled.
```
kubectl scale deployment edge-microgateway --replicas=2
```

(Optional) If you want to use autoscaling, use this command:

kubectl autoscale deployment edge-microgateway --cpu-percent=50 --min=1 --max=10

Check the deployments to verify scaling is enabled:

kubectl get deployments

Example output:

NAME                DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
edge-microgateway   2         2         2            2           18h
helloworld          1         1         1            1           1d

The state has been changed to include two replicas.

Check the pods:

kubectl get pods

Example output:

NAME                                 READY     STATUS    RESTARTS   AGE
edge-microgateway-57ccc7776b-g7nrg   1/1       Running   0          18h
edge-microgateway-57ccc7776b-rvfz4   1/1       Running   0          41s
helloworld-6987878fc4-cltc2          1/1       Running   0          1d

The output shows both replicas are in a running state.

Use namespaces for multiple Edge Microgateway configurations

You can deploy and configure multiple instances of Edge Microgateway services to your Kubernetes cluster. This use case allows you to configure each microgateway instance with its own set of plugins and parameters. For example:

Edge Microgateway Service A requires only the spike arrest plugin.
Edge Microgateway Service B requires the quota and oauth plugin, but not spike arrest.

To address this use case, use Kubernetes namespaces. For example, you can deploy Edge Microgateway Service A to namespace foo, and Edge Microgateway Service B to namespace bar.

In the following example, Edge Microgateway configured in organization OrgA is deployed as a service to namespace foo using the -n option:

kubectl apply -f <(edgemicroctl -org=myorgA -env=test-key=0e3ecea28a64099410594406b30e54439af5265f8 -sec=e3919250bee37c69cb2e5b41170b488e1c1d -conf=/Users/joed/.edgemicro/orgA-test-config.yaml -svc=samples/helloworld/helloworld.yaml) -n foo

Similarly, in the following example, Edge Microgateway configured in organization OrgB is deployed as a service to namespace bar using the -n option:

kubectl apply -f <(edgemicroctl -org=myorgB -env=test-key=0e3ecea28a64099410594406b30e54439af5265f8 -sec=e3919250bee37c69cb2e5b41170b488e1c1d -conf=/Users/joed/.edgemicro/orgB-test-config.yaml -svc=samples/helloworld/helloworld.yaml) -n bar