Skip to content

development-guide.md

Latest commit

 

History

History
131 lines (92 loc) · 4.58 KB

development-guide.md

File metadata and controls

131 lines (92 loc) · 4.58 KB

Development Guide

This doc explains how to build and run the Online Boutique source code locally using the skaffold command-line tool.

Prerequisites

  • Docker for Desktop
  • kubectl (can be installed via gcloud components install kubectl for Option 1 - GKE)
  • skaffold 2.0.2+ (latest version recommended), a tool that builds and deploys Docker images in bulk.
  • Clone the repository. 
    git clone https://github.com/GoogleCloudPlatform/microservices-demo
cd microservices-demo/
  • A Google Cloud project with Google Container Registry enabled. (for Option 1 - GKE)
  • Minikube (optional for Option 2 - Local Cluster)
  • Kind (optional for Option 2 - Local Cluster)

Option 1: Google Kubernetes Engine (GKE)

💡 Recommended if you're using Google Cloud and want to try it on a realistic cluster. Note: If your cluster has Workload Identity enabled, see these instructions

  1. Create a Google Kubernetes Engine cluster and make sure kubectl is pointing to the cluster.

    gcloud services enable container.googleapis.com
    gcloud container clusters create-auto demo --region=us-central1
    kubectl get nodes

  2. Enable Artifact Registry (AR) on your GCP project and configure the docker CLI to authenticate to AR:

    gcloud services enable artifactregistry.googleapis.com
    gcloud artifacts repositories create microservices-demo \
  --repository-format=docker \
  --location=us \
    gcloud auth configure-docker -q

  3. In the root of this repository, run:

    skaffold run --default-repo=us-docker.pkg.dev/PROJECT_ID/microservices-demo

    Where PROJECT_ID is replaced by your Google Cloud project ID.

    This command:

    • Builds the container images.
    • Pushes them to AR.
    • Applies the ./kubernetes-manifests deploying the application to Kubernetes.

    Troubleshooting: If you get "No space left on device" error on Google Cloud Shell, you can build the images on Google Cloud Build: Enable the Cloud Build API, then run skaffold run -p gcb --default-repo=us-docker.pkg.dev/[PROJECT_ID]/microservices-demo instead.

  4. Find the IP address of your application, then visit the application on your browser to confirm installation.

    kubectl get service frontend-external

  5. Navigate to http://EXTERNAL-IP to access the web frontend.

Option 2 - Local Cluster

  1. Launch a local Kubernetes cluster with one of the following tools:

    • To launch Minikube (tested with Ubuntu Linux). Please, ensure that the local Kubernetes cluster has at least:

      • 4 CPUs
      • 4.0 GiB memory
      • 32 GB disk space
      minikube start --cpus=4 --memory 4096 --disk-size 32g

    • To launch Docker for Desktop (tested with Mac/Windows). Go to Preferences:

      • choose “Enable Kubernetes”,
      • set CPUs to at least 3, and Memory to at least 6.0 GiB
      • on the "Disk" tab, set at least 32 GB disk space

    • To launch a Kind cluster:

      kind create cluster

  2. Run kubectl get nodes to verify you're connected to the respective control plane.

  3. Run skaffold run (first time will be slow, it can take ~20 minutes). This will build and deploy the application. If you need to rebuild the images automatically as you refactor the code, run skaffold dev command.

  4. Run kubectl get pods to verify the Pods are ready and running.

  5. Run kubectl port-forward deployment/frontend 8080:8080 to forward a port to the frontend service.

  6. Navigate to localhost:8080 to access the web frontend.

Adding a new microservice

In general, the set of core microservices for Online Boutique is fairly complete and unlikely to change in the future, but it can be useful to add an additional optional microservice that can be deployed to complement the core services.

See the Adding a new microservice guide for instructions on how to add a new microservice.

Cleanup

If you've deployed the application with skaffold run command, you can run skaffold delete to clean up the deployed resources.