Overview

In this lab, you learn about two policies that can be used for traffic management: SpikeArrest and Quota.

Objectives

In this lab, you learn how to perform the following tasks:

• Rate-limit traffic by using a SpikeArrest policy.
• Limit the number of orders that are created allowed for an entity by using a Quota policy.
• Configure quota limits in an API product.

Setup

For each lab, you get a new Google Cloud project and set of resources for a fixed time at no cost.

1. Sign in to Qwiklabs using an incognito window.

2. Note the lab's access time (for example, 1:15:00), and make sure you can finish within that time.
   There is no pause feature. You can restart if needed, but you have to start at the beginning.

3. When ready, click Start lab.

4. Note your lab credentials (Username and Password). You will use them to sign in to the Google Cloud Console.

5. Click Open Google Console.

6. Click Use another account and copy/paste credentials for this lab into the prompts.
   If you use other credentials, you'll receive errors or incur charges.

7. Accept the terms and skip the recovery resource page.

Activate Google Cloud Shell

Google Cloud Shell is a virtual machine that is loaded with development tools. It offers a persistent 5GB home directory and runs on the Google Cloud.

Google Cloud Shell provides command-line access to your Google Cloud resources.

1. In Cloud console, on the top right toolbar, click the Open Cloud Shell button.

   

2. Click Continue.

It takes a few moments to provision and connect to the environment. When you are connected, you are already authenticated, and the project is set to your PROJECT_ID. For example:

gcloud is the command-line tool for Google Cloud. It comes pre-installed on Cloud Shell and supports tab-completion.

• You can list the active account name with this command:

Output:

Example output:

• You can list the project ID with this command:

Output:

Example output:

Preloaded assets

These assets have already been added to the Apigee organization:

• The retail-v1 API proxy
• The oauth-v1 API proxy (for generating OAuth tokens)
• The backend-credentials shared flow (used by retail-v1)
• The TS-Retail target server in the eval environment (used by retail-v1)

These assets will be added to the Apigee organization as soon as the runtime is available:

• The API products, developer, and developer app (used by retail-v1)
• The ProductsKVM key value map in the eval environment (used by backend-credentials)
• The ProductsKVM key value map entries backendId and backendSecret

The highlighted items are used during this lab.

Task 1. Add a SpikeArrest policy

In this task, you add a SpikeArrest policy to protect against traffic surges.

Pin the Apigee console page

1. In the Google Cloud console, on the Navigation menu (), look for Apigee in the Pinned Products section.

   The Apigee console page will open.

2. If Apigee is not pinned, search for Apigee in the top search bar and navigate to the Apigee service.

3. Hover over the name, then click the pin icon ().

   The Apigee console page will now be pinned to the Navigation menu.

Create the policy

1. On the left navigation menu, select Proxy development > API proxies.

2. Select the retail-v1 proxy.

3. Click the Develop tab.

   You are modifying the version of the retail-v1 proxy that was created during Labs 1 through 10.

4. In the Navigator menu, click Proxy endpoints > default > PreFlow.

5. On the Request PreFlow flow, click Add Policy Step (+).

6. In the Add policy step pane, select Create new policy, and then select Traffic Management > Spike Arrest.

7. Specify the following values:

   Property	Value
   Name	SA-SpikeArrest
   Display name	SA-SpikeArrest

8. Click Add.

9. Click Policies > SA-SpikeArrest.

10. Replace the SpikeArrest configuration with:

    <SpikeArrest continueOnError="false" enabled="true" name="SA-SpikeArrest"> <Rate>2pm</Rate> </SpikeArrest>

    The rate of "2pm" indicates that requests will be allowed at a rate of only 2 per minute, or 1 per 30 seconds. This means that a request is allowed only if the previous request on the message processor was more than 30 seconds ago. The SpikeArrest rate is a sustained rate, and you might be able to make several requests in a row without being blocked.

    There may be multiple message processors running your proxy.

    Note: Two requests per minute is a very low SpikeArrest rate. This rate has been chosen only for ease of testing.

11. Click Proxy endpoints > default > PreFlow.

12. Drag the SpikeArrest policy to be first in the PreFlow.

    

13. Click Save, and then click Save as New Revision.

Task 2. Add a Quota policy

In this task you will add a Quota policy to limit the number of orders allowed for an app over a specific period of time.

1. In the Navigator pane, click Proxy endpoints > default > createOrder.

2. On the Request createOrder flow, click Add Policy Step (+).

3. In the Add policy step pane, select Create new policy, and then select Traffic Management > Quota.

4. Specify the following values:

   Property	Value
   Name	Q-EnforceQuota
   Display name	Q-EnforceQuota

5. Click Add.

6. Click Policies > Q-EnforceQuota.

7. Change the Quota configuration to:

   <Quota continueOnError="false" enabled="true" name="Q-EnforceQuota" type="calendar"> <Identifier ref="client_id"/> <UseQuotaConfigInAPIProduct stepName="VA-VerifyKey"> <DefaultConfig> <Allow>2</Allow> <Interval>1</Interval> <TimeUnit>hour</TimeUnit> </DefaultConfig> </UseQuotaConfigInAPIProduct> <Distributed>true</Distributed> <Synchronous>true</Synchronous> <StartTime>2021-01-01 00:00:00</StartTime> </Quota>

   You will be using the API product to specify the allowed rate. The stepName in the UseQuotaConfigInAPIProduct element specifies which step will determine the API product. When an API key or OAuth token is validated, it can be associated with an app that is associated with an API product. Using these policy settings, the VerifyAPIKey step called VA-VerifyKey determines the API product. The VerifyAPIKey policy must run before the Q-EnforceQuota policy.

   The quota policy is typically added after error checking is complete so that an error does not count against the quota. The createOrder request flow should now look like this:

   

   The default configuration values specified in the Quota policy specify a maximum of 2 (Allow) transactions per 1 (Interval) month (TimeUnit). The default values will only be used if the values are not available, which should only happen if the quota settings are not set for the API product associated with the API key.

   The Distributed element is set to true, so the Quota counter will be shared by all message processors.

8. Click Save, and then click Save as New Revision.

9. Click Deploy.

10. To specify that you want the new revision deployed to the eval environment, select eval as the Environment, and then click Deploy.

Check deployment status

A proxy that is deployed and ready to take traffic will show a green status on the Overview tab.

When a proxy is marked as deployed but the runtime is not yet available and the environment is not yet attached, you may see a red warning sign. Hold the pointer over the Status icon to see the current status.

If the proxy is deployed and shows as green, your proxy is ready for API traffic. If your proxy is not deployed because there are no runtime pods, you can check the provisioning status.

Check provisioning status

• In Cloud Shell, to confirm that the runtime instance has been installed and the eval environment has been attached, run the following commands:

  export PROJECT_ID=$(gcloud config list --format 'value(core.project)'); echo "PROJECT_ID=${PROJECT_ID}"; export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; export PREV_INSTANCE_STATE=; echo "waiting for runtime instance ${INSTANCE_NAME} to be active"; while : ; do export INSTANCE_STATE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}" | jq "select(.state != null) | .state" --raw-output); [[ "${INSTANCE_STATE}" == "${PREV_INSTANCE_STATE}" ]] || (echo; echo "INSTANCE_STATE=${INSTANCE_STATE}"); export PREV_INSTANCE_STATE=${INSTANCE_STATE}; [[ "${INSTANCE_STATE}" != "ACTIVE" ]] || break; echo -n "."; sleep 5; done; echo; echo "instance created, waiting for environment ${ENV_NAME} to be attached to instance"; while : ; do export ATTACHMENT_DONE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}/attachments" | jq "select(.attachments != null) | .attachments[] | select(.environment == \"${ENV_NAME}\") | .environment" --join-output); [[ "${ATTACHMENT_DONE}" != "${ENV_NAME}" ]] || break; echo -n "."; sleep 5; done; echo "***ORG IS READY TO USE***";

  When the script returns ORG IS READY TO USE, you can proceed to the next steps.

While you are waiting

While you wait, learn more about policies by reviewing:

• SpikeArrest policy
• Quota policy

Task 3. Test the spike arrest

In this task, you validate that request spikes are rejected.

Test the API proxy using private DNS

The eval environment in the Apigee organization can be called using the hostname eval.example.com. The DNS entry for this hostname has been created within your project, and it resolves to the IP address of the Apigee runtime instance. This DNS entry has been created in a private zone, which means it is only visible on the internal network.

Cloud Shell does not reside on the internal network, so Cloud Shell commands cannot resolve this DNS entry. A virtual machine (VM) within your project can access the private zone DNS. A virtual machine named apigeex-test-vm was automatically created for this purpose. You can make API proxy calls from this machine.

The curl command will be used to send API requests to an API proxy. The -k option for curl tells it to skip verification of the TLS certificate. For this lab, the Apigee runtime uses a self-signed certificate. For a production environment, you should use certificates that have been created by a trusted certificate authority (CA).

1. In Cloud Shell, open a new tab, and then open an SSH connection to your test VM:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   The first gcloud command retrieves the zone of the test VM, and the second opens the SSH connection to the VM.

2. If asked to authorize, click Authorize.

   For each question asked in the Cloud Shell, click Enter or Return to specify the default input.

   Your logged in identity is the owner of the project, so SSH to this machine is allowed.

   Your Cloud Shell session is now running inside the VM.

Store the app's key in a shell variable

The API key may be retrieved directly from the app accessible on the Publish > Apps page. It can also be retrieved via Apigee API call.

• In the Cloud Shell SSH session, run the following command:

  export PROJECT_ID=$(gcloud config list --format 'value(core.project)'); echo "PROJECT_ID=${PROJECT_ID}" export API_KEY=$(curl -q -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/retail-app" | jq --raw-output '.credentials[0].consumerKey'); echo "export API_KEY=${API_KEY}" >> ~/.bashrc; echo "API_KEY=${API_KEY}"

  This command retrieves a Google Cloud access token for the logged-in user, sending it as a Bearer token to the Apigee API call. It retrieves the retail-app app details as a JSON response, which is parsed by jq to retrieve the app's key. That key is then put into the API_KEY environment variable, and the export command is concatenated onto the .bashrc file which runs automatically when starting a the SSH session.

  Note: If you run the command and it shows API_KEY=null, the runtime instance is probably not yet available.

Make requests until you get a spike arrest failure

• In the Cloud Shell SSH session, send this curl request until you get a spike arrest failure:

  curl -i -k -X GET -H "apikey:${API_KEY}" "https://eval.example.com/retail/v1/categories" Note: To quickly repeat a command in Cloud Shell, click the UP arrow key and then press RETURN or ENTER.

  You should receive 200 responses until the SpikeArrest raises a fault. It may take several requests to make it fail because each message processor is separately tracking the time that traffic is received.

  You should eventually receive a 429 Too Many Requests error that looks like this:

  { "fault": { "faultstring": "Spike arrest violation. Allowed rate : MessageRate{messagesPerPeriod=2, periodInMicroseconds=60000000, maxBurstMessageCount=1.0}", "detail": { "errorcode": "policies.ratelimit.SpikeArrestViolation" } } } Note: The variable "system.uuid" is unique for each message processor. This variable can be useful if you want to distinguish requests that are handled by different message processors.

  Two requests per minute is a very low value. Now that you have confirmed that the SpikeArrest policy works, you will allow a much faster rate.

Update the SpikeArrest policy

1. On the Navigator pane, click Policies > SA-SpikeArrest.

2. In the policy configuration, replace the rate of 2pm with 100ps.

   A rate of 100 per second will make it difficult to accidentally cause a spike arrest.

3. Click Save, and then click Save as New Revision.

4. Click Deploy.

5. To specify that you want the new revision deployed to the eval environment, select eval as the Environment, and then click Deploy.

   Wait for the updated proxy to be deployed.

Task 4. Test the quota

In this task, you validate that the quota properly limits requests.

Test default configuration

• In the Cloud Shell SSH session, send this request until you get a quota failure:

  curl -i -k -H "Content-Type: application/json" -H "apikey: ${API_KEY}" -X POST "https://eval.example.com/retail/v1/orders" -d \ '{ "orderNumber": 342345, "lineItems": [ { "productId": "ME089LLA", "quantity": 1 }, { "productId": "MD388LLA", "quantity": 2 } ], "promisedDeliveryDate": "30 Oct 2020", "deliveryNotes": "If not home, please place inside backyard gate", "destination": { "addressType": "home", "address": { "streetAddr1": "1 Main St." } } }'

  You should quickly get a quota error that looks like this:

  { "fault": { "faultstring": "Rate limit quota violation. Quota limit exceeded. Identifier : VEq0HFZwGvcDGUOYmIRxx6p2I6LFyB2BTLWCKJcECOt4j2yb", "detail": { "errorcode": "policies.ratelimit.QuotaViolation" } } }

  Because there are no quota settings in the API product, the default configuration in the policy is 2 requests per 1 hour.

Add a quota to the operation in the API product

1. On the left navigation menu, click Distribution > API Products.
2. Select retail (full access).
3. Click Edit.
4. In the Operations section, click the Actions menu icon () and select Edit.
5. Set the operation's quota to 5 requests every 1 minute, and click Save to save the operation.
6. Click Save to save the API product.

Start a debug session

1. On the left navigation menu, click Proxy development > API proxies.

2. Click on the retail-v1 proxy.

   You should see that the proxy is deployed to the eval environment.

3. Click the Debug tab, and then click Start Debug Session.

4. In the Start debug session pane, on the Environment dropdown, select eval.

   The deployed revision number will also show in the dropdown.

5. Click Start.

Test API product configuration

1. In the Cloud Shell SSH session, send this request several times:

   curl -i -k -H "Content-Type: application/json" -H "apikey: ${API_KEY}" -X POST "https://eval.example.com/retail/v1/orders" -d \ '{ "orderNumber": 342345, "lineItems": [ { "productId": "ME089LLA", "quantity": 1 }, { "productId": "MD388LLA", "quantity": 2 } ], "promisedDeliveryDate": "30 Oct 2020", "deliveryNotes": "If not home, please place inside backyard gate", "destination": { "addressType": "home", "address": { "streetAddr1": "1 Main St." } } }'

2. Back in the Debug tool, select a request that was sent, and click the Quota policy.

   When you select the Quota policy, variables set by the Quota policy are displayed. The policy should read the API quota settings from the variables that were populated by the VerifyAPIKey policy:

   

   Note: These quota variables may remain empty for a short time after you change the API configuration. API product information is cached for a few minutes when it is read from the runtime data store. The updated values should be used when the API product information has expired from the cache. If you do not see the variables, send requests until you can see them.

   The Identifier element is set to the client_id variable, which is the API key that was verified. This variable was set by the VerifyAPIKey policy. Each app has a different API key, and therefore each app will be tracked separately.

   You should be able to send at least 5 successful requests before being rejected. If it took more requests than you expected to cause the quota violation, it may be because the quota is reset every 1 minute, indicated by the Interval and TimeUnit that were set in the API product operation.

Congratulations!

In this lab, you learned how to use the SpikeArrest and Quota policies and how to associate quota settings with an API product.

End your lab

When you have completed your lab, click End Lab. Google Cloud Skills Boost removes the resources you’ve used and cleans the account for you.

You will be given an opportunity to rate the lab experience. Select the applicable number of stars, type a comment, and then click Submit.

The number of stars indicates the following:

• 1 star = Very dissatisfied
• 2 stars = Dissatisfied
• 3 stars = Neutral
• 4 stars = Satisfied
• 5 stars = Very satisfied

You can close the dialog box if you don't want to provide feedback.

For feedback, suggestions, or corrections, please use the Support tab.

Copyright 2022 Google LLC All rights reserved. Google and the Google logo are trademarks of Google LLC. All other company and product names may be trademarks of the respective companies with which they are associated.