Overview

When you build proxies, it is important to not hardcode environment-specific configuration in a proxy.

In this lab, you will add a new environment and environment group to your organization. You will then use an environment-specific target server to specify the backend target URL.

Objectives

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

• Create a new environment and environment group within an organization, and attach the environment to the runtime instance.
• Create a named target server in an environment.
• Modify a proxy to call a named target server instead of a hardcoded URL.

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:

gcloud auth list

Output:

Credentialed accounts: - @.com (active)

Example output:

Credentialed accounts: - google1623327_student@qwiklabs.net

• You can list the project ID with this command:

gcloud config list project

Output:

[core] project =

Example output:

[core] project = qwiklabs-gcp-44776a13dea667a6 Note: Full documentation of gcloud is available in the gcloud CLI overview guide .

Preloaded assets

This asset has already been added to the Apigee organization:

• The retail-v1 API proxy

Note: Revision 1 of the retail-v1 proxy is marked as deployed, and is immutable. If you ever make a mistake in your proxy code that you can't recover from, you can select revision 1 and restart editing from there.

Task 1. Create a prod environment and environment group

In this task, you create a new environment group and environment for an organization.

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.

Examine eval environment group and environment

1. On the left navigation menu, select Management > Environments.

2. Click on the eval environment.

   Note: This lab uses an Apigee evaluation organization. By default, an evaluation organization has a single environment named "eval."

   This page shows the details for the eval environment. The eval environment is in the eval-group environment group.

   If the runtime is not yet available, you will be able to deploy API proxies to the environment, but the proxies will not accept API requests until the runtime is up, and the eval environment is attached.

   Once the runtime is up and the environment is attached, the runtime will query the management plane for the current API proxy deployments, and the runtime will host the API proxy and accept traffic.

3. In the left menu, click Management > Environments, and then select the Environment Groups tab.

   The page should show the default environment group named eval-group. It shows the hostnames and environments that are in the environment group. You should see the eval environment, as well as an example.com hostname. Selecting Edit from the more menu () lets you edit the environment group's hostnames and environments.

Create a prod environment group

1. Click +Create Environment Group.

2. Specify the following environment group settings:

   Property	Value
   Environment group name	prod-group
   Hostnames	prod.example.com

   Do not set Environments (optional).

3. Click Create.

Create a prod environment

1. Select the Environments tab, and then click +Create Environment.

2. Specify the following environment settings:

   Property	Value
   Name	prod
   Display name	Prod
   Environment group	select prod-group, and then click OK
   Deployment type	select Proxy

   Do not select the instance yet.

   Note: The "Deployment type" setting controls the type of proxy development and deployment you will do within an environment.
   The "Proxy" deployment type is done using the Apigee UI, and is the type of development and deployment used in the labs for this course.

3. Click Create.

   The status of the new prod environment is Inactive (not attached to an instance). A target server may be created for the environment, but proxies deployed to the environment won't handle traffic until the environment is successfully attached to an instance.

Task 2. Create a new target server for the eval environment

In this task, you create a new target server configuration for the eval environment.

Create a new target server

1. On the left navigation menu, select Management > Environments, and then click eval.

2. Select the Target Servers tab, and then click +Create Target Server.

3. Specify the following target server values:

   Property	Value
   Enable Target Server	selected
   Target Server name	TS-Retail
   Host	gcp-cs-training-01-test.apigee.net
   Protocol	select HTTP
   Port	443
   Enable SSL	selected

   When the SSL box is selected, the dialog shows additional configuration fields. Leave the default SSL values set to their defaults.

4. Click Create.

Task 3. Create a target server in the prod environment

In this task, you create a target server for the prod environment.

1. On the left navigation menu, select Management > Environments, and then click prod.

2. Select the Target Servers tab, and then click +Create Target Server.

3. Specify the following target server values:

   Property	Value
   Enable Target Server	selected
   Target Server name	TS-Retail
   Host	gcp-cs-training-01-prod.apigee.net
   Protocol	select HTTP
   Port	443
   Enable SSL	selected

   These settings are identical to the settings for the eval target server, except for the Host.

4. Click Create.

Task 4. Update the API proxy to use the target server

In this task, you modify your retail API proxy to use the target server instead of the hardcoded target URL.

Update the API proxy

1. On the left navigation menu, select Proxy development > API proxies, and then click retail-v1.

2. Click the Develop tab.

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

3. In the Navigator pane, click Target Endpoints > default.

   The TargetEndpoint configuration is displayed in the Code box.

4. In the HTTPTargetConnection section, on line 16, is the hardcoded URL.

   Replace the hardcoded URL with a reference to the target server you created.

   Replace:

   <HTTPTargetConnection> <Properties/> <URL>https://gcp-cs-training-01-test.apigee.net/training/db</URL> </HTTPTargetConnection>

   with:

   <HTTPTargetConnection> <LoadBalancer> <Server name="TS-Retail"/> </LoadBalancer> <Path>/training/db</Path> </HTTPTargetConnection>

   Note that /training/db is now specified in the Path element. The target server, TS-Retail, specifies the hostname that will be used.

   Combined, the URL used for the call to the backend will be the same as the hardcoded URL in the eval environment. When deployed to the prod environment, the hostname will automatically change for the prod backend without any changes to the code.

5. To save the changes, click Save.

   The message box indicates that the changes could not be saved to revision 1 because it is deployed.

6. Click Save As New Revision.

7. Click Deploy.

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

   Note: Leave the "Service Account" field empty.

9. Click Confirm.

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

• Learn more about load balancing across backend servers.
• Learn more about environments and environment groups.

Task 5. Attach the prod environment to the runtime instance

You can now deploy proxies to the prod environment, but they will not run unless the prod environment is attached to an instance.

Attach the prod environment to the instance

1. In Cloud Shell, to attach the prod environment to the instance, run the following commands:

   export ATTACHING_ENV=prod export INSTANCE_NAME=eval-instance curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -X POST "https://apigee.googleapis.com/v1/organizations/${GOOGLE_CLOUD_PROJECT}/instances/${INSTANCE_NAME}/attachments" \ --data "{ \"environment\": \"${ATTACHING_ENV}\" }"

   You should be notified that the attachment is in progress. The operation may take a few minutes to complete.

2. To check the status of the prod attachment, run the following commands:

   export ATTACHING_ENV=prod export INSTANCE_NAME=eval-instance echo "waiting for ${ATTACHING_ENV} attachment" while : ; do export ATTACHMENT_DONE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${GOOGLE_CLOUD_PROJECT}/instances/${INSTANCE_NAME}/attachments" | jq "select(.attachments != null) | .attachments[] | select(.environment == \"${ATTACHING_ENV}\") | .environment" --join-output); [[ "${ATTACHMENT_DONE}" != "${ATTACHING_ENV}" ]] || break; echo -n "."; sleep 5; done; echo echo "${ATTACHING_ENV} environment attached";

   Leave this command running in Cloud Shell.

   The eval environment should be ready to serve traffic, so you can test the API proxy in the eval environment now.

Deploy the proxy to the prod environment

1. On the left navigation menu, select Proxy development > API proxies, and then click retail-v1.

2. Select the Develop tab.

3. Click Deploy.

4. To specify that you want the latest revision deployed to the prod environment, select prod as the Environment, and then click Deploy.

5. Click Confirm.

   The proxy will not finish deploying until the prod environment has fully attached to the runtime instance.

Task 6. Test the API proxy in the eval environment

In this task, you use the debug tool to verify that the updated proxy still successfully calls the backend service.

Start the debug tool

1. Select the Debug tab.

2. Click Start Debug Session.

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

   The deployed revision number will also show in the dropdown.

4. Click Start.

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.

Call the API proxy

1. To make a call to proxy hosted in the eval environment, in the Cloud Shell SSH session, send a request to your API proxy by using this command:

   curl -i -k -X GET "https://eval.example.com/retail/v1/categories"

   The response from the curl command should be a 200 status code if your backend URL was correctly set. The backend service set the response headers, including the header named backend. In this case, the value of the backend header is test.

   A transaction for this request should soon appear in the Transactions pane on the left. If the transaction doesn't show up, try sending the request again.

   Note: Apigee debug traffic is retrieved by asynchronously polling for new API calls, so there may be a delay between when an API request is completed, and when it shows in the debug tool.

2. Select a transaction in the Transactions pane.

   When a transaction is selected, you'll see a trace of the request and response through Apigee.

3. In the transaction details pane, click Target Response Flow Started.

   In Response headers, you see that the backend sent a header named backend with a value of test.

   You can also see this header in the response from the curl command.

4. In the transaction details pane, click AnalyticsPredefinedVariablesPublisher.

   Apigee captures analytics for the API calls that travel through your proxies. This step in the transaction details shows the variables that were captured.

Task 7. Test the API proxy in the prod environment

In this task, you use the debug tool to test that the proxy, when deployed to the prod environment, calls the prod backend service.

Check to see whether the prod environment is attached yet

1. In the first Cloud Shell tab, confirm that the prod environment attachment has finished.

   Note: You ran a set of commands at the end of Task 5 that indicate when the prod environment is attached. You can rerun those commands if necessary.

2. Select the Debug tab.

3. Click Start Debug Session.

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

5. Click Start.

6. To make a call to proxy hosted in the prod environment, in the SSH session, send the following curl command:

   curl -i -k -X GET "https://prod.example.com/retail/v1/categories"

   The value of the backend header is prod.

7. Verify the analytics variables for the prod request.

Congratulations!

In this lab, you changed your API proxy to use a target server instead of the hardcoded target URL. You can now run your proxy in different environments without changing the target URL in the proxy code.

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.