GSP906

Overview

In this lab, you learn how to add a new environment and environment group to an Apigee X org.

An environment is a runtime execution context for API proxies. An API proxy must be deployed to an environment before the API it exposes is accessible over the network.

An environment group is a logical grouping of environments. Hostnames are defined on an environment group, and Apigee routes requests to the environments within a group based on the hostname. The request will then be handled by an API proxy that is deployed to one of the environments in the environment group and also has a matching basepath.

The instructions in this lab are also appropriate for adding environments and environment groups to paid orgs.

Objectives

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

• Add a second environment to an Apigee X org
• Add a second environment group to an Apigee X org, assigning environments and hostnames
• Deploy an environment to a runtime instance
• Deploy and call an API proxy in each environment

Setup and requirements

Before you click the Start Lab button

Read these instructions. Labs are timed and you cannot pause them. The timer, which starts when you click Start Lab, shows how long Google Cloud resources will be made available to you.

This hands-on lab lets you do the lab activities yourself in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials that you use to sign in and access Google Cloud for the duration of the lab.

To complete this lab, you need:

• Access to a standard internet browser (Chrome browser recommended).

Note: Use an Incognito or private browser window to run this lab. This prevents any conflicts between your personal account and the Student account, which may cause extra charges incurred to your personal account.

• Time to complete the lab---remember, once you start, you cannot pause a lab.

Note: If you already have your own personal Google Cloud account or project, do not use it for this lab to avoid extra charges to your account.

How to start your lab and sign in to the Google Cloud console

1. Click the Start Lab button. If you need to pay for the lab, a pop-up opens for you to select your payment method. On the left is the Lab Details panel with the following:

   • The Open Google Cloud console button
   • Time remaining
   • The temporary credentials that you must use for this lab
   • Other information, if needed, to step through this lab

2. Click Open Google Cloud console (or right-click and select Open Link in Incognito Window if you are running the Chrome browser).

   The lab spins up resources, and then opens another tab that shows the Sign in page.

   Tip: Arrange the tabs in separate windows, side-by-side.

   Note: If you see the Choose an account dialog, click Use Another Account.

3. If necessary, copy the Username below and paste it into the Sign in dialog.

   {{{user_0.username | "Username"}}}

   You can also find the Username in the Lab Details panel.

4. Click Next.

5. Copy the Password below and paste it into the Welcome dialog.

   {{{user_0.password | "Password"}}}

   You can also find the Password in the Lab Details panel.

6. Click Next.

   Important: You must use the credentials the lab provides you. Do not use your Google Cloud account credentials. Note: Using your own Google Cloud account for this lab may incur extra charges.

7. Click through the subsequent pages:

   • Accept the terms and conditions.
   • Do not add recovery options or two-factor authentication (because this is a temporary account).
   • Do not sign up for free trials.

After a few moments, the Google Cloud console opens in this tab.

Note: To view a menu with a list of Google Cloud products and services, click the Navigation menu at the top-left.

Activate Cloud Shell

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. Cloud Shell provides command-line access to your Google Cloud resources.

1. Click Activate Cloud Shell at the top of the Google Cloud console.

When you are connected, you are already authenticated, and the project is set to your Project_ID, . The output contains a line that declares the Project_ID for this session:

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

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

2. (Optional) You can list the active account name with this command:

gcloud auth list

3. Click Authorize.

Output:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

4. (Optional) You can list the project ID with this command:

gcloud config list project

Output:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Note: For full documentation of gcloud, in Google Cloud, refer to the gcloud CLI overview guide.

Open the Apigee UI

The Apigee UI is accessed on a page separate from the Google Cloud Console. This lab has automatically created an Apigee organization that has the same name as the Google Cloud project.

• Click to open the Apigee UI.

  You may also open the Apigee UI from the Google Cloud Console by opening the Navigation menu () click View All Products under Integration Services select Apigee.

If you see an error indicating that the project does not have an organization provisioned, the tab might be trying to load the organization for a previous lab.

If you get this error:

• Click on the organization dropdown.

  

  The organization dropdown should show an organization that has the same name as the Google Cloud project.

  

  The organizations listed are those that are accessible by the logged-in user. For this lab, you should be logged in with the lab credentials provided in the Lab Details panel when you started the lab.

  You can navigate the Apigee UI using its left navigation menu. The landing page also shows quick links for navigating to commonly used locations.

Task 1. Examine the eval environment and environment group

In this task, you explore environments and environment groups using the Apigee console.

An evaluation org for Apigee X initially contains a single environment named eval and a single environment group named eval-group. The eval environment is a member of the eval-group environment group.

1. Select the Apigee Console tab in your browser window.
2. Navigate to Admin > Environments > Overview.
3. Click on the eval environment.

The eval environment has been configured as a member of the eval-group environment group.

The eval environment is marked "Ready for deployment," indicating that API proxies may be deployed to the environment.

4. Navigate to Admin > Environments > Groups.
5. On the eval-group environment group box, click Edit ().

A single hostname (eval.example.com) is currently listed for the eval-group environment group, but more than one hostname may be used.

The eval-group environment group currently contains the eval environment as its only member, but more than one environment may be in an environment group.

6. Click Cancel.

Task 2. Create a prod environment

In this task, you create a new environment.

1. Navigate to Admin > Environments > Overview.
2. In the upper right corner, click +Environment.

Note: Expand your browser window horizontally if you do not see the +Environment button.

3. Specify prod for Display name and Environment name. Other fields should remain unchanged.
4. Click Create.

You should get a message that the environment has been defined. The new prod environment is marked Pending Provisioning.

Shortly after, you should see the message that the environment is ready for use, and the environment will no longer be marked Pending Provisioning.

Click Check my progress to verify the objective. Create a prod environment

Task 3. Create a prod-group environment group

In this task, you create a new environment group.

1. Navigate to Admin > Environments > Groups.

A warning indicates that the prod environment is not assigned to an environment group.

2. In the upper right corner, click +Environment Group.

Note: Expand your browser window horizontally if you do not see the +Environment Group button.

3. Name the environment group prod-group, and then click Add.
4. In the prod-group environment group box, click the edit (pencil) button ().
5. In the Environments box, click the + button.
6. Select the prod environment, and then click Add.
7. In the Hostnames box, replace the existing hostname with:

prod.example.com

8. Click Save.

Click Check my progress to verify the objective. Create a prod-group environment group

Task 4. Wait for instance provisioning to complete

In this task, you wait for the Apigee evaluation org provisioning to complete.

The Apigee organization provisioning takes quite a while to complete. The org provisioning progress can be monitored by using the Apigee API.

Start monitoring script

1. Return to the Cloud Console tab.
2. On the top-right toolbar, click Activate Cloud Shell ().
3. If prompted, click Continue.

It takes a few moments to provision and connect to Cloud Shell. When you are connected, you are already authenticated, and the project is set to your PROJECT_ID.

4. In Cloud Shell, verify the variable with your Apigee org name:

echo ${GOOGLE_CLOUD_PROJECT}

The variable GOOGLE_CLOUD_PROJECT should contain the name of your project, which is the same as your Apigee organization name.

5. If the GOOGLE_CLOUD_PROJECT variable is not set, set the variable manually using a command that looks like this, replacing {project} with your project name:

export GOOGLE_CLOUD_PROJECT={project} Note: The curly braces should be removed during this step.

6. Run the following commands in the Cloud Shell:

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/${GOOGLE_CLOUD_PROJECT}/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/${GOOGLE_CLOUD_PROJECT}/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; echo "${ENV_NAME} environment attached"; echo "***ORG IS READY TO USE***";

This series of commands uses the Apigee API to determine when the runtime instance has been created, and then waits for the eval environment to be attached to the instance.

When the text ***ORG IS READY TO USE*** is printed, proxies deployed to the eval environment can accept traffic.

Note: Learn about Apigee X users and roles while waiting for the instance and environment to be fully created. Pay attention to the time remaining in the lab and periodically check the Cloud Shell output to see when the org can be tested.

Users and roles

Access to Apigee is granted by using users and roles. A user represents an authenticated account that can access an Apigee organization and the entities within the organization, such as environments and API proxies. The capabilities that you grant to the user depend on the type of *role *assigned to them.

To add a new user to your Apigee organization, you grant access to the user's account, first in the Cloud project, and then optionally in the Apigee UI. Permissions granted on a resource in the Google Cloud resource hierarchy are inherited by resources contained within the resource.

If an Apigee role is assigned to a user on the Cloud project, then the user can access all Apigee resources within the organization (including all environments) in that role. Within the Apigee UI, an Apigee role can also be assigned to a user for a specific environment. This permission is in addition to the role set at the project level.

To adhere to the principle of least privilege, the minimum permissions for a given user should be specified at the project level, with expanded permissions given at the environment level.

This image shows how inheritance works for this access model:

Apigee roles

This table summarizes the pre-defined Apigee roles.

Apigee role	Description
Apigee Org Admin	Full access to all Apigee resources in an Apigee organization.
Apigee Read Only Admin	Read-only access to all Apigee resources in an Apigee organization.
Apigee Analytics Editor	Creates and analyzes reports on API proxy traffic for an Apigee organization. Can edit queries and reports.
Apigee Analytics Viewer	User of Apigee Analytics. Cannot edit queries or reports.
Apigee API Admin	A developer who creates and tests API proxies.
Apigee Environment Admin	Deploys and undeploys API proxies in environments.
Apigee Developer Admin	Manages developer access to APIs.

Learn more about API permissions for each Apigee role from the Apigee roles guide.

Task 5. Add the prod environment to the runtime instance

In this task, you add the prod environment to the runtime instance, allowing proxies deployed to prod to be run.

Attach the prod environment to the instance

1. Confirm that the commands run in Cloud Shell returned ***ORG IS READY TO USE***.
2. To begin the process of attaching the prod environment to the runtime, run the following command:

export INSTANCE_NAME=eval-instance; curl -s -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" -d '{ "environment": "prod" }' | jq

If you get an error message, look at the details of the message:

• A NOT_FOUND error might indicate that the prod environment was not created successfully.
• A FAILED_PRECONDITION error with a message that "the resource is locked by another operation" indicates that the full provisioning of the eval environment may not have completed.

When you have successfully begun the process of attaching the prod environment to the runtime, you should see a return message with a state of IN_PROGRESS looking similar to this:

{ "name": "organizations/qwiklabs-gcp-01-e12f9fd402f4/operations/c4e1a09f-05d2-4c46-95ed-559457507379", "metadata": { "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata", "operationType": "INSERT", "targetResourceName": "organizations/qwiklabs-gcp-01-e12f9fd402f4/instances/eval-instance/attachments/c2e04a79-15e6-4656-9d25-f618080b57fb", "state": "IN_PROGRESS" } }

3. Check the status of the prod attachment using this command:

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***";

This series of commands uses the Apigee API to determine when the prod environment is attached to the instance and proxies deployed to prod are ready to take traffic.

When the text ***prod ENVIRONMENT ATTACHED*** is printed, proxies deployed to the prod environment can accept traffic.

Leave the command running and continue with the next task.

Click Check my progress to verify the objective. Attach the prod environment to the instance

Task 6. Create an API proxy

In this task, you create an API proxy that uses flow variables to return the hostname and environment for the API call.

1. Select the Apigee console tab in your browser window.
2. On the left navigation menu, select Develop > API Proxies.
3. To start the proxy wizard, click Create New.
4. Click No Target.

Note: Do not click the "Use OpenAPI Spec" link.

5. Specify the following properties:

   Property	Value
   Name	test-env
   Base path	/test-env

6. Click Next.

7. Leave the Common policies settings as their defaults, and click Next.

8. On the Summary page, click Create.

Your API proxy will be generated. You will deploy your proxy later.

9. Click Edit proxy.
10. If a Switch to Classic link is in the upper right corner, click that link.
11. Click the Develop tab.

This tab is used to edit the API proxy. The Proxy Endpoint PreFlow is selected.

12. In the Flow pane, click +Step on the lower left.

Note: To see the +Step button on the lower left, you may need to expand the Flow pane by dragging the separator between the Flow and Code panes.

You will add a policy step to the PreFlow response. A policy implements a specific, limited management function.

13. Select Assign Message, then specify AM-SetResponse as the Name and Display Name, and then click Add.

This attaches a new AssignMessage policy to the API proxy. You should see the AssignMessage code below the Flow pane:

14. Replace the AssignMessage code with the following:

<AssignMessage continueOnError="false" enabled="true" name="AM-SetResponse"> <Set> <Payload contentType="application/json">{ "environment": "{environment.name}", "hostname": "{request.header.Host}" } </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="true" transport="http" type="response"/> </AssignMessage>

This policy creates a response returning the environment name and hostname. The proxy flow variable environment.name contains the environment of the deployed proxy that has received the traffic, and the variable request.header.Host contains the Host header, which indicates the hostname used for the API call.

15. Click Save.

Note: If you are prompted that a new revision was created, click OK.

16. Click Deploy to eval, and then, in the message box, click Deploy.

This deploys the proxy to the eval environment.

17. Expand the dropdown () next to Deploy to eval, and then click Deploy 1 for prod.

This deploys the proxy to the prod environment.

18. In the message box, click Deploy.
19. Click the Overview tab.
20. Wait for both deployments to complete.

When the proxy is deployed to both environments, the Deployments section of the Overview tab should look like this:

Note: If after a few minutes the proxy is not deployed to the prod environment, the prod environment may not have finished attaching to the runtime instance. You can check the status by returning to Cloud Shell and waiting for the commands to return "***prod ENVIRONMENT ATTACHED***".

Click Check my progress to verify the objective. Create an API proxy

Task 7. Test the prod and eval environments

In this task, you make calls to the test and prod environments.

A virtual machine named apigeex-test-vm was automatically created. Use this virtual machine to call the Apigee runtime using a private IP address.

Make calls to the Apigee runtime

1. In Cloud Shell, run the following to open an SSH connection to the 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

2. For each question asked, 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.

3. In the VM's shell, set required shell variables:

export PROJECT_NAME=$(gcloud config get-value project) export ORG=${PROJECT_NAME} export INSTANCE_NAME=eval-instance export INTERNAL_LB_IP=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${ORG}/instances/${INSTANCE_NAME}" | jq ".host" --raw-output) export EVAL_ENVGROUP_HOSTNAME=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${ORG}/envgroups/eval-group" | jq ".hostnames[0]" --raw-output) export PROD_ENVGROUP_HOSTNAME=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${ORG}/envgroups/prod-group" | jq ".hostnames[0]" --raw-output) echo "INTERNAL_LB_IP=${INTERNAL_LB_IP}" echo "EVAL_ENVGROUP_HOSTNAME=${EVAL_ENVGROUP_HOSTNAME}" echo "PROD_ENVGROUP_HOSTNAME=${PROD_ENVGROUP_HOSTNAME}"

The PROD_ENVGROUP_HOSTNAME was retrieved from the prod-group environment group you created in a previous task.

4. Call the deployed test-env API proxy in the eval environment:

curl -i -k --resolve "${EVAL_ENVGROUP_HOSTNAME}:443:${INTERNAL_LB_IP}" \ "https://${EVAL_ENVGROUP_HOSTNAME}/test-env"

The --resolve setting forces commands sent to the environment group hostname to resolve to the internal load balancer IP address instead of using DNS to resolve the IP address. The -k option skips verification of the TLS certificate of the internal load balancer, since the internal load balancer does not host a TLS certificate with the hostnames you are using.

Your curl command should return the response generated by the test-env proxy, which should look similar to this:

HTTP/2 200 content-type: application/json content-length: 66 date: Tue, 10 Aug 2021 17:02:53 GMT server: apigee { "environment": "eval", "hostname": "eval.example.com" }

5. Call the deployed test-env API proxy in the prod environment:

curl -i -k --resolve "${PROD_ENVGROUP_HOSTNAME}:443:${INTERNAL_LB_IP}" \ "https://${PROD_ENVGROUP_HOSTNAME}/test-env"

This time, the environment and hostname should both return prod instead of eval.

Congratulations!

In this lab, you created a new environment and environment group for your org, and attached the environment to your runtime instance. You then created and deployed an API proxy. Finally, you called the proxy using the eval and prod hostnames and the API proxy was able to detect the environment that was being called.

Next steps / learn more

• Users and roles
• Apigee predefined roles

Google Cloud training and certification

...helps you make the most of Google Cloud technologies. Our classes include technical skills and best practices to help you get up to speed quickly and continue your learning journey. We offer fundamental to advanced level training, with on-demand, live, and virtual options to suit your busy schedule. Certifications help you validate and prove your skill and expertise in Google Cloud technologies.

Manual Last Updated July 10, 2024

Lab Last Tested July 10, 2024

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