Jump Start Solution: Ecommerce platform with serverless computing

Last reviewed 2023-08-24 UTC

This guide helps you understand, deploy, and use the Ecommerce platform with serverless computing solution. This solution demonstrates how to build and run a simple ecommerce application for a retail organization, with a publicly visible online store website. It shows you how to create an application that scales to handle spikes in usage (for example, during peak scale events like a seasonal sale), and that can manage requests based on the visitor's location. This design helps the online store provide a consistent service to geographically distributed customers.

This solution is a good starting point if you want to learn how to deploy scalable ecommerce web apps with serverless capabilities. If you want granular operational control, check out the Ecommerce web app deployed on Kubernetes solution.

This document assumes that you're familiar with basic cloud concepts, though not necessarily Google Cloud. Experience with Terraform is helpful.

Objectives

This solution guide helps you do the following:

  • Learn how to design a system architecture for an ecommerce website.
  • Optimize an ecommerce website for performance, scale, and responsiveness.
  • Monitor and anticipate load limitations.
  • Use tracing and error reporting to understand and manage problems.

Products

The solution uses the following Google Cloud products:

  • Cloud Run: A fully managed service that lets you build and deploy serverless containerized apps. Google Cloud handles scaling and other infrastructure tasks so that you can focus on the business logic of your code.
  • Cloud SQL: A cloud-based PostgreSQL database that's fully managed on the Google Cloud infrastructure.
  • Secret Manager: A service that lets you store, manage, and access secrets as binary blobs or text strings. You can use Secret Manager to store database passwords, API keys, or TLS certificates that are needed by an application at runtime.
  • Cloud Storage: An enterprise-ready service that provides low-cost, no-limit object storage for diverse data types. Data is accessible from within and outside of Google Cloud and is replicated geo-redundantly.
  • Firebase Hosting: A fully managed hosting service to deploy and serve your web applications and static content.
  • Cloud Logging: A service that lets you store, search, analyze, monitor, and alert on logging data and events from Google Cloud and other clouds.
  • Cloud Trace: A distributed tracing system for Google Cloud that helps you understand how long it takes your application to handle incoming requests from users or other applications, and how long it takes to complete operations like RPC calls performed when handling the requests.
  • Error Reporting: This service aggregates and displays errors produced in your running cloud services. Error Reporting groups errors which are considered to have the same root cause.

Architecture

The following diagram shows the architecture of the solution:

Ecommerce web application deployed with Cloud Run

Request flow

The following is the request processing flow of the ecommerce platform. The steps in the flow are numbered as shown in the preceding architecture diagram.

  1. A Firebase Hosting client frontend. The frontend uses Lit and web components for client-side rendering of API data.
  2. The web client calls an API backend that is running as a Cloud Run service. The Cloud Run API server is written in Django using the Django REST Framework.
  3. The configuration and other secrets for the Python application are stored in Secret Manager.
  4. Static assets for the application are stored in Cloud Storage.
  5. A Cloud SQL database, using PostgreSQL, is used as the relational database backend for the Python application.
  6. Cloud Logging, Cloud Trace, and Error Reporting stores logs, OpenTelemetry traces, and error reports sent by other cloud products and the Cloud Run API server. This data enables monitoring for the correct application behavior and troubleshooting of unexpected behavior.

Cost

For an estimate of the cost of the Google Cloud resources that the Ecommerce platform with serverless computing solution uses, see the precalculated estimate in the Google Cloud Pricing Calculator.

Use the estimate as a starting point to calculate the cost of your deployment. You can modify the estimate to reflect any configuration changes that you plan to make for the resources that are used in the solution.

The precalculated estimate is based on assumptions for certain factors, including the following:

  • The Google Cloud locations where the resources are deployed.
  • The amount of time that the resources are used.

Deploy the solution

This section guides you through the process of deploying the solution.

Create or choose a Google Cloud project

When you deploy the solution, you choose the Google Cloud project where the resources are deployed. When you're deciding whether to use an existing project or to create a new project, consider the following factors:

  • If you create a project for the solution, then when you no longer need the deployment, you can delete the project and avoid continued billing. If you use an existing project, you must delete the deployment when you no longer need it.
  • Using a new project can help avoid conflicts with previously provisioned resources, such as resources that are used for production workloads.

If you want to deploy the solution in a new project, create the project before you begin the deployment.

To create a project, complete the following steps:

  1. In the Google Cloud console, go to the project selector page.

    Go to project selector

  2. To begin creating a Google Cloud project, click Create project.

  3. Name your project. Make a note of your generated project ID.

  4. Edit the other fields as needed.

  5. To create the project, click Create.

Get the required IAM permissions

To start the deployment process, you need the Identity and Access Management (IAM) permissions that are listed in the following table. If you have the roles/owner basic role for the project in which you plan to deploy the solution, then you already have all the necessary permissions. If you don't have the roles/owner role, then ask your administrator to grant these permissions (or the roles that include these permissions) to you.

IAM permission required Predefined role that includes the required permissions

serviceusage.services.enable

Service Usage Admin
(roles/serviceusage.serviceUsageAdmin)

iam.serviceAccounts.create

Service Account Admin
(roles/iam.serviceAccountAdmin)

resourcemanager.projects.setIamPolicy

Project IAM Admin
(roles/resourcemanager.projectIamAdmin)
config.deployments.create
config.deployments.list
Cloud Infrastructure Manager Admin
(roles/config.admin)

Service account created for the solution

If you start the deployment process through the console, Google creates a service account to deploy the solution on your behalf (and to delete the deployment later if you choose). This service account is assigned certain IAM permissions temporarily; that is, the permissions are revoked automatically after the solution deployment and deletion operations are completed. Google recommends that after you delete the deployment, you delete the service account, as described later in this guide.

View the roles that are assigned to the service account

These roles are listed here in case an administrator of your Google Cloud project or organization needs this information.

Choose a deployment method

To help you deploy this solution with minimal effort, a Terraform configuration is provided in GitHub. The Terraform configuration defines all the Google Cloud resources that are required for the solution.

You can deploy the solution by using one of the following methods:

  • Through the console: Use this method if you want to try the solution with the default configuration and see how it works. Cloud Build deploys all the resources that are required for the solution. When you no longer need the deployed solution, you can delete it through the console. Any resources that you create after you deploy the solution might need to be deleted separately.

    To use this deployment method, follow the instructions in Deploy through the console.

  • Using the Terraform CLI: Use this method if you want to customize the solution or if you want to automate the provisioning and management of the resources by using the infrastructure as code (IaC) approach. Download the Terraform configuration from GitHub, optionally customize the code as necessary, and then deploy the solution by using the Terraform CLI. After you deploy the solution, you can continue to use Terraform to manage the solution.

    To use this deployment method, follow the instructions in Deploy using the Terraform CLI.

Deploy through the console

Complete the following steps to deploy the preconfigured solution.

  1. In the Google Cloud Jump Start Solutions catalog, go to the Ecommerce platform with serverless computing solution.

    Go to the Ecommerce platform with serverless computing solution

  2. Review the information that's provided on the page, such as the estimated cost of the solution and the estimated deployment time.

  3. When you're ready to start deploying the solution, click Deploy.

    A step-by-step interactive guide is displayed.

  4. Complete the steps in the interactive guide.

    Note the name that you enter for the deployment. This name is required later when you delete the deployment.

    When you click Deploy, the Solution deployments page is displayed. The Status field on this page shows Deploying.

  5. Wait for the solution to be deployed.

    If the deployment fails, the Status field shows Failed. You can use the Cloud Build log to diagnose the errors. For more information, see Errors when deploying through the console.

    After the deployment is completed, the Status field changes to Deployed.

  6. To view and use the deployed ecommerce web app, follow the instructions in Explore your Avocano deployment.

  7. To view the Google Cloud resources that are deployed and their configuration, take an interactive tour.

    Start the tour

When you no longer need the solution, you can delete the deployment to avoid continued billing for the Google Cloud resources. For more information, see Delete the deployment.

Deploy using the Terraform CLI

This section describes how you can customize the solution or automate the provisioning and management of the solution by using the Terraform CLI. Solutions that you deploy by using the Terraform CLI are not displayed in the Solution deployments page in the Google Cloud console.

Set up the Terraform client

You can run Terraform either in Cloud Shell or on your local host. This guide describes how to run Terraform in Cloud Shell, which has Terraform preinstalled and configured to authenticate with Google Cloud.

The Terraform code for this solution is available in a GitHub repository.

  1. Clone the GitHub repository to Cloud Shell.

    Open in Cloud Shell

    A prompt is displayed to confirm downloading the GitHub repository to Cloud Shell.

  2. Click Confirm.

    Cloud Shell is launched in a separate browser tab, and the Terraform code is downloaded to the $HOME/cloudshell_open directory of your Cloud Shell environment.

  3. In Cloud Shell, check whether the current working directory is $HOME/cloudshell_open/terraform-dynamic-python-webapp/infra. This is the directory that contains the Terraform configuration files for the solution. If you need to change to that directory, run the following command:

    cd $HOME/cloudshell_open/terraform-dynamic-python-webapp/infra
    
  4. Initialize Terraform by running the following command:

    terraform init
    

    Wait until you see the following message:

    Terraform has been successfully initialized!
    

Configure the Terraform variables

The Terraform code that you downloaded includes variables that you can use to customize the deployment based on your requirements. For example, you can specify the Google Cloud project and the region where you want the solution to be deployed.

  1. Make sure that the current working directory is $HOME/cloudshell_open/terraform-dynamic-python-webapp/infra. If it isn't, go to that directory.

  2. In the same directory, create a text file named terraform.tfvars.

  3. In the terraform.tfvars file, copy the following code snippet, and set values for the required variables.

    • Follow the instructions that are provided as comments in the code snippet.
    • This code snippet includes only the variables for which you must set values. The Terraform configuration includes other variables that have default values. To review all the variables and the default values, see the variables.tf file that's available in the $HOME/cloudshell_open/terraform-dynamic-python-webapp/infra directory.
    • Make sure that each value that you set in the terraform.tfvars file matches the variable type as declared in the variables.tf file. For example, if the type that’s defined for a variable in the variables.tf file is bool, then you must specify true or false as the value of that variable in the terraform.tfvars file.

      # This is an example of the terraform.tfvars file.
      # The values in this file must match the variable types declared in variables.tf.
      # The values in this file override any defaults in variables.tf.
      
      # ID of the project in which you want to deploy the solution
      project_id = "PROJECT_ID"
      
      # Google Cloud region where you want to deploy the solution
      # Example: us-central1
      region = "REGION"
      
      # Google Cloud zone where you want to deploy the solution
      # Example: us-central1-a
      zone = "ZONE"
      
      # Container Registry that hosts the client image
      client_image_host = "hsa-public/serverless-ecommerce"
      
      # Container Registry that hosts the server image
      server_image_host = "hsa-public/serverless-ecommerce"
      

      For information about the values that you can assign to the required variables, see the following:

Validate and review the Terraform configuration

  1. Make sure that the current working directory is $HOME/cloudshell_open/terraform-dynamic-python-webapp/infra. If it isn't, go to that directory.

  2. Verify that the Terraform configuration has no errors:

    terraform validate
    

    If the command returns any errors, make the required corrections in the configuration and then run the terraform validate command again. Repeat this step until the command returns the following message:

    Success! The configuration is valid.
    
  3. Review the resources that are defined in the configuration:

    terraform plan
    
  4. If you didn't create the terraform.tfvars file as described earlier, Terraform prompts you to enter values for the variables that don't have default values. Enter the required values.

    The output of the terraform plan command is a list of the resources that Terraform provisions when you apply the configuration.

    If you want to make any changes, edit the configuration and then run the terraform validate and terraform plan commands again.

Provision the resources

When no further changes are necessary in the Terraform configuration, deploy the resources.

  1. Make sure that the current working directory is $HOME/cloudshell_open/terraform-dynamic-python-webapp/infra. If it isn't, go to that directory.

  2. Apply the Terraform configuration:

    terraform apply
    
  3. If you didn't create the terraform.tfvars file as described earlier, Terraform prompts you to enter values for the variables that don't have default values. Enter the required values.

    Terraform displays a list of the resources that will be created.

  4. When you're prompted to perform the actions, enter yes.

    Terraform displays messages showing the progress of the deployment.

    If the deployment can't be completed, Terraform displays the errors that caused the failure. Review the error messages and update the configuration to fix the errors. Then run the terraform apply command again. For help with troubleshooting Terraform errors, see Errors when deploying the solution using the Terraform CLI.

    After all the resources are created, Terraform displays the following message:

    Apply complete!
    
  5. To view and use the deployed ecommerce web app, follow the instructions in Explore your Avocano deployment.

  6. To view the Google Cloud resources that are deployed and their configuration, take an interactive tour.

    Start the tour

When you no longer need the solution, you can delete the deployment to avoid continued billing for the Google Cloud resources. For more information, see Delete the deployment.

Explore your Avocano deployment

You have now deployed the Avocano website application! You can visit the Avocano website and look around, and then explore how the solution works in Google Cloud console. Be aware that it can take a few minutes after deploying the application for the site to show up at the provided address.

What is Avocano?

This solution uses a sample application named Avocano to demonstrate the deployment and management of a web app with many of the tools and products used for serverless applications. Avocano is an application that mimics a real-world implementation of an ecommerce web app.

The Avocano frontend presents a faux storefront, where you can add items to your cart, and attempt to complete a checkout process, but then the store reveals it is fake (Avoca--no!). While you can't actually purchase an avocado, the application demonstrates inventory management by decreasing the amount of available product by one.

Avocano landing page

Explore the frontend

To launch the frontend of your solution deployment:

  1. Open the Firebase console.
  2. Select your existing project.
  3. Navigate to the Build > Hosting section.
  4. Select the Domain ending with web.app. The frontend of your sample application opens in a new browser window.

You can now interact with the Avocano website just as its customers would see it, including browsing through products, adding products to the shopping cart, and checking out as a guest.

View the autoscaling and concurrency configuration

Cloud Run automatically scales up or down container instances from zero depending on traffic, to provide a fast startup time for your app.

Understand the settings for autoscaling and concurrency

It's important to understand that the settings for autoscaling and concurrency on Cloud Run can affect the performance and costs for your app. These settings are briefly described below:

  • Minimum instances: You can set the minimum instances setting to enable idle instances for your service. By raising the minimum instances setting in anticipation of higher traffic, you can minimize response time for the first N users. If your service requires reduced latency, especially when scaling from zero active instances, you can specify a minimum number of container instances to be kept warm and ready to serve requests.

  • Maximum instances: Increasing the maximum instances setting in Cloud Run can help you to serve exceptionally high traffic that's anticipated. In such a scenario, you should also evaluate your current quota and consider requesting an increase. Reducing the maximum instances setting can help you avoid unexpected costs or a higher utilization of underlying backing infrastructure (such as your database capacity).

  • Concurrency: The Cloud Run concurrency setting specifies the maximum number of requests that can be processed simultaneously by a given container instance. Optimizing the memory, CPU, and concurrency for your application's behavior ensures that each container instance has the best utilization, and minimizes the need to scale up to new instances. For more information, see Optimize concurrency.

View autoscaling and concurrency settings

To view the current minimum and maximum instances settings, and concurrency settings for your Cloud Run service:

  1. Go to Cloud Run
  2. Click the service you are interested in to open the Service details page.
  3. Click the Revisions tab.
  4. In the details panel at the right, the current minimum instances, maximum instances, and concurrency settings are listed under the Container tab.

If you want to learn how to adjust these settings to optimize app performance, see the General development tips in the Cloud Run documentation.

View traffic logs

You can use the logging tools in Cloud Run to keep watch on traffic to your app and get alerts when problems arise.

To view logs for your Cloud Run service:

  1. Go to Cloud Run
  2. Click the desired service in the displayed list.
  3. Click the Logs tab to get the request and container logs for all revisions of this service. You can filter by log severity level.

Cloud Run automatically captures logs from many places: anything written to standard out and standard error, anything in /var/log/, and others. Any manual logging done with the Cloud Logging libraries is also captured. You can also view the logs for this service directly in Cloud Logging by clicking View in Logs Explorer.

In the Avocano app, try the following user actions to trigger corresponding output that you can view in the logs.

User action Log output
Purchase the shopping cart using Collect as the payment type and the product amount in the cart does not exceed the inventory count. The log output shows an info log, with httpRequest status of 200.
Purchase the shopping cart using Collect as the payment type but the product amount in the cart exceeds the inventory count. The log output shows a Warning log, with httpRequest status of 400.
Purchase the shopping cart using Credit as the payment type. The log output shows an Error log, with httpRequest status of 501.

You can view the code that raises the error that leads to the 400/501 HTTP response in the serializers.py file. Cloud Run notes the response, and generates a corresponding request log entry.

You can use log-based alerts to notify you whenever a specific message appears in your included logs.

View trace instrumentation and captured traces

This solution uses Open Telemetry Python automatic instrumentation to capture telemetry data for the Avocano application.

Understand how tracing is implemented

The solution implements the following code and configuration settings in order to generate traces using automatic instrumentation:

  1. Add dependencies for Cloud Trace in the requirements.txt file, including the following:
    • opentelemetry-distro: installs the Open Telemetry API, SDK, and command-line tools.
    • opentelemetry-instrumentation: adds support for Python auto-instrumentation.
    • opentelemetry-exporter-gcp-trace: provides support for exporting traces to Cloud Trace.
    • opentelemetry-resource-detector: provides support for detecting Google Cloud resources.
    • opentelemetry-instrumentation-django: allow tracing requests for Django application.
  2. Set the IAM binding in the iam.tf file to enable the server to write to Cloud Trace.
  3. Configure the OTEL_TRACES_EXPORTER environment variable in the services.tf file to use the exporter for Cloud Trace.
  4. In the server/Procfile, configure the server to run the opentelemetry-instrument command on the Avocano app. This command detects packages in Avocano and applies automatic tracing instrumentation on them, if possible.

To learn more about collecting Cloud Trace data for Python, see Python and OpenTelemetry.

View the latency data

To view the latency data for requests, follow these steps:

  1. Go to Cloud Trace
  2. In the Select a trace section of the Trace list page, click the blue dot, which represents a captured trace. The Latency column displays the latency for the captured traces.

You can also view trace data using the following visualizations in the Trace list page:

  • Waterfall graph: represents a complete request through the application. Each step in the timeline is a span, which you can click to view details. Cloud Run automatically creates spans for internal operations, such as request handling and load balancing. These spans appear in the same waterfall graph as spans produced by Avocano, allowing you to view the full lifetime of the request.
  • Span details: shows any labels or annotations you added to the app's code when you instrumented it for tracing.

If you want to add customized traces, refer to Manual Instrumentation in the Open Telemetry documentation.

Design recommendations

This section provides recommendations for using the Ecommerce platform with serverless computing solution to develop an architecture that meets your requirements for security, reliability, cost, and performance.

To view the design recommendations for each area, click the appropriate tab.

Enhance security

Design focus Recommendations
Data encryption

By default, Cloud Run encrypts data by using a Google-managed encryption key. To protect your containers by using a key that you control, you can use customer managed encryption keys. For more information, see Using customer-managed encryption keys.

Software supply-chain security To ensure that only authorized container images are deployed to the Cloud Run services, you can use Binary Authorization.

Improve reliability

Design focus Recommendations
App scaling The Cloud Run services in the solution are configured to autoscale the container instances horizontally based on the request load. Review and adjust the autoscaling parameters based on your requirements. For more information, see About container instance autoscaling.
Request handling To improve the responsiveness of Cloud Run services that store client-specific state on container instances, you can use session affinity. Requests from the same client are routed to the same container instance, on a best-effort basis. For more information, see